أساسيات REST API

لماذا يهم

تتيح لك أعراف REST أن تتوقع السلوك الصحيح قبل أن ترسل أي طلب: الإنشاء يعيد 201 Created، والمورد المحذوف لا يعود موجوداً، والطريقة غير المدعومة تُرفض بالرمز 405. وحيثما خالفت الواجهة عرفاً دون توثيق، يُرجَّح أن يكتب مطورو العملاء شيفرة تتعامل معه بشكل خاطئ.

وتتضاعف كلفة عيب الواجهة بعدد عملائها. فحقل أُعيدت تسميته أو 500 لمدخلات سيئة قد يعطّل واجهة الويب الأمامية وتكامل أحد الشركاء وإصدارات التطبيق المثبتة على هواتف المستخدمين، مع أن أياً منها لم يتغير. ومعرفة الأعراف تحوّل ملاحظة «الواجهة تبدو غريبة» إلى توقعات دقيقة لحالات الاختبار.

الموارد وعناوين URI والتمثيلات وانعدام الحالة

يعرّف فيلدينغ REST بستة قيود، أحدها اختياري، منها انعدام الحالة (Stateless) والواجهة الموحّدة (Uniform Interface). وكثيراً ما تطبّقها الواجهات الموصوفة بأنها REST تطبيقاً جزئياً — فروابط الوسائط التشعبية (Hypermedia) التي تخبر العميل بما يمكنه فعله بعد ذلك تُترك غالباً — لذا احكم على الواجهة بعقدها أولاً، واستخدم أعراف REST لاكتشاف التناقضات. وأهم أربع أفكار للاختبار:

• المورد (Resource): شيء مسمّى تعرضه الواجهة — مهمة أو مستخدم أو قائمة المهام. الموارد أسماء، والفعل يأتي من الطريقة: POST /tasks لا POST /createTask.
• عنوان URI: معرّف المورد، وصيغته معرّفة في RFC 3986. ومن الأعراف الشائعة مجموعة بصيغة الجمع /tasks، وأعضاؤها /tasks/42، وموارد فرعية مثل /tasks/42/comments.
• التمثيل (Representation): حالة المورد في صيغة محددة. يذكر العميل الصيغة التي يرسلها في Content-Type والصيغ التي يستطيع قراءتها في Accept.
• انعدام الحالة (Statelessness): يحمل كل طلب كل ما يحتاجه الخادم لفهمه — بيانات الاعتماد مثل الرمز المميّز (Token)، والمعرّفات، ورقم الصفحة. ولا يحتفظ الخادم بسياق جلسة من الطلبات السابقة (أما الموارد المخزّنة نفسها فتبقى بالطبع)، فيمكن تكرار الطلب أو إرساله منفرداً أو معالجته على خادم آخر ويبقى معناه واحداً. واختبره على هذا الأساس: اطلب الصفحة ⁦3⁩ مباشرةً دون جلب الصفحتين ⁦1⁩ و⁦2⁩ أولاً.

ربط الطرق بعمليات CRUD

تشير CRUD إلى العمليات الأساسية على البيانات المخزنة: الإنشاء (Create) والقراءة (Read) والتحديث (Update) والحذف (Delete). وفي REST تمثّل كل عملية طريقةَ HTTP تُطبَّق على المجموعة أو على عنصر واحد. وقد تعرّفت إلى الطرق وإلى خاصيتَي كونها آمنة (Safe) ومتكافئة (Idempotent) في درس طرق HTTP؛ ويجمع الجدول بينها وبين الموارد.

والنمط وراء الجدول: تُنشئ على المجموعة، والخادم يختار عنوان URI للعنصر الجديد؛ وتقرأ المجموعة أو عنصراً واحداً؛ وتحدّث عنصراً واحداً أو تحذفه في عنوانه الخاص. أما التركيبات الخارجة عن الجدول — POST /tasks/42، أو PUT وPATCH وDELETE على المجموعة كلها — فلا تُتاح عادةً، ويجب أن تُقابَل بالرمز 405 Method Not Allowed.

Operation  Method  URI          Typical success response
---------  ------  -----------  ---------------------------------------------
Create     POST    /tasks       201 Created + Location: /tasks/{id}
Read       GET     /tasks       200 OK, a list (often paged)
Read       GET     /tasks/{id}  200 OK, one task
Update     PUT     /tasks/{id}  200 OK or 204 No Content, whole task replaced
Update     PATCH   /tasks/{id}  200 OK or 204 No Content, sent fields only
Delete     DELETE  /tasks/{id}  204 No Content (200 with a body, 202 if queued)

رموز الحالة في واجهة REST

يتفرّع سلوك العملاء بحسب رمز الحالة قبل قراءة الجسم، ولذلك فالرمز جزء من العقد. وفي REST ينتج الرمز عن العملية وعن حالة المورد، فتستطيع كل حالة اختبار أن تذكر الرمز المتوقع.

