Texnologiyalar va infratuzilma → API versiyalash

API versiyasi

1) Nima uchun bu zarur?

• relizlarda hodisalar xavfini kamaytiradi,
• yaxshilanishlar va xavfsizlikni rejali joriy etish imkonini beradi,
• biznesga sheriklar migratsiyasining bashorat qilinadigan muddatlarini beradi.

2) O’zgartirishlar tasnifi

PATCH (buzilmaydigan): kontraktni o’zgartirmasdan tuzatishlar (ixtiyoriy maydonlarni qo’shish, validatsiya fikslari).
MINOR (kengaytiruvchi): back-compatible kengaytmalar (yangi endpointlar, default bilan maydonlar).
MAJOR (buzuvchi): strukturani, semantikani o’zgartirish yoki maydon/endpointlarni olib tashlash.

SemVer’MAJOR tavsiya etiladi. MINOR. Artefaktlar uchun PATCH’lar (SDK/sxemalar), bunda API «tashqi» raqami soddalashtirilishi mumkin (v1, v2).

3) REST versiyalash modellari

1. URIDA:

`GET /v1/payments/{id}`

Afzalliklari: shaffof, keshlash, yo’naltirish oson. Kamchiliklar: hujjatlarni takrorlash, nozik evolyutsiya qilish qiyinroq.

2. Sarlavhalarda (content negotiation):

`Accept: application/vnd. company. payments. v2+json`

Afzalliklari: moslashuvchanlik, URLda «axlat» yo’qligi, mediatipning qulay evolyutsiyasi. Kamchiliklari: brauzerda bahslashish qiyinroq, intizomli mijoz kerak.

3. Kastom sarlavhasida:

`X-API-Version: 2` (или `Api-Version: 2025-09-01`)

Afzalliklari: shunchaki shlyuzda. Kamchiliklar: standart yo’q, keshga ehtiyot bo’ling.

4. Versiya-sana (date-based):

Fintech/hisobot uchun yaxshi: o’zgarishlarning prognoz qilinadigan «kesmalari» (masalan, har chorakda).

5. Resurs/model versiyasi:

Tavsiya: tashqi integratsiyalar uchun -’URI vN’+ Deprecation/Sunset sarlavhalari; ichki uchun - agar shlyuz va platforma buni qo’llab-quvvatlasa,’Accept’yoki versiya sarlavhasi mumkin.

4) GraphQL

Afzallik - global versiyalarsiz. Maydonlarni/turlarni qoʻshish va deprikatsiya orqali evolyutsiya (’@deprecated (reason: «»...)’).
Buzuvchi o’zgarishlar - faqat migratsiya gaydasi bo’lgan «katta» derazalarda (versioned schema namespace).
«n + 1» ga va mavjud maydonlarning meaning oʻzgarmasligiga eʼtibor bering.

5) gRPC / Protobuf

Maydon raqamlari o’zgarmaydi. Masofadagi maydonlarni’reserved’deb belgilang.
Xavfsiz default bilan maydonlarni optional sifatida qoʻshing.
Moslashuvchanlikni avtomatik tekshirish uchun buf breaking/lint’dan foydalaning.
Paket/modullarni versiya qiling:’package payments. v1;` → `payments. v2`.

6) Voqealar API (EDA)

Tadbir sxemasi - xuddi shunday kontrakt. Uni Schema Registry (Euro/JSON-Schema/Protobuf) da saqlang.
Topiklar va versiyalar:’payments. v1. authorized`, `payments. v2. authorized`.
Buzuvchi oʻzgarishlar - yangi hodisa turi yoki yangi topik.
Evolyutsiya kafolatlari: LTS davrida konsumerlar uchun backward-compatible.

7) Deprikatsiya va EOL siyosati

