نسخه‌بندی API بسیار حائز اهمیت است. اما آیا شما با بهترین روش‌های نسخه‌بندی API آشنایی دارید؟ آیا استراتژی نسخه‌بندی API شما کاربردی و قابل قبول است؟

نسخه‌بندی API چیست؟

نسخه‌بندی API فرایند تولید نسخه‌های مختلف از API شما است. به طور کلی، نسخه‌بندی API تغییرات در نحوه استفاده API، تغییرات ساختاری API و تغییرات در نرم‌افزار یا برنامه اصلی که API برای آن ساخته شده است را در بر می‌گیرد.

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

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

چرا نسخه‌بندی API ضروری است؟

نسخه‌بندی API برای اطمینان از پایداری و اعتمادپذیری سرویس ضروری است. اگر شما API ها را به درستی نسخه‌بندی نکنید، می‌تواند تأثیرات وخیمی بر روی محصولات و خدمات ارائه شده داشته باشد.

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

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

۵ روش برتر برای نسخه‌بندی API

در این قسمت ۵ روش کاربردی برای نسخه‌بندی API را ذکر کرده‌ایم:

• امکان سازگاری با نسخه‌های قبلی
• به‌روزرسانی مستندات API برای نمایش نسخه‌های جدید
• تطبیق نسخه‌بندی API با الزامات کسب‌و‌کاری
• اولویت قرار دادن مسائل امنیتی API
• تنظیم نسخه‌های API برای مقیاس پذیری

نحوه ایجاد یک استراتژی نسخه‌بندی API

شما برای پشتیبانی از نسخه‌های مختلف یک API به یک استراتژی نسخه‌بندی API نیاز دارید.

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

برای حل این مسئله دو روش مرسوم برای نسخه‌بندی API وجود دارد.

نسخه بندی از طریق مسیر URI

شناسه منابع یکپارچه (URI) شما به عنوان مسیر والد برای آدرس URL شما عمل می‌کند. به طور ساده‌تر، اگر URL شما یک صفحه در کتاب باشد، URI شما خود کتاب است. نسخه بندی مسیر URI روش ترجیحی و استاندارد رایج است. این رویکرد در بین بسیاری از بازیگران برجسته عرصه فناوری که کسب‌و‌کارهای خود را بر پایه APIها ایجاد کرده‌اند، متداول است. از جمله این کسب‌وکارها می‌توان به فیسبوک، ایربی‌اندبی و توییتر اشاره کرد.

• نحوه انجام نسخه بندی مسیر URI برای API

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

• تغییرات اصلی یا کوچک

برای ارتباط با مشتریان API درباره اطلاع‌رسانی یک تغییر اصلی یا کوچک، روش‌های مختلفی وجود دارد.

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

خب اگر شما چندین نسخه از یک API را در حال اجرا داشته باشید چطور؟ در این حالت، نسخه اولیه خود را در حال اجرا نگه دارید و برنامه زمان‌بندی تغییرات برای انتقال به نسخه دوم را در اختیار مشتریان قرار دهید. روی کاغذ برنامه تغییرات می‌تواند بی‌نهایت باشد. اگر تغییر اساسی نباشد، می‌توانید به سادگی نسخه V1 API را در پلتفرم و زیرساخت‌ها تکرار کنید. اگر بخواهید، می‌توانید از مدیریت چرخه حیات (lifecycle coordinator) برای پیگیری تاریخچه‌ تغییرات نسخه‌های خاص API استفاده کنید.

نسخه بندی API از طریق مذاکره محتوا

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

• ایجاد اینترفیس‌های نوع‌دهی قوی ممکن نیست (Strongly Typed Interfaces)

از دیدگاه پلتفرم API و امکان نمایش اینترفیس‌های نوع‌دهی قوی، امکان پذیر نخواهد بود. به عبارت دیگر، سخت می‌توان به اپلیکیشن کلاینت برای تطابق با زیرساخت انتخاب‌شده در نسخه هدر محتوا اعتماد کرد.

• استفاده از سرویس مجازی (پروکسی API)

شما برای اینکه بتوانید از نسخه‌ها و پیاده‌سازی‌های مختلف استفاده کنید، نیاز به استفاده از یک سرویس مجازی (پروکسی API) خواهید داشت.

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

• دسترسی‌پذیری

