ما هي رموز حالة HTTP التي يجب أن تستخدمها واجهات برمجة تطبيقات REST؟

خلاصة القول (TL;DR)

يجب أن تستخدم واجهات برمجة تطبيقات REST رموز حالة HTTP بشكل صحيح: 200 لطلبات GET الناجحة، 201 لطلبات POST الناجحة مع إنشاء مورد، 204 لطلبات DELETE الناجحة، 400 لأخطاء العميل، 401 لأخطاء المصادقة، 404 للمورد غير الموجود، و 500 لأخطاء الخادم. تطبق Modern PetstoreAPI جميع رموز حالة HTTP القياسية بالدلالات الصحيحة واستجابات الأخطاء وفقًا لمعيار RFC 9457.

مقدمة

تعيد واجهة برمجة التطبيقات الخاصة بك 200 OK لكل شيء. نجاح؟ 200 OK. خطأ في التحقق؟ 200 OK مع رسالة خطأ في نص الاستجابة. المورد غير موجود؟ 200 OK مع {"error": "not found"}. فشل المصادقة؟ لقد خمنت صحيحًا — 200 OK.

هذا خطأ. رموز حالة HTTP موجودة لسبب. إنها تخبر العملاء بما حدث دون الحاجة إلى تحليل نص الاستجابة. تعتمد ذاكرات التخزين المؤقت (Caches) والوكلاء (proxies) وأدوات المراقبة على رموز الحالة. عندما تعيد 200 للأخطاء، فإنك تكسر نظام HTTP البيئي بأكمله.

ارتكب Swagger Petstore القديم أخطاء في رموز الحالة: إرجاع 200 لطلبات POST التي يجب أن تعيد 201، استخدام 200 لعمليات DELETE التي يجب أن تعيد 204، وعدم وجود رموز أخطاء مهمة. يعالج Modern PetstoreAPI هذا من خلال تطبيق دلالات HTTP الصحيحة عبر جميع نقاط النهاية.

💡

إذا كنت تبني أو تختبر واجهات برمجة تطبيقات REST، فإن Apidog يساعدك على التحقق من استخدام رموز الحالة، واختبار سيناريوهات الأخطاء، وضمان أن واجهة برمجة التطبيقات الخاصة بك تتبع معايير HTTP. يمكنك تحديد رموز الحالة المتوقعة، وتشغيل الاختبارات التلقائية، واكتشاف الاستجابات غير الصحيحة قبل النشر.

زر

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

مشكلة رمز الحالة

تتعامل العديد من واجهات برمجة التطبيقات مع رموز الحالة كأمر ثانوي. النتيجة: دلالات HTTP معطلة وعملاء مرتبكون.

نمط "200 OK لكل شيء" المضاد

// Success
GET /users/123
200 OK
{"id": 123, "name": "John"}

// Error (but still 200!)
GET /users/999
200 OK
{"error": "User not found"}

// Validation error (still 200!)
POST /users
200 OK
{"error": "Email is required"}

المشكلات:

لا يمكن للعملاء التمييز بين النجاح والفشل دون تحليل نص الاستجابة
ذاكرات التخزين المؤقت HTTP تخزن استجابات الأخطاء مؤقتًا
أدوات المراقبة تبلغ عن إيجابيات كاذبة
منطق إعادة المحاولة لا يعمل بشكل صحيح

لماذا يحدث هذا

يعيد المطورون 200 لأن:

لا يعرفون رموز الحالة الأخرى
يعتقدون أن رموز الحالة اختيارية
يريدون تجنب "كسر" العملاء
يقلدون أمثلة سيئة (مثل Swagger Petstore القديم)

رموز حالة HTTP الأساسية لواجهات برمجة تطبيقات REST

لا تحتاج إلى جميع رموز حالة HTTP التي تزيد عن 60 رمزًا. ركز على هذه الرموز الأساسية.

مرجع سريع

النجاح (2xx):

200 OK - طلبات GET, PUT, PATCH ناجحة
201 Created - طلب POST ناجح مع إنشاء مورد
204 No Content - طلب DELETE, PUT ناجح بدون نص استجابة

أخطاء العميل (4xx):

