API versiyalash strategiyalari

Nima uchun versiyalash kerak

API mijozlarga qaraganda tezroq o’zgaradi. Versionizatsiya integratsiyalarni buzmasdan fich chiqarish va xatolarni tuzatish imkonini beradi, o’zgarishlar marosimini belgilaydi va evolyutsiyani oldindan aytib bo’ladigan qiladi. Kalit: andoza qoʻshimcha oʻzgarishlar, majors - faqat sinish uchun, avtomatik muvofiqlik tekshiruvi va puxta oʻylangan sunset siyosati.

Asosiy tamoyillar

1. Additive-first: yangi ixtiyoriy maydonlar/usullar/hodisalar - taxminan; ma’nosini olib tashlash va o’zgartirish - major.
2. MGC (minimal kafolat kontrakti) barqaror; boyitish - capabilities/’? include =’orqali.
3. Tolerant reader: mijozlar nomaʼlum maydonlarga eʼtibor bermaydilar va enum kengaytmalarini toʻgʻri boshdan kechiradilar.
4. Semantic Versioning: `MAJOR. MINOR. Artefaktlar, SDK va voqealar uchun PATCH’.
5. Automate: schema-diff, linterlar va CDC testlari breaking-oʻzgarishlarni bloklaydi.

Varianti qayerda saqlanadi (manzil mexanikasi)

REST/HTTP

URI versiyasi: ’/v1/orders’→ faqat yo’naltirish, shlyuzlarda qulay. Minus - tasavvurlar evolyutsiyasini «to’sib qo’yadi».
Media/sarlavha:’Accept: application/vnd. example. orders. v1 + json’- formatni aniq boshqarish; bahslashish qiyinroq.
Query versiyasi:’? api-version = 1’- A/B uchun qulay, ammo kesh/loglarda yoʻqotish oson.
Tavsiya: major-liniyalar uchun URI + feature/capability flags va minor kengaytmalar uchun kontent negatsiyasi.

gRPC / Protobuf

Paketlar/servislar:’package payments. v1; service PaymentsV1;’- aniq chiziqlar.
Teglarning tartib raqami o’zgarishsiz; olib tashlangan teglar qayta ishlatilmaydi.
Yangi maydon -’optional’; breaking → yangi’.v2’.

GraphQL

URL’da aniq major boʻlmagan sxema. @deprecated va migratsiya oynalari orqali evolyutsiya; «haqiqiy» major - yangi endpint-sxema.
Complexity/depth - bu shartnomaning bir qismi.

Event-driven (Kafka/NATS/Pulsar)

Hodisa nomi:’payment. authorized. v1’- turdagi versiya.
Moslik rejimiga ega sxemalar reyestri (Euro/JSON Schema/Protobuf) (BACKWARD/FORWARD/FULL).
Major → dual-emit’v1’va’v2’o’tish davri uchun.

Versiyalar modeli va o’zgartirish siyosati

Semantic Versioning

MAJOR - sinuvchi o’zgarishlar: maydonlarni o’chirish/qayta nomlash, partiyalashtirish kalitlarini o’zgartirish, maqomlarning boshqa ma’nosi, validatsiyani kuchaytirish.
MINOR - qoʻshimcha: yangi ixtiyoriy maydonlar/endpointlar/hodisalar, tolerant-readerda yangi enum-qiymatlar.
PATCH - kontrakt va semantikani o’zgartirmasdan tuzatishlar.

Deprecation & Sunset

Eskirgan (’Deprecated: true’,’@deprecated’), sunset-sana, muqobil va gid migratsiyasini belgilang.
HTTP -’Sunset’,’Deprecation’sarlavhalari; hodisalarda - alohida’.deprecation. notice`.
Olib tashlash to’g’risida qaror qabul qilish uchun usage telemetriyasini o’tkazing.

Uslublar bo’yicha version strategiyalar

REST

/ v1 ,/v2 ga major-liniyalar.
MINOR: sxemalarni kengaytirish,’? fields =’,’? include =’; xavfsiz enum kengaytmalar.
ETAG/If-Match va idempotentli POST uzluksiz kelishuv uchun.
Xatolar - barqaror format (’type’,’code’,’trace _ id’).

gRPC

