کاوش api-catalog: استاندارد جدید کشف API
گروه کاری مهندسی اینترنت (IETF) استانداردی را تعریف کرده که ممکن است یکی از امیدوارکننده‌ترین استانداردها برای کشف API تا به امروز باشد. RFC 9727، که بیشتر با نام api-catalog شناخته می‌شود، نوید یک استاندارد باز برای کشف خودکار API را می‌دهد. اما این چیست، چگونه کار می‌کند و چرا جامعه گسترده‌تر API باید به آن اهمیت دهد؟
امروز، به این راه‌حل می‌پردازیم و جزئیات عملکرد آن را بررسی می‌کنیم. به برخی موارد استفاده جذاب نگاه می‌کنیم و تصور می‌کنیم که وضعیت کشف API در چند سال آینده چگونه خواهد بود.
api-catalog چیست؟
api-catalog یک استاندارد پیشنهادی است که به ناشران API اجازه می‌دهد یک کاتالوگ ماشین‌خوان از APIهای خود را منتشر کنند. این کاتالوگ اطلاعات حیاتی شامل نام‌ها، نسخه‌ها، endpointها و لینک به مستندات توصیفی را جمع‌آوری کرده و در یک کاتالوگ ذخیره می‌کند که سپس برای کشف استفاده می‌شود.
ایده ساده است: کشف API را با یک کاتالوگ متادیتای زمینه‌ای بهبود دهید، همانند کارت کاتالوگ در یک کتابخانه. در عمل، این استاندارد باید به این معنا باشد که یک کلاینت — چه انسانی و چه ماشینی — بتواند تمام APIها و متدهای موجود را از طریق یک endpoint کاتالوگ واحد کشف کند و پراکندگی مستندات پراکنده را کاهش دهد.
نحوه عملکرد
api-catalog با رسمی‌سازی چند مؤلفه اصلی کار می‌کند. در حالی که RFC کاملاً روشن می‌کند که برخی جنبه‌ها انعطاف‌پذیر هستند، به ویژه مسیر URI الزامی نیست طبق آنچه در RFC آمده، انتظار می‌رود کسانی که این استاندارد را اتخاذ می‌کنند، ساختارهای مؤلفه اصلی را رعایت کنند.
Well-Known URI
RFC 9727 مشخص می‌کند که api-catalog باید در یک URI قرار گیرد که با استاندارد تعیین‌شده توسط مشخصات Well-Known (تعریف‌شده در RFC 8615) همخوانی داشته باشد. در عمل، این باید چیزی شبیه به این باشد:
https://example.com/.well-known/api-catalogاینکه این چگونه حل می‌شود و به چه شکلی، به ناشر واگذار شده است. RFC موارد زیر را معتبر می‌داند، به شرطی که جریان نهایی به کاتالوگ مورد نظر برسد:
https://www.example.com/my_api_catalog.json می‌تواند مستقیماً درخواست شود یا از طریق درخواست به https://www.example.com/.well-known/api-catalog، که ناشر آن را به https://www.example.com/my_api_catalog حل می‌کند.این URI به عنوان نقطه ورود به کاتالوگ از طریق link relation عمل خواهد کرد.
Link Relation
بخش link relation دوباره به استاندارد پیشنهادی دیگر، یعنی RFC 8288، ارجاع می‌دهد. این فرمت به ناشران اجازه می‌دهد مکان کاتالوگ خود را تعریف کنند و حتی اگر کلاینت یا ایجنت از محل واقعی کاتالوگ آگاه نباشد، برخی متادیتای پایه ارائه دهند. مثال زیر از RFC یک فرمت نمونه است که به یک فایل .json کاتالوگ API اشاره می‌کند:
HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Location: /index.html
Link: </my_api_catalog.json>; rel=api-catalog
Content-Length: 356
<!DOCTYPE HTML>
<html>
<head>
<title>Welcome to Example Publisher</title>
</head>
<body>
<p>
<a href="my_api_catalog.json" rel="api-catalog">
Example Publisher's APIs
</a>
</p>
<p>(remainder of content)</p>
</body>
</html>کاتالوگ Linkset
حالا به بخش اصلی این پیشنهاد می‌رسیم — کاتالوگ لینک‌ست واقعی. فایل my_api_catalog.json می‌تواند چیزی شبیه به این باشد:
{
"linkset": [
{
"href": "https://api.example.com/v1/",
"rel": ["item"],
"title": "Core API",
"type": "application/json"
},
{
"href": "https://api.example.com/v1/openapi.yaml",
"rel": ["service-desc"],
"type": "application/vnd.oai.openapi+yaml"
},
{
"href": "https://docs.example.com/api/v1/getting-started.html",
"rel": ["service-doc"],
"type": "text/html"
},
{
"href": "https://api.example.com/payments/v2/",
"rel": ["item"],
"title": "Payments API",
"type": "application/json"
},
{
"href": "https://api.example.com/payments/v2/openapi.json",
"rel": ["service-desc"],
"type": "application/vnd.oai.openapi+json"
},
{
"href": "https://docs.example.com/payments/v2/index.html",
"rel": ["service-doc"],
"type": "text/html"
}
]
}همانطور که مشاهده می‌کنید، در سراسر این کاتالوگ چند قطعه متادیتا تعریف می‌کنیم. ابتدا href که API در آن قرار دارد را مشخص می‌کنیم، سپس رابطه لینک را بیان می‌کنیم. این به ما اجازه می‌دهد نوع عنصر را تعریف کنیم — برای مثال، مشخص کنیم چیزی یک item است یا یک service description.
توجه داشته باشید که این با رابطه لینک که قبلاً اشاره کردیم متفاوت است. آن رابطه لینک فقط به مکان api-catalog مربوط می‌شود، در حالی که رابطه لینک لینک‌ست نوع رابطه عنصر با API را مشخص می‌کند. این به ابزارهای توسعه‌دهنده، ایجنت‌ها یا حتی مدل‌های هوش مصنوعی اجازه می‌دهد یک لیست ساخت‌یافته از تمام APIهای موجود همراه با لینک‌های مستندات آن‌ها را دریافت کنند.
چرا این RFC و چرا حالا؟
APIها بسیار فراگیرتر از ده سال پیش هستند. با وجود خدمات بسیار زیاد، که اغلب از چندین سرویس کوچک‌تر و API تشکیل شده‌اند، نیاز به قابل کشف کردن APIها فقط افزایش یافته است. چند دلیل کلیدی برای این موضوع وجود دارد.
اولاً، فرآیند کشف API در گذشته یک فرآیند بسیار دستی بود که به شدت به پورتال‌های توسعه‌دهنده، مستندات و مواد دیگر وابسته بود. برای ماشین‌ها، این همیشه تجربه‌ای نامناسب بود، اما حالا که ایجنت‌های هوش مصنوعی روز به روز رایج‌تر شده‌اند، آنچه قبلاً یک نکته جانبی بود، حالا یک مانع بزرگ است. با ارائه یک روش استاندارد برای کشف ماشین‌خوان، api-catalog قصد دارد این مشکل را حل کند و سیستم‌های ایجنتیک را بهتر کند.
دوماً، حاکمیت و امنیت روز به روز مهم‌تر می‌شوند. نیاز به درک اینکه داده از کجا می‌آید، کجا ذخیره می‌شود، سیستم‌ها چگونه با آن تعامل دارند و APIها در یک سازمان کجا قرار دارند، حالا در سال ۲۰۲۵ حیاتی است. بنابراین، داشتن یک منبع واحد حقیقت برای کشف API تأثیر قابل توجهی دارد. همه چیز از شناسایی APIهای سایه تا بهبود مدیریت نسخه می‌تواند از این نوآوری ناشی شود.
سوماً، کشف API به عنوان یک موتور برای حذف حدس‌زنی حیاتی است، به ویژه در این واقعیت جدید ایجنتیک. فراتر از فقط توانایی کشف APIها، سیستم‌ها ممکن است نیاز به زمینه بهتری در مورد نحوه تعامل و عملکرد این سیستم‌ها در زمینه یکدیگر داشته باشند و این استاندارد به وفور این را فراهم می‌کند.
این برای چه کسی است؟
api-catalog یک راه‌حل جالب است، اما به این معنا نیست که توسعه‌دهنده متوسط از آن برای تعریف دستی کاتالوگ‌های API استفاده کند. در عوض، احتمالاً پلتفرم‌های مدیریت API این استاندارد را به عنوان روشی برای تولید خودکار کاتالوگ‌های مبتنی بر اسکیما اتخاذ خواهند کرد.
ارائه‌دهندگانی مانند Kong، Apigee یا AWS Gateway احتمالاً ارزش قابل توجهی در یک فرمت از پیش تعیین‌شده استاندارد در چندین سیستم API پیدا خواهند کرد که امکان تولید بر اساس محیط مشاهده‌شده را فراهم می‌کند. این در صورت پذیرش گسترده، پیاده‌سازی‌های خاص فروشنده را به طور قابل توجهی کاهش می‌دهد و می‌تواند راه را برای یک مدل جهانی مصرف و کشف API هموار کند.
البته، این چالش اصلی این راه‌حل است:
اگر به طور گسترده پذیرفته شود. در حال حاضر، این RFC کاملاً آزمایشی است و باید ببینیم پذیرش گسترده‌تری وجود دارد یا خیر تا ببینیم آیا RFC در آزمون زمان مقاومت می‌کند. اگر گیت‌وی‌های API، پورتال‌ها و ابزارهای توسعه‌دهنده به طور گسترده این استاندارد را یکپارچه کنند، api-catalog می‌تواند رنسانسی در کشف و مصرف API ایجاد کند، شبیه به آنچه RSS برای بلاگ‌ها و وب‌سایت‌ها انجام داد — تقریباً مانند یک robots.txt برای APIها. اگر به طور گسترده پذیرفته نشود، مشکل کشف زیربنایی ادامه خواهد یافت و احتمالاً استانداردهای جدیدی لازم خواهد بود.
زمان، پاسخ api-catalog را خواهد داد
RFC 9727 و api-catalog یک استاندارد آینده‌نگر است که می‌تواند نحوه کشف و مصرف APIها را، به ویژه در دنیایی که یکپارچه‌سازی‌های ماشین به ماشین و مبتنی بر هوش مصنوعی غالب هستند، تغییر شکل دهد. در حالی که پذیرش هنوز در مراحل اولیه است، مفهوم کاملاً با نیازهای اکوسیستم‌های مدرن همخوانی دارد، جایی که خودکارسازی، شفافیت و قابلیت کشف کلید هستند.
آنچه باقی می‌ماند این است که آیا پذیرش بزرگ و گسترده واقعاً اتفاق خواهد افتاد، یا اینکه این فقط یک استاندارد دیگر در دریایی از استانداردها است که برای پذیرش و آگاهی رقابت می‌کنند.
