API şertnama laýyklygy

Näme üçin şertnama laýyklygy zerur?

Şertnama laýyklygy, API-iň bar bolan integrasiýalary bozmazdan ösmek ukybydyr. Artýan API ulgamlarynda müşderileriň kody köplenç üýtgeýär; gabat gelmek, "uly geçişleri" gurnamazdan, çitleri iteratiw goýbermäge mümkinçilik berýär.

Esasy pikir: şertnama - birmeňzeş, üýtgeşmeler laýyklyk kadalary boýunça geçirilýär we awtomatiki usulda barlanýar.

Esasy düşünjeler

Şertnama - interfeýsiň resmi aýratynlygy: çeşmeler/usullar/wakalar, maglumat shemalary, ýalňyşlyk kodlary, çäkler, SLA, howpsuzlyk talaplary.
Üpjün ediji (provider) - API eýesi. Sarp ediji (consumer) - müşderi/integrasiýa.

• Backward: Täze üpjün ediji köne sarp edijiler bilen işleýär.
• Forward: köne üpjün ediji täze sarp edijiler bilen işleýär (adatça "çydamly okyjylar" tarapyndan gazanylýar).
• Doly: backward we forward (iň güýçli wariant).
• Additivity - bar bolanlary döwmezden goşmaça elementleri goşmak.

Wersiýa syýasaty

