REST API'ni versiyalash: nega va qanday

API'ingizni boshqa ilovalar ishlatishni boshlagach, uni o‘zgartirish xavfli bo‘ladi: bitta o‘zgarish yuzlab mijozni buzishi mumkin. Versiyalash — bu muammoni yechadi: eski mijozlar ishlab tursin, siz esa yangilikni qo‘shing.

Nega kerak#

Faraz qiling, javob formatini o‘zgartirdingiz:

// Eski
{"name": "Ali Valiyev"}
// Yangi
{"first_name": "Ali", "last_name": "Valiyev"}

Eski mijozlar name maydonini kutadi — ular endi buziladi. Versiyalash bilan eski v1 o‘zgarmaydi, yangilik v2'da chiqadi.

Asosiy usullar#

1. URL'da versiya (eng ko‘p tarqalgan):

GET /api/v1/users/
GET /api/v2/users/

Sodda, ko‘rinarli, keshlash oson. Ko‘pchilik shuni tanlaydi.

2. Sarlavhada versiya:

GET /api/users/
Accept: application/vnd.myapp.v2+json

Toza URL, lekin ko‘rinmas — sinash qiyinroq.

Qachon yangi versiya kerak#

Faqat buzuvchi o‘zgarish (breaking change) uchun: - Maydonni o‘chirish yoki nomini o‘zgartirish - Javob strukturasini o‘zgartirish - Majburiy parametr qo‘shish

Buzmaydigan o‘zgarishlar uchun yangi versiya shart emas: - Yangi ixtiyoriy maydon qo‘shish - Yangi endpoint qo‘shish

Amaliy maslahatlar#

• Eski versiyani darhol o‘chirmang — mijozlarga ko‘chib o‘tish uchun vaqt bering.
• Deprecation e'lon qiling — sarlavha yoki hujjatda "bu versiya X sanada o‘chadi" deb yozing.
• Ko‘p versiyani cheksiz saqlamang — har biri texnik qarz. Odatda 2 tasi yetarli.

Versiyalashni boshidan rejalashtiring — hatto birinchi versiyani ham /v1/ deb chiqaring. Bu kelajakdagi o‘zingizga sovg‘a bo‘ladi.