ما هو RFC 9457؟ وكيف يجب أن تُرجع واجهات برمجة التطبيقات الأخطاء؟

ملخص سريع

RFC 9457 (تفاصيل المشكلة لواجهات برمجة تطبيقات HTTP) هو التنسيق القياسي لاستجابات خطأ واجهة برمجة التطبيقات (API). إنه يستبدل تنسيقات الأخطاء المخصصة بهيكل متسق: النوع، العنوان، الحالة، التفاصيل، والمثال. ينفذ Modern PetstoreAPI معيار RFC 9457 عبر جميع استجابات الأخطاء مع تفاوض المحتوى المناسب وتفاصيل التحقق.

مقدمة

واجهة برمجة التطبيقات الخاصة بك تُرجع خطأ. كيف تبدو الاستجابة؟ إذا كنت مثل معظم واجهات برمجة التطبيقات، فقد اخترعت التنسيق الخاص بك:

{"error": "Invalid email"}
{"message": "Not found", "code": 404}
{"success": false, "errors": ["Email required"]}

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

RFC 9457 يحل هذه المشكلة. إنه معيار من IETF يحدد كيفية إرجاع واجهات برمجة التطبيقات للأخطاء. بدلاً من اختراع التنسيق الخاص بك، فإنك تستخدم معيارًا مثبتًا يفهمه العملاء بالفعل.

استخدم Swagger Petstore القديم تنسيقات أخطاء مخصصة بدون أي اتساق. Modern PetstoreAPI يطبق RFC 9457 عبر جميع استجابات الأخطاء، مما يوفر تفاصيل خطأ منظمة وقابلة للقراءة آليًا.

في هذا الدليل، ستتعلم ما هو RFC 9457، وكيفية تنفيذه بشكل صحيح، وكيف يستخدمه Modern PetstoreAPI لجميع استجابات الأخطاء.

مشكلة خطأ واجهة برمجة التطبيقات

قبل RFC 9457، اخترعت كل واجهة برمجة تطبيقات تنسيق الخطأ الخاص بها.

الاختلافات الشائعة في تنسيق الأخطاء

التنسيق 1: رسالة بسيطة

{"error": "User not found"}

التنسيق 2: الرمز والرسالة

{"code": "USER_NOT_FOUND", "message": "User not found"}

التنسيق 3: هيكل متداخل

{
  "success": false,
  "error": {
    "type": "NotFound",
    "message": "User not found"
  }
}

التنسيق 4: مصفوفة من الأخطاء

{
  "errors": [
    {"field": "email", "message": "Invalid email"}
  ]
}

مشاكل التنسيقات المخصصة

1. عدم الاتساق: يحتاج العملاء إلى تحليل مخصص لكل واجهة برمجة تطبيقات.

2. معلومات مفقودة: بعض التنسيقات تفتقر إلى رموز الأخطاء، وبعضها يفتقر إلى التفاصيل، وبعضها يفتقر إلى كليهما.

3. لا يوجد هيكل قابل للقراءة آليًا: من الصعب التعامل مع الأخطاء برمجيًا.

4. ضعف التدويل: رسائل الخطأ مكتوبة باللغة الإنجليزية بشكل ثابت.

5. لا يوجد معيار لأخطاء التحقق من الصحة: كل واجهة برمجة تطبيقات تتعامل مع أخطاء على مستوى الحقول بشكل مختلف.

ما هو RFC 9457؟

RFC 9457 (تم نشره في يوليو 2023) يحدد "تفاصيل المشكلة لواجهات برمجة تطبيقات HTTP". إنه معيار IETF يحدد كيفية تنظيم واجهات برمجة التطبيقات لاستجابات الأخطاء.

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

نوع وسائط قياسي: application/problem+json (أو application/problem+xml)

هيكل متسق: تتبع جميع الأخطاء نفس التنسيق

قابل للقراءة آليًا: يمكن للعملاء تحليل الأخطاء برمجيًا

قابل للتوسيع: يمكنك إضافة حقول مخصصة مع الحفاظ على التوافق

متوافق مع HTTP: يتكامل مع رموز حالة HTTP

RFC 9457 مقابل الأخطاء المخصصة

خطأ مخصص:

{"error": "Email is required"}

خطأ RFC 9457:

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request contains invalid data",
  "instance": "/pets",
  "errors": [
    {
      "field": "email",
      "message": "Email is required"
    }
  ]
}

يوفر إصدار RFC 9457 ما يلي:

• عنوان URL لنوع الخطأ للوثائق
• عنوان سهل القراءة
• رمز حالة HTTP
• شرح مفصل
• مسار الطلب الذي تسبب في الخطأ
• تفاصيل التحقق من صحة الحقول

