تطوير واجهات API لتطبيقات الجوال والشركاء: الإصدارات والتوافق والإيقاف

باختصار: الموقع يُحدَّث متى شئتم؛ أما التطبيق المثبت على هواتف المستخدمين ونظام الشريك فلا. بعد نشر الواجهة، افترضوا أن مستدعيها قد لا يتحدّثون لفترة طويلة. قواعدنا: التغييرات المتوافقة تدخل في النسخة الحالية، وغير المتوافقة في نسخة جديدة؛ والنسخة القديمة يُعلن إهمالها ويُقاس استخدامها لكل مستدعٍ؛ ولا تُوقف إلا حين يسمح الاستخدام بذلك؛ والعقد يعيش في ملف يتحقق منه CI.

مخطط دورة حياة نسخة API. /v1 فعّالة ولا تتلقى إلا تغييرات إضافية؛ التغيير غير المتوافق يفتح /v2؛ ثم يُعلن إهمال /v1 بترويستي Deprecation وSunset، ثم تُوقف مع خطأ واضح. في الأسفل: تتبع استخدام /v1 حسب إصدار التطبيق ومفتاح الشريك، مع الإيقاف فقط حين يسمح الاستخدام؛ وملف عقد (OpenAPI) يُقارن في CI بآخر إصدار، ويفشل أي تغيير غير متوافق خارج نسخة جديدة.
الشكل 1. نسخة رئيسية واحدة، من فعّالة إلى مهملة ثم موقوفة. الإيقاف يتبع الاستخدام لا التقويم.

1.0 ما الذي يُعد متوافقًا

التغييرمتوافق؟
حقل طلب اختياري جديد، حقل استجابة جديدنعم، إذا كان العملاء يتجاهلون الحقول غير المعروفة
نقطة نهاية جديدةنعم
حذف حقل أو إعادة تسميته أو تغيير نوعهلا
جعل حقل اختياري إلزاميًالا
إضافة قيمة تعداديتوقف على تعامل العملاء مع القيم غير المعروفة؛ احتياطًا يُعامل على أنه غير متوافق
تغيير رموز الأخطاء أو الترتيب الافتراضييُعد متوافقًا غالبًا، لكنه يكسر العملاء الذين يعتمدون عليه

في الصفّين الأخيرين تقع الحوادث. منذ النسخة الأولى تشترط إرشاداتنا للعملاء عرضًا بديلًا لقيمة التعداد غير المعروفة بدل الانهيار.

2.0 أين توضع النسخة

مقطع في المسار مثل /v1/ هو الأوضح، ويتوافق جيدًا مع السجلات وتوجيه البوابة والتخزين المؤقت؛ وهو خيارنا الافتراضي. الترويسة تبدو أنظف لكنها تُغفل بسهولة أثناء التشخيص. وأينما كانت، لا تتغير النسخة إلا لتغيير غير متوافق؛ ولا تتبع رقم إصدار المنتج.

داخل النسخة الرئيسية، يحتاج الخادم أحيانًا إلى فروق صغيرة في السلوك حسب إصدار العميل. اجعلوا التطبيق يرسل إصداره في ترويسة وقرّروا على الخادم، بدل إنشاء سلسلة من النسخ الفرعية للواجهة.

3.0 العقد ملف

صِفوا الواجهة في ملف مثل OpenAPI واحفظوه في المستودع. يفعل CI أمرين: يقارن التعديل بعقد آخر نسخة منشورة ويُفشل البناء عند أي تغيير غير متوافق لا يقع في نسخة جديدة، ويشغّل اختبارات عقد للتحقق من أن التنفيذ يطابق الوصف.

لواجهات الشركاء، ملف العقد هو مصدر دليل المطورين، لا وثيقة تُدار منفصلة. وثيقتان تُكتبان كلٌّ على حدة تتناقضان في النهاية دائمًا.

4.0 الإهمال والإيقاف

  1. عند صدور نسخة جديدة، تحمل استجابات القديمة ترويستي Deprecation وSunset (RFC 9745، RFC 8594)، وتذكر الوثائق تاريخ الإيقاف.
  2. قياس استخدام النسخة القديمة لكل مستدعٍ: أي إصدارات التطبيق وأي مفاتيح الشركاء لا تزال تستدعيها.
  3. للجوال، أضيفوا حدًا أدنى للإصدار المدعوم: ينشره الخادم، وتطلب التطبيقات الأقدم من المستخدم التحديث.
  4. لا توقفوا إلا بعد أن ينخفض الاستخدام إلى مستوى مقبول. وبعد الإيقاف، أعيدوا رمز خطأ واضحًا مع إرشادات التحديث بدل 404 مجرد.

يجب أن يراعي تاريخ الإيقاف مراجعة متاجر التطبيقات وعادات تحديث المستخدمين، كما يحتاج الشركاء إلى وقت للتطوير والاختبار والإصدار من جهتهم.

5.0 تكرار الأثر وإعادة المحاولة

في شبكات الجوال، إعادة المحاولة هي القاعدة. نقاط نهاية الإنشاء تقبل مفتاح تكرار الأثر: يولّد العميل مفتاحًا لكل عملية، ويعيد الخادم النتيجة نفسها للمفتاح نفسه خلال مدة معينة. فتتوقف مشكلات مثل إرسال الطلب مرتين عند مستوى البروتوكول.

لتصميم واجهات لتطبيق أو لشركاء، أو لإعادة ضبط واجهة خرجت عن السيطرة، راجعوا الويب والسحابة وإدارة الأجهزة، أو حدثونا عن مشروعكم.

المراجع

الأسئلة الشائعة

هل تحتاج نقاط النهاية التي لا تستخدمها إلا واجهة الويب الخاصة بنا إلى هذه الصرامة؟

واجهة الويب التي تُطلق وتُسحب مع الخادم في الوقت نفسه يمكن التعامل معها بمرونة أكبر، ما دام فحص العقد مستمرًا. وحين يوجد عميل لا يستطيع الإصدار بإيقاع الخادم، كتطبيق جوال أو تطبيق مصغّر أو نظام خارجي، تنطبق قواعد هذه المذكرة.

هل يغني GraphQL عن الإصدارات؟

العرف في GraphQL تجنب الإصدارات والتطور بإضافة الحقول ووسم القديمة بأنها مهملة، وهذا هو انضباط التوافق نفسه في صورة أخرى. وقبل حذف أي حقل لا بد دائمًا من معرفة من لا يزال يستعلم عنه.

كم مدة الإبقاء على النسخة القديمة؟

لا توجد إجابة عامة؛ يتوقف ذلك على سرعة تحديث المستخدمين ودورات إصدار الشركاء. نقرر بناءً على الاستخدام الفعلي، ونعلن تاريخ الإيقاف مع صدور النسخة الجديدة، ليتمكن المستدعون من التخطيط.

أعدنا هيكلة الشيفرة داخليًا. هل يجب أن تتغير الواجهة العامة أيضًا؟

الواجهة تصف التزامًا تجاه الخارج، لا البنية الداخلية. إجراء التحويل على الخادم مع إبقاء العقد الخارجي ثابتًا هو عادةً الطريقة الأقل تكلفة لاجتياز إعادة الهيكلة الداخلية.