API versiyalash va kontrakt mosligi

TL; DR

Uyg’unlik - bu muvaffaqiyat emas, balki intizomdir. Aniq versiya siyosatini (SemVer), o’zgarishlar matematikasini (buzadigan narsa), kontrakt testlarini, sxema registrlarini va Sunset-protseduralarini saqlang. Pul va komplayens uchun - vN bilan qat’iy REST/gRPC, UI-agregatsiyalar uchun - evolyutsion GraphQL s’@deprecated’. Har doim: kanar trafigi, teskari moslik ≥ bitta reliz sikli, migratsiya gaydalari, dalalardan foydalanish telemetriyasi.

1) Bazaviy tushunchalar va maqsadlar

Backwards-compatible (BC): yangi serverga eski mijozlar mos keladi.
Forwards-compatible (FC): eski serverga yangi mijozlar mos keladi (cheklangan).
Wire mosligi: «sim» formati buzilmaydi (ayniqsa gRPC/Protobuf uchun muhim).
SemVer: `MAJOR. MINOR. PATCH’- shartnomani buzasiz → MAJORni oshirasiz.

Maqsad: buzuvchi o’zgarishlarni kamaytirish va oldindan aytib bo’ladigan migratsiya oynalarini ta’minlash.

2) O’zgarishlar matritsasi: nima mumkin va nima mumkin emas

Oʻzgartirish turi	REST	gRPC (Protobuf)	GraphQL
Maydonni qoʻshish (response)	+ xavfsiz	+ xavfsiz (yangi field number)	+ xavfsiz
Ixtiyoriy maydonni qoʻshish (request)	️ agar server mavjud boʻlmasa	+ xavfsiz	+ xavfsiz
Maydonni olib tashlash	- sinuvchi	- agar raqamdan qayta foydalansangiz	️’@deprecated’orqali → oynadan keyin olib tashlash
Maydonning nomini oʻzgartirish	- sinuvchi	- (ismingizni, raqamingizni o’zgartiring)	️ alias/vaqtinchalik ikkita maydon
Turi/formatini oʻzgartirish	- sinuvchi	- wire-turi o’zgarganda	- sxemani buzsa
Maqom/xato semantikasini oʻzgartirish	- sinuvchi	- kod/tafsilotlar - kontrakt	- mijozlarni sindiradi
Enum tartibini oʻzgartirish	️ qiymati boʻyicha xavfsiz	️ agar enum raqamlari barqaror boʻlsa	+ nomi xavfsiz
Yangi endpoint/usullar	+ xavfsiz	+ xavfsiz	+ xavfsiz
Paginatsiya/filtrlarni oʻzgartirish	️ Ehtiyotkorlik bilan, variantlarni qoʻshing	+ yangi maydonlar orqali	+ yangi dalillar orqali

3) Turli uslubdagi API siyosati

3. 1 REST

URI (’/v1/...’) yoki domendagi (’api-v1.’) versiyasi. Sarlavha versiyasi - faqat ichki holatlar uchun.
Qoʻshing, oʻchirmang: yangi maydonlarni - tamom, eskisini - sxemada «deprecated» deb belgilang va kamida bir marta qoldiring.
Holatlar/xatolar:’error’kodlari va tuzilishini oʻzgartirmang. code/error. message/error. details`.
Dempotentlik o’zgarmaydi: xavfsiz’POST’s’Idempotency-Key’ni «xulq-atvor jihatdan boshqacha» chaqiruvga aylantirmang.

3. 2 gRPC / Protobuf

