إدارة إصدارات API وتوافق عمليات التكامل
· PoolByte Technology
يبدو أن إضافة حقل جديد إلى واجهة برمجة التطبيقات (API) أمر سهل؛ لكن التطبيقات الأخرى تقرأ هذا الرد بقواعدها الخاصة. قد يؤدي تغيير اسم الحقل أو النوع أو نمط الخطأ إلى تعطيل تكامل العميل. يحدد إصدار واجهة برمجة التطبيقات (API) العقد الذي سيتم من خلاله تقديم هذه التغييرات وكيفية انتقال المستهلكين إليها.
اجعل العقد مرئيًا أولاً
يجب توثيق حقول الاستجابة وأنواعها والقيم الخالية وتنسيق التاريخ ورموز الخطأ. العقد لا يتكون فقط من الأمثلة الناجحة. يعد الطلب غير الصالح، وعدم التفويض، وعدم العثور على السجل أيضًا من أشكال الاستجابة التي سيقوم المستهلك بمعالجتها. حدد ما إذا كان الحقل المفقود هو نفس الحقل الذي تم إرجاعه خاليًا بشكل صريح.
يناقش دليل إصدار Google API استخدام أسلوب متسق عند تقديم الإصدارات إلى المستخدم. يمكن استخدام عنوان URL أو ترويسة HTTP أو آلية أخرى لاختيار الإصدار؛ المهم أن تكون القاعدة التي يدعمها التطبيق واضحة ويمكن التنبؤ بها. ليس من الضروري أن يكون رقم الإصدار الداخلي لفريق التطوير وعقد واجهة برمجة التطبيقات (API) الخاص بالعميل متماثلين.
قد لا تكون كل إضافة متوافقة حقًا
في حين أن الحقل الجديد قد لا يسبب أي مشاكل لمعظم العملاء المتسامحين، إلا أن المخطط الصارم للتحقق من صحة العملاء قد يتأثر. قد تؤدي إضافة قيم جديدة إلى التعداد إلى تعطيل التطبيق الذي يتوقع القيم القديمة فقط. يعد تحويل حقل رقم إلى نص أو تغيير تنسيق التاريخ مشكلة توافق أكثر وضوحًا. لا تعتبر التغيير آمنًا لمجرد أنه يتم تجميع الخادم.
على سبيل المثال، تتم إضافة القيمة "قيد المراجعة" إلى حالة الطلب. يجب ألا يحول العميل القديم هذه القيمة إلى حالة خاطئة مثل "مدفوع" أو "فشل". يجب توثيق السلوك الآمن ذو القيمة غير المعروفة. تؤدي إضافة إصدار العميل القديم إلى مجموعة الاختبار إلى الكشف عن مثل هذه المشكلات مبكرًا.
الجدول الزمني للانتقال هو جزء من التسليم الفني
توفير نماذج الطلبات وقائمة التغيير وبيئة الاختبار للإصدار الجديد. اشرح المدة التي سيتم فيها دعم الإصدار الأقدم. إنشاء عملية لإخطار العملاء في الوقت المناسب إذا كان من الضروري تغيير تاريخ الإغلاق؛ مجرد إضافة ملاحظات ضمن المستند قد لا يصل إلى العميل الذي يستخدمه بفعالية.
تتبع المستهلكين الذين يبقون على الإصدار القديم في مقاييس الاستخدام. قد يكون الإصدار ومعرف التكامل كافيين دون الحاجة إلى تسجيل المعلومات الشخصية في المعرف أو نص الطلب. لا تفترض أن العميل قد قام بالترقية بناءً على طلب تجريبي واحد؛ التحقق من اكتمال سير العمل الفعلي مع العقد الجديد.
ما الذي يجب أن تغطيه الضوابط الآلية؟
- مقارنة العقد مع نماذج الاستجابة السابقة.
- قيم الحقول مفقودة وفارغة وغير معروفة.
- اتساق ترقيم الصفحات واستجابات الأخطاء.
- هناك نسختان تطبقان قواعد الصلاحيات نفسها على نفس المستخدم.
- تعيينات البيانات والحالة في ترحيل الإصدار.
- مراقبة استخدام الإصدار القديم وإغلاق البروفة.
تتطلب مشاريع التكامل تسليم إشعارات Webhook نظامًا تعاقديًا مماثلاً؛ لكن الإصدار هنا يحدد ماذا وكيف يقرأ مستهلك واجهة برمجة التطبيقات. لا يحدث النجاح عند إصدار إصدار جديد، ولكن عندما يمكن ترحيل التطبيقات التابعة بطريقة خاضعة للرقابة.