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

ابدأ بنمذجة الموارد لا بعناوين المسارات

قبل كتابة مسار واحد، نمذج الأسماء والعلاقات بينها. النمذجة الجيدة للموارد تجعل بنية الرابط قابلة للتنبؤ: مجموعات، وعناصر مفردة، وعلاقات متداخلة، وإجراءات لا تندرج ضمن CRUD. عندما لا يملك الإجراء اسماً طبيعياً — مثل إرسال إعادة تعيين كلمة المرور أو اعتماد طلب — نَمذجه كموارد فرعي تحت الاسم الذي يملكه لا كفعل في الرابط. النموذج هو ما يصمد؛ فالمسارات مجرد واجهته العامة.

النسخ: استقرار العقد أولاً

النسخ عبر الرابط (/v1/orders) صريح وسهل التشغيل لكنه ينشر منطق النسخ في كل عميل. النسخ عبر الترويسات يُبقي الروابط نظيفة على حساب سهولة الاكتشاف. توصيتي: أضف رقم الإصدار في الرابط للأسطح الرئيسية واستخدم مفاوضة ترويسة Accept للتطورات الثانوية. أياً ما اخترت، وثّقه في سجل التغييرات وفرض فترة إهمال — أعلن عن الإزالة قبل إصدار واحد على الأقل من وصولها، وأرجع تحذيراً منظمياً عبر ترويسة Deprecation حتى يهاجر العملاء اليقظون مبكراً.

الأخطاء كعقد لا كفكرة ثانوية

يجب أن تكون الأخطاء منظمة كاستجابات النجاح تماماً. اعتمد RFC 7807 بصيغة problem+json ليفك كل عميل غلافاً واحداً مشتركاً: رابط يشير إلى النوع، وعنواناً، وحالة، ورسالة تفصيلية. مييز الفئات الأربع المهمة — فشل التحقق (422)، والتفويض (403)، وتعارض حالة المورد (409)، وأعطال الخادم (500) — واكشف كود خطأ قابل للقراءة آلياً في كل حمولة حتى تفرز الواجهات الأمامية بالمنطق لا بمطابقة النصوص. لا تُرجع أبداً آثار الاستثناءات الخام إلى العملاء.

قابلية التكرار والتزامن

الشبكات المحمولة تعيد المحاولة. البوابات تعيد المحاولة. تكاملات الدفع تعيد المحاولة. إذا لم يكن POST /payments قابلاً للتكرار، فالإرسال المزدوج حادثة سلامة بيانات في انتظار الحدوث. اقبل ترويسة Idempotency-Key، وخزّنها مقابل المورد، وأرجع الاستجابة الأصلية للمفاتيح المكررة. للتزامن التفاؤلي، استخدم If-Match مع ETags حتى لا تستبدل لوحتا متابعة إحداهما الأخرى بصمت. هذان الواجدان يزيلان أشهر صنفين من أخطاء الإنتاج في واجهات الموارد.

الترقيم والتصفية واختيار الحقول

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

GraphQL: تصميم المخطط وفخ N+1

GraphQL يحل مرونة العميل ويخلق مشكلتين جديدتين: عمق استعلام بلا حدود وانفجار استعلامات N+1. صمم المخطط حول حالات الاستخدام لا جداول قاعدة البيانات. حقّق الدفعات لكل محلل بنمط DataLoader بحيث يصدر أرجحة عشرة عناصر استعلاماً واحداً لا أحد عشر. فرض حدود تكلفة الاستعلام، وحد أقصى للعمق، واستخدم الاستعلامات المحفوظة في تطبيقات الإنتاج حتى لا يصوغ العملاء استعلامات مرضية في زمن التشغيل.

استراتيجية REST + GraphQL موحدة

  • اكشف نفس الخدمات الأساسية عبر بوابة بحيث يُكتب المنطق مرة واحدة.
  • وثّق الواجهتين من مصدر حقيقة واحد (OpenAPI/SDL).
  • حدّد المعدل بمفتاح واجهة ورمز، مع أغلفة 429 واضحة وترويسة Retry-After.
  • سجل إصدار الواجهة والعميل ومعرف الارتباط في كل طلب.
  • شغّل اختبارات العقد ضد المخطط الموثق قبل كل إصدار.

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