API wersiýasy we şertnama laýyklygy

TL; DR

Gabat gelmek şowlulyk däl-de, düzgün-nyzamdyr. Takyk wersiýa syýasatyny (SemVer), üýtgeşmeleriň matematikasyny ("döwýän", ýok), şertnama synaglaryny, shema registrlerini we Sunset-proseduralaryny saklaň. Pul we gabat gelmek üçin - vN bilen berk REST/gRPC, UI-agregasiýalar üçin - '@deprecated' bilen ewolýusiýa GraphQL. Elmydama: kanareýanyň traffigi, ters gabat gelmek ≥ bir goýberiş aýlawy, migrasiýa gaýlary, meýdanlary ulanmagyň telemetriýasy.

1) Esasy düşünjeler we maksatlar

Backwards-compatible (BC): köne müşderiler täze serwere laýyk gelýär.
Forwards-compatible (FC): köne serwere täze müşderiler laýyk gelýär (çäkli).
Wire-gabat gelmek: "sim" formaty bozulmaýar (esasanam gRPC/Protobuf üçin möhümdir).
SemVer: `MAJOR. MINOR. PATCH '- şertnamany bozýarsyňyz → MAJOR-y ýokarlandyrýarsyňyz.

Maksat: döwüji üýtgeşmeleri azaltmak we öňünden aýdyp boljak migrasiýa penjirelerini üpjün etmek.

2) Üýtgeşmeleriň matrisi: näme mümkin we näme mümkin däl

3) Dürli API stilleri üçin syýasatlar

3. 1 REST

URI wersiýasy ('/v1/... ') ýa-da domen wersiýasy (' api-v1. '). Sözbaşy wersiýasy - diňe içerki ýagdaýlar üçin.
Goşuň, aýyrmaň: täze meýdanlar - tamam, köne - diagrammada 'deprecated' diýip belläň we azyndan bir aýlaw goýuň.
Statuslar/ýalňyşlyklar: kodlary we gurluşy 'error' üýtgetmäň. code/error. message/error. details`.
Idempotentlik üýtgewsiz: howpsuz 'POST' c 'Idempotency-Key' -ni "özüni alyp barşyň başga" çagyryşyna öwürmäň.

3. 2 gRPC / Protobuf

Meýdan belgileri mukaddes: uzakdaky belgileri gaýtadan ulanmaň, 'reserved' diýip belläň.
Diňe täze optional/repit meýdanlary goşmak; "gaty hökmany" - tassyklama arkaly, 'required' däl.
Wersiýa paketleri: 'payments. v1`, `payments. v2`.
Hyzmatlaryň laýyklygy: täze RPC → täze usul; garrylaryň özüni alyp barşyny üýtgetmeris.

proto message Payout {
reserved 4 ;//field deleted, number reserved string id = 1;
string currency = 2;
int64 amount_minor = 3;
// v2: optional string comment = 5;
}

3. 3 GraphQL

v2-siz ewolýusiýa: meýdanlary/görnüşlerini goşuň; öçürmek - penjiräniň yglan edilmegi bilen '@deprecated (reason)' arkaly.
Persisted Queries: aç-açan müşderiler üçin ak soraglaryň sanawyny ulanyň - gabat gelýändigine gözegçilik etmek has aňsat.
Field-level authZ we telemetriýa: aýyrmazdan ozal haýsy meýdanlaryň hakykatdanam ulanylýandygyny biliň.

graphql type Payout {
id: ID!
amountMinor: Long!
currency: String!
comment: String @deprecated(reason: "Use note")
note: String
}

3. 4 Webhuklar

Wersiýa ýolda ('/webhooks/v1/payments ') we wakanyň kesgitlenen konweri (' event _ id ',' type ',' ts ',' data ').
Gollary/NMAS-y üýtgewsiz saklaň; täze algoritmler - baýdakly opsiýa ýaly.
Diňe täze 'data.' we 'headers' älemleri geçer.

