مشخصات OpenAPI Overlay چیست؟

مشخصات ابتکار OpenAPI در حال حاضر مانند اتوبوس‌های لندن هستند: شما مدت‌ها منتظر می‌مانید و سپس چهار مورد از آن‌ها هم‌زمان می‌رسند. ما دیدیم که مشخصات Arazzo در اوایل سال ۲۰۲۴ وارد صحنه شد و علاقهٔ زیادی را در جامعهٔ API پیرامون توصیف چندین فراخوان API به‌عنوان یک جریان کاری ایجاد کرد. همچنین دو انتشار وصله برای مشخصات اصلی OpenAPI در اکتبر ۲۰۲۴ داشتیم، همراه با نسخهٔ ۱.۰.۰ Overlay، یک مشخصات برای اجرای به‌روزرسانی‌ها روی توصیف‌های OpenAPI به روشی استاندارد.

در انصاف نسبت به مشخصات Overlay، این سند به‌مدت دو سال به‌عنوان پیش‌نویس اجراکنندگان منتشر شده است. تیم درگیر در Overlay تصمیم گرفت که زمان مناسبی برای رسمی‌سازی مشخصات به‌عنوان یک نسخهٔ رسمی است. پیش‌نویس‌های اجراکنندگان برای آگاهی‌رسانی و ارائهٔ دید اولیه از قابلیت‌های کلیدی عالی هستند، اما نسخه‌های رسمی به سازندگان ابزار اجازه می‌دهند متعهد به ساخت ابزارهایی برای پشتیبانی از آن شوند.

مورد استفادهٔ Overlay با OpenAPI و Arazzo متفاوت است، به این معنا که به ارائه‌دهندگان API کمک می‌کند توصیف‌های API را منتشر و مدیریت کنند و از خودکارسازی، تضمین کیفیت، و عملکردهای حکمرانی پشتیبانی کنند. نکتهٔ عالی دربارهٔ مشخصات Overlay این است که می‌توان آن را در سراسر چرخهٔ عمر API هر زمان که یک به‌روزرسانی برای یک سند OpenAPI لازم باشد، مورد استفاده قرار داد.

Overlay چیست؟

به‌طور ساده، یک Overlay یک سند JSON یا YAML است که مجموعه‌ای از به‌روزرسانی‌ها را برای یک توصیف OpenAPI توضیح می‌دهد. هر به‌روزرسانی بر اساس یک Action Object است که یک فرمان (imperative) را نشان می‌دهد. در نسخهٔ ۱.۰.۰، فرمان‌های پشتیبانی‌شده update و remove هستند؛ که update دستوری برای افزودن یا ادغام یک شیء ارائه‌شده در سند Overlay با استفاده از شیئی تعریف‌شده به‌عنوان مقدار به‌روزرسانی است. مقدار remove همیشه true تنظیم می‌شود.

Action Object همچنین یک JSONPath را به‌عنوان اشاره‌گری به اشیائی که باید پردازش شوند پیاده‌سازی می‌کند. نکتهٔ عالی استفاده از JSONPath این است که یک Overlay را بسیار قابل‌گسترش می‌سازد. هدف در مشخصات Overlay یک توصیف OpenAPI است، اما می‌توان آن را واقع‌بینانه برای هر سند JSON یا YAML استفاده کرد.

همان‌طور که همیشه اتفاق می‌افتد، توضیح چیزی مانند Overlay با مثال بهترین کار است. برای مثال، Server Object در مشخصات OpenAPI اطلاعات استقرار را برای مصرف‌کنندگان API فراهم می‌کند، از جمله جزئیات URL که یک API مشخص در آن میزبانی شده است. یک ویژگی servers در ریشهٔ سند OpenAPI ارائه می‌شود. قطعهٔ زیر یک نمونه از ویژگی servers است، با یک نمونهٔ محلی پیش‌فرض HTTP برای توسعه و یک مقدار استاندارد برای تولید، با یک متغیر hostname که به مقدار localhost پیش‌فرض می‌شود.

بیایید فرض کنیم که یک سازمان نیاز دارد حکمرانی مشخصی را بر مقادیر Server Object هنگام انتشار توصیف API اعمال کند، یعنی:

• نمونهٔ محلی روی HTTP حذف می‌شود، زیرا هرگز خارج از محیط توسعهٔ محلی استفاده نمی‌شود.

• مقدار پیش‌فرض متغیر hostname برای API تولید باید به مقدار صحیح تغییر پیدا کند، تا مصرف‌کنندگان API به‌طور خودکار مقدار درست را دریافت کنند.

تغییرات بالا هر بار که توصیف API منتشر می‌شود اعمال می‌شوند، بنابراین خودکارسازی در این زمینه منطقی است. توصیف این تغییرات با استفاده از یک سند Overlay این کار را ساده می‌کند، زیرا ارائه‌دهندهٔ API می‌تواند تغییرات موردنیاز را یک‌بار بنویسد و بارها اعمال کند. نگه‌دارندهٔ سند Overlay همچنین می‌تواند سند Overlay را ایجاد کند، اگر منبع حقیقت برای چنین داده‌ای یک سیستم داخلی یا ابزار ساخت باشد.

