نسخه بندی API: پنج اشتباه رایجی که بعداً گران تمام می شود

نسخه بندی API: پنج اشتباه رایج و راه جلوگیری ازشون

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

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

اول ببین چی «تغییر شکننده» حساب می شه

خیلی از دعواها سر همین شروع می شه که تیم بک اند فکر می کنه تغییرش کوچیکه و تیم اپ موبایل می بینه اپش از کار افتاده. این جدول یه معیار ساده بهت می ده:

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

اشتباه اول: «فعلاً نسخه لازم نیست»

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

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

راه درست: از روز اول /v1 رو توی مسیر بذار. هزینه اش تقریباً صفره و بعداً جلوی یه هزینه بزرگ رو می گیره.

نسخه بندی API از کجا شروع می شه: مسیر، هدر یا پارامتر؟

سه روش رایجه:

• مسیر: /api/v1/orders. ساده ترین و قابل دیباگ ترین روشه. توی مرورگر، لاگ و مستندات یه نگاه می فهمی کدوم نسخه است.
• هدر: مثلاً Accept: application/vnd.myapp.v2+json. تمیزتره، ولی تست دستی و کش کردن سخت تر می شه.
• پارامتر: /orders?version=2. زود جواب می ده، ولی کنترلش از دستت در می ره و پارامتر رو راحت فراموش می کنن.

برای بیشتر کسب و کارهای کوچک و متوسط، مسیر انتخاب بهتریه. فقط وقتی یه روش رو انتخاب کردی، سر همون بمون. ترکیب کردنشون بعداً کابوسه.

یه نکته درباره شماره: فقط شماره اصلی (v1, v2) رو توی نشانی بذار. تغییرهای سازگار مثل اضافه شدن فیلد نباید نسخه جدید بسازن. اگه برای هر تغییر کوچیک v3.1.4 بسازی، کسی نمی تونه ردش کنه.

اشتباه دوم: تغییر بی صدا توی همون نسخه

یه فیلد رو توی v1 عوض می کنی و با خودت می گی «همین یه مورده، کسی متوجه نمی شه».

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

چرا این بده؟ چون خطایی ثبت نمی شه و هشداری هم نمی بینی. مشتری ها یا حسابدار مشکل رو پیدا می کنن، نه سیستم مانیتورینگ تو. این بدترین نوع باگه، چون هم پول رو می بره هم اعتماد رو.

برای جلوگیری:

1. هر چیزی که توی جدول بالا «شکننده» بود، فقط توی نسخه جدید بیاد.
2. اگه واحد یا معنی یه فیلد عوض می شه، اسمش رو هم عوض کن. مثلاً amount_rial و amount_toman، نه amount با دو معنی.
3. فیلد قدیمی رو توی v1 دست نزن و فیلد جدید رو توی v2 بذار.
4. برای فهرست های ثابت مثل status، از همون اول توی مستندات بنویس که مقدار جدید ممکنه اضافه بشه. مشتری باید برای مقدار ناشناس یه رفتار پیش فرض داشته باشه.

اشتباه سوم: حذف ناگهانی نسخه قدیمی

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

برای جلوگیری، یه برنامه بازنشستگی مشخص لازم داری، با سه جزء:

• اعلام زودهنگام: تاریخ پایان رو چند ماه قبل بگو. زمانش به مشتری هات بستگی داره. اگه مشتریت اپ موبایل داره، زمان بیشتری بده.
• هشدار توی خود پاسخ: فقط به ایمیل تکیه نکن، چون ایمیل گم می شه. توی هدر پاسخ هم هشدار بذار.
• اندازه گیری مصرف: قبل از خاموش کردن، ببین کی هنوز v1 رو صدا می زنه.

نمونه هدرها:

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jan 2026 00:00:00 GMT
Link: <https://example.ir/docs/migrate-v2>; rel="deprecation"

Sunset تاریخ خاموش شدن رو می گه و Deprecation نشون می ده نسخه منسوخه. تاریخ بالا فقط نمونه است و فرمت دقیق مقدار Deprecation رو قبل از استفاده با استاندارد فعلی چک کن. نکته اش اینه که مشتری فنی می تونه این هدرها رو خودکار بخونه و هشدار بگیره.

