نظرة سريعة#
تختلف القاعدة بحسب صاحب الواجهة.
| الواجهة | الإصدار في | مثال | التغييرات |
|---|---|---|---|
| منتج ينشره مزوّد | المسار، كإصدار رئيسي | <product-slug>/v2/orders | التغيير الكاسر يحتاج إصداراً رئيسياً جديداً؛ والتغيير المتوافق يدخل في الإصدار الحالي |
| واجهة نطاق في المنصة (الحسابات والفوترة والفهرس وبقية مسارات النطاقات) | لا مكان: بلا جزء إصدار | catalogue/consumer/products | تغييرات إضافية فقط؛ تمنع بوابة العقد التغيير الكاسر ما لم يقبله مشرف عن قصد |
info.version إصدار دلالي في الحالتين: MAJOR.MINOR.PATCH. وفي واجهة المزوّد يتفق الرقم الرئيسي مع المسار: info.version بقيمة 2.4.0 يناسب /v2/.
واجهات المزوّدين#
- الإصدار الرئيسي هو أول جزء في المسار،
/v<n>/. تنشئ البوابة مسارات إصدار المنتج تحت هذه البادئة، بجانب مسارات الإصدارات الأخرى. - يصف تعريف واحد إصداراً رئيسياً واحداً. الملف الذي فيه مسارات
/v1/و/v2/يُقسَّم إلى ملفين. - يمكن إعطاء الإصدار في عنوان الخادم الأول بدل كل مسار، ما دام العنوان ينتهي بـ
/v<n>. - لا يُحمَل الإصدار أبداً في ترويسة ولا في معامل استعلام.
يكون التغيير كاسراً حين قد يُفشل عميلاً يعمل: حذف خاصية أو إعادة تسميتها، أو تغيير نوع، أو تشديد التحقق، أو حذف قيمة من تعداد، أو تغيير رمز الحالة في حالة قائمة. إضافة خاصية أو ترويسة أو معامل اختياري أو قيمة تعداد إلى استجابة ليست كاسرة. التعريف المكتوب في صفحة الإصدارات والتغييرات الكاسرة.
واجهات نطاقات المنصة#
يُقدَّم كل تعريف نطاق تحت مسار نطاقه وليس فيه جزء إصدار: المسار هو العنوان، ويبقى العقد إضافياً. تفحص المنصة تعريفاتها بالملف الشخصي للمنصة، الذي يرفض جزء /v<n>/ هناك ويشترط info.version دلالياً. ويُكتشف التغيير الكاسر عند تعديل العقد، قبل الدمج.
يُوقَف الإصدار الرئيسي بإشعار لا يقل عن 90 يوماً، تعلن عنه ترويستا الاستجابة Deprecation وSunset، وتبقى مساراته قائمة حتى تاريخ الإيقاف النهائي.
اليوم يبقى الإصدار الرئيسي الموقوف متاحاً 30 يوماً بعد موافقة المنصة على إيقافه.
تتحقق منه#
| القاعدة | الشدة | الملف الشخصي | ما تتحقق منه |
|---|---|---|---|
api360-version-info | error | كلاهما | info.version إصدار دلالي |
api360-version-in-path | error | المزوّد | كل مسار تحت /v<n>/، أو ينتهي عنوان الخادم بـ /v<n>؛ ويتفق الرقم الرئيسي مع info.version؛ وإصدار رئيسي واحد في الملف |
api360-platform-unversioned-paths | error | المنصة | لا مسار يبدأ بـ /v<n> |
انظر أيضاً#
- الإيقاف: كيف تعلن العملية التي سيُوقف العمل بها عن نفسها.
- إنشاء إصدار وإيقاف إصدار: خطوات المزوّد.
- فحص تعريف الواجهة: الملفان الشخصيان.