این رویکرد نیز نسبت به APIهای دارای URI نسخه‌بندی‌شده، کمتر مرسوم است. وقتی شما به هدرهای HTTP با نوع رسانه نیاز دارید، بررسی API با استفاده از مرورگر دشوارتر است.

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

بایدها و نبایدهای نسخه‌بندی API

برای ایجاد استراتژی نسخه‌بندی هیچ‌وقت زود نیست

اکثرا اوقات وقتی در حال توسعه API خود هستیم، به این دلیل که در حال ساختن نسخه اولیه سرویس خود هستیم، به نسخه‌بندی توجه نمی‌کنیم. نسخه‌بندی مشکل آینده است، نه؟

نه، اینطور نیست.

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

پس بیایید به برخی از بایدها و نبایدها در طراحی و برنامه‌ریزی استراتژی نسخه‌بندی برای API بعدی خود نگاهی بیندازیم تا بتوانید از ضربه به خودمان در ابتدای کار جلوگیری کنیم.

استراتژی نسخه‌بندی

ایده کلی این مقاله این است که شما نیاز دارید یک استراتژی برای سازماندهی کردن نسخه بندی API خود را ایجاد کنید. هرچه استراتژی شما بهتر وضع شده باشد، سریع‌تر می‌توانید API خود را گسترش داده و بدون تأثیر بر کاربران‌تان رشد کنید.

استراتژی نسخه‌بندی چیست؟ در واقع، یک مجموعه از استانداردها است که هر بار که می‌خواهید یک نسخه جدید از API خود را مشخص کنید، از آن‌ها استفاده می‌کنید. طبق تعریف، استانداردها همواره دارای مستندات کامل هستند و همیشه قوانین منطقی را دنبال می‌کنند و اگر استثناءهایی نیز وجود داشته باشد، به طور واضح مستند شده‌اند. این استاندارد‌ها ممکن است شامل مواردی مانند زیر باشد:

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

در واقع، هر چه این موارد بیشتر باشد، برای کاربران‌تان بهتر خواهد بود.

بنابراین، یکی از نبایدها نسخه‌بندی API به صورت دلخواه و بدون منطق است.

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

شاید حتی درباره اینکه تغییرات اساسی که در API خود به وجود می‌آورید چگونگی تاثیر آن بر کاربران فعلی فکر هم نکنید. این مسئله بزرگی است و می‌تواند موجب مانع رشد و استفاده از API شود زیرا در واقع مشتریان آن را ناپایدار در نظر می‌گیرند.

شما یک برنامه زمانی انتشار ندارید تا کاربران بفهند آیا تغییری در راه است یا خیر؛ این باعث می‌شود تا زمانی که مشتری نیاز به یک بهبود یا عملکرد بیشتر را حس می‌کند، به دلیل عدم توانایی در تشخیص در راه بودن به‌روزرسانی، API کارایی خود را از دست می‌دهد.

برای جلوگیری از این مشکلات چه کاری می‌توانید انجام دهید؟ (زیرا ممکن است شما در حال کار بر روی بهترین API جهان باشید اما در نهایت هیچکس به دلیل نقص در استراتژی نسخه‌بندی شما این را درک نکند)

داشتن یک استراتژی قوی، تعریف شده و مستند

یک استراتژی نسخه‌بندی را تعریف کنید، آن را در جایی منتشر کرده و مطمئن شوید که به آن پایبند می‌مانید.

به عنوان مثال:

• تعریف روش نسخه‌بندی که استفاده می‌کنید

این کار به کاربران‌تان اطلاعاتی درباره هر نسخه جدید می‌دهد. به عنوان مثال، می‌توانید از روش نسخه‌بندی SemVer (نسخه‌بندی معنایی) استفاده کنید. در این روش اگر از ۱.۲ به ۱.۳ بروید، به کاربران‌تان اطلاع می‌دهید که فقط بهبود‌هایی که باعث کرش برنامه نمی‌شوند را اضافه کرده‌اید، اما اگر از ۱.۲ به ۲.۰ بروید، به احتمال زیاد مواردی در نسخه قبلی دچار مشکل می‌شود. یا می‌توانید از روش نسخه‌بندی Ubuntu پیروی کنید که تاریخ انتشار را نشان می‌دهد، بنابراین ۲۱.۰۱ به این معنی است که شما آن نسخه را در ژانویه ۲۰۲۱ منتشر کرده‌اید. به این ترتیب با نشان دادن زمان انتشار نسخه به کاربران خودتان ارزش افزوده ارائه می‌دهید. تا زمانی که یک روش را به کار ببرید و به طور واضح آن را مستند کنید، اهمیت زیادی ندارد که از چه روشی استفاده می‌کنید.