برای حذف نمونهٔ localhost که روی HTTP ارائه می‌شود، می‌توانیم remove را پیاده‌سازی کنیم:

JSONPath از تابع match برای حذف هر چیزی که روی localhost و از طریق HTTP ارائه می‌شود استفاده می‌کند، که می‌تواند بر اساس سیاست‌های امنیتی سازمان گسترش یابد تا شامل هر چیزی که از طریق HTTP ارائه می‌شود بشود. اقدام دوم سپس مقدار API تولید را به‌روزرسانی می‌کند و مقدار پیش‌فرض متغیر hostname را تغییر می‌دهد:

با هم پیاده‌سازی‌شده، سند Overlay که این دستورات را شامل می‌شود به‌صورت زیر تعریف می‌شود:

سپس می‌توان از سند Overlay برای پردازش یک سند OpenAPI مشخص استفاده کرد، با استفاده از یک CLI مانند overlayjs:

در نتیجه، رسیدن به وظیفهٔ به‌روز نگه‌داشتن اطلاعات استقرار تبدیل به فرآیندی می‌شود که یک سند Overlay یک‌بار ایجاد می‌شود، بر اساس منبع حقیقت صحیح نگهداری می‌شود، و سپس یک اسکریپت در نقطهٔ درست در خط لولهٔ توصیف API اجرا می‌شود.

Overlay و چرخهٔ عمر API

مثال بالا نشان می‌دهد که چگونه مشخصات Overlay یک سازوکار ثابت و قطعی برای به‌روزرسانی یک یا چند توصیف OpenAPI فراهم می‌کند. در نظر گرفتن به‌روزرسانی‌های توصیف OpenAPI به‌عنوان عملی یک‌باره، چگونگی وقوع چنین تغییراتی در سراسر چرخهٔ عمر API، اجرای دستی آن‌ها، و اینکه اطلاعات گنجانده‌شده در یک توصیف OpenAPI از چندین منبع مختلف وارد می‌شود را ساده‌سازی می‌کند. رمزگذاری به‌روزرسانی‌ها با استفاده از روش‌هایی مانند Overlay کیفیت را بهبود می‌بخشد، خطاها را کاهش می‌دهد، و منابع فنی را در بسیاری از بخش‌ها آزاد می‌کند.

سؤالات زیر را هنگام فکر کردن دربارهٔ اینکه چگونه اطلاعات استقرار به توصیف‌های OpenAPI شما اضافه می‌شود، و مثال Server Object فوق، از خود بپرسید:

• وقتی سازمان شما مقادیر servers را در توصیف‌های OpenAPI به‌روزرسانی می‌کند، چه کسی این کار را انجام می‌دهد؟

• وقتی اطلاعات servers به‌روزرسانی می‌شود، آیا همیشه صحیح است؟

• اطلاعات چگونه به سند اضافه می‌شود؟

اگر پاسخ‌های شما به سؤالات بالا «یک انسان»، «نه»، و «کپی‌کردن و چسباندن» هستند، Overlay احتمالاً برای شما مناسب است. شما می‌توانید از Overlay برای تمام انواع به‌روزرسانی‌های توصیف‌های OpenAPI خود استفاده کنید، از جمله:

• اعمال الزامات امنیتی استانداردشده بر اساس سیاست‌های سازمانی و در همین راستا برداشتن مسئولیت از طراحان API

• حذف یادداشت‌های داخلی و گسترش‌های مشخصات به‌عنوان مکانیزم پاک‌سازی پیش از انتشار برای مصرف‌کنندگان خارجی API

• ارائهٔ پاسخ‌های پیش‌فرض یا پاسخ‌های خطای استاندارد در سراسر کدهای وضعیت HTTP که یا رهنمودهای API یا قابلیت‌های دروازهٔ API شما را منعکس می‌کنند

آیندهٔ مشخصات Overlay

همان‌طور که همیشه اتفاق می‌افتد، پشتیبانی ابزارها زمان نیاز دارد تا بالغ شود، با اینکه برخی گزینه‌ها هم‌اکنون در دسترس هستند، اما Overlay یک مشخصات نسبتاً ساده برای پیاده‌سازی است. قدم برداشتن و ایجاد پیاده‌سازی خودتان از Overlay یک سرمایه‌گذاری عالی برای آینده است، به‌خصوص با رشد پشتیبانی ابزارها، زیرا اسناد Overlay شما می‌توانند بعدها بر اساس استانداردها به ابزارهای دیگر منتقل شوند. این همان قابلیت تعامل (interoperability) است، که یکی از دلایلی است که استانداردها وجود دارند، و اینکه چرا ابتکاراتی مانند Overlay برای جامعهٔ API بسیار مهم هستند.