HATEOAS

HATEOAS ومستويات نضج REST HATEOAS

القيد الرابع والأعلى في REST الأصلي: تضمين روابط في الاستجابة تدلّ العميل على الإجراءات المتاحة تاليًا.

HATEOAS اختصار لـ Hypermedia As The Engine Of Application State، أحد القيود الأربعة التي عرّفها Roy Fielding في رسالته الأكاديمية عام 2000 كجزء من الأسلوب المعماري REST. الفكرة: بدل أن يحفظ العميل رابطًا ثابتًا لكل إجراء ممكن، يكتشفها من روابط مضمَّنة داخل استجابة الخادم نفسها — تمامًا كما يتنقّل متصفح الويب بين الصفحات عبر الروابط لا عبر عناوين محفوظة مسبقًا.

هذا القيد هو المستوى الثالث والأعلى في نموذج Richardson Maturity Model الذي يصف تدرّج نضج تصميم REST API: من مستوى صفر (نقطة نهاية واحدة تشبه RPC) إلى مستوى يستخدم موارد متعددة، ثم مستوى يستخدم طرق وأكواد حالة HTTP الصحيحة، وأخيرًا مستوى يضيف روابط الاكتشاف الذاتي. رغم أهميته النظرية، فإن HATEOAS نادرًا ما يُطبَّق كاملًا في واجهات الإنتاج — معظم REST APIs الشائعة تتوقف عند المستوى الثاني.

الصياغة

{
  "id": 42,
  "...": "...",
  "links": [
    { "rel": "self", "href": "/articles/42" },
    { "rel": "...", "href": "/articles/42/..." }
  ]
}

📄 مثال

GET /api/orders/9

{
  "id": 9,
  "status": "pending",
  "links": [
    { "rel": "self", "href": "/orders/9" },
    { "rel": "cancel", "href": "/orders/9/cancel", "method": "POST" },
    { "rel": "pay", "href": "/orders/9/pay", "method": "POST" }
  ]
}

أهم النقاط

العنصر	الوظيفة
مستوى 0	نقطة نهاية واحدة تشبه RPC — كل شيء POST لنفس الرابط
مستوى 1	موارد متعددة، رابط مختلف لكل مورد
مستوى 2	طرق HTTP وأكواد حالة صحيحة — معظم REST APIs الفعلية هنا
مستوى 3 (HATEOAS)	روابط اكتشاف ذاتية داخل الاستجابة تدلّ على الإجراءات التالية الممكنة

💡 نصائح عملية

لا تحتاج غالب المشاريع الصغيرة والمتوسطة لمستوى 3 الكامل — لكن إضافة روابط "self" و"related" الأساسية تحسّن قابلية الاستكشاف بتكلفة بسيطة
إن كان عميلك يحتاج معرفة "ما الإجراءات المتاحة الآن على هذا المورد" ديناميكيًا (كحالة طلب تتغيّر)، HATEOAS يحل هذا فعليًا

⚠️ أخطاء شائعة

الادّعاء أن أي API يرجع JSON بروابط هو "RESTful بالكامل" — الالتزام الحرفي بالنموذج نادر حتى في واجهات كبرى
بناء عميل يعتمد كليًا على استنتاج الروابط من التوثيق بدل اتباعها من الاستجابة نفسها، رغم أن الواجهة توفّرها — يفقد الغرض من القيد

خصائص ذات صلة

Location ترويسة Location GET طريقة GET

🎓 تريد فهم الصورة الكاملة خطوة بخطوة؟ ابدأ من مسار REST-API الكامل بالعربي.

📚 للتعمق التقني الكامل بالإنجليزية: MDN Web Docs