انتقل إلى المحتوى

فهرس الواجهات البرمجية (API catalog) لا يصلح

api-catalog-invalidبسيط
في هذه الصفحة

لماذا يهم

  • يحدد RFC 9727 عنواناً ثابتاً، ‎/.well-known/api-catalog‎، يجد فيه البرنامج أو الوكيل قائمة الواجهات البرمجية للموقع، مع وصف كل واجهة (OpenAPI) وتوثيقها.
  • الفهرس المكسور أسوأ من غيابه: الوكيل يجد العنوان ويخفق في قراءته، فلا يصل إلى الواجهات.
  • غياب الفهرس ليس مخالفة: كثير من المواقع لا تقدّم واجهات برمجية.

كيف تُصلح

قدّم الملف بالنوع application/linkset+json، وفيه مدخل لكل واجهة:

json
{
  "linkset": [
    {
      "anchor": "https://api.example.com/v1",
      "service-desc": [{ "href": "https://api.example.com/v1/openapi.json", "type": "application/json" }],
      "service-doc": [{ "href": "https://example.com/docs/api" }]
    }
  ]
}

كيف نكشف

في أداة جاهزية الوكلاء وحدها، نطلب ‎/.well-known/api-catalog‎ من أصل الصفحة باسم ArablyzerBot، حيث يسمح robots.txt، بالترويسة Accept: application/linkset+json, application/json، ونطلب بها أيضاً عنواناً لا يوجد في أي موقع. والرد 4xx، أو صفحة HTML في مكانه، أو موقع يرد على ذلك العنوان المعدوم بحالة 2xx ولا يجتاز ملفه الفحص، يعني أن الموقع لا يقدّم فهرساً. ونقرأ الرد 2xx على أنه JSON، فنطلب linkset غير فارغة، وanchor لكل مدخل (RFC 9264)، والنوع الذي يطلبه RFC 9727.