4) API Gateway we wersiýalary ugrukdyrmak

Rules-based routing: '/v1 'prefiksi boýunça,' X-Api-Version 'sözbaşy boýunça, domen boýunça.
Shadow/Canary: Önümçilik traffiginiň bir bölegini "kölegä" täze wersiýasyna görkeziň, jogaplary deňeşdiriň.
Rate/Quotas per-version: göçmek wagtynda köne müşderileri goraýar.

• 'Sunset: ' - wersiýanyň öçürilen senesi
• 'Deprecation: true' - wersiýasy köne
• `Link: ; rel = "deprecation" '- changelog/hyde göçmek

nginx location ~ ^/v2/ {
proxy_pass http://api_v2;
}
location ~ ^/v1/ {
add_header Deprecation "true";
add_header Sunset "Thu, 01 May 2026 00:00:00 GMT";
proxy_pass http://api_v1;
}

5) Shemalaryň we şertnamalaryň registrleri

OpenAPI / JSON Schema для REST; Protobuf descriptors для gRPC; SDL registry для GraphQL.
CI-barlaglar: linters + "breaking-changes check" PR-da.
Consumer-Driven Contracts (CDC): Sarp ediji synaglary (Pact/analog) - göze görünmeýän döwüklerden goramak.
Changelog: machine-readable (mysal üçin 'CHANGELOG. md '+ sanawdaky goýberiş bellikleri).

6) Meýdanlaryň ewolýusiýasy: amaly düzgünler

ID/açarlar: Täze '_ v2' meýdany we geçiş döwri bolmazdan formaty (UUID, int) üýtgetmäň.
Wagt/walýuta: UTC ISO-8601/epoch we amount_minor + currency saklaň; masştabyny (teňňe/sent) üýtgetmäň.
Enum: bellik goşuň - ok; köne manysyny üýtgetmäň. REST üçin - ints däl-de, string bahalaryny beriň.
Paginasiýa: cursor-based has durnukly; kursoryň semantikasyny üýtgetmäň.

7) Deprikasiýa we "Sunset" - protsedura

1. Bildiriş (T-90/60): changelog, hyzmatdaşlara ibermek, "Deprecation/Sunset" sözbaşylary.
2. Gaýtalanýan döwür: V1 we V2 paralel işleýär; V1 jogaplarda/bloglarda duýduryşlar bilen üpjün edilýär.
3. Telemetriýa ulanyşy: başga kim V1 diýýär? nokat aragatnaşyklary.
4. V1 doňdurmak: diňe bagfikler/çyzgysyz.
5. Öçürmek (Sunset): 410 Gone ýa-da göçmek üçin görkezmeler bilen blok sahypasy.

8) Agyrysyz goýberişler: ýerleşdiriş strategiýalary

Blue/Green ýa-da Weighted routing: 1-5-25-50-100% traffik.
"Compatibility window": daşarky API-ler üçin azyndan 1-2 sany minor çykyşy, 6-12 aýdan köp.
Feature Flags: wersiýasyny üýtgetmezden täze logika meýdançalaryny/şahalaryny goşmak üçin.
Okamak/Write-bölmek: ilki bilen täze meýdany okamak üçin goldaw goşuň, soň bolsa ýazyp başlaň.

9) Laýyklyk synagy (tejribe bukjasy)

Köne wersiýalaryň jogaplary üçin altyn-synaglar.
Diagrammalaryň Diff synaglary: CI-de breaking gadaganlygy.
V2 (shadow) üçin staging-da önümçilik ýollaryny replay.
Back/Forward ssenarileri: köne serwerde täze müşderi we tersine (FC kabul edilýän ýerde).
Webhuklaryň şertnama synaglary: goly, formaty, wagty barlamak.

10) Wersiýalaşdyryş prosesiniň metrikleri we SLO

Iň soňky MINOR-daky müşderileriň% -i (maksat Sunset-den 80% öň ≥).
Goýbermek üçin laýyklyk/elýeterlilik ýalňyşlyklary (maksat - 0).
Köne wersiýadaky jaňlaryň paýy (Sunset-e çenli azalýar).
Müşderiniň göçýän wagty (median/p95).
Latency/regression delta wersiýalarynyň arasynda (bazadan erbet däl).

11) Artefaktlaryň mysallary

yaml components:
schemas:
Payout:
type: object properties:
id: { type: string, format: uuid }
amount_minor: { type: integer }
currency: { type: string }
comment:
type: string deprecated: true description: "Use note"
note: { type: string }

proto syntax = "proto3";
package payouts. v1;
message Payout { reserved 5; string id=1; int64 amount_minor=2; string currency=3; }

graphql type Query { payout(id: ID!): Payout }

12) Ýanaşyk kanallary wersiýalaşdyrmak

SDK/CLI: SemVer + API wersiýasyna garaşlylyk, laýyklyk README-de göz öňünde tutulandyr.
Wakalar/akymlar (WS/Kafka): in 'envelope wersiýasy. version`; täze atributlar - opsiýa; dedup we rezýume wersiýalaryň arasynda birmeňzeş işleýär.
Hasabat/CSV: faýl/şlýapa adyndaky wersiýa; sag tarapdaky sütünleri goşuň; Tertibi/görnüşleri üýtgetmäň.

