التعمق في أساليب HTTP ورموز الحالة

// الحصول على جميع المستخدمين
GET /api/users
الاستجابة: 200 OK
[
  {"id": 1, "name": "أحمد"},
  {"id": 2, "name": "محمد"}
]

// الحصول على مستخدم واحد
GET /api/users/123
الاستجابة: 200 OK
{"id": 123, "name": "أحمد", "email": "ahmed@example.com"}

// الحصول مع معاملات الاستعلام (التصفية، الفرز، الترقيم)
GET /api/users?role=admin&sort=name&page=1&limit=20
الاستجابة: 200 OK
{
  "data": [...],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_items": 100
  }
}

// الحصول على الموارد المتداخلة
GET /api/users/123/posts
الاستجابة: 200 OK
[
  {"id": 1, "title": "منشوري الأول"},
  {"id": 2, "title": "منشور آخر"}
]

POST /api/users
Content-Type: application/json

{
  "name": "سارة",
  "email": "sara@example.com",
  "role": "user"
}

الاستجابة: 201 Created
Location: /api/users/456
{
  "id": 456,
  "name": "سارة",
  "email": "sara@example.com",
  "role": "user",
  "created_at": "2026-02-14T10:30:00Z"
}

// البحث بمعايير معقدة (معقدة جداً لمعاملات استعلام GET)
POST /api/users/search
{
  "filters": {
    "age_range": [18, 65],
    "countries": ["US", "UK", "CA"],
    "interests": ["tech", "sports"]
  }
}

// معالجة إجراء
POST /api/orders/123/ship
{
  "tracking_number": "ABC123",
  "carrier": "FedEx"
}

// عمليات دفعية
POST /api/users/batch-create
{
  "users": [
    {"name": "User1", "email": "user1@example.com"},
    {"name": "User2", "email": "user2@example.com"}
  ]
}

PUT /api/users/123
Content-Type: application/json

{
  "name": "أحمد محدث",
  "email": "ahmed.new@example.com",
  "role": "admin",
  "bio": "مطور برمجيات"
}

الاستجابة: 200 OK
{
  "id": 123,
  "name": "أحمد محدث",
  "email": "ahmed.new@example.com",
  "role": "admin",
  "bio": "مطور برمجيات",
  "updated_at": "2026-02-14T11:00:00Z"
}

PATCH /api/users/123
Content-Type: application/json

{
  "email": "ahmed.newest@example.com"
}

الاستجابة: 200 OK
{
  "id": 123,
  "name": "أحمد محدث",  // لم يتغير
  "email": "ahmed.newest@example.com",  // محدث
  "role": "admin",  // لم يتغير
  "bio": "مطور برمجيات",  // لم يتغير
  "updated_at": "2026-02-14T11:15:00Z"
}

// حذف مورد واحد
DELETE /api/users/123

الاستجابة: 204 No Content
// جسم فارغ

// أو مع بيانات تأكيد
الاستجابة: 200 OK
{
  "message": "تم حذف المستخدم بنجاح",
  "deleted_at": "2026-02-14T11:30:00Z"
}

// حذف ناعم (وضع علامة كمحذوف، عدم الإزالة)
DELETE /api/users/123
الاستجابة: 200 OK
{
  "id": 123,
  "deleted": true,
  "deleted_at": "2026-02-14T11:30:00Z"
}

// حذف مورد متداخل
DELETE /api/users/123/posts/456
الاستجابة: 204 No Content

HEAD /api/users/123

الاستجابة: 200 OK
Content-Type: application/json
Content-Length: 256
Last-Modified: Wed, 14 Feb 2026 11:00:00 GMT
ETag: "abc123"
// لا يوجد جسم مُعاد

// حالات الاستخدام:
// - التحقق من وجود المورد (200 مقابل 404)
// - الحصول على حجم المورد قبل التنزيل
// - التحقق مما إذا تم تعديل المورد (ETag، Last-Modified)
// - التحقق من المصادقة دون تنزيل البيانات

OPTIONS /api/users/123

الاستجابة: 200 OK
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Access-Control-Allow-Methods: GET, PUT, PATCH, DELETE
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Headers: Content-Type, Authorization

// مثال CORS preflight
OPTIONS /api/users
Origin: https://frontend.example.com

الاستجابة: 200 OK
Access-Control-Allow-Origin: https://frontend.example.com
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: Content-Type
Access-Control-Max-Age: 86400

// 200 OK - نجاح قياسي
GET /api/users/123
الاستجابة: 200 OK
{"id": 123, "name": "أحمد"}

// 201 Created - مورد جديد
POST /api/users
الاستجابة: 201 Created
Location: /api/users/456
{"id": 456, "name": "محمد"}

// 202 Accepted - معالجة غير متزامنة
POST /api/reports/generate
الاستجابة: 202 Accepted
{"job_id": "abc123", "status": "processing"}

// 204 No Content - نجاح، لا بيانات
DELETE /api/users/123
الاستجابة: 204 No Content

// 400 Bad Request - JSON مشوه
POST /api/users
{name: "محمد"}  // علامات اقتباس مفقودة حول المفتاح

الاستجابة: 400 Bad Request
{
  "error": "بناء جملة JSON غير صالح"
}

// 401 Unauthorized - لا مصادقة
GET /api/users/123

الاستجابة: 401 Unauthorized
{
  "error": "المصادقة مطلوبة",
  "message": "يرجى تقديم رمز وصول صالح"
}

// 403 Forbidden - أذونات غير كافية
DELETE /api/users/456

الاستجابة: 403 Forbidden
{
  "error": "أذونات غير كافية",
  "message": "ليس لديك إذن لحذف المستخدمين"
}

// 404 Not Found - المورد غير موجود
GET /api/users/99999

الاستجابة: 404 Not Found
{
  "error": "المستخدم غير موجود",
  "message": "لا يوجد مستخدم بالمعرف 99999"
}

// 409 Conflict - مورد مكرر
POST /api/users
{"email": "existing@example.com"}

الاستجابة: 409 Conflict
{
  "error": "البريد الإلكتروني موجود بالفعل",
  "message": "يوجد بالفعل مستخدم بهذا البريد الإلكتروني"
}

// 422 Unprocessable Entity - فشل التحقق
POST /api/users
{"name": "أ", "email": "invalid-email"}

الاستجابة: 422 Unprocessable Entity
{
  "error": "فشل التحقق",
  "errors": {
    "name": ["يجب أن يكون الاسم 3 أحرف على الأقل"],
    "email": ["يجب أن يكون البريد الإلكتروني عنوان بريد إلكتروني صالح"]
  }
}

// 429 Too Many Requests - حد المعدل
GET /api/users

الاستجابة: 429 Too Many Requests
Retry-After: 60
{
  "error": "تم تجاوز حد المعدل",
  "message": "حاول مرة أخرى في 60 ثانية"
}