• MAJOR - bozýan üýtgeşmeler (diňe täze API setiri çykarylanda: '/v2 ',' service. v2`).
• MINOR - goşmaça üýtgeşmeler (täze goşmaça meýdanlar/usullar).
• PATCH - şertnamany üýtgetmezden düzedişler.
• Deprecation Policy: köne elementleriň yglan edilmegi, goldaw penjiresi (sunset), sözbaşy/meta maglumatlar duýduryşlary, aýyrmak meýilnamasy.

Howpsuz vs howply üýtgeşmeler

Howpsuz (adatça backward-compatible)

JSON/Protobuf/Euro-a goşmaça meýdan goşmak.
Täze endpoint/usul/wakany goşmak.
Sarp edijiler näbelli gymmatlyklara çydamly bolsa, täze gymmatlyklar bilen giňeltmek.
Iň pes çäkleri berkitmezden çäkleri ýokarlandyrmak (mysal üçin 'maxItems').
Dogry defoltlar bilen nullable goşmak.
Düşündirişleriň/mysallaryň tekstini üýtgetmek.

Howply (laýyklygy bozýar)

Meýdanlaryň adyny üýtgetmek/aýyrmak, olaryň görnüşini ýa-da borçlylygyny üýtgetmek.
Status-kodlaryň/ýalňyşlyklaryň semantikasynyň üýtgemegi (mysal üçin '200', '204' ýa-da '404' boldy).
ID formatyny üýtgetmek (UUID → int).
Wersiýasyz tassyklamany berkitmek (has berk minimumlar/patternler).
gRPC akymlarynda/wakalarynda tertibi we gurluşy üýtgetmek.
Täze meýdanlar üçin Protobuf bellik belgilerini gaýtadan ulanmak.

Özara gatnaşyk stilleri boýunça gabat gelmek

REST/HTTP + JSON Schema

Additivity: Täze meýdanlary 'optional '/' nullable' diýip belleýäris.
Müşderide Tolerant Reader: näbelli ýerleri äsgermezlik etmek; tertibe bil baglamazlyk.
Wersiýalanma: major - ýolda ('/v2 ') ýa-da mediatipde (' application/vnd. example. v2+json`).
ETag/If-Match: ýaryşsyz howpsuz täzelenmeler üçin.
Hatalar: ýekeje format ('type', 'code', 'title', 'detail', 'trace _ id'), 'code' -ni maýorsyz üýtgetmäň.
Paginasiýa: kursorlar ofset has gowy; 'next _ cursor' meýdançalaryny goşuň, bar bolanlaryň manysyny üýtgetmäň.

gRPC / Protobuf

Bellikleriň belgisi üýtgewsiz. Öçürilen bellikleri gaýtadan ulanmaň.
Täze meýdanlar - 'optional '/' repeated' serwerde akylly defoltlar.
Akym-RPC-daky habarlaryň tertibini we borçlylygyny üýtgetmäň.
Ýalňyşlyklaryň ýagdaýy - durnukly ('INVALID _ ARGUMENT', 'FAILED _ PRECONDITION' we ş.m.); täze semantika → usulyň/hyzmatyň täze wersiýasy.

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

Wakalaryň ady: 'domain. action. v{major}`.
Täze meýdanlar - goşmaça; ýadro we baýlaşdyryş ('.enriched').
Shema registrleri: Tema/waka boýunça laýyklyk düzgünleri (BACKWARD/FORWARD/FULL).
Enum giňeltmek sarp edijileriň tarapynda tolerant reader bilen rugsat berilýär.
Partizan açaryny/tertibini üýtgetmek = bozýan üýtgeşmeler.

GraphQL

Meýdanlary/görnüşleri goşmak - howpsuz; aýyrmak/adyny üýtgetmek - diňe @deprecated we göçmek penjiresi arkaly.
Major bolmazdan görnüşleriňizi/nullable etmäň.
Complexity/depth gözegçilik - çäklendirmeler şertnamanyň bir bölegidir.

Durnukly ewolýusiýanyň nusgalary

Additive-first: döwmezden giňeldiň.
Capability negotiation: Müşderiler goldaýandyklaryny habar berýärler (sözbaşylar/parametrler/ylalaşyklar), serwer sazlanýar.
Şertnamanyň çäkleri: MGC-ni (iň az kepillik şertnamasy) belläň we giňeltmeleri bölüň (ters piramida modeli).
Tolerance by default: Müşderiler gereksiz zady äsgermezlik edýärler we näbelli enum (fallback) bahalaryny dogry dolandyrýarlar.
Dual-write/Dual-emit: major üýtgeşmelerinde birnäçe wagt paralel 'v1' we 'v2' çykaryň.
Sunset headers/Events: wersiýalaryň aýrylmagy barada öňünden habar beriň.

Governance we awtomatlaşdyryş

• OpenAPI/Spectral: at, paginasiýa, ýalňyşlyk kodlary, meýdan formatlary.
• Buf/Protobuf: bellikleri gaýtadan ulanmagy gadagan etmek, paketleri bellik etmek.
• AsyncAPI/Schema Registry: CI derejesindäki shemalaryň laýyklygy.
• Şertnamalaryň katalogy (SSOT): diffleriň taryhy bolan shemalaryň/wersiýalaryň merkezleşdirilen sanawy.
• API Guild: düzgünleri, şablonlary we üýtgeşmeleri kabul edýän gildiýa/komitet.
• Change Management: RFC/ADR, release notes, migrasiýa gidleri.

Laýyklyk synagy

CI-de Schema-diff: Bölýän üýtgeşmeleri bloklaýarys (OpenAPI-diff, Buf breaking, SR compatibility).
Consumer-Driven Contracts (CDC): Pact/şuňa meňzeş - belli bir sarp edijiniň şertnamalaryna garşy üpjün edijini barlamak.
Golden samples: regress üçin salgylanma soraglary/jogaplar we wakalar.
E2E Canary: traffigiň paýyna aýlanmak/aýry-aýry konsumer toparlary.
Chaos/latency: wagtlary/retraýlary barlamak - latency-SLO-ny üýtgetmek şertnamanyň üýtgemegi hasaplanýar.

Migrasiýa we deprekeýt

1. Deprekate bildiriň: elementi belläň, sunset möhletini we alternatiwasyny görkeziň.
2. Gabat gelmek döwrüni saklaň: dual-write/dual-emit, köprüler, adapterler.
3. Telemetriýany ýygnaň: köne zady başga kim ulanýar?
4. Aragatnaşyk: poçta, goýberiş-bellikler, synag stendleri.
5. Aýyrmak: penjireden soň - kesgitlenen çykaryş bilen aýyrmak.

Üýtgeşmeleriň mysallary

REST

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

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

Näbelli meýdanlary äsgermezlik edýän müşderiler bozulmaýarlar.

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 '(ýadro) +' payment. enriched. v1 '(baýlaşdyrmak). Möhüm ýoly ulanýanlar özeni okaýarlar we baýlaşdyrmaga bagly däldirler.

Anti-patternler

Swagger-wash: aýratynlyklar resmi taýdan bar, ýöne hyzmatyň özüni alyp barşy ondan tapawutlanýar.
Breaking by stealth: täze wersiýa we göçmek penjiresi bolmazdan görnüşi/statusy/formaty üýtgedildi.
Çig CDC wakalary jemgyýetçilik şertnamasy hökmünde: DD shemalarynyň syzmagy, ewolýusiýanyň mümkin däldigi.
Gaty müşderi: näbelli meýdanlara/gymmatlyklara düşýär; tolerant reader ýok.
Protobuf-tegleri gaýtadan ulanmak: maglumatlaryň ýuwaş korrupsiýasy.
Gizlinlik "şertnamasyz": garaşylmadyk ýagdaýda p95 uzaldyldy - sarp edijiler wagtlaýynça döwülýärler.

Laýyklyk çek-sanawy (merjeniň öň ýanynda)

• Üýtgeşmeler goşmaça (ýa-da esasy wersiýasy taýýarlandy).
• Linterler/diff-barlaglar geçdi, laýyklyk düzgünleri ýaşyl.
• Ýalňyşlyklar/kodlar/statuslar semantikany üýtgetmedi.
• Enum köne bahalary gadagan etmezden giňeldildi; müşderiler - tolerant.
• MGC çäkleri üýtgewsiz.
• Täzelenen mysallar/resminamalar/SDK.
• Major üçin - dual-write/dual-emit meýilnamasy, sunset-date, komm-plan.
• Synaglar CDC/Golden/E2E geçdi.

FAQ

Backward forward-dan nähili tapawutlanýar?
Backward - täze serwerler köne müşderileri bozmaýar. Forward - täze müşderiler köne serwerlerde bozulmaýarlar (tolerant reader we arassa defoltlar arkaly).

Haçan etmeli '/v2 '?
Invariantlar/semantika üýtgese, meýdanlar/usullar aýrylanda, täze howpsuzlyk modeli talap edilýär - täze setiri açmak has aňsat we dogruçyl.

Schema registry/lintersiz ýaşap bolarmy?
Teoretiki taýdan - hawa, diýen ýaly - ýygy-ýygydan regresler we "gizlin" döwükler. Awtomatlaşdyryş öwezini dolýar.

Enum giňeldilip bilnermi?
Hawa, eger müşderiler näbelli gymmatlyklary (fallback/ignore) dogry işleseler. Otherwiseogsam - major.

Jemi

Şertnama laýyklygy - düzgünler + düzgün-nyzam + awtomatlaşdyryş. Goşmaça dizaýn ediň, döwýän üýtgeşmeleri wersiýa ediň, tolerant reader ulanyň, diffleri we CDC-leri awtomatiki barlaň, deprekeýti meýilleşdiriň. Şeýlelik bilen, API-ler çalt ösüp, integrasiýa durnukly bolup biler.