API wersiýa strategiýalary

Näme üçin wersiýa gerek?

API müşderilerden has çalt üýtgeýär. Wersiýalaşdyrmak, çeňňekleri çykarmaga we integrasiýa bozulmazdan ýalňyşlyklary düzetmäge mümkinçilik berýär, üýtgeşmeleriň däp-dessuryny kesgitleýär we ewolýusiýany öňünden aýdyp bolýar. Açar: additiw üýtgeşmeler, majors - diňe döwükler, awtomatiki laýyklyk barlagy we oýlanyşykly sunset syýasaty üçin.

Esasy ýörelgeler

1. Additive-first: täze opsiýa meýdançalary/usullary/wakalary - takmynan; manysyny aýyrmak we üýtgetmek - major.
2. MGC (iň az kepillik şertnamasy) durnukly; baýlaşdyrmak - capabilities/'? include = 'arkaly.
3. Tolerant reader: Müşderiler näbelli ýerleri äsgermezlik edýärler we enum giňeldişlerini dogry başdan geçirýärler.
4. Semantic Versioning: `MAJOR. MINOR. Artefaktlar, SDK we wakalar üçin PATCH '.
5. Automate: schema-diff, linterler we CDC synaglary breaking-üýtgeşmeleri bloklaýar.

Wersiýany nirede saklamaly (salgy mehanikasy)

REST/HTTP

URI wersiýasy: '/v1/orders '→ diňe marşrutlamak, şlýuzlarda amatly. Minus - pikirleriň ewolýusiýasyny "ýapýar".
Mediatip/sözbaşy: 'Accept: application/vnd. example. orders. v1 + json '- formaty takyk dolandyrmak; jedel etmek has kyn.
Query-wersiýasy: '? api-version = 1' - A/B üçin amatly, ýöne keshlerde/bloglarda ýitirmek aňsat.
Maslahat: major-liniýalar üçin URI + feature/capability flags we minor giňeltmek üçin mazmun negasiýa.

gRPC / Protobuf

Paketler/Hyzmatlar: 'package payments. v1; service PaymentsV1; '- açyk çyzyklar.
Bellikleriň belgisi üýtgewsiz; Öçürilen bellikleri gaýtadan ulanmaň.
Täze meýdanlar - 'optional'; breaking → täze '.v2'.

GraphQL

URL-de düşnüksiz major shemasy. Migrasiýa @deprecated we penjirelerinden ewolýusiýa; "hakyky" major - täze endpoint-shema.
Complexity/depth - bu şertnamanyň bir bölegidir.

Event-driven (Kafka/NATS/Pulsar)

Wakanyň ady: 'payment. authorized. v1 '- görnüşdäki wersiýa.
Gabat gelmek tertibi bolan shemalaryň sanawy (Euro/JSON Schema/Protobuf) (BACKWARD/FORWARD/FULL).
Major → dual-emit 'v1' и 'v2' geçiş döwri üçin.

Wersiýalaryň modeli we üýtgetmek syýasaty

Semantic Versioning

MAJOR - döwýän üýtgeşmeler: meýdanlary aýyrmak/adyny üýtgetmek, partizasiýa açarlaryny üýtgetmek, statuslaryň başga manysy, tassyklamany berkitmek.
MINOR - additives: tolerant-reader-de täze goşmaça meýdanlar/endpointler/wakalar, täze enum-gymmatlyklar.
PATCH - şertnamany we semantikany üýtgetmezden düzedişler.

Deprecation & Sunset

Köne ('Deprecated: true', '@deprecated') belläň, senesini, alternatiwasyny we göçmek ýoluny çap ediň.
HTTP-de - "Sunset", "Deprecation" sözbaşylary; wakalarda - aýratyn '.deprecation. notice`.
Aýyrmak barada karar bermek üçin usage telemetriýasyny geçiriň.

Stillere görä wersiýa strategiýalary

REST

/ v1 ,/v2.
MINOR: shemalary giňeltmek, '? fields =', '? include ='; howpsuz enum-giňeltmek.
ETag/If-Match we idempotent POST.
Hatalar - durnukly format ('type', 'code', 'trace _ id').

gRPC

Döwmek üçin täze hyzmatlary/usullary giriziň: 'PaymentsV2. Capture`.
Ýalňyşlyklaryň ýagdaýlary we deadline semantikasy - şertnamanyň bir bölegi; üýtgetmek → täze usul/hyzmat.
Akym: Habarlaryň tertibi barada ylalaşyň we minor bilen üýtgetmäň.

GraphQL

Meýdanlary we görnüşleri erkin goşuň; aýyrmak - '@deprecated' + göçmek penjiresi arkaly; uly täzeden dizaýn → täze shema ('/graphql-v2 ').
Introspektsiýa we düşündirişler - müşderileriň göçmegi üçin must-have.

Events

Core vs enriched: ýadro durnukly, baýlaşdyryş golaýda ýaşaýar we aýratyn wersiýa edilýär.
Partiýa ýerleşdirmegiň açary major-setiriň çäginde üýtgemeýär.
Major-migrasiýalar - 'dual-emit' + proýeksiýalaryň/konsumerleriň göçmegi.

Negotiation we capability-baýdaklar

Capabilities: Müşderi iberýär 'X-Capabilities: risk_score,price_v2'; serwer giňeldilen görkezme bilen jogap berýär.
Bölekleýin jogaplar üçin Prefer (HTTP) we "hints".
Soketlerde/akymlarda - goldanýan giňeltmeleriň sanawy bolan handshake-habar.

