استخدام JSON في REST APIs: أفضل الممارسات

JSON في REST APIs

JSON و REST APIs متطابقان تمامًا. صياغة JSON خفيفة الوزن ودعمها الأصلي للمصفوفات ودعمها الشامل لجميع اللغات يجعلها التنسيق الافتراضي لواجهات API الحديثة على الويب. لكن مجرد استخدام JSON في API الخاصة بك ليس كافيًا -- اتباع الاتفاقيات الراسخة وأفضل الممارسات يضمن أن تكون API الخاصة بك متسقة وبديهية وسهلة التكامل.

تنسيق الطلب والاستجابة

هيكل مغلف متسق

اعتمد مغلف JSON متسقًا لجميع استجابات API. هذا يجعل المعالجة من جانب العميل قابلة للتنبؤ ويبسط معالجة الأخطاء.

{
  "status": "success",
  "data": {
    "user": {
      "id": 123,
      "name": "Alice",
      "email": "alice@example.com"
    }
  },
  "meta": {
    "requestId": "req-a1b2c3d4",
    "timestamp": "2026-07-19T10:30:00Z"
  }
}

Snake Case مقابل Camel Case

اختر اصطلاح تسمية واحدًا والتزم به عبر API بالكامل:

• Camel Case (createdAt, firstName): شائع في أنظمة JavaScript/TypeScript البيئية
• Snake Case (created_at, first_name): شائع في أنظمة Python و Ruby و PHP البيئية

أيًا كان اختيارك، قم بتوثيقه بوضوح وفكر في استخدام طبقة تحويل إذا كانت لغة الخلفية الخاصة بك تستخدم اصطلاحًا مختلفًا.

رموز حالة HTTP مع JSON

تكمل رموز حالة HTTP المناسبة استجابات JSON الخاصة بك. استخدمها باستمرار:

| رمز الحالة | المعنى | متى تستخدم | |-------------|---------|-------------| | 200 OK | نجاح | نجاح GET, PUT, PATCH | | 201 Created | تم إنشاء المورد | نجاح POST | | 204 No Content | نجاح الحذف | نجاح DELETE (بدون جسم JSON) | | 400 Bad Request | صياغة JSON غير صالحة | جسم طلب مشوه | | 401 Unauthorized | المصادقة مطلوبة | رمز مفقود أو غير صالح | | 403 Forbidden | صلاحيات غير كافية | مصادقة صالحة لكن غير مسموح | | 404 Not Found | المورد غير موجود | معرف أو مسار غير صالح | | 422 Unprocessable Entity | فشل التحقق | أخطاء دلالية في JSON صالح | | 429 Too Many Requests | تم الوصول لحد المعدل | تجاوز العميل للحدود | | 500 Internal Server Error | فشل من جانب الخادم | أخطاء غير متوقعة |

تنسيق استجابة الخطأ القياسي

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body contains invalid fields",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "code": "INVALID_FORMAT"
      },
      {
        "field": "age",
        "message": "Must be a positive integer",
        "code": "OUT_OF_RANGE"
      }
    ]
  }
}

الموارد المتداخلة

تمثيل العلاقات

تحتاج REST APIs بشكل متكرر إلى تمثيل الموارد المرتبطة. إليك الأنماط الشائعة:

مضمن (تحميل فوري):

{
  "order": {
    "id": 5001,
    "total": 29.99,
    "customer": {
      "id": 123,
      "name": "Alice",
      "email": "alice@example.com"
    },
    "items": [
      {
        "productId": 42,
        "name": "Widget",
        "quantity": 2,
        "price": 14.99
      }
    ]
  }
}

بالمرجع (تحميل كسول) -- استخدم المعرفات ووفر نقاط نهاية منفصلة:

{
  "order": {
    "id": 5001,
    "total": 29.99,
    "customerId": 123,
    "itemIds": [101, 102]
  }
}

