هل يجب على واجهات برمجة تطبيقات REST تطبيق روابط الوسائط الفائقة (HATEOAS)؟

TL;DR

HATEOAS (الوسائط الفائقة كمحرك لحالة التطبيق) أنيق نظريًا ولكنه معقد عمليًا. تتجاوز معظم واجهات برمجة التطبيقات تطبيق HATEOAS الكامل وتستخدم روابط وسائط فائقة انتقائية للترقيم والموارد ذات الصلة والإجراءات. تطبق PetstoreAPI الحديثة روابط وسائط فائقة عملية دون إجبار العملاء على أن يكونوا مدفوعين بالوسائط الفائقة بالكامل.

مقدمة

أنت تقرأ عن تصميم واجهات برمجة تطبيقات REST. ستصادف HATEOAS (الوسائط الفائقة كمحرك لحالة التطبيق). يقول الشرح: "يجب على العملاء اكتشاف جميع الإجراءات من خلال روابط الوسائط الفائقة، وليس ترميز عناوين URL بشكل ثابت".

تفكيرك: "يبدو ذلك معقدًا. هل يقوم أي شخص بهذا بالفعل؟"

الإجابة: ليس حقًا. HATEOAS هو قيد REST الأكثر تجاهلاً. يقول روي فيلدينغ (مخترع REST) إنه ضروري. يقول معظم مصممي واجهات برمجة التطبيقات إنه غير عملي. والنتيجة: معظم واجهات برمجة تطبيقات "REST" ليست RESTful حقًا وفقًا لتعريف فيلدينغ.

Modern PetstoreAPI تتبع نهجًا عمليًا: استخدم روابط الوسائط الفائقة حيث تضيف قيمة (الترقيم، الموارد ذات الصلة، الإجراءات) ولكن لا تُجبر العملاء على أن يكونوا مدفوعين بالوسائط الفائقة بالكامل.

💡

إذا كنت تقوم ببناء أو اختبار واجهات برمجة تطبيقات REST، فإن Apidog يساعدك على اختبار روابط الوسائط الفائقة، والتحقق من صحة تنسيقات الروابط، والتأكد من أن واجهة برمجة التطبيقات الخاصة بك توفر تنقلًا مفيدًا. يمكنك التحقق من صحة الروابط واختبار سير العمل المدفوع بالوسائط الفائقة.

زر

في هذا الدليل، ستتعلم ما هو HATEOAS، ولماذا هو مثير للجدل، وكيفية تطبيق روابط وسائط فائقة عملية باستخدام Modern PetstoreAPI كمرجع.

ما هو HATEOAS؟

HATEOAS هو قيد REST ينص على أنه يجب على العملاء اكتشاف إمكانيات واجهة برمجة التطبيقات من خلال روابط الوسائط الفائقة، وليس من خلال التوثيق.

المفهوم

بدلاً من ترميز عناوين URL بشكل ثابت:

// Client hardcodes URLs
const response = await fetch('https://petstoreapi.com/v1/pets/123');
const pet = await response.json();

// Client knows the URL structure
await fetch(`https://petstoreapi.com/v1/pets/${pet.id}/orders`);

يتتبع العملاء الروابط من الاستجابات:

// Client starts at root
const root = await fetch('https://petstoreapi.com/v1');
const rootData = await root.json();

// Client follows link to pets
const petsUrl = rootData._links.pets.href;
const pets = await fetch(petsUrl);
const petsData = await pets.json();

// Client follows link to specific pet
const petUrl = petsData._links.self.href;
const pet = await fetch(petUrl);
const petData = await pet.json();

// Client follows link to orders
const ordersUrl = petData._links.orders.href;
const orders = await fetch(ordersUrl);

النظرية

مع HATEOAS:

1. العملاء لا يقومون بترميز عناوين URL بشكل ثابت

يمكن أن تتغير عناوين URL دون تعطيل العملاء. يتحكم الخادم في بنية عنوان URL.

2. العملاء يكتشفون الإمكانيات

إذا كان الرابط موجودًا، فالإجراء متاح. إذا لم يكن كذلك، فهو غير متاح (أو غير مسموح به لهذا المستخدم).

3. واجهات برمجة التطبيقات ذاتية التوثيق

يستكشف العملاء واجهة برمجة التطبيقات من خلال تتبع الروابط، مثل تصفح موقع ويب.