• اطلاع‌رسانی به کاربران‌تان درباره اتفاقی که برای نسخه‌های قدیمی پس از هر به‌روزرسانی جدید رخ می‌دهد

آیا این نسخه‌ها قدیمی شده‌اند؟ دیگر قابل دسترس نیستند؟ شاید برای مدتی قابل دسترس باقی مانده‌اند؟ در نظر داشته باشید که درباره این مسئله صادقانه و با وضوح مستندسازی شود.

• به کاربران‌تان یک نقشه مفصل از آینده ارائه دهید

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

هدف از این استراتژی، ارائه یک روش استاندارد برای کاربران و توسعه‌دهندگان در جهت شناختن چگونگی ارتباط با API و نسخه‌های مختلف آن است.

یک نسخه برای همه

نسخه‌بندی تا زمانی که نوبت به تصمیم‌گیری درباره نسخه‌های قدیمی می‌رسد، کاری مفرح است.

البته این موضوع تنها زمانی مهم است که کسی واقعاً از نسخه‌های قدیمی شما استفاده می‌کند، اما بیایید فرض کنیم که این مورد صادق است.

یک نباید بزرگ: فقط آخرین نسخه را آنلاین در دسترس قرار دهید

فقط داشتن یک نسخه در دسترس ممکن است ایده خوبی به نظر برسد، چرا که مشتریان شما همیشه آخرین نسخه را خواهند داشت و هر اصلاحیه باگ و ویژگی جدید به صورت خودکار برای آن‌ها در دسترس خواهد بود. 

اما اینطور نیست.

زیرا یکی از کارهایی می‌توانید هنگام به روز رسانی API انجام دهید، انتشار تغییرات اساسی است که باعث تداخل می‌شود؛ این موضوع کاملا طبیعی است. در واقع یک نسخه اساسی جدید ممکن است پر از باگ‌های مختلفی باشد که باعث کرش شدن برنامه می‌شوند. در صورت بروز این اتفاق و در دسترس بودن تنها آخرین نسخه، مشتریان شما یک تجربه کاربری ناپایدار خواهند داشت.

نگه داشتن چند نسخه به صورت موازی

چاره چیست؟ با استفاده از یک استراتژی نسخه‌بندی مشخص، هنگام انتشار یک نسخه غیر سازگار با نسخه قبلی، می‌توانید نسخه قبلی و نسخه جدید را به صورت موازی برای مدت زمان مشخصی فعال نگه دارید.

در این حالت، می‌توانید قبل از حذف کردن نسخه قبلی،  به مشتریان خود درباره تغییرات و ددلاین برای به روزرسانی اطلاع‌رسانی کنید.

علاوه بر این، اگر شما از یک روش نسخه‌بندی مانند SemVer استفاده کنید، می‌توانید بدون اینکه نگران مشکلات مشتریان خود باشید، به طور خودکار به روزرسانی‌های جزئی و ترمیمی را اعمال کرده و تغییرات اصلی را فقط از طریق این فرایند منتشر کنید. به این ترتیب، مشتریان فقط باید نگران نسخه‌های اصلی باشند (به عنوان مثال، آن‌ها می‌توانند به جای ۱.۲.۵ یا ۱.۵.۲ بگویند که از نسخه ۱ استفاده می‌کنند).

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

مستندسازی یک API تعیین کننده‌ میزان پذیرش آن توسط کاربران است. هر چه بهتر باشد، استفاده از آن برای کاربران آسان‌تر خواهد بود و این به معنی کاهش شیب یادگیری برای کاربران است.

یک نباید بزرگ: نیازی به مستند کردن موارد بارز نیست

تصور این که برخی موارد برای کاربران بارز است و اشاره نکردن و یا اشاره کوتاه به آن‌ها در مستندات، یکی از نبایدهای بزرگ است.

هیچ چیز را به تصور کاربران خود واگذار نکنید و برای هر جنبه‌ای از محصول خود مستند داشته باشید.

