API va yangilanish mosligi

1) Muvofiqlikning bazaviy prinsiplari

Additive-first: eskisini buzmasdan yangisini qoʻshing (yangi opsion maydonlari/endpointlar, yangi enum qiymatlari).
Barqaror kontraktlar: «spetsifikatsiyada va’da qilingan narsa ishlayapti»; xulq-atvori hujjatlashtirilgan.
Backward> Forward: teskari moslashuv ustuvorligi; forward tolerant-readers orqali ruxsat etiladi.
Hujjatlar birlamchi: haqiqatning yagona manbai - registry (OpenAPI/AsyncAPI/Proto) dagi sxema versiyasi.
Aniq evolyutsiya: breaking - faqat yangi major versiyasi va migratsiya qo’llanmasi orqali.

2) O’zgarishlar taksonomiyasi

2. 1 Mos keladi (MINOR/PATCH)

Variant maydonlari/xederlar, yangi endpointlar, defoltlar bilan query-parametrlarni qoʻshish.
Limitlarni oshirish (’page _ size’, TTL), kodlarni/semantikani oʻzgartirmasdan xatolarni aniqlashtirish.
Agar mijozlar «notanish» (tolerant-reader) ni eʼtiborsiz qoldirsalar, enum qiymatlarini qoʻshish.

2. 2 Noaniq (Behavioral)

Defoltlar, saralash tartibi, nozik taymautlar, kvotalarning o’zgarishi biznes-mantiqni «buzishi» mumkin. RFC + eʼlon va kanareykalarni talab qiladi.

2. 3 Sinuvchi (MAJOR)

Maydonlarni qayta nomlash/olib tashlash, turi/formatini o’zgartirish, xato kodlarini almashtirish, kontraktlar/autentifikatsiya sxemalarining teskari nomuvofiqligi.

3) Versiyalash siyosati

Strategiya:’path versioning’(’/v1’, ’/v2’).
Minor/patch: «qo’shing, buzmang».

Manba: ’X-API-Version-Date ’

Media turlari (ops.) : `Accept: application/vnd. acme. v1 + json’ingichka granulyatsiya uchun.

4) Deprekatsiya va sunset

4. 1 Kommunikatsiya sarlavhalari

Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"

4. 2. Olib chiqish tartibi

1. Portal/tarqatish/SDK release notes.
2. Ogohlantirish oynasi ≥ 90-180 kun.
3. Adoption dashbordidagi holatlar.
4. Agar kelishilgan bo’lsa, sunset - 410 Gone yoki grace davri uchun «read-only» rejimidan keyin.

5) Migratsiya va birgalikda yashash versiyalari

O’tish davrida dual-write/dual-o’qish va hisobotlar bilan solishtirish.
Adapterlar (vaqtinchalik): eski payload’ning gateway-konvertatsiyalari → yangi sxemalar; adapterning umr ko’rish muddati cheklangan.
SDK yordami: ikkala versiyani qoʻllab-quvvatlovchi relizlar, deprekatsiya ogohlantirishlari bilan (har bir jarayonda 1 marta).
Ficha bayroqlar: kalitlar/tenantlar roʻyxati boʻyicha yangi semantikani kiritish.

6) Backward va forward mosligi

6. 1 Backward (eski mijozlar yangi server)

Turlar/majburiyat formatini oʻzgartirmaslik.
Yangi maydonlar faqat ixtiyoriydir.
Xatolar avvalgi’error _ code’, yangi kodlarni qoʻshish, almashtirish mumkin emas.

6. 2 Forward (eski serverning yangi mijozlari)

’OPTIONS ’/’/versions’ orqali imkoniyatlar mavjudligini tekshirish.
Greys-xulq-atvor: Mijoz yo’q fichlarga nisbatan sabr-toqatli bo’lishi kerak.

7) Kontraktlar va avtomatik tekshirishlar

Registry: sxemalar versiyasini saqlayapmiz; PR-diflar → «breaking/non-breaking» hisobotlari.
Linter: nomlar/turlar, idempotentlik, paginatsiya, barqaror kodlar.
CDC (Consumer-Driven Contracts): provayderning CI (Pact va analoglar) dagi integrator testlari.
Gate: PR’major bump ’/RFC’siz breaking’da bloklanadi.

yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml

8) Kanar chiqarish va orqaga qaytish

Canary: 10% → 25% → 50% → 100% trafik; SLO yomonlashganda avto-orqaga qaytish (5xx/latency/429).
Beta kalitlari: allowlist uchun yangi versiyalarga kirish.
Release freeze: error-budget yonganda.
Qabul qilish tahlili: yangi versiyadagi trafikning/mijozlarning ulushi, migratsiya vaqti.

9) Tafsilotlarda moslik: xatolar, paginatsiya, idempotentlik

9. 1 Xato

Mavjud skriptlardagi HTTP maqomlarini oʻzgartirmaslik.
’error _ code’ - barqaror; Yangi kodlarni faqat qoʻshish.
’application/problem + json’ - yagona format.

9. 2 Paginatsiya

Agar eski’offset/limit’qoʻllansa, cursor/keyset = MINOR ga oʻtish.
Kursorning’updated_at,id’va barqarorligini hujjatlashtiring.

9. 3 Idempotency

write uchun -’Idempotency-Key’+’409 IDEMP_REPLAY'.
Migratsiyalar idempotentlik semantikasini o’zgartirmasligi kerak.

10) Gateway-transformatsiya (o’rinli bo’lganda)

Map v1 → v2 maydonlar, xatolarni normallashtirish, sana/pul formatlarini konvertatsiya qilish.
Guardrails: transformatsiyalar shaffof va mantiqiy; breaking’ni yashirmang, lekin muddati cheklangan ko’prik sifatida ishlating.

11) Kommunikatsiyalar va portal

Changelog с датами (`added/changed/deprecated/removed/fixed`).
Versiya kartochkasi: maqomi (beta/GA/deprecated), sanasi sunset, gaydaga havolalar.
Ogohlantirish vebxuklari:’deprecation. notice`, `version. released`, `plan. change`.
Portalda SDK release notes + banner.

