واجهة REST API مع Spring MVC

ينتهي الأمر دائمًا بأن يكون لتطبيق الويب عملاء ليسوا متصفحات: تطبيق جوال، أو لوحة تحكم مبنية بـ React، أو سكربت استيراد ليلي، أو شريك يزامن كتالوجه. لا أحد من هؤلاء العملاء يريد HTML؛ إنهم يريدون بيانات، وطريقة موثوقة لمعرفة ما إذا نجحت العملية.

الاستجابة الغريزية هي إرجاع JSON من المتحكمات الموجودة واعتبار العمل منتهيًا. من هنا تولد واجهات API سيئة التصميم، والعَرَض دائمًا واحد: كل شيء يرد بالرمز 200. مورد غير موجود يعيد 200 مع جسم null. تحقق فاشل يعيد 200 مع حقل "erreur" داخل JSON. استثناء يعيد 200 مع جسم فارغ. عندها لا يستطيع العميل أن يقرر شيئًا تلقائيًا؛ عليه فحص المحتوى ليخمّن ما حدث، وكل عميل يخمّن بطريقة مختلفة.

رمز حالة HTTP ليس زخرفة: إنه القناة الوحيدة التي يفهمها جميع العملاء وجميع مكتبات HTTP وجميع الوسطاء في الشبكة دون اتفاق مسبق. يعالج الكاش الرمز 404 معالجة صحيحة، ويؤدي الرمز 429 إلى إعادة المحاولة في عميل مكتوب جيدًا، ويدل الرمز 201 المصحوب بترويسة Location على مكان المورد المنشأ. إرجاع 200 في كل مكان يعني رفض استخدام بروتوكول ندفع ثمنه أصلًا.

يبني هذا الدرس واجهة API فوق التطبيق نفسه: @RestController، وكائنات DTO للإدخال والإخراج، ورموز حالة صحيحة، وResponseEntity، والترقيم الصفحي، وقبل كل ذلك معالجة مركزية للأخطاء، بحيث لا يضطر أي متحكم إلى أن يقرر وحده صيغة الخطأ.