400 Bad Request - تنسيق طلب غير صالح أو خطأ في التحقق
401 Unauthorized - مصادقة مفقودة أو غير صالحة
403 Forbidden - تم المصادقة عليه ولكنه غير مصرح له
404 Not Found - المورد غير موجود
409 Conflict - تعارض المورد (تكرار، عدم تطابق الإصدار)
422 Unprocessable Entity - تنسيق صالح ولكن أخطاء دلالية
429 Too Many Requests - تجاوز حد المعدل

أخطاء الخادم (5xx):

500 Internal Server Error - خطأ غير متوقع في الخادم
502 Bad Gateway - خطأ في الخدمة الأصلية
503 Service Unavailable - عدم توفر مؤقت للخدمة
504 Gateway Timeout - مهلة بوابة الخدمة الأصلية

رموز النجاح (2xx)

تشير رموز النجاح إلى أن الطلب قد نجح. تنقل الرموز المختلفة معاني مختلفة.

200 OK

يستخدم لـ: طلبات GET, PUT, PATCH الناجحة التي تعيد بيانات.

GET /pets/123
200 OK
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "CAT"
}

لا تستخدم لـ: طلبات POST التي تنشئ موارد (استخدم 201)، طلبات DELETE (استخدم 204).

201 Created

يستخدم لـ: طلبات POST الناجحة التي تنشئ موردًا جديدًا.

POST /pets
201 Created
Location: https://petstoreapi.com/pets/019b4132-70aa-764f-b315-e2803d882a24
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "CAT"
}

نقاط رئيسية:

قم بتضمين رأس Location مع عنوان URL للمورد الجديد
أعد المورد الذي تم إنشاؤه في نص الاستجابة
يعرف العملاء أنه تم إنشاء مورد، وليس فقط تحديثه

يعيد Modern PetstoreAPI الرمز 201 لجميع عمليات POST التي تنشئ موارد.

204 No Content

يستخدم لـ: طلبات DELETE, PUT, أو PATCH الناجحة بدون نص استجابة.

DELETE /pets/019b4132-70aa-764f-b315-e2803d882a24
204 No Content

نقاط رئيسية:

لا يوجد نص استجابة (يوفر النطاق الترددي)
يشير إلى النجاح
شائع لعمليات DELETE

رموز أخطاء العميل (4xx)

تشير رموز أخطاء العميل إلى أن العميل ارتكب خطأ. يجب عدم إعادة محاولة الطلب دون تعديل.

400 Bad Request

يستخدم لـ: الطلبات غير الصحيحة، JSON غير صالح، الحقول المطلوبة المفقودة.

POST /pets
400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "invalid-params": [
    {
      "name": "name",
      "reason": "Name is required"
    }
  ]
}

يستخدم Modern PetstoreAPI تنسيق RFC 9457 لجميع استجابات الأخطاء.

401 Unauthorized

يستخدم لـ: بيانات اعتماد المصادقة المفقودة أو غير الصالحة.

GET /pets
401 Unauthorized
WWW-Authenticate: Bearer realm="PetstoreAPI"

{
  "type": "https://petstoreapi.com/errors/authentication-required",
  "title": "Authentication Required",
  "status": 401,
  "detail": "Valid authentication credentials required"
}

نقاط رئيسية:

قم بتضمين رأس WWW-Authenticate
يجب أن يطلب العميل بيانات الاعتماد أو رمز التحديث
لا تخلط بينه وبين 403 (الترخيص)

403 Forbidden

يستخدم لـ: المستخدم الذي تم المصادقة عليه يفتقر إلى الإذن.

DELETE /pets/019b4132-70aa-764f-b315-e2803d882a24
403 Forbidden

{
  "type": "https://petstoreapi.com/errors/insufficient-permissions",
  "title": "Insufficient Permissions",
  "status": 403,
  "detail": "You don't have permission to delete this pet"
}

الفرق عن 401:

401: "من أنت؟" (المصادقة)
403: "أعرف من أنت، لكن لا يمكنك فعل ذلك" (الترخيص)

404 Not Found

يستخدم لـ: المورد غير موجود.

GET /pets/nonexistent-id
404 Not Found

{
  "type": "https://petstoreapi.com/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Pet not found"
}