شرح هيكل RFC 9457

يحدد RFC 9457 خمسة حقول قياسية ويسمح بالتوسعات المخصصة.

الحقول القياسية

1. النوع (سلسلة، مطلوب)

مرجع URI يحدد نوع الخطأ. يجب أن يشير إلى وثائق سهلة القراءة.

"type": "https://petstoreapi.com/errors/validation-error"

إذا تم حذفه، يكون الافتراضي about:blank.

2. العنوان (سلسلة، مطلوب)

ملخص قصير وسهل القراءة لنوع الخطأ. يجب ألا يتغير بين الحدوث.

"title": "Validation Error"

3. الحالة (رقم، مطلوب)

رمز حالة HTTP. مدرج للراحة حتى لا يحتاج العملاء إلى تحليل الرؤوس.

"status": 400

4. التفاصيل (سلسلة، اختياري)

شرح سهل القراءة خاص بهذا الحدوث للخطأ.

"detail": "The email field must be a valid email address"

5. المثال (سلسلة، اختياري)

مرجع URI يحدد الحدوث المحدد للخطأ. غالبًا ما يكون مسار الطلب.

"instance": "/pets/019b4132-70aa-764f-b315-e2803d882a24"

التوسعات المخصصة

يمكنك إضافة حقول مخصصة لسياق إضافي:

{
  "type": "https://petstoreapi.com/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded the rate limit of 100 requests per minute",
  "instance": "/pets",
  "retryAfter": 42,
  "limit": 100,
  "remaining": 0,
  "resetAt": "2026-03-13T10:30:00Z"
}

كيف ينفذ Modern PetstoreAPI معيار RFC 9457

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

مثال 1: المورد غير موجود

GET /pets/invalid-id
404 Not Found
Content-Type: application/problem+json

{
  "type": "https://docs.petstoreapi.com/errors/not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "The requested pet does not exist",
  "instance": "/pets/invalid-id"
}

مثال 2: خطأ المصادقة

GET /pets
401 Unauthorized
Content-Type: application/problem+json

{
  "type": "https://docs.petstoreapi.com/errors/unauthorized",
  "title": "Authentication Required",
  "status": 401,
  "detail": "Valid authentication credentials are required to access this resource",
  "instance": "/pets"
}

مثال 3: تجاوز حد المعدل

GET /pets
429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 60

{
  "type": "https://docs.petstoreapi.com/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded the rate limit of 100 requests per minute",
  "instance": "/pets",
  "limit": 100,
  "remaining": 0,
  "resetAt": "2026-03-13T10:31:00Z"
}

انظر وثائق معالجة الأخطاء في Modern PetstoreAPI لجميع أنواع الأخطاء.

أخطاء التحقق من الصحة مع RFC 9457

تحتاج أخطاء التحقق من الصحة إلى تفاصيل على مستوى الحقول. يسمح RFC 9457 بالتوسعات المخصصة لذلك.

تنسيق التحقق من الصحة في Modern PetstoreAPI

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

{
  "type": "https://docs.petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request contains 2 validation errors",
  "instance": "/pets",
  "errors": [
    {
      "field": "name",
      "message": "Name is required",
      "code": "REQUIRED_FIELD"
    },
    {
      "field": "species",
      "message": "Species must be one of: DOG, CAT, BIRD, FISH, REPTILE, OTHER",
      "code": "INVALID_ENUM_VALUE",
      "rejectedValue": "DRAGON"
    }
  ]
}

النقاط الرئيسية

مصفوفة الأخطاء (errors array): تحتوي على تفاصيل التحقق من الصحة على مستوى الحقول

الحقل (field): مسار JSON للحقل غير الصالح

الرسالة (message): رسالة خطأ سهلة القراءة

الرمز (code): رمز خطأ قابل للقراءة آليًا

القيمة المرفوضة (rejectedValue): القيمة التي تم رفضها (اختياري)

يسمح هذا التنسيق للعملاء بما يلي:

• عرض الأخطاء على مستوى الحقول في النماذج
• تمييز الحقول غير الصالحة
• تقديم رسائل خطأ محددة
• معالجة الأخطاء برمجيًا

اختبار استجابات الأخطاء باستخدام Apidog

Apidog يساعدك على اختبار توافق RFC 9457.

حالة اختبار: خطأ التحقق من الصحة

// Apidog test script
pm.test("Returns RFC 9457 error format", () => {
  const response = pm.response.json();

  // Check required fields
  pm.expect(response).to.have.property("type");
  pm.expect(response).to.have.property("title");
  pm.expect(response).to.have.property("status");

  // Check status matches HTTP status
  pm.expect(response.status).to.equal(pm.response.code);

  // Check content type
  pm.expect(pm.response.headers.get("Content-Type"))
    .to.include("application/problem+json");
});

