تصميم عقود API واضحة تتحمّل التكاملات الفعلية

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

ابدأ بحالة استخدام محددة

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

اجعل العقد قابلًا للمراجعة

توفّر OpenAPI بنية لوصف العمليات والمعاملات والاستجابات والمخططات وآليات الأمان. وجود ملف مواصفات لا يضمن أن التطبيق يطبّقه. اربط تغييرات العقد بالمراجعة، واستخدم أمثلة نجاح وفشل واختبارات توافق حيث تكون مفيدة. احذر من أن تبقى الوثائق على شكل قديم بعد تعديل serializer أو validation.

{
  "error": {
    "code": "ORDER_STATE_CONFLICT",
    "message": "The order cannot be cancelled in its current state.",
    "request_id": "req_example_123"
  }
}

أعط الأخطاء معنى ثابتًا

على العميل أن يعتمد على code ثابت أكثر من نص الرسالة الذي قد يُترجم. فرّق بين غياب الهوية ورفض الصلاحية وعدم العثور وتعارض الحالة والمدخلات غير الصحيحة، واختر HTTP status مناسبًا لعقدك. لا تعِد stack traces أو أسماء جداول للمستهلك. في سياقات البيانات الحساسة، راجع أيضًا هل رسالة «غير موجود» تكشف وجود مورد لا يملك المستخدم حق معرفته.

صمّم صفحات مستقرة

Offset pagination بسيط، لكنه قد يكرّر أو يتجاوز نتائج عندما تتغيّر قائمة كثيرة التحديث. يمكن أن يكون cursor قائم على created_at وid أنسب لمسار «أحدث الطلبات»، مع ترتيب حتمي. اجعل cursor معتمًا للمستهلك، وقيّد حجم الصفحة، وتحقّق من صلاحيته وشروط البحث المرتبطة به. لا تعتبر cursor إذن وصول؛ أعد تطبيق صلاحيات العميل في كل صفحة.

افصل المصادقة عن التفويض

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

طوّر دون كسر المستهلكين

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

سيناريو عملي: عميل قديم يتلقّى حالة جديدة

قد تبدو إضافة حالة جديدة للطلب تغييرًا بسيطًا في الخادم، لكن تطبيقًا قديمًا قد يفشل عند تفسير enum غير معروف. حدّد هل يقبل العقد قيمًا مستقبلية وكيف يعرضها العميل. اختبر نموذجًا من المستهلكين الفعليين، ولا تكتفِ بمولّد توثيق يوافق على صحة المخطط. التوافق يشمل طريقة استخدام الحقل، وليس صحة JSON وحدها.

قائمة مراجعة لعقد جديد

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

إعداد: Noor Yasser