لا تستخدم لـ: فشل الترخيص (استخدم 403)، أخطاء التحقق (استخدم 400).

409 Conflict

يستخدم لـ: تعارضات الموارد مثل التكرارات أو عدم تطابق الإصدارات.

POST /pets
409 Conflict

{
  "type": "https://petstoreapi.com/errors/duplicate-resource",
  "title": "Duplicate Resource",
  "status": 409,
  "detail": "A pet with this microchip ID already exists"
}

422 Unprocessable Entity

يستخدم لـ: تنسيق طلب صالح ولكن أخطاء دلالية.

POST /pets
422 Unprocessable Entity

{
  "type": "https://petstoreapi.com/errors/business-rule-violation",
  "title": "Business Rule Violation",
  "status": 422,
  "detail": "Cannot adopt more than 5 pets per household"
}

الفرق عن 400:

400: طلب غير صحيح (JSON غير صالح، أنواع خاطئة)
422: طلب جيد التكوين ولكنه ينتهك قواعد العمل

429 Too Many Requests

يستخدم لـ: تجاوز حد المعدل.

GET /pets
429 Too Many Requests
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 1678886400

{
  "type": "https://petstoreapi.com/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "Rate limit of 100 requests per hour exceeded"
}

يستخدم Modern PetstoreAPI رؤوس IETF لتحديد المعدل.

رموز أخطاء الخادم (5xx)

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

500 Internal Server Error

يستخدم لـ: أخطاء الخادم غير المتوقعة.

GET /pets
500 Internal Server Error

{
  "type": "https://petstoreapi.com/errors/internal-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred"
}

لا تقم بتضمين: تتبعات الأخطاء (Stack traces)، التفاصيل الداخلية، أخطاء قاعدة البيانات في بيئة الإنتاج.

503 Service Unavailable

يستخدم لـ: عدم توفر مؤقت (صيانة، تحميل زائد).

GET /pets
503 Service Unavailable
Retry-After: 3600

{
  "type": "https://petstoreapi.com/errors/service-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Service temporarily unavailable for maintenance"
}

قم بتضمين رأس Retry-After لإخبار العملاء بموعد إعادة المحاولة.

كيف يستخدم Modern PetstoreAPI رموز الحالة

يطبق Modern PetstoreAPI دلالات HTTP الصحيحة عبر جميع نقاط النهاية.

مثال: إدارة الحيوانات الأليفة

// قائمة الحيوانات الأليفة
GET /pets
200 OK

// إنشاء حيوان أليف
POST /pets
201 Created
Location: https://petstoreapi.com/pets/{id}

// الحصول على حيوان أليف
GET /pets/{id}
200 OK (تم العثور عليه) or 404 Not Found

// تحديث حيوان أليف
PUT /pets/{id}
200 OK (مع نص الاستجابة) or 204 No Content

// حذف حيوان أليف
DELETE /pets/{id}
204 No Content (نجاح) or 404 Not Found

استجابات الأخطاء

تستخدم جميع الأخطاء تنسيق RFC 9457:

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "instance": "/pets",
  "invalid-params": [
    {
      "name": "name",
      "reason": "Name must be between 1 and 100 characters"
    }
  ]
}

راجع وثائق معالجة الأخطاء في Modern PetstoreAPI للحصول على أمثلة كاملة.

اختبار رموز الحالة باستخدام Apidog

يساعدك Apidog على اختبار سلوك رموز الحالة عبر جميع السيناريوهات.

تحديد رموز الحالة المتوقعة

paths:
  /pets:
    post:
      responses:
        '201':
          description: Pet created // وصف: تم إنشاء الحيوان الأليف
        '400':
          description: Validation error // وصف: خطأ في التحقق
        '401':
          description: Authentication required // وصف: المصادقة مطلوبة
        '429':
          description: Rate limit exceeded // وصف: تجاوز حد المعدل

اختبار جميع السيناريوهات

أنشئ حالات اختبار لـ:

سيناريوهات النجاح (200, 201, 204)
أخطاء التحقق (400, 422)
المصادقة/الترخيص (401, 403)
غير موجود (404)
تحديد المعدل (429)
أخطاء الخادم (500, 503)

الاختبار الآلي

