ربط نظامين عبر API: البيانات والأخطاء ومنع التكرار

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

API واجهة تسمح لنظام يتعامل مع نظام آخر وفق قواعد وصلاحيات محددة. المقال ده يساعد صاحب المشروع يجهز متطلبات الربط ويراجعها مع المطور؛ مش تعليمات لتشغيل حسابات أو نقل بيانات حقيقية بدون تصريح.

حدد مصدر الحقيقة واتجاه النقل

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

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

الجدول تعليمي. أسماء الحقول الحقيقية وأنواعها وحدودها تُراجع في توثيق النظامين، بما فيها الحقول الناقصة والقيم الفارغة.

فرّق بين الطلب والإشعار

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

توثيق Stripe للـWebhooks يقدم مثالًا واضحًا على أن الأحداث قد تتكرر أو تصل بترتيب مختلف، مع ضرورة التعامل مع ذلك والتحقق من التوقيع. ده مثال من مزود بعينه؛ راجع ضمانات النظام الذي تستخدمه بدل افتراض إن كل واجهات الربط متطابقة.

امنع تكرار الأثر مش الرسالة فقط

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

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

اعمل سياسة للفشل والمراقبة

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

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

اختبر قبل الاعتماد

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

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