۳ مثال از تعریفهای OpenAPI
برای سالهای زیادی، هر زمان که کسی میخواست دربارهی APIها یاد بگیرد، ناگزیر با API مربوط به فروشگاه حیوانات خانگی روبهرو میشد. این API که توسط Swagger ایجاد شده، بهعنوان یک الگوی کاملاً عملی عمل میکند تا بتوانید یک API را در حال کار مشاهده کنید. این API مانند Example.com است اما برای تعریفهای API. این امکان را میدهد که توکنهای احراز هویت را امتحان کنید، نقاط پایانی مختلف را تست کنید و با یک پایگاه داده تعامل داشته باشید. شما میتوانید بارهای برگشتی را بهصورت فایلهای JSON ببینید و فرمانهای پایهی CRUD را امتحان کنید.
API مربوط به فروشگاه حیوانات تنها الگوی API موجود نیست. APIها تکامل یافتهاند تا فراتر از بهروزرسانی یک پایگاه داده عمل کنند. بهعنوان مثال، APIها میتوانند محصولات و خدمات را بهطور مستقل تأمین کنند، همانطور که با API موزه مشاهده خواهید کرد. نمونههای دیگر با چندین سیستم تعامل میکنند و شمای کلی چیزی شبیه یک اپلیکیشن سفر را ایجاد میکنند، که API سفر قطار این کار را بهخوبی انجام میدهد.
در ادامه، ما هر سه توصیف API از نوع OpenAPI را بهطور دقیق بررسی خواهیم کرد تا درک بهتری از اشتراکات، تفاوتها و نحوهی تغییرات از زمانی که Swagger برای اولین بار API فروشگاه حیوانات را معرفی کرد به شما بدهیم.
API فروشگاه حیوانات (PetStore API)
API فروشگاه حیوانات بهعنوان راهی شناخته میشود برای تمرین کار با REST و اجرای فرمانهای استاندارد HTTP که اکثر APIها را هدایت میکنند.
برای بهترین نتیجه، نمونه API فروشگاه حیوانات را در یک تب جدید باز کنید. ممکن است بخواهید کد منبع را نیز در تب جداگانهای باز کنید. ما عمدتاً به فایل openapi.yaml علاقهمند هستیم.
نگاه کردن به این دو مثال کمک میکند تا دید بهتری از نحوهی شکلگیری یک توصیف OpenAPI در دنیای واقعی پیدا کنید. همانطور که از توصیف OpenAPI میبینید، این توصیف با استفاده از نسخه OpenAPI 3.0.2 ایجاد شده است.
پس از یکسری توضیحات عمومی، توصیف API و منشأ آن توضیح داده میشود و بخشهای مختلف تشکیلدهندهی API فروشگاه حیوانات معرفی میشود. سپس اقداماتی که میتوان در هر بخش انجام داد مشخص میشود. برای مثال، بخش Pet به کاربران اجازه میدهد با استفاده از POST یک تصویر از حیوان خانگی خود آپلود کنند. دنبال کردن فایل openapi.yaml یک نقشهی عالی برای یادگیری تفکر در مورد طراحی API است.
فروشگاه حیوانات همچنین میتواند به شما سرنخهایی دربارهی چگونگی کدنویسی یک API از نوع REST بدهد اگر وقت بگذارید و کد را با دقت بررسی کنید. اگر به پایین Petstore.Swagger.io اسکرول کنید، بخشی از مدلها را خواهید دید. مرور هر مدل به شما نشان میدهد که هر مدل چه متغیرهایی انتظار دارد. برای مثال، پارامتر petId تنها عدد صحیح را میپذیرد، همانطور که توسط integer($int64) مشخص شده. پارامتر name یک رشته انتظار دارد، همانطور که در توصیف API ذکر شده.
البته این API منتقدانی هم دارد. برخی ایراد میگیرند که منابع جمع بسته نشدهاند. برای مثال اولین تگ “Pet” است، در حالی که باید “pets” باشد. زمانی که خطاها را متوجه شوید، سایر اشتباهات نیز آشکار میشوند. قابلیتهای ورود و خروج کمتر واضح هستند، زیرا زیر بخش USER قرار گرفتهاند، که شاید باید جمع بسته میشد.
با توجه به انتقادهایی که توسعهدهندگان از API فروشگاه حیوانات دارند، واضح است که این API در دنیای واقعی چندان مفید نیست. این API یک Hello World مناسب است، اما بهعنوان یک راهنمای آموزشی برای طراحی API کارآمد، کامل نیست.
API سفر قطار (Train Travel API)
اکنون توجه خود را به نخستین تعریف OpenAPI که جایگزین API فروشگاه حیوانات شده است معطوف کنیم. API سفر قطار برای رفع برخی از نگرانیهای طراحی API مطرحشده در بالا ایجاد شد. این API در یک فایل openapi.yaml سازماندهی شده، که آن را برای استفاده در ماکتها و مستندسازی کارآمدتر میکند.
API سفر قطار بر اساس مثالهای دنیای واقعی ساخته شده، بنابراین نسبت به API فروشگاه حیوانات کاربردیتر و مفیدتر است. همچنین بر اساس نیازهای واقعی ایجاد شده، زیرا نویسنده به روشی برای جستجوی قطارهایی نیاز داشت که دوچرخه یا حیوانات خانگی را میپذیرند. تابع BookingPayments بر اساس API واقعی Stripe Payments طراحی شده است. زمان گذاشتن روی این ماکت به کاربر دید خوبی از چگونگی پیادهسازی انواع پرداختها میدهد.
API سفر قطار از استانداردهای مناسب وب استفاده میکند و هرجا لازم باشد از استانداردهای پیشنویس. همچنین از کدهای استاندارد HTTP استفاده میکند که باعث میشود خروجیها برای ابزارهایی مانند تولیدکنندههای مستندات قابل فهم باشند. برخی از پیادهسازیهای این API بسیار زیباست، مانند استفاده از Wrapper-Collection برای نگهداری نتایج بهجای بازگرداندن JSON خام. این ساختار به کاربر امکان میدهد کنترلهای HATEOAS یا صفحهبندی را بهراحتی اضافه کند.
این API صراحتاً برای OpenAPI 3.1 ایجاد شده، در حالی که API فروشگاه حیوانات ابتدا در OpenAPI 2.0 نوشته شد و بعداً به ۳.۰ تبدیل شد. این بدین معناست که API سفر قطار با WebHooks سازگاری بهتری دارد. همچنین از unevaluatedProperties بهجای additionalProperties استفاده میکند که باعث میشود زیرساخت allOf را بهتر درک کند و هیچ خاصیتی بهطور تصادفی حذف نشود. OpenAPI 3.1 همچنین از Property Examples پشتیبانی میکند.
API سفر قطار الگویی بسیار بهتر از بهترینروشهای امروزی API است. همچنین به دلیل ساختار .yaml کارآمد، در دمویها آسانتر استفاده میشود. اگر میخواهید اصول مدرن API را یاد بگیرید یا نمایش دهید، API سفر قطار گزینهی بسیار بهتری نسبت به PetStore است.
API موزه (Museum API)
این تعریف OpenAPI که توسط Redocly ایجاد شده، نمونهی دیگری از یک API است که از OpenAPI 3.1 بهره میبرد. عملکرد آن مشابه API سفر قطار است و چندین قابلیت ارائه میدهد که یک API موزه واقعی را شبیهسازی میکند. این عملکردها شامل ایجاد رویدادهای ویژه، بازیابی ساعات کاری موزه و غیره است.
این API عمدتاً با استفاده از تگهای OpenAPI سازماندهی میشود، که یکی از ویژگیهای بارز آن است. تگها تعیین میکنند که هر منبع مربوط به کدام endpoint است و امکان درج توضیح دربارهی هر تگ را فراهم میکنند. بخش تگها در API موزه به صورت زیر است:
هر endpoint نیز بخشی برای تگهای مربوط به خودش دارد:
بهترین بخش این است که بسیاری از ابزارهای مستندسازی از تگها برای گروهبندی مسیرها در ناوبری استفاده میکنند. همچنین میتوانند اطلاعات اضافی را با x-displayName بازگردانند. x-tagGroups نیز قابل استفاده است برای گروهبندی تگها.
جمعبندی نهایی
اگرچه API فروشگاه حیوانات مستحق این حجم از انتقاد نیست، اما کاملاً نمایندهی طراحی مدرن API نیست. همانطور که دیدیم، بررسی فایل .yaml آن میتواند مفید باشد، اما از تمام قابلیتهای OpenAPI 3.0 بهره نمیبرد و همهی بهترین روشهای امروزی را دنبال نمیکند.
اگر واقعاً قصد یادگیری طراحی مدرن API را دارید، API سفر قطار گزینهی بهتری است و میتوانید آن را با API موزه تکمیل کنید.
همچنین مثالهای بیشتر از طراحی درست API وجود دارد. برای مثال میتوانید به مرجع OpenAPI 3.1 در Speakeasy نگاه کنید. این مرجع بسیار تمیز، واضح و قابل فهم است. بهترین بخش این است که مستندات و کد نمونه در کنار هم نمایش داده میشوند — بدون نیاز به تعویض تب. دیدن توضیح هر بخش در کنار کد .yaml بسیار کمککننده است.