مثال: استجابة HATEOAS كاملة

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "CAT",
  "status": "AVAILABLE",
  "_links": {
    "self": {
      "href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24"
    },
    "update": {
      "href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24",
      "method": "PUT"
    },
    "delete": {
      "href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24",
      "method": "DELETE"
    },
    "orders": {
      "href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/orders"
    },
    "adopt": {
      "href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/adopt",
      "method": "POST"
    }
  }
}

لا يحتاج العميل إلى معرفة أنماط عناوين URL. إنه يتتبع الروابط.

نقاش HATEOAS

HATEOAS مثير للجدل لأن النظرية والممارسة تتباعدان.

الحجج المؤيدة لـ HATEOAS

1. الاقتران المرن (Loose coupling)

لا يعتمد العملاء على بنية عنوان URL. يمكن للخادم تغيير عناوين URL دون تعطيل العملاء.

2. قابلية الاكتشاف

يمكن للعملاء استكشاف واجهة برمجة التطبيقات دون قراءة التوثيق.

3. الإجراءات الموجهة بالحالة

تظهر الروابط الإجراءات المتاحة. إذا تم تبني حيوان أليف، يختفي رابط "التبني".

4. REST الحقيقي

يقول روي فيلدينغ إن HATEOAS ضروري لـ REST. بدونها، أنت لا تقوم بـ REST.

الحجج ضد HATEOAS

1. التعقيد

يحتاج العملاء إلى منطق تحليل الوسائط الفائقة. تصبح عملاء HTTP البسيطون آلات حالة معقدة.

2. الأداء

يقوم العملاء بإجراء طلبات متعددة لاكتشاف عناوين URL. الوصول المباشر إلى عنوان URL أسرع.

3. صعوبة التصحيح

تتبع الروابط يجعل التصحيح أصعب. لا يمكنك ببساطة استخدام curl لعنوان URL - تحتاج إلى تتبع سلسلة الروابط.

4. سوء الأدوات

تفترض معظم عملاء HTTP وأدوات الاختبار ومولدات التوثيق عناوين URL مبرمجة بشكل ثابت.

5. لا أحد يفعل ذلك

GitHub، Stripe، Twilio، Twitter — واجهات برمجة التطبيقات الكبرى لا تستخدم HATEOAS بالكامل. إذا لم يكونوا بحاجة إليها، فهل أنت بحاجة إليها؟

الواقع

تدعي معظم واجهات برمجة التطبيقات أنها "REST" ولكنها تتجاهل HATEOAS. إنها في الواقع "واجهات برمجة تطبيقات HTTP" أو "واجهات برمجة تطبيقات شبيهة بـ REST". REST الحقيقي (مع HATEOAS) نادر.

روابط الوسائط الفائقة العملية

بدلاً من HATEOAS الكامل، استخدم روابط الوسائط الفائقة حيث تضيف قيمة.

1. روابط الترقيم

المشكلة: يحتاج العملاء إلى بناء عناوين URL للترقيم.

الحل: توفير روابط "التالي/السابق".

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "totalPages": 10
  },
  "links": {
    "self": "https://petstoreapi.com/v1/pets?page=2&limit=20",
    "first": "https://petstoreapi.com/v1/pets?page=1&limit=20",
    "prev": "https://petstoreapi.com/v1/pets?page=1&limit=20",
    "next": "https://petstoreapi.com/v1/pets?page=3&limit=20",
    "last": "https://petstoreapi.com/v1/pets?page=10&limit=20"
  }
}

الفائدة: لا يقوم العملاء بإنشاء عناوين URL للترقيم. بل يتتبعون الروابط.

2. روابط الموارد ذات الصلة

المشكلة: يحتاج العملاء إلى معرفة أنماط عناوين URL للموارد ذات الصلة.

الحل: توفير روابط للموارد ذات الصلة.

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "_links": {
    "self": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24",
    "orders": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/orders",
    "owner": "https://petstoreapi.com/v1/users/019b4127-54d5-76d9-b626-0d4c7bfce5b6"
  }
}

الفائدة: يكتشف العملاء الموارد ذات الصلة دون الحاجة إلى توثيق.

3. روابط الإجراءات

المشكلة: يحتاج العملاء إلى معرفة الإجراءات المتاحة.

الحل: توفير روابط للإجراءات المتاحة.

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "status": "AVAILABLE",
  "_links": {
    "adopt": {
      "href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/adopt",
      "method": "POST"
    }
  }
}