اگر حق انتخاب وجود داشته باشد، ممکن است کاربران فکر کنند قفل کردن کلاینت روی یک نسخه خاص و رها کردن آن‌ها بهترین کار است؛ با این حال، اگر شما تصمیم به حذف آن نسخه بگیرید، چه اتفاقی می‌افتد؟

یا شاید آن‌ها فکر کنند “نسخه جدید” به معنای “نسخه بهتر” است، بنابراین آن‌ها همیشه از آخرین نسخه استفاده می‌کنند. اما ممکن است به‌روزرسانی جدید شما کلاینت آن‌ها را از کار بیندازد. این موضوع را چه زمانی به آن‌ها اطلاع دهید بهتر است؟

باید استراتژی خود درباره نسخه‌بندی را به شکل کامل مستند کنید

بهترین روش این است که در یک بخش مجزا از مستندات مدل نسخه‌بندی استفاده‌شده، اتفاقی که بعد از انتشار هر نسخه می‌افتد و تاثیر نسخه‌های مختلف بر مشتری را توضیح دهید. بخش آخر از اهمیت بالایی برخوردار است، زیرا کاربران می‌خواهند بدانند انتشار هر نسخه چطور آن‌ها را تحت تاثیر قرار می‌دهد.

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

برای مثال مستندات انتشار Shopify را در تصویر زیر مشاهده می‌کنید:

در این تصویر چند مورد را می‌توانید تشخیص دهید:

• آن‌ها از یک طرح نسخه‌بندی مبتنی بر زمان پیروی می‌کنند.
• هر نسخه جدید را به صورت جداگانه و با جزئیات مستند می‌کنند.
• آن‌ها حتی یک نسخه “پیش‌نمایش توسعه‌دهنده” دارند که به احتمال زیاد با آخرین تغییرات جدید به‌روز می‌شود.

اگر روی هر یک از آن‌ها کلیک کنید، سطح جزئیات را مشاهده خواهید کرد که شامل مواردی مانند زیر می‌شود:

• تاریخ انتشار، بنابراین دقیقاً می‌دانید این نسخه چقدر قدیمی است.
• تاریخ منسوخ‌سازی، یا تاریخی که این نسخه دیگر پشتیبانی نخواهد شد. این نکته خیلی مهم است، چون به عنوان مشتری این نسخه، شما دقیقاً می‌دانید که کی دیگر قادر به استفاده از آن نخواهید بود.
• چه چیزهایی جدید است؟ لیست به روزرسانی‌ها.
• تغییراتی که باعث تداخل می‌شوند. بله، آن‌ها سناریوهای احتمالی کرش برنامه مشتریان بعد از کوچ به نسخه جدید را در نظر گرفته‌اند. این همان چیزی است که به آن رویکرد متمرکز بر کاربر می‌گویم.

به کاربران خود فکر کنید، نه به حجم مستنداتی که باید بنویسید.

نباید بزرگ: یک روش بسیار منحصر به فرد برای انجام آن پیدا کنید

شاید شما فکر کنید نسخه‌بندی API جزء استانداردهای ارتباطی شما نیست و تصمیم گرفته‌اید یک روش جدید و منحصر‌به‌فرد را برای تعیین نسخه API خود ابداع کنید.

یا شاید، شما وقت نکرده‌اید درباره پروتکل ارتباطی خودتان تحقیق کرده و روش‌های مختلف و استاندارد نسخه‌بندی را بخوانید.

موضوع هر چه که باشد، مجبور کردن مشتریان به پیروی از راه‌های غیر استاندارد، کتابخانه‌های آن‌ها را بلااستفاده خواهد کرد. به خاطر داشته باشید که آن‌ها به احتمال زیاد از کتابخانه‌هایی استفاده می‌کنند که با پروتکل ارتباطی شما سروکار دارند، تا نیازی به اختراع چرخ دوباره نداشته باشند. این کتابخانه‌ها به طور معمول (تقریباً ۹۹% وقت‌ها) فرض می‌کنند که هم مشتری و هم سرور از استانداردها پیروی می‌کنند.

بنابراین، اگر از HTTP استفاده می‌کنید – که اگر واقع‌بین باشیم به احتمال ۹۹.۹% شما از آن استفاده می‌کنید – کتابخانه‌ای که استفاده می‌کنید هیچ چیزی خارج از هدرها، URL یا پارامترهای کوئری را برای تعیین نسخه بررسی نمی‌کند.

