كيف تصمّم واجهات API يثق بها العملاء: دليل عملي يبدأ بالعقد

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

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

1. اكتب قصة العميل وقواعد العمل

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

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

2. صمّم الموارد وفق المهمة

الطلب	الغرض	نجاح معتاد
GET /v1/courses/{courseId}	قراءة دورة	200 OK
GET /v1/courses?cursor=...&limit=20	استعراض الدورات	200 OK
POST /v1/courses/{courseId}/enrollments	طلب تسجيل	201 Created
GET /v1/enrollments/{enrollmentId}	قراءة الحالة	200 OK
DELETE /v1/enrollments/{enrollmentId}	إلغاء مسموح	204 No Content

إذا كانت العملية غير متزامنة، فقد يناسبها 202 Accepted مع مورد لمتابعة الحالة. اختر رمز النجاح بحسب ما أنجزه الخادم فعلاً. GET للقراءة، وPOST لبدء إنشاء أو عملية؛ وكون بعض طرق HTTP قابلة لإعادة التطبيق لا يجعل POST آمناً تلقائياً. لا تكشف أسماء الجداول والمتحكمات في المسارات العامة.

3. حدّد الطلب والرد معاً

POST /v1/courses/crs_42/enrollments HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
Idempotency-Key: 9bfa06f8-3eb5-4d5d-85cd-43b02b56bf11

{"source":"course_page"}

استخرج هوية المتعلم من الاعتماد الموثق، ولا تقبل learnerId قابلاً للتغيير في جسم الطلب. الرد الناجح يمكن أن يكون:

HTTP/1.1 201 Created
Location: /v1/enrollments/enr_7f3
Content-Type: application/json

{"id":"enr_7f3","courseId":"crs_42","status":"confirmed","createdAt":"2026-09-29T10:30:00Z"}

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

للقوائم، استخدم شكلاً ثابتاً مثل data وpage.nextCursor وpage.hasMore. عرّف ترتيب النتائج والمرشحات. المؤشر المبهم يسمح بتغيير التنفيذ الداخلي، لكن الترقيم بلا ترتيب مستقر يؤدي إلى عناصر مفقودة أو مكررة.

4. اجعل الأخطاء قابلة للتصرف

لا يستطيع العميل معالجة عبارة عامة مثل «حدث خطأ». ميّز فشل المصادقة عن نقص الصلاحية والدورة المغلقة وعطل الخادم. يقدم RFC 9457 صيغة Problem Details:

{
  "type": "https://api.example.com/problems/enrollment-closed",
  "title": "Enrollment is closed",
  "status": 409,
  "detail": "This course stopped accepting enrollments."
}

في الإنتاج يجب أن يقود type إلى تعريف حقيقي للمشكلة. وثّق شكل أخطاء التحقق من الحقول. لا تعرض تفاصيل SQL أو التتبعات أو الأسرار للعميل؛ احتفظ بها في سجلات آمنة مع معرف ربط للدعم. اتفق على استخدام 401 للمصادقة و403 للصلاحية و404 لعدم توفر المورد و409 للتعارض و429 للحد من الطلبات وفق سياسة واضحة.

5. عالج إعادة المحاولة والتزامن

قد يُحفظ التسجيل ويضيع الرد في الشبكة. يرسل العميل Idempotency-Key فريداً للمحاولة؛ يحتفظ الخادم بالنتيجة ويعيدها عند تكرار المفتاح والطلب نفسه. ارفض استخدام المفتاح لطلب مختلف، وحدد نطاقه ومدة الاحتفاظ به. هذا سلوك تصممه أنت، وليس ضماناً آلياً من HTTP لطلبات POST.

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

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

المصادقة تجيب: من المتصل؟ والتفويض: هل يُسمح له بهذا المورد تحديداً؟ رمز صالح لا يعطي المتعلم حق قراءة تسجيل شخص آخر. اختبر صلاحيات المتعلم والمدرس والمدير على الخادم. لا تثق بدور يرسله العميل في جسم الطلب، ولا تسجل الرموز السرية في السجلات. إذا فرضت حدود معدل، وثّق نطاقها وطريقة التراجع بعد 429.

7. وثّق العقد واختبره وادِر تغييره

صف المسارات والمخططات والصلاحيات والردود وأمثلة الفشل في OpenAPI. اطلب من مطور عميل أن ينفذ اعتماداً على الوثيقة وحدها؛ أسئلته تكشف الفجوات. اجعل التحقق من العقد جزءاً من الاختبارات، مع حالات: نجاح 201، تكرار المفتاح بنفس البيانات، رفضه مع بيانات مختلفة، امتلاء الدورة، منع الوصول لتسجيل الآخرين، وعدم تجاوز المقعد الأخير، وترتيب الترقيم.

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

مراجعة سريعة قبل النشر

هل يفهم العميل النجاح والأخطاء القابلة للمعالجة؟ هل تُفرض صلاحية المورد على الخادم؟ ماذا يحدث عند تكرار الطلب أو تسابق طلبين؟ هل الترقيم والترتيب واضحان؟ هل تطابق OpenAPI التنفيذ؟ هل يمكنك تتبع الفشل دون كشف بيانات حساسة؟ وما خطة التغيير؟

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

مراجع

• دلالات HTTP، RFC 9110
• Problem Details، RFC 9457
• مواصفة OpenAPI