Dala raqamlari muqaddasdir: masofadagi raqamlarni qayta ishlatmang,’reserved’deb belgilang.
Faqat yangi optional/repit maydonlarini qoʻshish; «qattiq majburiy» - validatsiya orqali,’required’emas.
Version paketlar:’payments. v1`, `payments. v2`.
Xizmatlarning mosligi: yangi RPC → yangi usul; keksalarning xatti-harakatlarini o’zgartirmaymiz.

proto message Payout {
reserved 4 ;//field deleted, number reserved string id = 1;
string currency = 2;
int64 amount_minor = 3;
// v2: optional string comment = 5;
}

3. 3 GraphQL

v2 bo’lmagan evolyutsiya: maydonlarni/turlarni qo’shing; o’chirish -’@deprecated (reason)’oynasi orqali.
Persisted Queries: Ochiq mijozlar uchun oq so’rovlar ro’yxatidan foydalaning - muvofiqlikni nazorat qilish osonroq.
Field-level authZ va telemetriya: oʻchirishdan oldin qaysi maydonlardan foydalanilayotganini biling.

graphql type Payout {
id: ID!
amountMinor: Long!
currency: String!
comment: String @deprecated(reason: "Use note")
note: String
}

3. 4 Vebxuki

Yo’ldagi versiya (’/webhooks/v1/payments’) va voqeaning qat’iy konvertidir (’event _ id’,’type’,’ts’,’data’).
Imzolaringizni/NMASni o’zgarishsiz saqlang; yangi algoritmlar - bayroqli variant kabi.
Kengaytmalar faqat yangi’data’va’headers’maydonlari orqali eskisini olib tashlamaydi.

4) Gateway API va versiyalarni yo’naltirish

Rules-based routing: ’/v1’prefiksi bo’yicha,’X-Api-Version’sarlavhasi bo’yicha, domen bo’yicha.
Shadow/Canary: prodakshn trafigining bir qismini yangi versiyaga «soyada» aks ettiring, javoblarni solishtiring.
Rate/Quotas per-version: migratsiya paytida eski mijozlarni himoya qiladi.

REST uchun Sunset headers:

’Sunset: ’ - versiyasi oʻchirilgan sana
’Deprecation: true’ - versiyasi eskirmoqda
`Link: ; rel = «deprecation»’- changelog/gaid migratsiyasiga

Misol (Nginx-style, soddalashtirilgan):

nginx location ~ ^/v2/ {
proxy_pass http://api_v2;
}
location ~ ^/v1/ {
add_header Deprecation "true";
add_header Sunset "Thu, 01 May 2026 00:00:00 GMT";
proxy_pass http://api_v1;
}

5) Sxemalar registrlari va kontraktlar

OpenAPI / JSON Schema для REST; Protobuf descriptors для gRPC; SDL registry для GraphQL.
CI-tekshirishlar: linters + PRda «breaking-changes check».
Consumer-Driven Contracts (CDC): iste’molchilar testlari (Pact/analog) - ko’rinmas sinishlardan himoya qilish.
Changelog: machine-readable (masalan,’CHANGELOG. md’+ reyestrdagi reliz-notalar).

6) Dalalar evolyutsiyasi: amaliy qoidalar

ID/kalitlar:’_ v2’yangi maydonisiz va oʻtish davrisiz formatni (UUID, int) oʻzgartirmang.
Vaqt/valyuta: UTC ISO-8601/epoch va amount_minor + currency; oʻlchamini oʻzgartirmang (tiyin/sent).
Enum: qiymatlarni qoʻshing - tamom; eskilarining maʼnosini oʻzgartirmang. REST uchun - ints emas, string qiymatlarini bering.
Paginatsiya: cursor-based barqarorroq; kursorning semantikasini oʻzgartirmang.

7) Deprikatsiya va «Sunset» protsedurasi

1. E’lon (T-90/60): changelog, sheriklarga yuborish, «Deprecation/Sunset» sarlavhalari.
2. Takrorlanuvchi davr: V1 va V2 parallel ishlaydi; V1 javoblar/loglarda ogohlantirishlar bilan jihozlangan.
3. Foydalanish telemetriyasi: V1 ni yana kim chaqiradi? nuqtaviy aloqalar.
4. V1 muzlatish: faqat bagfiks/fichsiz.
5. Oʻchirish (Sunset): 410 Gone yoki koʻchirish yoʻriqnomasi bilan blok sahifa.

8) Og’riqsiz relizlar: joylashtirish strategiyasi

Blue/Green yoki Weighted routing: 1-5-25-50-100% trafik.
Compatibility window: tashqi API uchun kamida 1-2 minor reliz, ko’proq 6-12 oy.
Feature Flags: yangi mantiq maydonlarini/filiallarini versiyani oʻzgartirmasdan yoqish uchun.
O’qish/Yozish-bo’linish: avval yangi maydonni o’qish uchun qo’llab-quvvatlashni qo’shing, so’ngra uni yozishni boshlang.

9) Muvofiqlikni sinovdan o’tkazish (amaliyot paketi)

