API kontrakt mosligi

Nima uchun kontrakt mosligi kerak?

Kontrakt muvofiqligi - bu APIning mavjud integratsiyalarni buzmasdan evolyutsiya qilish qobiliyatidir. O’sib borayotgan API tizimlarida mijozlar kodi tez-tez o’zgaradi; uyg’unlik fichlarni «katta o’tish joylarini» tashkil qilmasdan iterativ ravishda chiqarish imkonini beradi.

Asosiy g’oya: kontrakt birlamchi bo’lib, o’zgarishlar muvofiqlik qoidalariga muvofiq amalga oshiriladi va avtomatik tarzda tekshiriladi.

Bazaviy tushunchalar

Kontrakt - interfeysning rasmiy tavsifi: resurslar/usullar/voqealar, ma’lumotlar sxemalari, xato kodlari, limitlar, SLA, xavfsizlik talablari.
Provider - API egasi. Iste’molchi (consumer) - mijoz/integratsiya.

Moslik:

Backward: Yangi yetkazib beruvchi eski isteʼmolchilar bilan ishlaydi.
Forward: Eski yetkazib beruvchi yangi isteʼmolchilar bilan ishlaydi (odatda «chidamli oʻquvchilar»).
Full: ham backward, ham forward (eng kuchli variant).
Qo’shimcha - mavjud elementlarni sindirmasdan qo’shish.

Version siyosati

Semantic Versioning (tavsiya etiladi):

MAJOR - buzuvchi oʻzgarishlar (faqat yangi API liniyasi chiqarilganda: ’/v2’,’service. v2`).
MINOR - qoʻshimcha oʻzgarishlar (yangi ixtiyoriy maydonlar/usullar).
PATCH - kontraktni o’zgartirmasdan tuzatishlar.
Deprecation Policy: eskirgan elementlarni e’lon qilish, qo’llab-quvvatlash oynasi (sunset), sarlavhalar/meta ma’lumotlar ogohlantirishlari, olib tashlash rejasi.

Xavfsiz va xavfli o’zgarishlar

Xavfsiz (odatda backward-compatible)

JSON/Protobuf/Yevroga ixtiyoriy maydon qoʻshish.
Yangi endpoint/usul/hodisani qoʻshish.
Agar isteʼmolchilar nomaʼlum qiymatlarga chidamli boʻlsa, enumni yangi qiymatlar bilan kengaytirish.
Chegaralarni (masalan,’maxItems’) minimal chegaralarni qattiqlashtirmasdan oshirish.
Notoʻgʻri defoltlar bilan nullable qoʻshish.
Tavsif/misol matnini oʻzgartirish.

Xavfli (muvofiqlikni buzadi)

Maydonlarning nomini oʻzgartirish/olib tashlash, ularning turi yoki majburiyligini oʻzgartirish.
Status-kodlar/xatolar semantikasini oʻzgartirish (masalan,’200’,’204’yoki’404’).
Identifikator formatini oʻzgartirish (UUID → int).
Versiyasi bo’lmagan validatsiyani (qattiqroq minimumlar/patternlar) kuchaytirish.
gRPC oqimlarida/hodisalarida tartib va tuzilmani oʻzgartirish.
Yangi maydonlar uchun Protobuf tag raqamlaridan foydalanish.

O’zaro ta’sir uslubi bo’yicha moslik

REST/HTTP + JSON Schema

Qo’shimcha: Yangi maydonlarni’optional ’/’ nullable’deb belgilaymiz.
Tolerant Reader: nomaʼlum maydonlarga eʼtibor bermaslik; tartibga tayanmaslik.
Version: major - yo’lda (’/v2’) yoki mediatipda (’application/vnd. example. v2+json`).
ETag/If-Match: poygasiz xavfsiz yangilanishlar uchun.
Xatolar: yagona format (’type’,’code’,’title’,’detail’,’trace _ id’), majorsiz’code’qiymatini oʻzgartirmang.
Paginatsiya: kursorlar afzalroq offset; ’next _ cursor’ maydonlarini qoʻshing, mavjudlarining maʼnosini oʻzgartirmang.

