کمتر اپلیکیشنی رو می‌شه پیدا کردن که مستقیم یا غیرمستقیم با APIها خصوصا REST مرتبط نباشن. حالا Arazzo Specification یه استاندارد جدید و البته «باز»، از OpenAPI Initiative است که به‌عنوان مکمل OpenAPI Specification برای توصیف جریان کار (workflow) APIها طراحی شده. توسعه‌دهنده/معمار می‌تونه دنباله‌ای از فراخونی‌های API و وابستگی‌هاش رو به‌صورت ساختاریافته و قابل فهم برای انسان (فنی و کسب‌وکاری) و ماشین تعریف کنه.
📜 سابقه و هدف
قبلن، OpenAPI با تمرکز روی توصیف endpointها توسعه داده شده بود. با swagger یا ابزارهای دیگه به راحتی endpointها رو می‌شه بررسی کرد، ولی خیلی از فرایندها، چندین endpoint رو درگیر می‌کنن اما در عمل، حالا چرخه‌ی فراخونی این endpointها به نحوی باید مستند و قابل رویت باشه. چه تیم فنی و چه تیم کسب‌وکاری باید بتونن فرایند فراخونی APIها رو بررسی کنن، که کدوم API اول باید کال بشه و بعد دومی و سومی و الی آخر. برای پاسخ به این نیاز، Arazzo Specification سال ۲۰۲۴ معرفی شد تا بشه جریان‌های کاری، خصوصا پیچیده‌ها رو توصیف و تشریح کرد.
🎯 اهمیت و کاربرد
- مستندسازی API call workflow: توصیف دقیق دنباله‌ی فراخونی APIها برای سناریو خاص.
- تولید خودکار مستندات و SDK: ایجاد مستندات اینتراکتیو و تولید کدهای کلاینت بر اساس جریان‌های کاری تعریف‌شده.
- تسهیل تست‌های end-to-end: تعریف سناریوهای تست پیچیده با استفاده از جریان‌های کاری.
- ادغام با هوش مصنوعی: ارائه ساختار قابل فهم برای مدل‌های زبانی بزرگ (LLMs) برای تعامل با APIها.
- بهبود تجربه توسعه‌دهنده (DX): کاهش نیاز به مستندسازی دستی و افزایش وضوح استفاده از APIها.
🧩 ساختار Arazzo
یک سند Arazzo معمولاً شامل بخش‌های زیره:
بخش arazzo: نسخه مشخصه Arazzo (مثلاً 1.0.1).
بخش info: اطلاعات متادیتا درباره سند.
بخش sourceDescriptions: فهرستی از منابع (مثل فایل‌های OpenAPI) که جریان‌های کاری بهشون ارجاع می‌دن.
بخش workflows: تعریف یک یا چند جریان کاری، شامل مراحل، ورودی‌ها، خروجی‌ها و معیارهای موفقیت یا شکست.
بخش components: تعریف مؤلفه‌های قابل استفاده مجدد برای جلوگیری از تکرار.
مثال توی کامنت
لینک مستند رسمی Arazzo Specification
مخزن GitHub Arazzo
مقاله در Swagger Blog
جدی گرفتن رویکرد API First نه تنها کمک بزرگی به توسعه اصولی‌تره، بلکه به تیم/سازمان‌سازی بهتر کمک می‌کنه، همون‌طور که تست نوشتن بخشی از مسیر بلوغ تیم و سازمانه؛ مستندسازی درست و ساختارمند هم بخشی از مسیر بلوغ توسعه‌دهنده، تیم و سازمانه. فایل ورد یا کانفولئنس یا ... ابزار مدیریت مستندات API نیستن!
💬 نظر شما چیه؟!