• 201 Created بعد الإنشاء، مع ترويسة Location تحمل عنوان المورد الجديد (RFC 9110). وإعادة 200 مع المعرّف في الجسم فقط انحراف شائع، والعقد هو الذي يحدد هل هو عيب.
• 204 No Content لتحديث أو حذف ناجح لا يعيد شيئاً: يجب أن يكون الجسم فارغاً.
• 404 Not Found لعنصر غير موجود، ومنه العنصر المحذوف للتو. أما القائمة الفارغة فهي 200 مع مصفوفة فارغة.
• 405 Method Not Allowed لطريقة لا يدعمها المورد، مع ترويسة Allow تذكر الطرق التي يدعمها؛ وهذه الترويسة يشترطها RFC 9110.
• 415 Unsupported Media Type لجسم بصيغة لا يقبلها المورد؛ و406 Not Acceptable حين لا يستطيع الخادم إنتاج أيٍّ من الصيغ المذكورة في Accept، مع أن RFC 9110 يسمح له أيضاً بإرسال صيغته الافتراضية بدلاً من ذلك.
• 409 Conflict حين يتعارض الطلب مع الحالة الحالية، مثل بريد إلكتروني مسجّل مسبقاً؛ و400 أو 422 للمدخلات غير الصالحة، باستخدام متسق.
• لا 5xx أبداً لخطأ من العميل: فالرمز 500 لمدخلات سيئة يعني غالباً أن التحقق من صحة المدخلات أو معالجة الأخطاء مفقودة.

جرّبها: محلّل رموز حالة HTTP جرّبها: مرجع رموز حالة HTTP

مثال تطبيقي: مهمة واحدة عبر دورة حياتها

يمرّر المختبِر مهمة واحدة عبر كل العمليات، ويتحقق بعد كل خطوة من رمز الحالة ومن الحالة المخزنة. ويبدأ حساب الاختبار دون أي مهام.

• تستخدم الخطوات اللاحقة /v1/tasks/57 المأخوذ من ترويسة Location بدلاً من عنوان مخمَّن.
• الطريقة POST تخص المجموعة: فعلى العنصر /v1/tasks/57 تُقابَل بالرمز 405، وتذكر ترويسة Allow الطرق التي يدعمها العنصر فعلاً.
• بعد الحذف يختفي العنصر، فيعيد GET /v1/tasks/57 الرمز 404؛ أما المجموعة فما زالت موجودة، فيعيد GET /v1/tasks الرمز 200 مع مصفوفة فارغة، لا 404.
• وتبقى لكل طريقة وعودها الخاصة هنا أيضاً — فـPATCH يغيّر الحقول المرسلة فقط، وPUT يحمل الحالة الكاملة، وطلب DELETE المكرر قد يعيد 404 ويبقى متكافئاً — كما يشرح قسما الطرق الآمنة والمتكافئة وما تختبره في كل طريقة في درس طرق HTTP.

POST /v1/tasks  {"title": "Pay rent", "done": false}
  -> 201 Created, Location: /v1/tasks/57
GET /v1/tasks/57
  -> 200 OK, {"id": 57, "title": "Pay rent", "done": false}
PATCH /v1/tasks/57  {"done": true}
  -> 200 OK, {"id": 57, "title": "Pay rent", "done": true}
POST /v1/tasks/57
  -> 405 Method Not Allowed, Allow: GET, HEAD, PUT, PATCH, DELETE
DELETE /v1/tasks/57
  -> 204 No Content
GET /v1/tasks/57
  -> 404 Not Found
GET /v1/tasks
  -> 200 OK, []

جرّبها: مختبِر REST API جرّبها: منشئ طلبات API

إدارة الإصدارات والتغييرات الكاسرة

للواجهة عملاء لا يتحكم فيهم فريقها، فلا يستطيع تغييرها بحرية. والتغيير الكاسر (Breaking Change) هو ما يجعل عميلاً سليماً لم يتغير يتعطّل: حذف حقل أو إعادة تسميته، أو تغيير نوعه، أو جعل حقل اختياري في الطلب إلزامياً، أو تغيير عنوان URI أو رمز حالة. أما إضافة نقطة نهاية أو حقل اختياري فآمنة عادةً، بشرط أن يتجاهل العملاء الحقول التي لا يعرفونها.

لا يفرض REST نظاماً لإدارة الإصدارات (Versioning). تختار الفرق نظاماً وتوثّقه في العقد، وغالباً ما يكون مستند OpenAPI: مسار URI (/v1/tasks)، أو معامل استعلام (?version=2)، أو ترويسة طلب مخصصة مثل Api-Version: 2 (ويختلف اسمها من واجهة لأخرى)، أو نوع الوسائط (Accept: application/vnd.example.v2+json).

• بعد إطلاق نسخة جديدة، شغّل اختبارات الانحدار للنسخة القديمة دون تعديل: يجب أن تبقى v1 تتصرف كما ينص عقدها.
• أرسل الطلب نفسه إلى النسختين، وتأكد من أن الفروق الظاهرة هي الفروق الموثّقة فقط.
• أرسل طلباً بلا نسخة، وبنسخة مجهولة، وبنسخة أُوقف العمل بها: توقّع السلوك الافتراضي الموثّق أو خطأ 4xx واضحاً، لا 500 أبداً.

جرّبها: مقارنة استجابات API جرّبها: عارض OpenAPI

أسئلة شائعة

المراجع

• RFC 9110: HTTP SemanticsIETF · 2022معاني أساليب HTTP وحقول الترويسات ورموز الحالة والتفاوض على المحتوى، بغضّ النظر عن إصدار البروتوكول.
• RFC 3986: Uniform Resource Identifier (URI): Generic SyntaxIETF · 2005أجزاء URI (النظام والسلطة والمسار والاستعلام والجزء) والمحارف المحجوزة والترميز بالنسبة المئوية.
• RFC 5789: PATCH Method for HTTPIETF · 2010أسلوب PATCH للتحديثات الجزئية، مقابل PUT الذي يستبدل المورد كاملاً.
• OpenAPI SpecificationOpenAPI Initiativeالمعيار لوصف واجهات REST: المسارات والعمليات والمعاملات والمخططات والاستجابات وأنظمة الأمان.