تخيّل أن موقعًا أرسل طلب شراء إلى نظام إدارة العمليات. حفظ النظام الطلب، لكن التأكيد لم يصل إلى الموقع. هل يعيد الموقع الإرسال؟ وهل قد ينشئ ذلك طلب شراء ثانيًا؟ يوضح هذا المثال الافتراضي أهمية مواصفات واجهة API للأعمال اليومية. فهي تصف السلوك المتوقع لدى الطرفين، بما في ذلك حالات قد لا تظهر في عرض تجريبي ناجح.
في هذه المقالة
ابدأ بمسار العمل ومصدر البيانات المعتمد
ارسم التفاعل من إجراء المستخدم إلى النتيجة المؤكدة. في مثال الشراء، حدّد من ينشئ رقم الطلب، وأي نظام يقرر قبوله، وأين يستطيع العميل معرفة حالته. ميّز بين استلام طلب الإرسال وقبول طلب الشراء؛ فقد تكون لكل منهما مرحلة مستقلة. وحدّد من يستطيع تعديل كل معلومة. إذا كان النظامان يسمحان بتغيير عنوان التسليم، فيجب الاتفاق على قواعد التحديث، بدل افتراض أن آخر شاشة عُرضت تحتوي القيمة المعتمدة.
- حدّد المسؤول عن بيانات الطلب والعميل والحالة.
- وضّح النتيجة التي يجب عرضها للمستخدم فورًا.
- احصر التحديثات اللاحقة التي يحتاج النظام الآخر إلى استلامها.
فسّر الحقول بأمثلة محددة
وثّق المعلومات المطلوبة والقيم المقبولة ومعنى غياب البيانات في كل رسالة. يحتاج السعر إلى عملة وتفسير واضح، ويحتاج الوقت إلى اتفاق على المنطقة الزمنية المستخدمة. راجع هذه القواعد باستخدام طلب شراء نموذجي. هل تعني حالة «ملغى» إلغاء الطلب كاملًا أم إلغاء أحد عناصره؟ وهل يعني العنوان الفارغ أنه غير معروف أم أنه حُذف عمدًا؟ وضّح أيضًا السجلات المسموح لكل جهة بقراءتها أو تعديلها. تؤثر هذه القرارات في المواصفات وتجربة المستخدم؛ تشابه أسماء الحقول وحده لا يحسم معناها.
حدّد قواعد إعادة الإرسال ورسائل الخطأ
في المثال التوضيحي، يمكن اقتراح القاعدة التالية: خلال مدة احتفاظ متفق عليها، تؤدي إعادة الإرسال بالمعرّف نفسه والتفاصيل نفسها إلى إرجاع رقم طلب الشراء الموجود. أما استخدام المعرّف نفسه بتفاصيل مختلفة فينتج عنه تعارض يجب معالجته. حدّد نطاق المعرّف ومدة الاحتفاظ به صراحةً. ثم ميّز الأخطاء التي تتطلب تصحيحًا عن الأعطال المؤقتة. انتهاء مهلة الاتصال لا يثبت أن الطلب لم يُحفظ؛ لذلك تحتاج الجهة المرسلة إلى وسيلة للتحقق من النتيجة قبل تحديد الخطوة التالية.
- عنوان تسليم ناقص: أعد توضيحًا للحقل المطلوب، وصحّح البيانات قبل إعادة الإرسال.
- نتيجة غير مؤكدة: ابحث باستخدام معرّف الطلب وقارن الحالة المسجلة.
- عطل مؤقت في الخدمة: اتبع سياسة إعادة المحاولة المتفق عليها، دون إنشاء هوية طلب شراء جديدة لكل محاولة.
اتفق على فحص المواصفات وتغييرها
اطلب من الفريقين مراجعة طلب ناجح، وإرسال مكرر، وعنوان غير صالح، وتأكيد انقطع قبل وصوله. تحقّق من توقعهما النتيجة نفسها في كل حالة. احتفظ بهذه الأمثلة مع المواصفات، واستخدمها عند تغيير التكامل. عيّن المسؤولين عن اعتماد التعديلات وإبلاغ الفرق المرتبطة والتحقيق في الأعطال. ينبغي لوثائق التسليم أن تشرح تتبّع الطلب دون كشف معلومات غير لازمة عن العميل، وكيفية تنسيق التغييرات التي تتطلب تعديلات في الأنظمة التي تستخدم الواجهة بالفعل.