مقدمة إلى واجهات برمجة REST

ما هي واجهة برمجة REST؟

REST (نقل الحالة التمثيلية) هو نمط معماري لتصميم التطبيقات الشبكية. واجهة برمجة REST (واجهة برمجة التطبيقات) هي طريقة لتواصل التطبيقات البرمجية المختلفة مع بعضها البعض عبر الإنترنت باستخدام أساليب HTTP القياسية.

فكر في واجهة برمجة REST كنادل في مطعم. أنت (العميل) تخبر النادل (الواجهة البرمجية) بما تريده من القائمة (موارد الخادم)، والنادل يحضره لك. لا تحتاج إلى معرفة كيفية عمل المطبخ - تحتاج فقط إلى معرفة كيفية الطلب.

لماذا تهم واجهات برمجة REST

أصبحت واجهات برمجة REST المعيار لخدمات الويب لأنها تقدم عدة مزايا رئيسية:

• البساطة: تستخدم أساليب HTTP المألوفة (GET، POST، PUT، DELETE) التي يفهمها المطورون بالفعل
• قابلية التوسع: البنية عديمة الحالة تسمح بالتوسع الأفقي السهل
• المرونة: يمكن إرجاع البيانات بتنسيقات متعددة (JSON، XML، HTML)
• استقلالية المنصة: تعمل مع أي لغة برمجة أو منصة تدعم HTTP
• فصل المخاوف: يمكن تطوير الواجهة الأمامية والخلفية بشكل مستقل

المبادئ الستة لـ REST

لكي تُعتبر واجهة برمجية متوافقة مع REST، يجب أن تتبع هذه القيود المعمارية:

1. معمارية العميل-الخادم

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

العميل (React، Vue، تطبيق موبايل)
    ↓ طلب HTTP
الخادم (Node.js، PHP، Python)
    ↓ استجابة HTTP
العميل يستقبل ويعرض البيانات

2. عدم الحالة

يجب أن يحتوي كل طلب من العميل إلى الخادم على جميع المعلومات اللازمة لفهم الطلب ومعالجته. لا يخزن الخادم أي سياق للعميل بين الطلبات. كل طلب مستقل ومكتفٍ ذاتياً.

3. إمكانية التخزين المؤقت

يجب أن تحدد الاستجابات نفسها على أنها قابلة للتخزين المؤقت أو غير قابلة للتخزين المؤقت. إذا كانت الاستجابة قابلة للتخزين المؤقت، يمكن للعميل إعادة استخدام بيانات تلك الاستجابة للطلبات المماثلة لاحقاً، مما يحسن الأداء ويقلل الحمل على الخادم.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=3600

{
  "id": 1,
  "name": "أحمد محمد"
}

4. واجهة موحدة

تتبع واجهات برمجة REST نهجاً متسقاً وموحداً للتفاعل مع الموارد. يشمل ذلك:

• تحديد المورد: يتم تحديد الموارد بواسطة URIs (مثل /users/123)
• معالجة المورد: يتلاعب العملاء بالموارد من خلال التمثيلات (JSON، XML)
• الرسائل الوصفية الذاتية: تتضمن كل رسالة معلومات كافية لوصف كيفية معالجتها
• HATEOAS: تتضمن الاستجابات روابط للموارد ذات الصلة

5. نظام طبقي

لا يمكن للعميل معرفة ما إذا كان متصلاً مباشرة بالخادم النهائي أو وسيط. هذا يسمح بإضافة موازنات التحميل والوكلاء والبوابات بشكل شفاف.

6. الكود عند الطلب (اختياري)

يمكن للخوادم توسيع وظائف العميل مؤقتاً عن طريق نقل الكود القابل للتنفيذ (مثل JavaScript). هذا هو القيد الاختياري الوحيد.

أساليب HTTP: أفعال REST

تستخدم واجهات برمجة REST أساليب HTTP القياسية لإجراء العمليات على الموارد. فكر في هذه كأفعال تصف الإجراء الذي تريد تنفيذه:

رموز حالة HTTP: لغة الاستجابة

تخبر رموز الحالة العميل ما إذا كان طلبه ناجحاً وماذا حدث. يتم تجميعها في خمس فئات:

1xx - معلوماتي

تم استلام الطلب وجارٍ معالجته. نادراً ما تُرى في واجهات برمجة REST.

2xx - نجاح

• 200 OK: نجح الطلب (GET، PUT، PATCH)
• 201 Created: تم إنشاء مورد جديد بنجاح (POST)
• 204 No Content: نجح الطلب ولكن لا يوجد محتوى للإرجاع (DELETE)

3xx - إعادة توجيه

• 301 Moved Permanently: انتقل المورد بشكل دائم إلى عنوان URL جديد
• 304 Not Modified: الإصدار المخزن مؤقتاً لا يزال صالحاً

4xx - أخطاء العميل