Maýor wersiýalaryny agyrysyz çykarmak

1. RFC/ADR: näme üçin maýor gerek, näme döwülýär, töwekgelçilik matrisi.
2. Dual-run: paralel 'v1' we 'v2' (wakalary goşa çap etmek, iki gateway-rout, traffigi aýna etmek).
3. Migrasiýa adapterleri: agyr müşderiler üçin proxy/translatorlar 'v1 v2'.
4. Kanareýa: gateway-daky müşderiler/topikler/bellikler boýunça.
5. Sunset-plan: seneler, aragatnaşyk, stendler, synag maglumatlary, ulanylyşa gözegçilik.

Platformanyň we infrastrukturanyň rollary

API Gateway/Service Mesh: wersiýa, sözbaşylar, ýollar boýunça marşrut; rate-limit и auth per-version.
Schema Registry & Catalog: diff taryhy bilen spekulýasiýa/shemalar üçin hakykat çeşmesi.
CI/CD: линтеры (Spectral, Buf), schema-diff (OpenAPI-diff, Buf breaking), CDC (Pact).
Observability: wersiýa loglere/treyslere/metriklere düşmelidir.

Wersiýalary barlamak

PR-da schema-diff: breaking-i bloklamak.
"Consumer-Driven Contracts": üpjün ediji hakyky sarp edijileriň şertnamalaryna garşy barlanýar.
Golden samples: wersiýalara salgylanma jogaplary.
E2E-kanareýa: p95/p99, wersiýalaryň arasyndaky ýalňyşlyklary we wagtlary deňeşdirmek.
Wakalar üçin replay: proýeksiýalar gapma-garşylyksyz v2-e geçirilýär.

Maglumat we maglumat bazalarynyň göçmegi

REST/gRPC üçin: BD göçmeleri expand-and-contract arkaly utgaşdyrylýar (sütün goşuň → ýazmaga başla → okaň → köne okaň).
Events üçin: dual-emit we konsumerleriň göçmegi; käwagt - täze proýeksiýalara logyň täzeden oýnalmagy.
"Uly partlamalary" etmäň - gaýdýan ädimlere bölüň.

Howpsuzlyk bilen baglanyşyk

Skopes per version: v1/v2 üçin aýratyn OIDC-skopes/rollary.
Tokeniň syrlary/claim's - şertnamanyň bir bölegi; olary üýtgetmek = major.
PII/PCI - zerur bolmasa payload etmäň; täze meýdanlar - iň az artykmaçlyklary bilen.

Antipattern

Swagger-wash: spesifikasiýa täzelendi, serwer - ýok (ýa-da tersine).
Protobuf-tegleri gaýtadan ulanmak - maglumatlaryň ýuwaşlyk bilen zaýalanmagy.
Majorsyz enum-manylary üýtgetmek.
Global '/v2 '"kosmetika üçin": döwülmedik wersiýa.
Sunset/usage-metrikleri ýatdan çykardyňyz: köne wersiýasyny howpsuz aýyrmak mümkin däl.
Dürli maýor üçin bir umumy topik: sargytlary we açarlary garyşdyrmak.

Çykmazdan öň çek sanawy

• Üýtgeşmeler goşmaça ýa-da aýratyn major-çyzyk taýýarlandy.
• Linterler we schema-diff ýaşyl (arakesme geçmedi).
• SDK/mysallar/resminamalar, gabat gelýänligi baradaky bellikler täzelendi.
• Müşderilerde tolerant reader goşuldy; enum-fallback synagdan geçirildi.
• Major üçin - dual-run meýilnamasy, adapterler, kanareýa, sunset-seneler we poçta.
• Metrikler/loglar/söwdalar wersiýany we onuň boýunça segmentasiýany öz içine alýar.
• Deňeşdirmek üçin stend we altyn toplumlar v1, v2.
• Wakalar üçin - BACKWARD/FULL re modeimindäki shemalaryň sanawy, partizasiýa açarlary üýtgemez.

Şablon mysallary

REST (URI + negotiation)

Ugur: '/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 '(ýadro) we' payment. enriched. v2 '(jikme-jiklikler).
Geçiş döwri üçin prodýuserden 'v1' we 'v2' gidýär.

FAQ

Haçan hökman '/v2 'gerek?
Haçan-da inwariantlar/semantika üýtgese, meýdanlar/usullar aýrylanda, kesgitleýjileriň formaty, partizasiýa açary, SLA/taýtingler üýtgäp, müşderiler bozulýarlar.

REST-de aç-açan görnüşsiz ýaşap bilersiňizmi?
Diňe kiçi ulgamlar üçin. Daşarky integrasiýa üçin - açyk major-çyzyklar has gowudyr.

Köne wersiýany saklamak üçin näçe wagt gerek?
Ekosistemasyna baglydyr. Daşarky hyzmatdaşlar üçin, adatça, irki habar we kanareýka bilen 6-12 aý.

Wakalaryň wersiýasy API-den nähili tapawutlanýar?
Wakalar - append-only; täze semantika = täze '.v2' we dual-emit. Partiýanyň açary - şertnamanyň bir bölegi.

Jemi

Wersiýalaşdyrmak strategiýalary - bu proses we gurallar: additiv ewolýusiýa, açyk esasy çyzyklar, capability-negotiation, dual-run we sunset. Oňa awtomatiki laýyklyk barlaglaryny, ulanyş telemetriýasyny we dokumentleriň tertibini goşuň - şonda siziň API-leriňiz "gijeki göçmezden" we müşderilerde garaşylmadyk ýykylmazdan çalt öser.