12) Muvaffaqiyat metrikasi

Adoption rate v2 (so’rovlar/mijozlar bo’yicha).
Backward-compat incidents («sinish» soni).
Error mix (ulushlar 4xx/5xx/429) relizdan oldin/keyin.
Time-to-Adopt mediana.
Support load (tiketlar/hafta).
Cost-to-Serve (chaqiruv uchun infratuzilma qiymati).

13) Namunalar va misollar

13. 1 Versiyalar va depreksiyalar sarlavhalari

X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"

13. 2 Versiyalar siyosati (YAML fragmenti)

yaml versioning:
strategy: "path"
compatibility:
minor: "additive-only"
patch: "bugfix/perf, no schema change"
deprecation:
min_notice_days: 120 rollout:
canary_steps: [10,25,50,100]
rollback_checks: ["5xx_rate","p95_latency","429_rate","adoption"]

13. 3 OpenAPI: mos keladigan maydon qoʻshish

yaml components:
schemas:
Report:
type: object required: [id, createdAt]
properties:
id: { type: string }
createdAt: { type: string, format: date-time }
cursor: { type: string, description: "optional for v1. 2+" } # additive

14) Reliz chek-varaqasi (MINOR/MAJOR)

MINOR

• DIFF: non-breaking, yashil linter
• Hujjatlar/SDK yangilandi (misollar/kodeklar)
• Kanareyka + SLO bo’yicha avtotransport
• Komm-reja, portaldagi sahifasi
• Adoption va xato dashbordlari

MAJOR

• RFC/ADR, sana sunset va oyna ≥ 90-180 kun
• v1 v2 ko’prik (gateway) va migratsiya qo’llanmasi
• Dual-write/o’qish va solishtirish
• SDK ikkala API + ogohlantirishlar bilan
• Asosiy integratorlar bilan uchuvchi

15) Joriy etish rejasi (3 ta iteratsiya)

1. Poydevor (2 hafta):

CIdagi sxemalar, lint va auto-diff registry; muvofiqlik siyosati; «Deprecation/Sunset» sarlavhalari.

2. Boshqariladigan relizlar (3-4 hafta):

Kanareykalar, ficha-bayroqlar, SLO-alertlar; versiyalar portali; 2 ta filialni qo’llab-quvvatlaydigan SDK-relizlar.

3. Avtomatlashtirish va masshtab (uzluksiz):

CDC testlari, adoption trendlari bo’yicha sunset prognozi, avtomatik notifikatsiyalar va eslatmalar.

16) Mini-FAQ

Maydon turini majorsiz oʻzgartirish mumkinmi?
Yo’q. Hatto «satr → son» - breaking. Yangi maydonni kiriting, eskisini deprecate.

Enum: qiymatlarni qoʻshish mumkinmi?
Ha, agar mijozlar tolerant-readers bo’lsa. Aks holda, avval ogohlantirish va beta.

Eski versiyani qancha saqlash kerak?
Hozircha yangi ≥ adoption 95% va deprekatsiya oynasi saqlangan. Siyosatda muddatni belgilang.

Jami

APIning muvofiqligi - bu intizom: additive-yondashuv, rasmiy sxemalar va diflar, kanar relizlari, aniq deprekatsiyalar va boshqariladigan migratsiyalar. O’zgarishlar siyosatini o’rnating, tekshirish va kommunikatsiyalarni avtomatlashtiring, adoption o’lchang va yangilanishlaringiz mijozlarni buzishni to’xtatadi va evolyutsiya tezligi ishonchni yo’qotmasdan o’sadi.