’PaymentsV2. Capture`.
Xato holatlari va deadline semantikasi - kontraktning bir qismi; o’zgartirish → yangi usul/xizmat.
Striming: xabarlarning tartibi to’g’risida kelishib oling va uni minorga o’zgartirmang.

GraphQL

Boʻsh joylar va turlarni qoʻshing; olib tashlash -’@deprecated’+ migratsiya oynasi orqali; katta rasm → yangi sxema (’/graphql-v2’).
Introspektsiya va tavsiflar - mijozlar migratsiyasi uchun must-have.

Events

Core vs enriched: yadro barqaror, boyitish yonma-yon yashaydi va alohida versiyalashtiriladi.
Partiyalash kaliti major-liniya doirasida o’zgarmaydi.
Major-migratsiya -’dual-emit’+ proyeksiyalar/konsumerlar migratsiyasi.

Negotiation va capability-bayroqlar

Capabilities: mijoz’X-Capabilities: risk_score,price_v2'; server kengaytirilgan koʻrinish bilan javob beradi.
Prefer (HTTP) va qisman javoblar uchun «hints».
Soket/oqimlarda qo’llab-quvvatlanadigan kengaytmalar ro’yxatiga ega handshake xabari mavjud.

Major-versiyalarini og’riqsiz chiqarish

1. RFC/ADR: nima uchun major kerak, nima buzilmoqda, xavf matritsasi.
2. Dual-run: parallel ishga tushirish’v1’va’v2’(voqealarni ikki marta chop etish, ikkita gateway-rout, trafikni oynalash).
3. Migratsiya adapterlari: og’ir mijozlar uchun proksi/translatorlar’v1 v2’.
4. Kanareyka :/topiklar/taglar boʻyicha gateway.
5. Sunset-reja: sana, kommunikatsiya, stendlar, test ma’lumotlari, foydalanish monitoringi.

Platforma va infratuzilmaning roli

API Gateway/Service Mesh: versiya, sarlavha, yo’llar bo’yicha yo’naltirish; rate-limit и auth per-version.
Schema Registry & Catalog: diff tarixiga ega sxemalar uchun haqiqat manbai.
CI/CD: линтеры (Spectral, Buf), schema-diff (OpenAPI-diff, Buf breaking), CDC (Pact).
Observability: versiya loglar/treyslar/metriklarga tushishi kerak.

Versiyalar sinovdan oʻtkazilmoqda

PRdagi schema-diff: breaking.
Consumer-Driven Contracts: provayder haqiqiy iste’molchilarning shartnomalariga qarshi tekshiriladi.
Golden samples: versiyalar uchun mos javoblar.
E2E-kanareyka: p95/p99, xato va vaqtni versiyalar orasiga solishtirish.
Hodisalar uchun replay: proyeksiyalar farqsiz v2 ga qayta yigʻiladi.

Maʼlumotlar va bazalar koʻchishi

REST/gRPC uchun: BD migratsiyasi expand-and-contract orqali muvofiqlashtiriladi (ustun qo’shing → yozishni boshla → o’qishni o’zgartir → eskisini o’qing).
Events uchun: dual-emit va konsumerlar migratsiyasi; ba’zan - yangi proyeksiyalar uchun logni qayta o’ynash.
«Katta portlashlar» qilmang - orqaga qaytish bilan qadam tashlang.

Xavfsizlik bilan o’zaro bog’liqlik

Scopes per version: v1/v2 uchun alohida OIDC-scopes/rollar.
Tokenning sirlari/claim’lari - kontraktning bir qismi; ularni almashtirish = major.
PII/PCI - keraksiz payload’ni kengaytirmang; eng kam imtiyozli yangi dalalar.

Antipatternlar

Swagger-wash: spetsifikatsiya yangilandi, server yoʻq (yoki aksincha).
Protobuf-teglardan qayta foydalanish - ma’lumotlarning jimgina buzilishi.
Majorsiz enum-maʼnolarni oʻzgartirish.
Global ’/v2’«kosmetika uchun»: sinish faktisiz versiya.
Sunset/usage-metriklarni unuting: eski versiyani xavfsiz olib tashlab boʻlmaydi.
Turli major uchun bitta umumiy topik: tartib va kalitlarni aralashtirish.

Chiqarish oldidan chek varaqasi

• O’zgarishlar qo’shimcha yoki alohida major liniyasi tayyorlangan.
• Linterlar va schema-diff yashil (breaking o’tmadi).
• SDK/misollar/hujjatlar, muvofiqlik izohlari yangilandi.
• Mijozlarda tolerant reader yoqilgan; enum-fallback sinovdan o’tkazildi.
• Major uchun - dual-run rejasi, adapterlar, kanareyka, sunset-sanalar va tarqatish.
• Metriklar/loglar/treyslar versiyani va uning segmentatsiyasini o’z ichiga oladi.
• Taqqoslash uchun stend va golden-to’plamlar mavjud.
• Hodisalar uchun - BACKWARD/FULL rejimidagi sxemalar reestri, partiyalash kalitlari o’zgarishsiz.

Namunalar namunalari

REST (URI + negotiation)

Yo’nalish: ’/api/v2/orders/{ id} ’

Заголовок: `Prefer: include=items,customer`, `X-Capabilities: risk_score`

Deprecation: `Sunset: 2026-06-30`, `Link: ; rel="alternate"`

Protobuf/gRPC

proto package payments.v2;

service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}

Events

`payment. captured. v2’(yadro) va’payment. enriched. v2’(tafsilotlar).
O’tish davri uchun prodyuserdan’v1’va’v2’keladi.

FAQ

Qachon aniq ’/v2’kerak?
Invariantlar/semantika o’zgarganda, maydonlar/usullar o’chiriladi, identifikatorlarning formati, partiyalash kalitlari, SLA/tayminglar o’zgarib, mijozlar buziladi.

RESTda aniq versiyasiz yashash mumkinmi?
Faqat kichik tizimlar uchun. Tashqi integratsiya uchun aniq major-liniyalar yaxshiroqdir.

Eskirgan versiyani qancha vaqt ushlab turish kerak?
Ekotizimga bog’liq. Tashqi sheriklar uchun, odatda, 6-12 oy oldin xabar va kanareyka bilan.

Voqealarni versiyalash API dan qanday farq qiladi?
Voqealar - append-only; yangi semantika = yangi’.v2’va dual-emit turi. Partiyalashtirishning kaliti - kontraktning bir qismi.

Jami

Versiyalash strategiyalari - bu jarayon va vositalar: andoza qo’shimcha evolyutsiya, aniq major chiziqlar, capability-negotiation, dual-run va sunset. Bunga muvofiqlikni avtomatik tekshirish, foydalanish telemetriyasi va hujjatlar intizomini qo’shing - va sizning API’laringiz tez rivojlanadi, «tungi migratsiyalar» va kutilmagan pasayishlarsiz.