تغییر در ماهیت سیستم‌های نرم‌افزاری اجتناب‌ناپذیر است و API هم نوعی از سرویس‌ها است که دائم بلوغ پیدا کرده و بالتبع مستلزم تغییر است و از همین روی و به منظور جلوگیری از هر گونه سردرگمی از جانب کاربران یا بهتر بگوییم توسعه‌دهندگانی که از سرویس ما استفاده می‌کنند، الزامی است که ای‌پی‌آی خود را نسخه‌بندی کنیم.

چه زمانی باید نسخهٔ جدیدی از API را در اختیار کاربران قرار دهیم؟

در پاسخ به این پرسش می‌توان گفت زمانی که یکی از شرایط زیر وجود داشته باشد، نیاز است تا نسخهٔ جدیدی از ای‌پی‌آی خود را عرضه کنیم:

وقتی تغییری در فرمت ریسپانس صورت گیرد (به طور مثال، پراپرتی name به firstName تغییر یابد.)
وقتی یک پراپرتی از ریسپانس حذف گردد.
وقتی تغییری در دیتا تایپ ریسپانس صورت گیرد.
وقتی بخشی از ای‌پی‌آی حذف گردد.

آشنایی با نحوهٔ نسخه‌‌بندی API

یکی از روش‌های نسخه‌بندی اصطلاحاً URI Versioning نام دارد که از قضا پرکاربردترین روش نیز توسط کمپانی‌ها و دولوپرهای مختلف از سراسر جهان است به طوری که به عنوان مثال داریم:

http://api.example.com/v1/users

در حقیقت، v1 حاکی از آن است که ما با اولین نسخهٔ از ای‌پی‌آی سرویس مذکور سروکار داریم و چنانچه در آینده تغییراتی کلیدی در این سرویس صورت گیرد، می‌توان آن را به v2 تغییر داد.

همچنین لازم به یادآوری است که در نسخه‌بندی ای‌پی‌آی حتماً نیاز به استفاده از عدد نیست بلکه با توجه به اینکه هیچ‌گونه گایدلاینی (راهنمایی) برای این منظور به صورت رسمی تعریف نشده است، هر فرمتی که شفاف، گویا و قابل‌فهم باشد می‌تواند مورد استفاده قرار گیرد به طوری که مثلاً می‌توان نمونهٔ زیر را مد نظر قرار داد:

http://api.example.com/2019/users

به عنوان راه‌کاری دیگر به منظور نسخه‌بندی ای‌پی‌آی، می‌توان از یک هِدِر شخصی‌سازی‌شده مثلاً به صورت زیر استفاده کرد:

Accept-version: v1

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

همچنین به منظور مشخص کردن نسخه، می‌توان از هدر Content-Type به صورت زیر استفاده کرد:

Content-Type: application/json; version=2

همان‌طور که ملاحظه می‌شود، به وب سرور گفته‌ایم که فرمت جیسون باشد و نسخه‌ٔ ای‌پی‌آی مورد استفاده هم ۲ باشد.

همچنین افزودن مستندات واضح و شفاف به دولوپرها کمک می‌کند تا تغییرات وب سرویس مذکور را درک کرده مضاف بر اینکه پس از هر گونه تغییری در نسخهٔ ای‌پی‌آی، می‌توان از طریق میلینگ لیست کاربران را از تغییرات صورت گرفته مطلع ساخت.

آشنایی با نحوهٔ نسخه‌بندی API