مبادئ تصميم واجهة البرمجة وأفضل الممارسات

❌ سيء - أفعال في عناوين URL:
GET  /api/getUsers
POST /api/createUser
POST /api/updateUser/123
POST /api/deleteUser/123

✅ جيد - أسماء مع أساليب HTTP:
GET    /api/users          // الحصول على جميع المستخدمين
POST   /api/users          // إنشاء مستخدم
PUT    /api/users/123      // تحديث مستخدم
DELETE /api/users/123      // حذف مستخدم

❌ سيء - مفرد/جمع غير متسق:
GET /api/user/123        // مستخدم واحد
GET /api/users           // مستخدمون متعددون
GET /api/product/456     // منتج واحد
GET /api/products        // منتجات متعددة

✅ جيد - دائماً صيغة الجمع:
GET /api/users/123       // مستخدم واحد
GET /api/users           // مستخدمون متعددون
GET /api/products/456    // منتج واحد
GET /api/products        // منتجات متعددة

// منشورات المستخدم
GET /api/users/123/posts

// منشور محدد لمستخدم
GET /api/users/123/posts/456

// التعليقات على منشور
GET /api/posts/456/comments

// تعليق محدد
GET /api/posts/456/comments/789

// متداخل ثلاثة مستويات (تجنب عموماً التداخل الأعمق)
GET /api/users/123/posts/456/comments

❌ سيء:
/api/UserProfiles
/api/user_profiles
/api/userProfiles

✅ جيد:
/api/user-profiles

❌ سيء:
GET /api/users.json
GET /api/users.xml

✅ جيد:
GET /api/users
Accept: application/json

// البحث والتصفية
GET /api/users/search?q=أحمد
GET /api/products?category=electronics&price_max=1000

// العمليات الدفعية
POST /api/users/batch-create
POST /api/products/batch-update
DELETE /api/users/batch-delete

// الإجراءات التي لا تناسب CRUD
POST /api/users/123/activate
POST /api/orders/456/cancel
POST /api/invoices/789/send

// التجميعات والإحصائيات
GET /api/users/count
GET /api/sales/statistics
GET /api/reports/summary

// المصادقة والتفويض
POST /api/auth/login
POST /api/auth/logout
POST /api/auth/refresh
GET /api/auth/me

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

المزايا:
✅ واضح ومرئي
✅ سهل توجيه إصدارات مختلفة
✅ بسيط للتنفيذ
✅ يعمل مع جميع عملاء HTTP

العيوب:
❌ تتغير عناوين URL بين الإصدارات
❌ يمكن أن يؤدي إلى ازدواجية الكود

GET /api/users?version=1
GET /api/users?version=2

المزايا:
✅ عنوان URL الأساسي يبقى كما هو
✅ سهل الافتراض إلى أحدث إصدار

العيوب:
❌ أقل وضوحاً
❌ يمكن نسيانه في الطلبات
❌ أصعب للتخزين المؤقت

GET /api/users
X-API-Version: 1

أو

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

المزايا:
✅ عناوين URL نظيفة
✅ يتبع مبادئ REST (التفاوض على المحتوى)

العيوب:
❌ غير مرئي في عناوين URL
❌ أصعب للاختبار (حاجة لتعيين الرؤوس)
❌ أكثر تعقيداً للتنفيذ

GET https://api-v1.example.com/users
GET https://api-v2.example.com/users

المزايا:
✅ عزل كامل بين الإصدارات
✅ سهل نشر الإصدارات بشكل منفصل

العيوب:
❌ يتطلب إدارة DNS
❌ تعقيد شهادة SSL
❌ مزيد من النفقات العامة للبنية التحتية

// تحذير الإهمال في رؤوس الاستجابة
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Dec 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"

{
  "data": [...],
  "meta": {
    "deprecation_warning": "سيتم إزالة نقطة النهاية هذه في 31 ديسمبر 2026. قم بالترحيل إلى v2."
  }
}