Eski versiyalar uchun Golden-testlar.
Sxemalarning diff-testlari: CI’da breaking taqiqlanadi.
V2 (shadow) uchun replay prodakshn-trassasi.
Back/Forward stsenariylari: eski serverda yangi mijoz va aksincha (FC boʻlganda).
Vebxuklarning kontrakt testlari: imzo, format, vaqtni tekshirish.

10) Versiyalash jarayoni metrikasi va SLO

Oxirgi MINORdagi mijozlar% (maqsad Sunset oldidan 80% ≥).
Chiqarish uchun mos kelmaslik xatosi (maqsad - 0).
Eskirgan qoʻngʻiroqlar ulushi (Sunsetga nisbatan kamayib boruvchi).
Mijozning migratsiya vaqti (median/p95).
Versiyalar orasidagi Latency/regression delta (bazadan yomon emas).

11) Artefaktlar namunalari

OpenAPI (fraqment, maydon deprikatsiyasi):

yaml components:
schemas:
Payout:
type: object properties:
id: { type: string, format: uuid }
amount_minor: { type: integer }
currency: { type: string }
comment:
type: string deprecated: true description: "Use note"
note: { type: string }

Protobuf (reserved va v2 paket):

proto syntax = "proto3";
package payouts. v1;
message Payout { reserved 5; string id=1; int64 amount_minor=2; string currency=3; }

GraphQL (deprikatsiya):

graphql type Query { payout(id: ID!): Payout }

12) Turdosh kanallarni versiyalash

SDK/CLI: SemVer + API versiyasiga bogʻliqligi, mosligi READMEda kelishilgan.
Hodisalar/oqimlar (WS/Kafka): v’envelope versiyasi. version`; yangi atributlar - opsion; dedup va rezyum versiyalar o’rtasida bir xil ishlaydi.
Hisobot/CSV: fayl/shapka nomidagi versiya; oʻngdagi ustunlarni qoʻshing; tartib/turlarni o’zgartirmang.

13) Governance va rollar

Shartnoma egasi (domain owner), API Steward (qoidalar va linterlar), Release Manager (Sunset/kommunikatsiyalar).
Breaking-o’zgarishlar uchun RFC jarayoni: biznes asoslari, migratsiya rejasi, artefaktlar, sanalar.
Yagona API katalogi: sxemalar, versiyalar, Sunset kalendari, aloqa koʻrinadi.

14) Anti-patternlar

«Jim» buzilishlar: status/xato/dala turini versiyasiz oʻzgartiramiz.
Protobuf raqamlaridan qayta foydalanish eski mijozlarni ham buzadi.
Telemetriyasiz GraphQL - «teginish» ni olib tashlash.
Global v2 - nuqtaviy evolyutsiya o’rniga megamigratsiya.
Ommaviy API uchun query-parametrdagi versiya - noaniq va zaif sxema.
Migratsiya gaydalari va misollari yo’q - sheriklar to’xtab qoladi, muddatlar buziladi.

15) Check-list reliz yangi versiyasi

Sxema yangilandi (OpenAPI/Protobuf/SDL), linterlar va breaking-checks oʻtildi.
Integratsiya va shartnoma testlari (CDC) qoʻshildi.
SDK/kod namunasi/migratsiya gid va Changelog tayyor.
«Deprecation/Sunset» (eski versiya uchun) + «How to migrate» sahifasi kiritilgan.
Canary/Shadow rejasi, alertlar va metrik taqqoslash dashbordlari.
Teskari muvofiqlik kelishilgan muddatga saqlanib qoldi.
Qaytish rejasi (rollback) va xavf matritsasi kelishilgan.

Xulosa

Barqaror API - bu «abadiy» emas, balki jarayon. Quyidagi qoidalarga amal qiling: SemVer + add-only evolyutsiya + sxemalar registri + kontrakt testlari + Sunset-protseduralar. Stillarni (REST/gRPC/GraphQL) va ularning siyosatini ajrating, API Gateway versiyalarini yoʻnaltiring, kanareykalar bilan aylantiring, effektni oʻlchang. Shunday qilib, siz «kutilmagan hodisalarni» oldini olasiz, hamkorlarning integratsiyasini tezlashtirasiz va pul va komplayens-tanqidiy domenlar uchun oldindan aytib bo’ladigan darajada bo’lasiz.

API versiyalash va kontrakt mosligi

TL; DR

Xulosa

Biz bilan bog‘laning

Tez aloqa

Video tez orada yangilanadi

Hozir loyihalar bilan juda bandmiz