تطوير API: REST و GraphQL و WebSocket وأفضل الممارسات

تاريخ الإنشاء: ٢٧ مارس ٢٠٢٦ · آخر تحقق: ٣ نوفمبر ٢٠٢٦.

أنواع API وحالات استخدامها

REST: طلب-استجابة لمعالجة البيانات

لا تزال REST هي المعيار للـ APIs التي تعتمد بكثافة على CRUD. يمثل كل نقطة نهاية (endpoint) مورداً، وتحدد أفعال HTTP الإجراءات.

متى تستخدم REST:

• الـ APIs العامة ذات التنوع الواسع في العملاء
• عمليات الإنشاء والقراءة والتحديث والحذف البسيطة
• عندما يكون التخزين المؤقت (caching) مهماً (توفر ترويسات HTTP تحكماً مدمجاً)

GraphQL: استعلامات كفؤة يقودها العميل

تنقل GraphQL منطق الاستعلام من الخادم إلى العميل. بدلاً من أن يقرر الخادم شكل الاستجابة، يطلب العميل حقولاً محددة.

مقارنة:

متى تستخدم GraphQL:

• عملاء واجهة أمامية متعددون باحتياجات بيانات مختلفة
• تطبيقات الهاتف المحمول حيث يمثل عرض النطاق الترددي (bandwidth) أهمية
• علاقات بيانات معقدة عبر الخدمات

WebSocket: اتصالات ثنائية الاتجاه ومستمرة

تحافظ WebSockets على اتصال TCP مفتوح، مما يسمح للخادم بدفع البيانات إلى العملاء دون الحاجة إلى الاستطلاع (polling).

ws.addEventListener('open', () => {
  ws.send(JSON.stringify({ action: 'subscribe', channel: 'prices' }));
});

ws.addEventListener('message', (event) => {
  console.log('Price update:', event.data);
});

متى تستخدم WebSockets:

• الدردشة، والتعاون، والألعاب الجماعية في الوقت الفعلي
• الإشعارات والخلاصات المباشرة
• بث البيانات (أسعار الأسهم، قراءات المستشعرات)

Server-Sent Events (SSE): دفع الخادم عبر HTTP

تعتبر SSE أبسط من WebSockets — حيث يقوم الخادم بدفع التحديثات عبر اتصال HTTP أحادي الاتجاه.

const sse = new EventSource('/api/price-stream');
sse.addEventListener('price-update', (e) => {
  console.log(JSON.parse(e.data));
});

متى تستخدم SSE:

• تحديثات من الخادم إلى العميل في اتجاه واحد (لا حاجة لمدخلات من العميل)
• لوحات البيانات والإشعارات في الوقت الفعلي
• أسهل في التنفيذ من WebSockets

Async APIs: مواصفات AsyncAPI

بالنسبة للـ APIs القائمة على الأحداث والرسائل، توفر AsyncAPI توثيقاً مشابهاً لـ OpenAPI للأنظمة غير المتزامنة.

تغطي AsyncAPI:

• أنماط Pub/Sub (مثل Kafka، RabbitMQ، وطوابير رسائل السحابة)
• WebSocket APIs
• توثيق Server-Sent Events

أدوات الاختبار والتصميم

Postman: الخيار الافتراضي منذ فترة طويلة

لطالما كان Postman منصة اختبار API المهيمنة، حيث يتيح لك تنظيم الطلبات، وأتمتة الاختبارات، والتعاون مع فريقك. ملاحظة: اعتباراً من مارس ٢٠٢٦، أصبحت الخطة المجانية في Postman مقتصرة على مستخدم واحد فقط — ويتطلب التعاون الجماعي الآن خطة مدفوعة (Solo أو Team أو Enterprise)، مما دفع العديد من الفرق الصغيرة نحو البدائل المذكورة أدناه.

الميزات الرئيسية:

• منشئ طلبات مع سكربتات ما قبل الطلب واختبارات ما بعد الاستجابة
• مجموعات (Collections) لتنظيم الطلبات ذات الصلة
• متغيرات البيئة لإدارة الأسرار وعناوين URL
• خوادم وهمية (Mock servers) للاختبار بدون وجود خلفية برمجية (backend) حية
• إنشاء توثيق لـ API

// Post-request test in Postman
pm.test('Status is 200', function() {
  pm.response.to.have.status(200);
});

pm.test('Response has user ID', function() {
  pm.expect(pm.response.json()).to.have.property('id');
});

Hoppscotch: البديل مفتوح المصدر

Hoppscotch هو عميل API مجاني ومفتوح المصدر يشبه Postman. يعمل بالكامل في متصفحك، ولا يتطلب أي تثبيت، ويحترم الخصوصية — حيث لا تمر الطلبات عبر خوادم Hoppscotch.

المزايا:

• يعمل بدون اتصال بالإنترنت
• خفيف وسريع
• لا يتطلب حساباً
• مفتوح المصدر (يمكن استضافته ذاتياً)

Bruno: يركز على سطح المكتب ومتوافق مع Git

يركز Bruno على تخزين مجموعات الطلبات في Git، مما يجعل اختبارات API جزءاً من نظام التحكم في الإصدارات الخاص بك. إنه خفيف ويعتمد على تطبيقات سطح المكتب.

المزايا:

• تُخزن الطلبات كملفات نصية بسيطة (وليست ثنائية)
• مثالي للتعاون الجماعي عبر Git
• لا يتطلب حساباً أو مزامنة سحابية

Newman: التكامل مع CI/CD

يقوم Newman بتشغيل مجموعات Postman من سطر الأوامر، مما يتيح أتمتة اختبارات API في خطوط أنابيب CI/CD.

newman run collection.json \
  --environment env.json \
  --reporters cli,json \
  --reporter-json-export results.json

استخدم Newman في GitHub Actions، أو GitLab CI، أو Jenkins لاختبار API الخاص بك تلقائياً مع كل عملية commit.

أفضل الممارسات لـ APIs قوية

إصدارات API (Versioning)

مع تطور API الخاص بك، ستحتاج إلى إجراء تغييرات جذرية (breaking changes). تتيح لك عملية تحديد الإصدارات دعم إصدارات متعددة من العملاء في وقت واحد.

الأساليب:

1. إصدار مسار URL (صريح وواضح)

GET /api/v1/users
GET /api/v2/users

2. إصدار الترويسة (Header Versioning) (عناوين URL أكثر نظافة)

GET /api/users
Accept: application/vnd.myapi.v2+json

3. إصدار معاملات الاستعلام (Query Parameter Versioning) (أقل شيوعاً)

GET /api/users?version=2

أفضل ممارسة: استخدم إصدار مسار URL للتغييرات الجذرية الكبرى، لأنه صريح ويمنع الارتباك.

تقسيم الصفحات (Pagination) لمجموعات البيانات الكبيرة

قم دائماً بتقسيم استجابات القوائم إلى صفحات. فالمستخدم الذي يطلب جميع السجلات البالغ عددها ١٠ ملايين قد يتسبب في تعطل خادمك.

{
  "data": [{ "id": 1 }, { "id": 2 }],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 10000
  }
}

وفر كلاً من تقسيم offset/limit (بسيط وجيد لواجهات المستخدم التقليدية) وتقسيم cursor (فعال لمجموعات البيانات الكبيرة وعملاء الهاتف المحمول).

التعامل المتسق مع الأخطاء

يجب أن يكون للأخطاء تنسيق يمكن التنبؤ به. قم بتضمين رمز (code)، ورسالة (message)، وتفاصيل اختيارية.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": [{ "field": "email", "reason": "required" }]
  }
}

استخدم رموز حالة HTTP بشكل صحيح:

• ٤٠٠: Bad Request (مدخلات غير صالحة)
• ٤٠١: Unauthorized (لا توجد بيانات اعتماد صالحة)
• ٤٠٣: Forbidden (تم التحقق من الهوية ولكن غير مسموح بالوصول)
• ٤٠٤: Not Found (غير موجود)
• ٤٠٩: Conflict (مورد مكرر)
• 5xx: أخطاء الخادم

أنماط بوابة API (Gateway Patterns)

مع توسع نطاق عملك، تعمل بوابة API (API Gateway) أمام خدماتك للتعامل مع المهام المشتركة.

المسؤوليات:

• المصادقة والتفويض (Authentication and authorization)
• تحويل الطلبات والاستجابات
• تحديد معدل الطلبات (Rate limiting) وإدارة الحصص
• توجيه الطلبات إلى الخدمات المصغرة (microservices) المناسبة
• المراقبة وتسجيل السجلات (Monitoring and logging)

الحلول الشائعة:

• Kong: مفتوح المصدر، يعتمد على الإضافات، ويمتلك نظام إضافات ممتاز
• AWS API Gateway: مدار، ويتكامل مع خدمات AWS
• Cloudflare Workers: بدون خادم (Serverless)، شبكة حافة عالمية
• Nginx Ingress: لعمليات نشر Kubernetes

توثيق OpenAPI

قم بتوثيق الـ API الخاصة بك باستخدام OpenAPI 3.2 (الذي صدر في سبتمبر ٢٠٢٥)، وهو المعيار الحالي في الصناعة. يعتمد OpenAPI 3.2 على الأساس المتوافق مع JSON Schema الذي تم تقديمه في الإصدار 3.1، ويضيف دعماً أساسياً لأنواع الوسائط المتدفقة (SSE, JSON Lines)، وتفويض الأجهزة لـ OAuth 2.0، والتنقل المنظم عبر الوسوم. وهو متوافق مع الإصدارات السابقة ٣٫١، لذا تستمر المواصفات الحالية في العمل. تقوم أدوات مثل Swagger UI بتوليد توثيق تفاعلي تلقائياً من المواصفات الخاصة بك.

openapi: 3.2.0
info:
  title: User API
  version: 1.0.0
paths:
  /api/v1/users:
    get:
      summary: List all users
      parameters:
        - name: limit
          in: query
          schema: { type: integer }
      responses:
        '200':
          description: User list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

تحديد المعدل والتحكم في التدفق (Rate Limiting and Throttling)

امنع إساءة الاستخدام واضمن التوزيع العادل للموارد من خلال تحديد المعدل.

الاستراتيجيات الشائعة:

• لكل عنوان IP: ١٬٠٠٠ طلب/ساعة
• لكل مفتاح API: ١٠٬٠٠٠ طلب/ساعة (الفئات المدفوعة أعلى)
• لكل مستخدم: حد يعتمد على فئة الاشتراك

تتضمن معظم حلول بوابة API ميزة تحديد المعدل مدمجة.

الخلاصة

تتطلب تطوير الـ API الحديثة ما هو أكثر من مجرد كتابة الأكواد لنقاط النهاية. إن فهم أنواع الـ API المختلفة — REST, GraphQL, WebSocket, SSE — يتيح لك اختيار الأداة المناسبة لكل مشكلة. وتضمن أدوات الاختبار مثل Postman و Newman الموثوقية. كما أن أفضل الممارسات في تحديد الإصدارات، ومعالجة الأخطاء، والتقسيم الصفحي (pagination) تمنع الصداع في المستقبل.

ابدأ بـ REST و OpenAPI. أضف الاختبارات إلى سير عملك. ومع زيادة التعقيد، قم بإدخال بوابة API وفكر في GraphQL لتحسين كفاءة العميل. إن الاستثمار في هذه الممارسات اليوم سيؤتي ثماره في سهولة الصيانة لاحقاً.

قراءات ذات صلة

• إتقان إصدارات الـ API: الاستراتيجيات، المقايضات، وأفضل الممارسات
• كيفية كتابة كود نظيف وأفضل الممارسات