اگر فکر می‌کنید یک ایده جدید جذاب دارید، تاثیر آن بر مشتریان را نیز در نظر بگیرید. 

به مشتریان  اجازه دهید به شما بگویند دوست دارند از چه نسخه‌ای استفاده کنند.

هرچه شما این فرایند را ساده‌تر کنید، مشتریان شما خوشحال‌تر خواهند بود؛ به خاطر داشته باشید، شما می‌خواهید مشتریان‌تان خوشحال باشند.

برای این کار چه گزینه‌هایی وجود دارد؟

هدر به عنوان بخشی از درخواست

اما نه هر هدری، HTTP یک مفهوم به نام مذاکره محتوا دارد که به شما اجازه می‌دهد نوع نمایشی که مشتری شما از منبع درخواست شده قبول می‌کند را مشخص کنید. بنابراین با استفاده از هدر Accept می‌توانید نوع mime پاسخ همچنین نسخه آن را مشخص کنید. به این ترتیب، می‌توانید همان مجموعه‌ اندپوینت‌ها را داشته باشید، اما از طریق این هدر نسخه آن‌ها را مشخص کنید. اگر شما در حال ساخت یک API کاملاً RESTful هستید، این مدل بهترین روش برای نسخه‌بندی است.

نسخه داخل URL

این یعنی باید URL‌هایی مانند /api/v1/your-endpoint-here داشته باشید. بنابراین اگر می‌خواهید به نسخه ۲ بروید، فقط آن را به /api/v2/your-endpoint-here تغییر دهید. این یک گزینه مناسب است که بسیاری از آن استفاده می‌کنند. اما مشکل آن چیست؟ در واقع شما از نظر فنی URI را با سورس جفت می‌کنید. به عنوان مثال، دو درخواست زیر را در نظر بگیرید:

GET /api/v1/images/family-photo.jpg و GET /api/v2/images/family-photo.jpg

برای پروتکل HTTP و در واقع برای یک API کاملاً RESTful، این دو منبع متفاوت هستند، اما در عمل، هر دو یک تصویر را برمی‌گردانند. این یعنی شما با به‌روزرسانی نسخه API شناسه آن‌ها را تغییر داده‌اید. طبق تعریف، URI/URL منبع در طول زمان نباید تغییر کند، بنابراین شما یک استاندارد را نقض می‌کنید. به خاطر داشته باشید، اگر قصد ساخت یک REST API را ندارید، ممکن است این مشکل برای شما اهمیتی نداشته باشد.

تعیین نسخه به عنوان بخشی از پارامترهای کوئری

اگر می‌خواهید نسخه را در آدرس اینترنتی (URL) نشان دهید اما مشکل فوق را نداشته باشید، می‌توانید تغییرات را در پارامترهای کوئری اعمال کنید. بنابراین به جای /api/v1/images/family-photo.jpg می‌توانید از /api/images/family-photo.jpg?v=1 استفاده کنید. در این حالت از پارامترها (که بخشی از شناسه یکتا نیستند) برای مذاکرهٔ محتوا استفاده می‌کنید. اگر تعداد زیادی پارامتر در هر لحظه ندارید، این روش یک راه‌حل عالی است. با این حال، اگر در تمام اندپوینت‌های خود از این پارامترها استفاده می‌کنید، این کار تنها باعث شلوغ شدن URL می‌شود. این روش همان مشکل اولیه را دارد: شما باید بفهمید چگونه درخواست را به نسخه درست هدایت کنید. این موضوع از آنجایی که چندین روش برای انجام این کار وجود دارد، مشکل بزرگی نیست اما همچنان نیاز به تفکر بیشتر دارد.

این سه روش رایج‌ترین روش‌ها برای مشخص کردن نسخه یک API است.

استراتژی نسخه‌بندی API شوخی نیست!

بنابراین، مسئله نسخه‌بندی API نیازمند یک رویکرد جدی است و باید به همان اندازه که به سایر جنبه‌های توسعه API توجه می‌کنید، به استراتژی نسخه‌بندی توجه داشته و از اول برای آن برنامه‌ریزی کنید. 

در نهایت، هنگام تعریف استراتژی نسخه‌بندی، به کاربران و پذیرش API خود فکر کنید. این موضوع تأثیر مستقیمی بر مشتریان دارد و اگر به درستی انجام نشود، تأثیر نامطلوبی بر آن‌ها خواهد داشت.