عقود تكامل API التي تتحمل التغيير

أسماء الحقول لا تكفي لاتفاق التكامل

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

لنفترض نظام طلبات يرسل الطلب المعتمد إلى تطبيق مستودع. اتفق الفريقان على حقول العميل والأصناف، لكنهما لم يحددا معنى انتهاء المهلة. هل حُفظ الطلب ثم ضاعت الاستجابة، أم لم يصل أصلًا؟ قد تنشئ إعادة المحاولة طلبين إذا لم توجد هوية أعمال ثابتة.

حدد ملكية الهوية والحالة

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

وضح هل التحديث يستبدل سجلًا كاملًا أم يعدل حقولًا معينة أم ينفذ فعلًا مثل الإلغاء. قد يختلف معنى الحقل الغائب عن القيمة الفارغة وعن null. حدد العملة ودقة القيم المالية، وميّز التاريخ التقويمي عن اللحظة الزمنية عند وصف التوقيت.

يوفر OpenAPI صيغة معيارية لوصف واجهات HTTP. اختر نسخة تدعمها أدواتك، وافحص الأمثلة مقابل المخطط. لكن المخطط لا يحسم وحده قواعد العمل؛ أضف أمثلة مكتوبة لسلوك العملية واختبارات مشتركة لها.

تعامل مع النتيجة المجهولة بوضوح

تفرق دلالات HTTP بين الطرق المتكررة الأثر وغيرها؛ المقصود أن تكرار الطلب المطابق لا يغير الأثر المقصود عن تنفيذه مرة واحدة. هذا لا يجعل إنشاء طلب شراء قابلًا للتكرار بأمان تلقائيًا. يجب تصميم منع الازدواج على مستوى المعاملة نفسها.

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

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

اجعل الخطأ قابلًا للتصرف

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

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

خطط للتغيير مع المستهلكين

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

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

اختبر ضياع الاستجابة عمدًا

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