pm.test("Validation errors include field details", () => {
  const response = pm.response.json();

  pm.expect(response).to.have.property("errors");
  pm.expect(response.errors).to.be.an("array");

  response.errors.forEach(error => {
    pm.expect(error).to.have.property("field");
    pm.expect(error).to.have.property("message");
  });
});

حالة اختبار: عناوين URL لنوع الخطأ

pm.test("Error type URL is accessible", async () => {
  const response = pm.response.json();
  const typeUrl = response.type;

  // Verify type URL returns documentation
  const docResponse = await pm.sendRequest(typeUrl);
  pm.expect(docResponse.code).to.equal(200);
});

الترحيل من تنسيقات الأخطاء المخصصة

إذا كنت تستخدم تنسيقات أخطاء مخصصة، فإليك كيفية الترحيل إلى RFC 9457.

الخطوة 1: إضافة رأس Content-Type

ابدأ بإرجاع application/problem+json:

Content-Type: application/problem+json

الخطوة 2: ربط الحقول الموجودة

اربط التنسيق المخصص الخاص بك بـ RFC 9457:

قبل:

{
  "error": "USER_NOT_FOUND",
  "message": "User not found"
}

بعد:

{
  "type": "https://api.example.com/errors/user-not-found",
  "title": "User Not Found",
  "status": 404,
  "detail": "User not found"
}

الخطوة 3: دعم كلا التنسيقين (فترة انتقالية)

استخدم تفاوض المحتوى لدعم كلا التنسيقين:

Accept: application/json ← إرجاع التنسيق المخصص
Accept: application/problem+json ← إرجاع تنسيق RFC 9457

الخطوة 4: إهمال التنسيق المخصص

بعد ترحيل العملاء، قم بإهمال التنسيق المخصص وإرجاع RFC 9457 بشكل افتراضي.

الخاتمة

يوفر RFC 9457 تنسيقًا قياسيًا لاستجابات خطأ واجهة برمجة التطبيقات. إنه يستبدل تنسيقات الأخطاء المخصصة بهيكل متسق وقابل للقراءة آليًا يمكن للعملاء تحليله برمجيًا.

Modern PetstoreAPI ينفذ RFC 9457 عبر جميع استجابات الأخطاء، مما يوضح كيفية تنظيم الأخطاء بشكل صحيح مع تفاصيل التحقق من الصحة المناسبة، وعناوين URL لنوع الخطأ، ورموز حالة HTTP.

استخدم Apidog لاختبار توافق RFC 9457، والتحقق من هياكل الأخطاء، والتأكد من أن واجهة برمجة التطبيقات الخاصة بك تُرجع استجابات أخطاء مناسبة.

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

هل RFC 9457 مطلوب لواجهات برمجة تطبيقات REST؟

لا، ولكنه المعيار الموصى به. استخدام RFC 9457 يجعل واجهة برمجة التطبيقات الخاصة بك أكثر اتساقًا وأسهل على العملاء للاندماج معها.

هل يمكنني استخدام RFC 9457 مع XML؟

نعم، يحدد RFC 9457 كلا من تنسيقات JSON (application/problem+json) و XML (application/problem+xml).

هل يجب علي دائمًا تضمين جميع الحقول القياسية الخمسة؟

type و title و status مطلوبة. أما detail و instance فهي اختيارية ولكن يوصى بها للحصول على سياق أفضل للخطأ.

هل يمكنني إضافة حقول مخصصة لاستجابات RFC 9457؟

نعم، RFC 9457 قابل للتوسيع. يمكنك إضافة حقول مخصصة مثل errors، retryAfter، أو traceId للحصول على سياق إضافي.

كيف أتعامل مع أخطاء التحقق من الصحة باستخدام RFC 9457؟

أضف مصفوفة errors مخصصة تحتوي على تفاصيل على مستوى الحقول. يوضح Modern PetstoreAPI هذا النمط في استجابات أخطاء التحقق من الصحة.

ماذا يجب أن يشير إليه عنوان URL لنوع الخطأ؟

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

هل أحتاج إلى تغيير رموز حالة HTTP عند استخدام RFC 9457؟

لا، يعمل RFC 9457 مع رموز حالة HTTP القياسية. يجب أن يتطابق حقل status في الاستجابة مع رمز حالة HTTP.

كيف أختبر توافق RFC 9457؟

استخدم Apidog للتحقق من بنية استجابة الخطأ، والتحقق من الحقول المطلوبة، والتأكد من تطابق أنواع المحتوى مع مواصفات RFC 9457.