• 400 Bad Request: بناء جملة أو معاملات طلب غير صالحة
• 401 Unauthorized: المصادقة مطلوبة أو فشلت
• 403 Forbidden: تم المصادقة ولكن غير مصرح
• 404 Not Found: المورد غير موجود
• 422 Unprocessable Entity: فشل التحقق
• 429 Too Many Requests: تم تجاوز حد المعدل

5xx - أخطاء الخادم

• 500 Internal Server Error: خطأ عام في الخادم
• 503 Service Unavailable: الخادم غير متاح مؤقتاً

دورة الطلب-الاستجابة

فهم كيفية تدفق البيانات في واجهة برمجة REST أمر بالغ الأهمية. إليك ما يحدث في طلب واجهة برمجية نموذجي:

1. العميل يقوم بطلب HTTP
   → GET https://api.example.com/users/123
   → الرؤوس: Authorization، Content-Type، إلخ.

2. ينتقل الطلب عبر الإنترنت
   → قد يمر عبر الوكلاء وموازنات التحميل

3. الخادم يستقبل الطلب
   → يصادق على المستخدم
   → يتحقق من الطلب
   → يعالج منطق العمل

4. الخادم يعد الاستجابة
   → ينسق البيانات (عادةً JSON)
   → يضع رمز الحالة
   → يضيف الرؤوس

5. يتم إرسال الاستجابة إلى العميل
   → الحالة: 200 OK
   → الجسم: {"id": 123, "name": "أحمد"}

6. العميل يعالج الاستجابة
   → يحدث واجهة المستخدم
   → يخزن مؤقتاً إذا كان مناسباً

تشريح طلب واجهة برمجة REST

دعنا نحلل كيف يبدو طلب واجهة برمجية نموذجي:

GET /api/v1/users/123 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
Accept: application/json
User-Agent: MyApp/1.0

التحليل:

• الأسلوب: GET - نحن نسترجع البيانات
• المسار: /api/v1/users/123 - المورد الذي نريده
• المضيف: api.example.com - عنوان الخادم
• التفويض: رمز Bearer للمصادقة
• نوع المحتوى: تنسيق البيانات التي نرسلها
• القبول: التنسيق الذي نريد استقباله

تشريح استجابة واجهة برمجة REST

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=3600
X-RateLimit-Remaining: 999

{
  "id": 123,
  "name": "أحمد محمد",
  "email": "ahmed@example.com",
  "created_at": "2026-01-15T10:30:00Z",
  "links": {
    "self": "/api/v1/users/123",
    "posts": "/api/v1/users/123/posts"
  }
}

مكونات الاستجابة:

• سطر الحالة: HTTP/1.1 200 OK
• الرؤوس: البيانات الوصفية حول الاستجابة
• الجسم: البيانات الفعلية (كائن JSON)
• الروابط: الموارد ذات الصلة (HATEOAS)

REST مقابل الأساليب الأخرى

كيف تقارن REST بمعماريات واجهات برمجة أخرى؟

أمثلة واقعية لواجهات برمجة REST

دعنا ننظر إلى كيفية هيكلة الخدمات الشهيرة لواجهات برمجة REST الخاصة بها:

واجهة برمجة تويتر - الحصول على جدول المستخدم الزمني

GET https://api.twitter.com/2/users/123/tweets
Authorization: Bearer YOUR_TOKEN

الاستجابة: 200 OK
{
  "data": [
    {
      "id": "1234567890",
      "text": "مرحباً بالعالم!",
      "created_at": "2026-02-14T10:00:00Z"
    }
  ],
  "meta": {
    "result_count": 1,
    "next_token": "xyz789"
  }
}

واجهة برمجة GitHub - إنشاء مستودع

POST https://api.github.com/user/repos
Authorization: token YOUR_TOKEN
Content-Type: application/json

{
  "name": "my-new-repo",
  "description": "مشروعي الرائع",
  "private": false
}

الاستجابة: 201 Created
{
  "id": 123456,
  "name": "my-new-repo",
  "full_name": "username/my-new-repo",
  "html_url": "https://github.com/username/my-new-repo"
}

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

• REST هو نمط معماري، وليس بروتوكول أو معيار
• يستخدم أساليب HTTP القياسية (GET، POST، PUT، PATCH، DELETE)
• التصميم عديم الحالة يجعل واجهات برمجة REST قابلة للتوسع والصيانة
• رموز الحالة تتواصل بشأن ما حدث مع الطلب
• يتم تحديد الموارد بواسطة URIs ومعالجتها من خلال التمثيلات
• واجهات برمجة REST مستقلة عن المنصة ومحايدة للغة

ما التالي؟

في الدرس التالي، سنتعمق أكثر في أساليب HTTP ورموز الحالة. ستتعلم بالضبط متى تستخدم كل أسلوب، وكيفية التعامل مع رموز الحالة المختلفة، وأفضل الممارسات لهيكلة استجابات واجهتك البرمجية.