إذا تم تبني الحيوان الأليف بالفعل:

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "status": "ADOPTED",
  "_links": {
    // No "adopt" link - action not available
  }
}

الفائدة: تشير الروابط إلى الإجراءات المتاحة بناءً على الحالة.

4. الترقيم المستند إلى المؤشر

المشكلة: يحتاج العملاء إلى بناء عناوين URL للمؤشر.

الحل: توفير عناوين URL مبهمة للروابط التالية/السابقة.

{
  "data": [...],
  "links": {
    "next": "https://petstoreapi.com/v1/pets?cursor=eyJpZCI6IjAxOWI0MTMyIn0"
  }
}

الفائدة: لا يقوم العملاء بتحليل المؤشرات. بل يتتبعون الروابط.

كيف تستخدم Modern PetstoreAPI الوسائط الفائقة

Modern PetstoreAPI تستخدم روابط وسائط فائقة انتقائية.

روابط الترقيم

تتضمن جميع نقاط نهاية المجموعات روابط الترقيم:

GET /v1/pets?limit=20

{
  "data": [...],
  "pagination": {
    "limit": 20,
    "hasMore": true
  },
  "links": {
    "self": "https://petstoreapi.com/v1/pets?limit=20",
    "next": "https://petstoreapi.com/v1/pets?cursor=eyJpZCI6IjAxOWI0MTMyIn0&limit=20"
  }
}

روابط الموارد ذات الصلة

تتضمن استجابات الموارد روابط إلى الموارد ذات الصلة:

GET /v1/pets/019b4132-70aa-764f-b315-e2803d882a24

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "ownerId": "019b4127-54d5-76d9-b626-0d4c7bfce5b6",
  "_links": {
    "self": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24",
    "owner": "https://petstoreapi.com/v1/users/019b4127-54d5-76d9-b626-0d4c7bfce5b6",
    "orders": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/orders"
  }
}

لا HATEOAS كامل

لا تتطلب Modern PetstoreAPI من العملاء أن يكونوا مدفوعين بالوسائط الفائقة. يمكن للعملاء:

الخيار 1: تتبع الروابط (مدفوع بالوسائط الفائقة)

const pet = await fetch(petUrl);
const ownerUrl = pet._links.owner.href;
const owner = await fetch(ownerUrl);

الخيار 2: بناء عناوين URL (تقليدي)

const pet = await fetch(`https://petstoreapi.com/v1/pets/${petId}`);
const owner = await fetch(`https://petstoreapi.com/v1/users/${pet.ownerId}`);

يعمل كلا النهجين. يتم توفير الروابط للراحة، وليس للإجبار.

اختبار واجهات برمجة تطبيقات الوسائط الفائقة باستخدام Apidog

Apidog يساعدك على اختبار روابط الوسائط الفائقة والتحقق من صحتها.

اختبار وجود الرابط

تحقق من أن الاستجابات تتضمن الروابط المتوقعة:

// Apidog test script
pm.test("Response includes pagination links", () => {
  const links = pm.response.json().links;
  pm.expect(links).to.have.property('self');
  pm.expect(links).to.have.property('next');
});

اختبار صلاحية الرابط

تتبع الروابط وتحقق من عملها:

// Apidog test script
const nextUrl = pm.response.json().links.next;

pm.sendRequest(nextUrl, (err, response) => {
  pm.test("Next link returns 200", () => {
    pm.expect(response.code).to.equal(200);
  });
});

اختبار تنسيق الرابط

تحقق من أن الروابط تتبع التنسيق المتوقع:

pm.test("Links are absolute URLs", () => {
  const links = pm.response.json().links;
  Object.values(links).forEach(link => {
    pm.expect(link).to.match(/^https:\/\//);
  });
});

متى تستخدم HATEOAS

استخدم روابط الوسائط الفائقة عندما تضيف قيمة. وتجاهلها عندما لا تفعل ذلك.

استخدم روابط الوسائط الفائقة من أجل:

1. الترقيم - لا ينبغي للعملاء بناء عناوين URL للترقيم

2. الموارد ذات الصلة - تنقل مريح

3. الإجراءات المعتمدة على الحالة - إظهار الإجراءات المتاحة بناءً على حالة المورد

4. سير العمل المعقدة - توجيه العملاء خلال عمليات متعددة الخطوات

تجاهل HATEOAS من أجل:

1. واجهات برمجة تطبيقات CRUD البسيطة - يمكن للعملاء بناء عناوين URL بسهولة

2. واجهات برمجة التطبيقات الداخلية - يمكن للفرق تنسيق تغييرات عناوين URL

3. واجهات برمجة التطبيقات الحرجة للأداء - الروابط الإضافية تزيد من حجم الاستجابة

4. واجهات برمجة تطبيقات الهاتف المحمول - عرض النطاق الترددي مهم، وتضيف الروابط حملًا إضافيًا

الخلاصة

HATEOAS أنيق نظريًا ولكنه معقد عمليًا. تتجاوز معظم واجهات برمجة التطبيقات تطبيق HATEOAS الكامل وتستخدم روابط وسائط فائقة انتقائية حيث تضيف قيمة.

Modern PetstoreAPI تعرض الوسائط الفائقة العملية: روابط الترقيم، روابط الموارد ذات الصلة، وروابط الإجراءات — دون إجبار العملاء على أن يكونوا مدفوعين بالوسائط الفائقة بالكامل.

استخدم Apidog لاختبار روابط الوسائط الفائقة، والتحقق من صحتها، والتأكد من أن واجهة برمجة التطبيقات الخاصة بك توفر تنقلًا مفيدًا.

النقاط الرئيسية:

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

استكشف توثيق Modern PetstoreAPI للاطلاع على تطبيق عملي للوسائط الفائقة.

زر

الأسئلة الشائعة

هل HATEOAS مطلوب لواجهات برمجة تطبيقات REST؟

وفقًا لروي فيلدينغ (مخترع REST)، نعم. عمليًا، لا. تتجاوز معظم واجهات برمجة تطبيقات "REST" تطبيق HATEOAS وهي من الناحية الفنية "واجهات برمجة تطبيقات HTTP" أو "واجهات برمجة تطبيقات شبيهة بـ REST".

ماذا تعني اختصار HATEOAS؟

الوسائط الفائقة كمحرك لحالة التطبيق (Hypermedia as the Engine of Application State). وهذا يعني أن العملاء يكتشفون إمكانيات واجهة برمجة التطبيقات من خلال روابط الوسائط الفائقة، وليس عناوين URL المبرمجة بشكل ثابت.

هل تستخدم واجهات برمجة التطبيقات الكبرى HATEOAS؟

لا. GitHub وStripe وTwilio ومعظم واجهات برمجة التطبيقات الكبرى لا تستخدم HATEOAS بالكامل. قد تتضمن بعض روابط الوسائط الفائقة (الترقيم، الموارد ذات الصلة) ولكنها لا تتطلب من العملاء أن يكونوا مدفوعين بالوسائط الفائقة.

ما الفرق بين HATEOAS وروابط الوسائط الفائقة؟

HATEOAS هو قيد يتطلب من العملاء أن يكونوا مدفوعين بالوسائط الفائقة بالكامل. روابط الوسائط الفائقة هي مجرد روابط في الاستجابات. يمكنك تضمين روابط دون فرض HATEOAS.

هل يجب أن أطبق HATEOAS في واجهة برمجة التطبيقات الخاصة بي؟

ربما ليس HATEOAS الكامل. استخدم روابط وسائط فائقة انتقائية للترقيم والموارد ذات الصلة. لا تُجبر العملاء على أن يكونوا مدفوعين بالوسائط الفائقة ما لم يكن لديك سبب محدد.

كيف يمكنني اختبار واجهات برمجة تطبيقات HATEOAS؟

استخدم Apidog للتحقق من وجود الروابط، وتتبع الروابط، والتحقق من صحتها. اختبر أن الروابط تعيد استجابات متوقعة.

ما هو تنسيق HAL؟

HAL (Hypertext Application Language) هو تنسيق قياسي لروابط الوسائط الفائقة. يستخدم حقلي _links و _embedded. تستخدم Modern PetstoreAPI تنسيق روابط مستوحى من HAL.

هل يمكن للعملاء تجاهل روابط الوسائط الفائقة؟

نعم. إذا كانت واجهة برمجة التطبيقات الخاصة بك توفر روابط ولكنها لا تتطلب من العملاء استخدامها، فيمكن للعملاء بناء عناوين URL مباشرة. هذا هو النهج العملي الذي تتبعه معظم واجهات برمجة التطبيقات.