مولّد فهرس API
أدرج واجهات API العامة مرة واحدة واحصل على مجموعة روابط JSON التي يتطلبها RFC 9727 في المسار /.well-known/api-catalog، مع كتلة nginx لتقديمها بنوع الوسائط الصحيح.
{
"linkset": [
{
"anchor": "https://api.example.com/v1",
"service-desc": [
{
"href": "https://api.example.com/v1/openapi.json",
"type": "application/openapi+json"
}
],
"service-doc": [
{
"href": "https://example.com/docs/api",
"type": "text/html"
}
],
"status": [
{
"href": "https://status.example.com"
}
]
}
]
}
location = /.well-known/api-catalog {
default_type application/linkset+json;
add_header Link '</.well-known/api-catalog>; rel="api-catalog"';
try_files /.well-known/api-catalog =404;
}
ارفع الملف إلى /.well-known/api-catalog وقدّمه بنوع الوسائط application/linkset+json. تضبط كتلة nginx هذا النوع وتضيف ترويسة Link بالقيمة rel="api-catalog"، التي يتوقعها RFC 9727 في طلبات HEAD.
لماذا تنشر فهرس API؟
على الوكيل الذي يريد استدعاء API أن يعثر عليها أولًا. يوفّر RFC 9727، المنشور في يونيو 2025، نقطة بداية ثابتة لهذا البحث: عنوان URL المعروف /.well-known/api-catalog، بالإضافة إلى علاقة الرابط api-catalog التي يمكن لأي صفحة استخدامها للإشارة إليه.
الفهرس عبارة عن مجموعة روابط بصيغة JSON. يستند كل إدخال إلى عنوان URL الأساسي لـ API، ويرتبط بوصفها القابل للقراءة آليًا (service-desc، وعادةً ما يكون ملف OpenAPI)، ووثائقها الموجّهة للبشر (service-doc)، وصفحة حالتها. يقرأ العميل ملفًا صغيرًا واحدًا بدلًا من الزحف إلى صفحات التوثيق.
ينص RFC على أن الاستجابة يجب أن تستخدم application/linkset+json، وينبغي أن تتضمن المَعلمة profile بالقيمة https://www.rfc-editor.org/info/rfc9727. لا تتوفر لدينا بعد بيانات عن الوكلاء الذين يطلبون هذا الملف، لكن نشره لا يتطلب سوى ملف ثابت واحد.
أسئلة عن api-catalog
ما هو /.well-known/api-catalog؟
هو الموقع الذي يحدده RFC 9727 لقائمة قابلة للقراءة آليًا بواجهات API التابعة لمؤسسة ما. الملف عبارة عن مجموعة روابط بصيغة JSON تربط كل API بوصفها ووثائقها وصفحة حالتها. يمكن للعملاء العثور عليه مباشرةً في ذلك الموقع أو عبر علاقة الرابط api-catalog.
ما نوع Content-Type المطلوب لـ api-catalog؟
ينص RFC 9727 على وجوب استخدام application/linkset+json، وعلى أن تتضمن الاستجابة مَعلمة profile بالقيمة https://www.rfc-editor.org/info/rfc9727. تضبط كتلة nginx في هذه الصفحة نوع الوسائط وترويسة Link؛ أضف مَعلمة profile بنفسك إذا كان إعداد الخادم يتيح ذلك.
هل أحتاج إلى ملف OpenAPI لنشر فهرس؟
لا. في هذا المولّد، لا يحتاج كل إدخال إلا إلى عنوان URL الأساسي لـ API، أما روابط الوصف والتوثيق والحالة فهي اختيارية. يتيح وصف OpenAPI للعميل معرفة نقاط النهاية من دون قراءة نصوص توضيحية، لذا أضِفه إن كان متوفرًا.
ما الفرق بين api-catalog وllms.txt؟
api-catalog معيار RFC من IETF يسرد واجهات API على هيئة روابط JSON للبرامج التي تستدعيها. أما llms.txt فهو مقترح لفهرس صفحات بصيغة Markdown، موجّه إلى نماذج اللغة التي تقرأ الوثائق. لا يتداخل الغرضان، لذا يمكنك نشر كليهما.