gRPC / Protobuf

Teglarning tartib raqami oʻzgarmaydi. Olib tashlangan teglar qayta ishlatilmaydi.
Yangi maydonlar -’optional ’/’ repeated’serverda oqilona defoltlarga ega.
streaming-RPC’dagi xabarlarning tartibi va majburiyligini o’zgartirmang.
Xato holatlari - barqaror (’INVALID _ ARGUMENT’,’FAILED _ PRECONDITION’va h.k.); yangi semantika → usul/servisning yangi versiyasi.

Event-driven (Kafka/NATS/Pulsar) + Avro/JSON Schema

Hodisaning nomi:’domain. action. v{major}`.
Yangi maydonlar - opsion; yadro va boyitishni ajrating (’.enriched’).
Sxemalar registrlari: mavzu/hodisa boʻyicha muvofiqlik qoidalari (BACKWARD/FORWARD/FULL).
Isteʼmolchilar tomonida tolerant reader boʻlganda enum kengaytiriladi.
Agregat uchun turkumlash kaliti/tartibi = buzuvchi oʻzgarishlar.

GraphQL

Maydonlarni/turlarni qoʻshish - xavfsiz; olib tashlash/qayta nomlash - faqat @deprecated va migratsiya oynasi orqali.
Majorsiz turlarni oʻzgartirmang/nullable qilmang.
Complexity/depth nazorat qiling - limitlar shartnomaning bir qismidir.

Barqaror evolyutsiya patternlari

Additive-first: uzilmasdan kengaytiring.
Capability negotiation: mijozlar (sarlavhalar/parametrlar/kelishuvlar) ni qoʻllab-quvvatlayotganlarini, server moslashayotganliklarini bildirishadi.
Kontrakt chegaralari: MGC (minimal kafolat shartnomasi) ni belgilang va kengayishlarni ajrating (teskari piramida modeli).
Tolerance by default: mijozlar ortiqcha narsaga eʼtibor bermaydilar va nomaʼlum enum (fallback) qiymatlariga toʻgʻri ishlov beradilar.
Dual-write/Dual-emit: major oʻzgarishlarida bir muddat parallel ravishda «v1» va «v2» ni chiqaring.
Sunset headers/Events: versiyalarni olib tashlash haqida oldindan xabar bering.

Governance va avtomatlashtirish

API linterlar:

OpenAPI/Spectral: nomlash, paginatsiya, xato kodlari, maydon formatlari.
Buf/Protobuf: tag’lar va paket notalarini qayta ishlatishni taqiqlash.
AsyncAPI/Schema Registry: sxemalarning CI darajasidagi mosligi.
Kontraktlar katalogi (SSOT): difflar tarixiga ega sxemalar/versiyalarning markazlashtirilgan reyestri.
API Guild: qoidalar, shablonlar va oʻzgarishlarni qabul qiluvchi gildiya/qoʻmita.
Change Management: RFC/ADR, release notes, migratsiya gaydalari.

Muvofiqlikni sinash

Schema-diff in CI: sinuvchi spek oʻzgarishlarini blokirovka qiling (OpenAPI-diff, Buf breaking, SR compatibility).
Consumer-Driven Contracts (CDC): Pact/analoglar - yetkazib beruvchini aniq iste’molchilarning shartnomalariga qarshi tekshirish.
Golden samples: regress uchun talablar/javoblar va hodisalar.
E2E Canary: traffik/alohida konsumer guruhlari.
Chaos/latency: taymaut/retraylarni tekshirish - latency-SLOni o’zgartirish shartnomani o’zgartirish hisoblanadi.

Migratsiya va deprekeyt

1. Elementni belgilab, sunset muddati va muqobilini koʻrsating.
2. Dual-write/dual-emit, ko’priklar, adapterlar kabi mos keladigan davrni qo’llab-quvvatlang.
3. Telemetriyani yig’ib oling: eskisini yana kim ishlatadi?
4. Kommunikatsiya: tarqatmalar, reliz-notalar, test stendlari.

5. Oynani olib tashlash: Oynani olib tashlash

Oʻzgartirish namunalari

REST

Mavjud:

json
{ "id":"p1", "status":"authorized" }

Bu (qo’shimcha, xavfsiz):

json
{ "id":"p1", "status":"authorized", "risk_score": 0. 12 }

Nomaʼlum maydonlarga eʼtibor bermaydigan mijozlar buzilmaydi.

Protobuf

proto message Payment {
string id = 1;
string status = 2; // don't change tag numbers optional double risk_score = 3; // additive
}

Event

`payment. authorized. v1’(yadro) +’payment. enriched. v1’(boyitish). Tanqidiy yo’l iste’molchilari boyitishga bog’liq bo’lmagan yadro o’qiydilar.