القاعدة العامة: قم بتضمين البيانات المرتبطة التي تكون مطلوبة دائمًا معًا. استخدم المرجع للبيانات التي يتم استرجاعها بشكل مشروط أو في وقت مختلف.

أنماط الترحيل

عند إرجاع قوائم الموارد، يكون الترحيل ضروريًا. استخدم تنسيق ترحيل متسق:

الترحيل القائم على الإزاحة

{
  "status": "success",
  "data": [
    { "id": 1, "name": "User 1" },
    { "id": 2, "name": "User 2" }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "totalItems": 156,
    "totalPages": 8,
    "links": {
      "first": "/api/users?page=1&perPage=20",
      "prev": null,
      "next": "/api/users?page=2&perPage=20",
      "last": "/api/users?page=8&perPage=20"
    }
  }
}

الترحيل القائم على المؤشر (موصى به لمجموعات البيانات الكبيرة)

{
  "status": "success",
  "data": [
    { "id": 100, "name": "User 100" },
    { "id": 101, "name": "User 101" }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6MTAxfQ==",
    "hasMore": true
  }
}

الترحيل القائم على المؤشر أكثر موثوقية للبيانات في الوقت الفعلي حيث يمكن أن تؤدي السجلات الجديدة إلى تغيير حدود الصفحات.

JSON في طلبات API

أجسام طلبات POST / PUT

اقبل JSON مع رأس Content-Type: application/json:

{
  "title": "New Blog Post",
  "content": "This is the content...",
  "tags": ["json", "rest-api"],
  "published": false
}

التحديثات الجزئية باستخدام PATCH

استخدم PATCH للتحديثات الجزئية. اقبل فقط الحقول التي يجب أن تتغير:

// PATCH /api/users/123
{
  "email": "newemail@example.com"
}

التصفية والفرز والبحث

استخدم معاملات الاستعلام لمعالجة البيانات، مع الحفاظ على جسم JSON نظيفًا:

GET /api/users?filter[role]=admin&sort=-createdAt&search=alice

{
  "status": "success",
  "data": [ /* filtered, sorted results */ ]
}

تحديد المعدل

قم بتضمين معلومات تحديد المعدل في رؤوس الاستجابة واختياريًا في جسم JSON:

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later."
  },
  "meta": {
    "rateLimit": {
      "limit": 100,
      "remaining": 0,
      "resetAt": "2026-07-19T11:00:00Z"
    }
  }
}

قائمة أفضل ممارسات JSON

• [ ] استخدم تسمية مفاتيح متسقة (camelCase أو snake_case في كل مكان)
• [ ] أعد رموز حالة HTTP المناسبة مع كل استجابة
• [ ] قم بتضمين تنسيق خطأ متسق مع رموز خطأ قابلة للقراءة آليًا
• [ ] قم بترحيل نقاط نهاية القوائم باستخدام كائن ترحيل موحد
• [ ] استخدم JSON Schema لتوثيق والتحقق من هياكل الطلب/الاستجابة
• [ ] عيّن Content-Type: application/json على جميع نقاط نهاية JSON
• [ ] قم بضغط استجابات JSON باستخدام gzip أو brotli في بيئة الإنتاج
• [ ] فرض حدود الحجم الأقصى للحمولة (مثل 1 ميجابايت افتراضيًا)
• [ ] استخدم HTTPS لتشفير بيانات JSON أثناء النقل
• [ ] قم بهيكلة تفاصيل الخطأ لمساعدة العملاء على التصحيح دون كشف التفاصيل الداخلية

التحقق من صحة JSON الخاص بـ API

قم بتشغيل استجابات API الخاصة بك من خلال مدقق JSON لاكتشاف أخطاء التنسيق قبل أن تصل إلى العملاء. استجابات JSON المتسقة والصالحة تجعل API الخاصة بك موثوقة وصديقة للمطورين. استخدم أداة منسق ومدقق JSON الخاصة بنا لاختبار حمولاتك أثناء التطوير.