رابط API محصول Optifora چگونه کار میکند
این صفحه شکل API را شرح میدهد: هویت چگونه اثبات میشود، نسخهها چگونه پیش میروند، یک درخواست درون کدام حدود میماند، خطا چه ریختی دارد، و داده چگونه با بیرون مبادله میشود.
محصول در دست توسعه است و سطح API هنوز در حال تکمیل. سند مرجع نقطههای پایانی جداگانه منتشر خواهد شد؛ این صفحه هیچ نشانی و هیچ نمونه فراخوانی ندارد، تنها سازوکار را میگوید.
احراز هویت
هر درخواست یا به یک شخص تعلق دارد یا به یک برنامه ثبتشده. درخواستی که بدون هویت به یک نقطه پایانی حفاظتشده برسد، با پاسخ «احراز هویت نشده» بازمیگردد.
- توکن Bearerتوکن دسترسی در سرایند authorization درخواست جابهجا میشود. این توکن امضا شده است و تنها میگوید درخواست به چه کسی تعلق دارد.
- عمر کوتاهتوکن دسترسی پس از بازهای که با دقیقه سنجیده میشود منقضی میگردد؛ طول این بازه یک تنظیم استقرار است و مقدار پیشفرض آن سی دقیقه است.
- تازهسازی و چرخشنشست با توکن تازهسازی تمدید میشود و هر تمدید یک جفت تازه صادر میکند. اگر توکن تازهسازیِ مصرفشده بار دوم ارائه شود، همه نشستهای آن شخص باطل میشود.
- دسترسیها درون توکن پخته نمیشوندتوکن تنها هویت را حمل میکند؛ اینکه یک شخص مجاز به دیدن چیست، در هر درخواست از پایگاه داده پرسیده میشود. به همین دلیل دسترسی پسگرفتهشده پیش از انقضای توکنِ در دست، از کار میافتد.
- کلید یکپارچهسازهر برنامه ثبتشده با کلید اختصاصی خود متصل میشود. مقدار خام تنها یک بار، هنگام ساخت، نمایش داده میشود؛ آنچه نگهداری میشود چکیده آن است به همراه پیشوند غیرمحرمانهای که کلید را قابل شناسایی میکند.
- دسترسی را سازمان میدهدهر اندازه هم که یک برنامه پرکاربرد باشد، بدون مجوزی که سازمان ثبت کرده باشد حتی یک سطر داده نمیبیند. این مجوز تاریخدار، دامنهدار و قابل لغو است.
نسخهبندی
- نسخه در مسیر مینشیندنقطههای پایانی پشت یک پیشوند نسخه منتشر میشوند؛ سطح امروزی نسخه یک است.
- تغییر شکننده، مسیر تازهای باز میکندپیمان یک نقطه پایانی موجود، سرِ جای خود شکسته نمیشود. تغییر ناسازگار روی مسیر نسخه تازه منتشر میشود و نسخه قدیم به کار خود ادامه میدهد.
- سند، نسخه خود را اعلام میکندسند مرجع شماره نسخهای را که از آن ساخته شده حمل میکند؛ اینکه کدام نسخه را میخوانید، خودِ سند پاسخ میدهد.
محیطها و حدود
سند مرجع دو محیط را اعلام میکند: تولید و توسعه محلی. نشانی ریشه همراه با کلید به یکپارچهساز داده میشود؛ در این صفحه منتشر نمیشود.
- زنده بودن و آماده بودن جدا سنجیده میشوندیک نقطه پایانی میگوید فرایند بالاست؛ دومی یک پرسوجوی واقعی به پایگاه داده میفرستد و در دسترس بودن آن را تأیید میکند. تنها دومی تصمیم میگیرد که ترافیک فرستاده شود یا نه.
- مبدأهای مرورگر به یک فهرست محدود شدهانددرخواستهای میانمبدأ تنها از مبدأهایی پذیرفته میشوند که از پیش اعلام شده باشند؛ تا وقتی این فهرست خالی است، درخواست میانمبدأ از مرورگر رد میشود.
- حد اندازه بدنهبدنه یک درخواست نمیتواند از پنج مگابایت بیشتر شود. مجموعههای بزرگ بهجای یک درخواست واحد، در قالب کار انتقال انبوه با رکورد وضعیت مستقل خود جابهجا میشوند.
- اسرار در گزارش نوشته نمیشوندگزارش سرور هیچ سرایند authorization، هیچ کوکی، هیچ گذرواژه و هیچ شماره ملی را نگه نمیدارد.
محدودیت نرخ درخواست
حد مجاز برای هر نشانی و در هر دقیقه است. مقدار پیشفرض 120 درخواست در دقیقه است و هنگام استقرار تنظیم میشود. مقدار باقیمانده روی سرایندهای هر پاسخ گزارش میشود.
| سرایند پاسخ | چه میگوید |
|---|---|
| x-ratelimit-limit | کل سهمیه درون بازه. |
| x-ratelimit-remaining | آنچه در این بازه باقی مانده است. |
| x-ratelimit-reset | ثانیههای مانده تا تازه شدن سهمیه. |
| retry-after | چند ثانیه تا تلاش دوباره. تنها روی پاسخی حاضر است که درخواست را رد کرده باشد. |
پس از عبور از حد مجاز، درخواست رد میشود و پاسخ میگوید چند ثانیه باید صبر کرد. تلاش دوباره پس از آن مدت انجام میشود، نه بیدرنگ.
قالب خطا
هر خطا در یک پوشش یکسان بازمیگردد: یک فیلد کد کوتاه تا ماشین بر پایه آن مسیر بگیرد، و یک فیلد توضیح تا انسان بخواند.
- errorکد کوتاهی که کلاینت بر پایه آن تصمیم میگیرد.
- messageشرح آنچه رخ داده است.
| وضعیت | فیلد کد | معنای آن |
|---|---|---|
| 400 | Bad Request | درخواست با طرحواره همخوان نیست. توضیح، نام فیلدی را میگوید که جا افتاده یا نامعتبر است. |
| 401 | unauthenticated | هویت معتبری وجود ندارد: توکنی فرستاده نشده، منقضی شده، یا تأیید نشده است. |
| 404 | Not Found | چنین نقطه پایانی وجود ندارد، یا چنین رکوردی نیست. |
| 429 | Too Many Requests | محدودیت نرخ درخواست رد شده است؛ پاسخ میگوید چقدر باید صبر کرد. |
| 5xx | internal_error | خطای پیشبینینشده. جزئیات آن به کلاینت داده نمیشود؛ در گزارش سرور نوشته میشود. |
صفحهبندی
نقطههای پایانی که فهرست برمیگردانند همان دو پارامتر را میگیرند و همان شمارندهها را برمیگردانند، پس کلاینتِ صفحهبندی برای هر نقطه پایانی از نو نوشته نمیشود.
- limitهر صفحه چند رکورد را نگه دارد. دستکم یک، حداکثر دویست؛ و پنجاه وقتی تنظیم نشده باشد.
- offsetچند رکورد نادیده گرفته شود. از صفر آغاز میشود.
- totalدر مجموع چند رکورد با پالایهها همخوان است.
- countاین پاسخ در عمل چند رکورد را حمل میکند.
پاسخ، مقدار limit و offsetی را هم که به کار برده بازتاب میدهد؛ کلاینت جای خود را بهجای حدس زدن، از خودِ پاسخ میخواند.
تبادل داده و وبهوکها
کیپ تبادل یک تنظیم است، نه محصولی جداگانه: هر برنامه ثبتشده کیپی را که در آن کار میکند روی رکورد خود حمل میکند.
| کیپ | معنای آن |
|---|---|
| یکسویه — به بیرون | محصول Optifora داده را منتشر میکند؛ طرف مقابل آن را میخواند یا مشترک رویدادها میشود. |
| یکسویه — به درون | طرف مقابل داده را میفرستد؛ محصول Optifora آن را اعتبارسنجی و ثبت میکند. |
| دوسویه | هر دو طرف مینویسند؛ قاعده حل تعارض از پیش تعریف شده است. |
| دستدادن | هر انتقال یک نشست باز میکند: پیشنهاد، راستیآزمایی، تأیید، انتقال و رسید. رسید نزد هر دو طرف میماند. |
- رویدادها به بیرون فرستاده میشوندوبهوک رویداد را به نشانی بازگشتیای میفرستد که برنامه ثبتشده اعلام کرده است. رویدادی که تحویل نشود در صف میماند و دوباره تلاش میشود؛ هرگز بیصدا دور انداخته نمیشود.
- یک درخواست دو بار نمینویسدهر درخواست نوشتن یک کلید idempotency حمل میکند. درخواست دوم با همان کلید، رکورد دومی نمیسازد.
- هر فراخوانی سنجیده میشودچه کسی، کِی، با کدام دامنه و با چه نتیجهای فراخوانی کرده است — همه ثبت میشود. همین رکورد هم به عیبیابی پاسخ میدهد و هم به این پرسش که این داده را چه کسی بیرون کشیده است.
- برنامههای خودِ ما از همان در میگذرندهیچ مسیر دوم ویژهای وجود ندارد. یکپارچهسازی خودِ ما گواه همان سطحی است که یک توسعهدهنده بیرونی با آن روبهرو میشود.
مدل داده لایه تبادل آماده است؛ نقطههای پایانی آن هنوز منتشر نشدهاند. وقتی منتشر شوند، این بخش به مدخل آنها در سند مرجع پیوند خواهد خورد.
سندهای مرجع
سند مرجع دستی نوشته نمیشود؛ از طرحواره نقطههای پایانی ساخته میشود. هر نقطه پایانی که طرحواره خود را تحویل دهد، سند خودبهخود پر میشود، پس سند و رفتار نمیتوانند از هم فاصله بگیرند.
- امروز: در دست آمادهسازیطرحوارهها ماژول به ماژول جابهجا میشوند. پیش از انتشار سند، درخواست و پاسخ هر نقطه پایانی در آن دیده خواهد شد.
- دو قالب منتشر خواهد شدیک سند OpenAPI خوانا برای ماشین، و یک صفحه مرجع که از همان سند ساخته میشود و در مرورگر قابل مرور است.
- دسترسی پلکانی استنمای کلی برای همه باز است. مرجع کامل میتواند پشت یک توکن مستندات بنشیند که به یکپارچهساز ثبتشده داده میشود؛ کلیدهای محیط تولید و نشانیهای بازگشتی اصلاً موضوع مستندات نیستند — آنها به رکورد برنامه تعلق دارند.
- استاندارد نشانیدو سند مرجع منتشر میشود و نشانیهای آنها ثابت است: client-api.optifora.com/docs باز است و admin-api.optifora.com/docs نیازمند مجوز و بسته به بیرون است. هیچکدام امروز فعال نیستند؛ بهمحض فعال شدن، پیوندها به همین بخش افزوده میشود.
اگر نقشه یکپارچهسازی شما از هماکنون روشن است، از صفحه تماس برای ما بنویسید: در میان نخستین کسانی خواهید بود که از باز شدن این سطح باخبر میشوند.
درخواست مشخصی دارید؟
این صفحهها شرح میدهند که فرایند پشتیبانی چگونه کار میکند. اگر درخواست یا پرسشی دارید، از صفحه تماس برای ما بنویسید.
به صفحه تماس بروید