برای اندازه گیری مصرف، کافیه توی لاگ دسترسی (access log) مسیرها رو بر اساس نسخه بشماری. اگه مانیتورینگ داری، یه داشبورد ساده «تعداد درخواست به /v1 در روز» کافیه. اگه می خوای این بخش رو به یه تیم بسپاری، مانیتورینگ و پایداری این کار رو پوشش می ده.

دو نسخه کنار هم، بدون دردسر

اجرای همزمان v1 و v2 سخت نیست. می تونی هر نسخه رو توی یه کانتینر جدا بالا بیاری (اگه هنوز داکر نصب نکردی، چک لیست نصب داکر روی اوبونتو رو ببین) و با nginx مسیرها رو جدا کنی:

location /api/v1/ {
    proxy_pass http://127.0.0.1:8001;
}

location /api/v2/ {
    proxy_pass http://127.0.0.1:8002;
}

پورت ها فقط نمونه اند. فایده اش اینه که باگ یا خرابی توی v2 تا حد زیادی به v1 نمی رسه و هر نسخه رو جدا می تونی برگردونی. فقط اگه هر دو به یه دیتابیس وصلن، تغییر ساختار جدول ها رو جوری انجام بده که هر دو نسخه باهاش کار کنن.

ایده توی استقرار هم همینه: نسخه قبلی رو همیشه دم دست نگه دار تا برگشت به عقب ارزون و سریع باشه.

اشتباه چهارم: قرارداد فقط توی ذهن تیم بک اند

رفتار API فقط توی کد و ذهن توسعه دهنده است. مستندات یا قدیمیه یا اصلاً نیست. نتیجه اش اینه که هیچ کس دقیق نمی دونه کدوم تغییر شکننده است و بررسی هر انتشار می شه حدس و گمان. وقتی توسعه دهنده عوض بشه، دانش هم می ره.

چیکار کنی:

1. یه فایل مشخصات (مثلاً OpenAPI) کنار کد نگه دار و هر نسخه رو جدا بنویس.
2. توی فرایند انتشار، مشخصات نسخه جدید رو با نسخه قبلی مقایسه کن. ابزارهایی هستن که تغییر شکننده رو خودکار پیدا می کنن. قبل از اینکه بهشون تکیه کنی، خودت یکی رو امتحان کن.
3. یه فایل changelog ساده بذار: تاریخ، نسخه، چی اضافه شد، چی منسوخ شد.
4. چند تست قراردادی بنویس که پاسخ v1 رو با یه نمونه ثابت مقایسه کنن. اگه تست شکست، یعنی کسی v1 رو خراب کرده.

این تست ها ارزون ترین بیمه ای هستن که می تونی داشته باشی. اگه تیمت کوچیکه و وقت نداری، حتی ۵ تا تست برای مهم ترین endpointها بهتر از هیچیه.

اشتباه پنجم: نسخه جدید برای هر چیز کوچیک

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

راه درست ساده است:

• تغییر سازگار (فیلد جدید، endpoint جدید) رو توی همون نسخه منتشر کن.
• تغییرهای شکننده رو جمع کن و یکجا توی یه نسخه اصلی جدید بیار.
• معمولاً بیشتر از دو نسخه فعال همزمان نگه نداشته باش.

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

سوالات متداول

آیا API داخلی هم باید نسخه بندی بشه؟

اگه فقط یه تیم هم بک اند رو می نویسه هم فرانت رو و هر دو همیشه با هم منتشر می شن، می تونی ساده تر بگیری. ولی همین که یه اپ موبایل وارد بازی بشه، شرایط عوض می شه، چون نسخه های قدیمی اپ روی گوشی کاربرها می مونن. بهتره /v1 رو از اول بذاری، چون هزینه اش تقریباً صفره.

چقدر باید نسخه قدیمی رو زنده نگه دارم؟

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

اضافه کردن یه فیلد جدید هم نسخه جدید می خواد؟

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

اگه مشتری ها نسخه جدید رو قبول نکنن چی؟

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

قبل از انتشار بعدی، این پنج مورد رو چک کن

نسخه بندی API یه کار بزرگ نیست، یه عادته. این پنج مورد رو بررسی کن:

1. نسخه توی مسیر هست (/v1).
2. هیچ تغییر شکننده ای بدون نسخه جدید منتشر نمی شه.
3. نسخه های منسوخ هدر Deprecation و Sunset دارن.
4. یه فایل مشخصات و یه changelog به روز وجود داره.
5. می دونی هر نسخه امروز چند درخواست می گیره.

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