Antipatternlar

Swagger-wash: Rasmiy tavsiflar mavjud, ammo xizmatning xatti-harakati undan farq qiladi.
Breaking by stealth: yangi versiyasiz va migratsiya oynasisiz turi/holati/formati oʻzgartirildi.
Xom CDC hodisalari ommaviy shartnoma sifatida: DD sxemalarining chiqib ketishi, evolyutsiyaning mumkin emasligi.
Qattiq mijoz: nomaʼlum maydonlarda/qiymatlarda tushadi; tolerant reader mavjud emas.
Protobuf-teglardan qayta foydalanish: ma’lumotlarning jimgina korrupsiyasi.
Yashirlik «kontrakt emas»: p95 kutilmaganda uzaytirildi - iste’molchilar taymautlarda buziladi.

Moslik chek-varaqasi (merjdan oldin)

O’zgarishlar qo’shimcha (yoki major versiyasi tayyorlangan).
Linterlar/diff-cheklar o’tdi, muvofiqlik qoidalari - yashil.
Xatolar/kodlar/holatlar semantikani o’zgartirmadi.
Enum eski qiymatlarni taqiqlamasdan kengaytirildi; mijozlar - tolerant.
MGC chegaralari oʻzgarmaydi.
Namunalar/hujjatlar/SDK yangilandi.
Major uchun - dual-write/dual-emit rejasi, sunset-sana, komm-reja.
Sinovlar CDC/Golden/E2E o’tdi.

FAQ

Backward forward moslashuvidan qanday farq qiladi?
Backward - yangi serverlar eski mijozlarni buzmaydi. Forward - yangi mijozlar eski serverlarda buzilmaydi (tolerant reader va ehtiyotkor defoltlar orqali).

’/v2’ni qachon qilish kerak?
Invariant/semantika o’zgarganda, maydon/usullar o’chiriladi, yangi xavfsizlik modeli talab etiladi - yangi liniyani ishga tushirish osonroq va halol.

Schema registry/linterlarsiz yashash mumkinmi?
Nazariy jihatdan - ha, amalda - bu tez-tez regress va «yashirin» sinish. Avtomatlashtirish o’zini oqlaydi.

Enumni kengaytirish mumkinmi?
Agar mijozlar notoʻgʻri qiymatlarga (fallback/ignore) toʻgʻri ishlov bersa. Aks holda - major.

Jami

Kontrakt muvofiqligi - qoidalar + intizom + avtomatlashtirish. Qo’shimcha loyihalashtiring, buzuvchi o’zgarishlarni versiyalashtiring, tolerant readerni qo’llang, diff va CDCni avtomatik tekshiring, deprekeytni rejalashtiring. Shunday qilib, APIlar tez rivojlanib, integratsiyalar barqaror bo’lib qolishi mumkin.