// فلتر واحد
GET /api/users?status=active

// فلاتر متعددة
GET /api/users?status=active&role=admin

// فلاتر النطاق
GET /api/products?price_min=10&price_max=100
GET /api/posts?created_after=2026-01-01

// مطابقة جزئية
GET /api/users?name_contains=أحمد
GET /api/products?sku_starts_with=ABC

// قيم متعددة (مفصولة بفواصل أو معامل متكرر)
GET /api/users?roles=admin,editor
GET /api/users?role=admin&role=editor

// فرز بسيط
GET /api/users?sort=name

// ترتيب تنازلي (بادئة بعلامة ناقص)
GET /api/users?sort=-created_at

// حقول فرز متعددة
GET /api/users?sort=role,-created_at

// بناء جملة بديل
GET /api/users?sort_by=name&order=asc

GET /api/users?page=1&limit=20
GET /api/users?offset=0&limit=20

الاستجابة:
{
  "data": [...],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total": 150,
    "total_pages": 8,
    "links": {
      "first": "/api/users?page=1",
      "prev": null,
      "next": "/api/users?page=2",
      "last": "/api/users?page=8"
    }
  }
}

GET /api/users?cursor=abc123&limit=20

الاستجابة:
{
  "data": [...],
  "pagination": {
    "next_cursor": "xyz789",
    "prev_cursor": "abc123",
    "has_more": true
  }
}

المزايا:
✅ نتائج متسقة (لا تكرارات/تخطيات)
✅ أداء أفضل على مجموعات البيانات الكبيرة
✅ يعمل بشكل جيد مع البيانات في الوقت الفعلي

// تحديد حقول محددة
GET /api/users?fields=id,name,email

// استبعاد الحقول
GET /api/users?fields=-password,-ssn

// الحقول المتداخلة
GET /api/users?fields=id,name,profile.avatar

// الاستجابة الافتراضية (بدون توسيع)
GET /api/posts/123
{
  "id": 123,
  "title": "منشوري",
  "author_id": 456
}

// العلاقات الموسعة
GET /api/posts/123?expand=author,comments
{
  "id": 123,
  "title": "منشوري",
  "author": {
    "id": 456,
    "name": "أحمد محمد"
  },
  "comments": [
    {"id": 1, "text": "منشور رائع!"}
  ]
}

// هيكل استجابة متسق
{
  "data": {...},           // بيانات المورد الفعلية
  "meta": {...},           // البيانات الوصفية (الترقيم، العدادات)
  "links": {...}           // روابط الوسائط الفائقة
}

// هيكل خطأ متسق
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "فشل التحقق",
    "details": [
      {
        "field": "email",
        "message": "البريد الإلكتروني مطلوب"
      }
    ]
  }
}

GET /repos/{owner}/{repo}
GET /repos/{owner}/{repo}/issues
GET /repos/{owner}/{repo}/issues/{number}
GET /repos/{owner}/{repo}/pulls
GET /user/repos?sort=updated&direction=desc

الميزات:
✅ هيكل هرمي واضح
✅ إصدار مسار URL (/v3/)
✅ تصفية شاملة
✅ ترقيم المؤشر للمجموعات الكبيرة

GET /v1/customers
POST /v1/customers
GET /v1/customers/{id}
GET /v1/customers/{id}/subscriptions
GET /v1/charges?limit=10

الميزات:
✅ عناوين URL بسيطة وقابلة للتنبؤ
✅ إصدار بادئة (/v1/)
✅ تسمية معامل متسقة
✅ موارد قابلة للتوسيع

GET /2/tweets/{id}
GET /2/users/{id}/tweets
GET /2/tweets/search/recent?query=api

الميزات:
✅ إصدار في المسار (/2/)
✅ تصميم يركز على الموارد
✅ بحث قائم على الاستعلام
✅ رؤوس حد المعدل