13) Dolandyryş we rollar

Şertnamanyň eýesi (domain owner), API Steward (düzgünler we linterler), Release Manager (Sunset/Aragatnaşyk).
Breaking-üýtgeşmeler üçin RFC prosesi: iş esaslary, migrasiýa meýilnamasy, artefaktlar, seneler.
API-iň ýeke-täk katalogy: shemalary, wersiýalary, Sunset-senenamany, aragatnaşygy görüp bilersiňiz.

14) Anti-patternler

"Sessiz" döwükler: statusyny/ýalňyşlygyny/görnüşini wersiýasyz üýtgedýäris.
Protobuf-belgileri gaýtadan ulanmak köne müşderileriň belliklerini hem ýok edýär.
Telemetri bolmadyk GraphQL - "degip" aýyrmak.
Global v2 - nokat ewolýusiýasynyň ýerine megamigrasiýa.
Jemgyýetçilik API üçin query-parametrdäki wersiýa aç-açan we gowşak shema.
Migrasiýa gidleri we mysallar ýok - hyzmatdaşlar çekilýär, möhletler bozulýar.

15) Täze wersiýanyň çykarylmagyny barlamak

• Shema täzelendi (OpenAPI/Protobuf/SDL), linterler we breaking-checks geçdi.
• Integrasiýa we şertnama synaglary (CDC) goşuldy.
• SDK/kod mysaly/migrasiýa gollanmasy we Changelog taýýar.
• 'Deprecation/Sunset' (köne wersiýa üçin) + "How to migrate" sahypasy goşuldy.
• Canary/Shadow meýilnamasy, ölçegleri deňeşdirmek üçin alertler we daşbordlar.
• Ters gabat gelmek ylalaşylan möhlete saklanýar.
• Yzyna gaýtarmak meýilnamasy (rollback) we töwekgelçilik matrisi ylalaşyldy.

Gysgaça maglumat

Durnukly API "birbada" däl-de, bir prosesdir. Düzgünlere laýyklykda ýaşaň: SemVer + add-only ewolýusiýa + shemalaryň sanawy + şertnama synaglary + Sunset-proseduralary. Stilleri (REST/gRPC/GraphQL) we olaryň syýasatlaryny bölüň, API Gateway-e wersiýalary ugrukdyryň, kanareýkalar bilen çykaryň, täsirini ölçäň. Şeýlelik bilen, "döwýän garaşylmadyk ýagdaýlardan" gaça durarsyňyz, hyzmatdaşlaryň integrasiýasyny çaltlaşdyrarsyňyz we pul we gabat gelýän möhüm domenler üçin öňünden aýdylýanlygy saklarsyňyz.