Api
رهنمودهای یکپارچه‌سازی#
این‌ها عمل‌هایی هستند که یک یکپارچه‌سازی را در طول زمان درست، کم‌هزینه و امن نگه می‌دارند. آن‌ها توصیه‌ای هستند، نه چیزی که API آن‌ها را تحمیل کند، اما بیشتر پرسش‌های پشتیبانی به نادیده گرفته‌شدن یکی از آن‌ها بازمی‌گردد.
هویت و امنیت#
| عمل | چرا |
|---|---|
| یک اعتبارنامه برای هر سیستم مصرف‌کننده | مصرف قابل انتساب است و بازپس‌گیری دقیق |
| کمترین صلاحیت‌ها | یک کار گزارش‌گیری به stock:read یا orders:read نیاز ندارد |
| کمترین شعبه‌ها | یک ابزار محلی نباید همه شعبه‌ها را بخواند |
| راز در یک مدیر راز | از نشت از طریق لاگ‌ها و مخازن کد جلوگیری می‌کند |
| چرخش با تغییر کارمندان | اعتبارنامه اختییار کارمند را به ارث می‌برد |
| بازپس‌گیری اعتبارنامه‌های رهاشده | یک توکن بی‌کار یک دری است که زیر نظارت نیست |
هیچ‌گاه توکن حامل را log نکنید. هرگز آن را در مرورگر، اپ موبایل یا یک مخزن عمومی جاسازی نکنید.
مدیریت داده#
| عمل | چرا |
|---|---|
id منبع را به‌عنوان کلید خارجی ذخیره کنید | شناسه‌ها باثبات‌اند؛ شماره فاکتورها ممکن است ویرایش شوند |
created_at را برای واترمارک‌ها ذخیره کنید | همگام‌سازی تدریجی بدون تکرار را ممکن می‌سازد |
| مبلغ‌ها را اعشاری در نظر بگیرید | مقدارها و مبلغ‌ها می‌توانند کسری باشند |
| کود ارز فاکتور را نگه دارید | API هیچ تبدیلی انجام نمی‌دهد |
language_code را ثابت (pin) کنید | نام‌ها در غیر این صورت با زبان رابط کاربری تغییر می‌کنند |
| وضعیت را از برچسب‌ها استنتاج نکنید | برای منطق از status_id و برای نمایش از status استفاده کنید |
داده‌های شخصی (نام مشتریان، تلفن‌ها، ایمیل‌ها) در جزئیات فروش و خرید ظاهر می‌شوند. با آن‌ها مطابق سیاست حریم خصوصی شرکت شما و شرایط پلتفرم رفتار کنید.
همگام‌سازی#
- برای هر منبع یک واترمارک انتخاب کنید، نه یک واترمارک سراسری.
- کوچک‌ترین صفحه‌ای را درخواست کنید که تعداد درخواست‌ها را معقول نگه می‌دارد؛
per_page=100برای کارهای زمان‌بندی‌شده معمولاً درست است. - پردازش را با upsert روی
idمنبع idempotent بسازید. - وقتی تازه‌ترین رشته از قبل شناخته شده است، متوقف شوید.
- یک نشانگر شکست برای هر منبع نگه دارید تا یک رکورد بد همه‌چیز را بلوکه نکند.
فراتر از آنچه API مستند می‌کند فرض ترتیب نسازید. محصولات و موجودی بر اساس id مرتب می‌شوند؛ اسناد تجارت جدیدترین اول.
مدیریت خطا#
| موقعیت | پاسخ درست |
|---|---|
401 | هشدار دهید، اعتبارنامه را بچرخانید، در یک حلقه دوباره تلاش نکنید |
403 api_ability_denied | هشدار دهید؛ یک نقش در سیستم مبدأ تغییر کرده است |
403 branch_scope_denied | پیکربندی را درست کنید؛ شناسه‌های شعبه دیگر را امتحان نکنید |
422 branch_required | X-Business-Branch را صریحاً بفرستید |
429 | Retry-After را رعایت کنید، سپس backoff نمایی |
500 | با backoff و یک سقف دوباره تلاش کنید؛ پس از شکست‌های مکرر هشدار دهید |
وضعیت، error.code و نقطه پایانی را log کنید. بدنه درخواست‌های حاوی داده شخصی را log نکنید.
کارایی#
- پاسخ context را برای مدت یک کار کش کنید به‌جای فراخوانی آن برای هر رکورد.
- کاتالوگ محصولات را کش کنید؛ آن بسیار کمتر از فروش‌ها تغییر می‌کند.
- یک صفحه 100 تایی را به چهار صفحه 25 تایی ترجیح دهید.
- همگام‌سازی‌های سنگین را بیرون از ساعات اوج تجارت اجرا کنید تا از ترافیک تعاملی دور بمانید.
- اتصالات HTTP را دوباره استفاده کنید و اگر کلاینت‌تان پشتیبانی می‌کند فشرده‌سازی را فعال سازید.
نسخه‌بندی و مدیریت تغییر#
- بر اساس
/api/v2بسازید؛ v1 یک سطح داخلی است. - فیلدهای افزوده را تحمل کنید: کلیدهای جدید ممکن است در پاسخ‌ها ظاهر شوند.
- به ترتیب فیلدها در شیءهای JSON وابسته نشوید.
- گزارش تغییرات را دنبال کنید و پس از تغییرات دوباره آزمون کنید.
- انتظارات یکپارچه‌سازی را در آزمون‌های قراردادی خودکار ثابت کنید.
چک‌لیست مرور#
- [ ] اعتبارنامه به نام سیستم مصرف‌کننده نام‌گذاری شده.
- [ ] فقط صلاحیت‌های لازم اعطا شده‌اند.
- [ ] دامنه شعبه با نیاز تجارت هم‌خوان است.
- [ ] راز بیرون از مخزن کد ذخیره شده.
- [ ] واترمارک برای هر منبع ذخیره شده.
- [ ]
429باRetry-Afterمدیریت می‌شود. - [ ] توکن هرگز log نمی‌شود.
- [ ] مسئول چرخش و تاریخ آن مستند شده.
- [ ] یکپارچه‌سازی روی یک تجارت staging آزمون شده.