// نص اختبار Apidog
pm.test("يعيد 201 للإنشاء الناجح", () => {
  pm.response.to.have.status(201);
  pm.response.to.have.header("Location");
});

pm.test("يعيد 400 للحقول المطلوبة المفقودة", () => {
  pm.response.to.have.status(400);
  pm.expect(pm.response.json().type).to.include("validation-error");
});

أخطاء شائعة يجب تجنبها

الخطأ 1: استخدام 200 لطلب POST

// خطأ
POST /pets
200 OK

// صحيح
POST /pets
201 Created
Location: https://petstoreapi.com/pets/{id}

الخطأ 2: استخدام 200 لطلب DELETE

// خطأ
DELETE /pets/{id}
200 OK
{"message": "Deleted successfully"}

// صحيح
DELETE /pets/{id}
204 No Content

الخطأ 3: الخلط بين 401 و 403

// خطأ: المستخدم مصادق عليه ولكنه يفتقر إلى الإذن
401 Unauthorized

// صحيح
403 Forbidden

الخطأ 4: استخدام 500 لأخطاء العميل

// خطأ: خطأ في التحقق يعيد 500
POST /pets
500 Internal Server Error

// صحيح
POST /pets
400 Bad Request

الخاتمة

رموز حالة HTTP ليست اختيارية. إنها جزء من مواصفات HTTP وضرورية لبناء واجهات برمجة تطبيقات REST الصحيحة.

استخدم رموز الحالة الصحيحة:

200 لعمليات القراءة الناجحة
201 لعمليات الإنشاء الناجحة
204 لعمليات الحذف الناجحة
400 لأخطاء العميل
401 للمصادقة
404 للمورد غير الموجود
500 لأخطاء الخادم

يوضح Modern PetstoreAPI الاستخدام الصحيح لرموز الحالة عبر جميع نقاط النهاية. ادرس وثائق واجهة برمجة تطبيقات REST للاطلاع على التنفيذ الصحيح.

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

الأسئلة الشائعة

هل يجب أن أستخدم 200 أو 204 لعملية DELETE ناجحة؟

استخدم 204 No Content. يشير إلى النجاح بدون نص استجابة، مما يوفر النطاق الترددي. استخدم 200 فقط إذا كنت بحاجة إلى إرجاع معلومات حول المورد المحذوف.

ما الفرق بين 400 و 422؟

400 يعني أن الطلب غير صحيح (JSON غير صالح، أنواع خاطئة). 422 يعني أن الطلب جيد التكوين ولكنه ينتهك قواعد العمل.

متى يجب أن أستخدم 401 مقابل 403؟

401 يعني "صادق نفسك" (بيانات اعتماد مفقودة أو غير صالحة). 403 يعني "أنت مصادق عليه ولكن غير مصرح لك" (أذونات غير كافية).

هل يجب أن أعيد 404 أو 403 للموارد التي لا يستطيع المستخدمون الوصول إليها؟

أعد 403 إذا كان المورد موجودًا ولكن المستخدم يفتقر إلى الإذن. أعد 404 إذا كنت ترغب في إخفاء وجود المورد عن المستخدمين غير المصرح لهم.

كيف أختبر جميع سيناريوهات رموز الحالة؟

استخدم Apidog لإنشاء حالات اختبار للنجاح، أخطاء التحقق، فشل المصادقة، عدم العثور، وأخطاء الخادم. قم بتشغيل الاختبارات الآلية في CI/CD.

ما هو رمز الحالة لتحديد المعدل؟

استخدم 429 Too Many Requests مع رؤوس RateLimit-*. قم بتضمين Retry-After لإخبار العملاء بموعد إعادة المحاولة.

هل يجب أن أستخدم 500 لجميع أخطاء الخادم؟

استخدم 500 للأخطاء غير المتوقعة. استخدم 502 لأخطاء الخدمة الأصلية، 503 لعدم التوفر المؤقت، و 504 للمهلات.

كيف يتعامل Modern PetstoreAPI مع الأخطاء؟

تستخدم جميع الأخطاء تنسيق RFC 9457 مع رموز الحالة المناسبة. راجع وثائق معالجة الأخطاء للحصول على أمثلة.