✍️ Massimo Dev

🔵⚪️ نسخه‌بندی API یا API Versioning میدونی چیه؟

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

✳️ بذار یه مثال ساده بزنم:

فرض کن یه API داری که اطلاعات آب و هوا رو می‌ده. اولین نسخه‌ی API (v1) یه اندپوینت داره به اسم
/weather
که اطلاعات ساده‌ای مثل دما و رطوبت رو برمی‌گردونه.

نسخه 1 (v1):

GET /v1/weather?city=London
Result:
{
"temperature": "15°C",
"humidity": "75%"
}

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

نسخه 2 (v2):

GET /v2/weather?city=London
Result:
{
"temperature": "15°C",
"humidity": "75%",
"wind_speed": "10 km/h",
"forecast": [
{"day": "Monday", "temperature": "16°C"},
{"day": "Tuesday", "temperature": "17°C"}
]
}

به این ترتیب، کاربرهایی که از نسخه قدیمی (v1) استفاده می‌کنن همچنان بدون تغییر به کارشون ادامه می‌دن و کاربرهای جدید می‌تونن از ویژگی‌های جدید نسخه 2 (v2) استفاده کنن.

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

🔹نسخه‌بندی URL:
- شماره نسخه رو توی مسیر URL قرار بده، مثل
/v1/resource
و
/v2/resource
- مثال:
GET /api/v1/weather،
GET /api/v2/weather.

🔹نسخه‌بندی با هدرها:
- از هدرهای سفارشی برای مشخص کردن نسخه استفاده کن.
- مثال:
GET /api/weather
با
headers: {"API-Version": "v2"}

🔹نسخه‌بندی با پارامترهای کوئری:
- شماره نسخه رو به عنوان پارامتر کوئری قرار بده.
- مثال:
GET /api/weather?version=2

🔹استراتژی پایان‌دهی به نسخه‌های قدیمی:
- به کاربرها بگو که نسخه قدیمی چه زمانی غیرفعال می‌شه و راهنمایی برای مهاجرت به نسخه‌های جدید بده.
- یه بازه زمانی مشخص و راهنمای مهاجرت ارائه کن.

🔹مستندسازی:
- برای هر نسخه از API مستندات واضح و دقیقی فراهم کن.
- مثال‌ها، موارد استفاده و راهنماهای مهاجرت رو توضیح بده.

🔹سازگاری با نسخه‌های قبلی:
- تا حد ممکن نسخه‌های جدید رو سازگار با نسخه‌های قبلی نگه دار تا کاربرها دچار مشکل نشن.
- از نسخه‌بندی معنایی (مثل major.minor.patch) استفاده کن تا سطح تغییرات رو نشون بدی مثلا نسخه ،29.5.0 شده 29.5.1

🔹سیاست نسخه‌بندی:
- یه سیاست نسخه‌بندی تعریف کن که مشخص کنه کی و چطور نسخه‌های جدید منتشر می‌شن.
- واضح بگو که چه زمانی تغییرات بزرگ نیاز به یه نسخه جدید دارن.

Source:
@gopher_academy

#api_versioning

@Syntax_fa