• Deprecation: changelog va spetsifikatsiyadagi belgilar (OpenAPI/GraphQL SDL), sarlavha
• ’Deprecation: true’ va mumkin bo’lganda’Sunset: Tue, 31 Mar 2026 00:00:00 GMT’.
• Kommunikatsiyalar: email/portal sherigi, webhooks-bildirishnomalar, release notes.
• Muddatlari: MINOR - 3-6 oy, MAJOR - 9-18 oy (tanqidiyligiga bog’liq).
• Vaqt oynalari: «API versiyalash siyosati» ga kiriting.

8) Yo’naltirish va relizlar

API Gateway (Kong/Apigee/Nginx/Envoy): ’/v1/’ prefiksi qoidalari, sarlavha yoki mediatip qoidalari.

if ($http_accept ~ "vnd.company.payments.v2") { proxy_pass http://payments-v2; }

Canary/Blue-Green/Shadow: Yangi versiyani 1-5% trafikka aylantiring, kontrakt xatolari va metrikalarini solishtiring.
Feature Flags: Shartnomani oʻzgartirmasdan xatti-harakatlaringizni yashiring.
Zero-downtime migratsiyasi: MAJOR’da ma’lumotlar sxemasini ikki marta yozish/o’qish (dual-write/read) ta’minlang.

9) Kontrakt-test va muvofiqlikni nazorat qilish

OpenAPI Diff (yoki swagger-diff) - MINOR/PATCH sxemalarni buzmasligiga ishonch hosil qiling.
Spectral linting - uslubi, majburiy meta maʼlumotlar (versiya, Deprecation).
Consumer-Driven Contracts (Pact) - provayder mijozlarni buzmasligini kafolatlaydi.
buf breaking для protobuf.
CI MAJOR’ni oshirmasdan buzuvchi oʻzgarishlarda tushishi kerak.

10) Hujjatlar va SDK

’/docs/api/v1/openapi. json`, `/docs/api/v2/…`.
SemVer va changelog bilan (npm/maven/pypi) SDKni yarating.
Eskirgan usullarni SDKda/Deprecated izohlari bilan belgilang.

11) Observability versiyalari bo’yicha

• Versiya uchun RPS/yashirin/xato (’api _ version’leybl).
• Endpointlardan foydalanish xaritalari: yana kim v1?
• Alertlar: «> 10% 4xx due to contract mismatch», «eski mijozlar> X% T-sanadan keyin».

12) Keshlash va versiyalar

Yoʻldagi versiya CDN keshni yaxshilaydi.

• `Vary: Accept, X-API-Version`.
• MINOR’dagi javob semantikasini kesh kalitlarini sindirish uchun oʻzgartirmang.

13) Xavfsizlik

JWT versiyasini shifrlamang yoki tikmang - versiya tokenni emas, soʻrovni aniqlaydi.
Yigʻishning ichki raqamlarini oshkor qilmang. Tashqi xabarlarda «v1/v2» dan foydalaning.
MAJORda PIIning validatsiyasi, limitlari va niqoblanishini qayta ko’rib chiqing.

14) Migratsiya va avto-yordamchilar

«Migration Guide v1 → v2»: maydon muvofiqlik jadvalini, soʻrov/javob misollarini, edge-keyslarni nashr eting.
Mijozlar uchun eskirgan maydonlarni yoritadigan linterlarni (CLI) taklif qilyapsiz.
Yirik hamkorlar uchun - ikki versiyali sandbox va test-dataset.

15) Anti-patternlar

«Abadiy v1»: foydalanish muddatlari va metrikalari yo’qligi.
MINOR/PATCH’dagi yashirin buzuvchi oʻzgarishlar.
«Versiya query string» (’? v = 2’) - kesh va o’qishni buzadi.
«Bitta endpoint - bayroqning yuz qiymati»: sinovdan o’tkazish/hujjatlashtirish qiyin.

16) Joriy etish chek-varaqasi

1. Tashqi va ichki mijozlar uchun model (URI/Accept/Header) tanlandi.
2. Spetsifikatsiyalar va SDK uchun SemVer, CIda avtomatik breaking-check.
3. Deprecation/Sunset aloqa siyosati va shablonlari.
4. Gateway-marshrutlash + kanareykalar, versiyalar boʻyicha dashbordlar.
5. CDC/Contract tests kritik integratsiyalarga (to’lovlar, KYC, hisobot).
6. Hujjatlar/SDK/migratsiya gidi reliz bilan bir vaqtda e’lon qilingan.
7. Sana va mas’ullar bilan EOL rejasi.

17) Misollar

17. 1 REST (URI + sarlavhalar)

GET /v2/withdrawals/12345
Accept: application/json
Idempotency-Key: 4a1c-…-9f

json
{
"id": "12345",
"status": "PENDING_REVIEW",
"amount": {"value": "100.00", "currency": "EUR"},
"limits": {"daily": "500.00"},
"created_at": "2025-10-02T10:00:00Z",
"links": [{"rel": "cancel", "href": "/v2/withdrawals/12345/cancel", "method": "POST"}]
}

Deprecation: true
Sunset: Tue, 31 Mar 2026 00:00:00 GMT
Link: </v2/docs>; rel="successor-version"

17. 2 Content Negotiation (mediatip)

GET /payments/987
Accept: application/vnd.company.payments.v2+json
Vary: Accept

17. 3 GraphQL (maydon deprikatsiyasi)

graphql type Payment {
id: ID!
amount: Money!
status: PaymentStatus!
method: PaymentMethod!
legacyCode: String @deprecated(reason: "Use field `method`")
}

17. 4 gRPC (protobuf)

proto package payments.v2;

message Withdrawal {
string id = 1;
Money amount = 2;
string status = 3; // previously enum, now string with documented values reserved 4; // legacy field removed in v1 -> v2
}

17. 5 Hodisa modeli

• `wallet. v1. balance. updated`
• `wallet. v2. balance. changed’(kengaytirilgan sxemali yangi hodisa)

Sxemalar Registry-da saqlanadi, prodyuser muvofiqlikni buzadigan sxemali voqealarni e’lon qilmaydi.

18) iGaming/fintech konteksti (amaliyot)

To’lovlar:’status ’/’ decline _ reason’kengaytirilgan yangi PSP uchun v2 kiritish; hisobot uchun mapping v1 → v2 shlyuzida.
KYC: MINOR’pep _ screening’maydonini qoʻshadi, v1 mijozlari eʼtiborsiz qoldiradi, v2 - talab qiladi.
Mas’ul o’yinlar/limitlar: MAJOR limitlar modelini o’zgartiradi (sutkalik/haftalik). EOL v1 gacha hisobotga ikki marta eksport qilish.
Regulyatorlarga hisobot: belgilangan versiya-sanalar:’reporting-2025-01’.

19) Mini-siyosat (wiki uchun misol)

Model: tashqi API uchun -’URI/vN/’; ichki uchun -’Accept:... vN + json’yoki’X-API-Version: N’.
SemVer: spetsifikatsiyalar va SDK’N. sifatida nashr etiladi. minor. patch`. MAJOR RFC/ADR talab qiladi.
Moslik: MINOR/PATCH - buzuvchi o’zgarishlarsiz. Buzuvchi → faqat MAJOR orqali.
Deprecation/EOL: 90 kun ≥ e’lon; Sarlavhalarda Sunset-sana; Tanqidiy mijozlar uchun LTS filiali.
Nazorat: OpenAPI diff/buf breaking in CI, CDC uchun asosiy integratsiyalar.
Observability: metriklar/loglar bilan’api _ version’.
Relizlar: canary 5% ≥ 24 soat, so’ngra bosqichma-bosqich yashil metriklarda 100% gacha.

Jami

Version - bu «URLda/v2» haqida emas, balki jarayon haqida: evolyutsiyaning aniq qoidalari, muvofiqlikni avtomatik tekshirish, boshqariladigan relizlar va integratsiyalarni hurmat qilish. Tushunarli siyosatni kiriting, nazorat va kuzatuvni avtomatlashtiring - va o’zgarishlar mahsulot uchun xavf tug’dirmaydi.