Tehnologiýa we infrastruktura → API wersiýasy

API wersiýasy

1) Bu näme üçin zerur?

• goýberilende hadysalaryň töwekgelçiligini azaldar,
• gowulaşmagy we howpsuzlygy meýilleşdirmäge mümkinçilik berýär,
• hyzmatdaşlaryň migrasiýasynyň öňünden aýdyp boljak möhletlerini berýär.

2) Üýtgetmeleriň klassifikasiýasy

PATCH (döwmeýän): şertnamany üýtgetmezden düzedişler (goşmaça meýdanlary goşmak, tassyklama fiksleri).
MINOR (giňeldiji): back-compatible uzaldyşlar (täze endpointler, default bilen meýdanlar).
MAJOR (döwüjiler): gurluşy, semantikany üýtgetmek ýa-da meýdanlary/endpointleri aýyrmak.

SemVer 'MAJOR maslahat berilýär. MINOR. Artefaktlar üçin PATCH '(SDK/shemalar), şonda API-iň "daşarky" belgisi ýönekeýleşdirilip bilner (v1, v2).

3) REST wersiýa modelleri

1. URI:

`GET /v1/payments/{id}`

Plýuslar: aç-açan, kesilen, ugrukdyrmak aňsat. Minuslar: resminamalary köpeltmek, inçe ewolýusiýa etmek has kyn.

2. Sözbaşyda (content negotiation):

`Accept: application/vnd. company. payments. v2+json`

Artykmaçlyklary: çeýeligi, URL-de "zibil" ýoklugy, mediatipiň amatly ewolýusiýasy. Minuslar: brauzerde jedel etmek has kyn, tertipli müşderi gerek.

3. Kastom sözbaşyda:

`X-API-Version: 2` (или `Api-Version: 2025-09-01`)

Plýuslar: diňe şlýuzda. Minuslar: hiç hili standart ýok, kese seresap boluň.

4. Wersiýa-senesi (date-based):

Fintech/hasabat üçin gowy: üýtgeşmeleriň öňünden aýdyp boljak "bölekleri" (mysal üçin, çärýekleýin).

5. Resurs/model görnüşi:

Maslahat: daşarky integrasiýa üçin - 'URI vN' + Deprecation/Sunset sözbaşylary; içerki üçin - "Accept" ýa-da wersiýanyň ady, eger şlýuz we platforma muny goldaýan bolsa.

4) GraphQL

Has gowusy - global wersiýalarsyz. Meýdanlar/görnüşler we deprikasiýa arkaly ewolýusiýa ('@deprecated (reason: ""...)').
Bozýan üýtgeşmeler - diňe migrasiýa gollanmasy bolan "uly" penjirelerde (versioned schema namespace).
Bar bolan meýdanlaryň meaning üýtgemezligi üçin "n + 1" -e gözegçilik ediň.

5) gRPC / Protobuf

Meýdan belgileri üýtgemez. Uzakdaky ýerleri 'reserved' diýip belläň.
Howpsuz default bilen ýerleri optional hökmünde goşuň.
Utgaşyklygy awtomatiki barlamak üçin buf breaking/lint ulanyň.
Paketleri/modullary wersiýa ediň: 'package payments. v1;` → `payments. v2`.

6) Waka API-leri (EDA)

Wakanyň shemasy - şol bir şertnama. Ony Schema Registry (Euro/JSON-Schema/Protobuf) -da saklaň.
Topikler we wersiýalar: 'payments. v1. authorized`, `payments. v2. authorized`.
Bozýan üýtgeşmeler - wakanyň täze görnüşi ýa-da täze topik.
Ewolýusiýa kepillikleri: LTS döwründe konsumerler üçin backward-compatible.

7) Deprikasiýa syýasaty we EOL

• Deprecation: bellikler (OpenAPI/GraphQL SDL), sözbaşy
• 'Deprecation: true' we mümkin bolanda 'Sunset: Tue, 31 Mar 2026 00:00:00 GMT'.
• Aragatnaşyk: email/partnýor portaly, webhooks-bildirişler, release notes.
• Möhletler: MINOR - 3-6 aý, MAJOR - 9-18 aý (kritiklige bagly).
• Wagtlaýyn penjireler: "API wersiýa syýasatynda" belläň.

8) Ugrukdyrmak we goýbermek

API Gateway (Kong/Apigee/Nginx/Envoy): '/v1/' prefiksi boýunça düzgünler, sözbaşy ýa-da mediatip boýunça.

if ($http_accept ~ "vnd.company.payments.v2") { proxy_pass http://payments-v2; }

Canary/Blue-Green/Shadow: täze wersiýany traffigiň 1-5% -ine geçiriň, kontrakt ýalňyşlyklarynyň ölçeglerini we ýazgylaryny deňeşdiriň.
Feature Flags: Şertnamany üýtgetmän özüni alyp barşyny gizleýäris.
Sıfır-downtime migrasiýasy: MAJOR-da, maglumat shemasynyň goşa ýazylmagyny/okalmagyny (dual-write/read) üpjün ediň.

9) Şertnama-synag we laýyklyk gözegçiligi

OpenAPI Diff (ýa-da swagger-diff) - MINOR/PATCH-iň shemalary bozmaýandygyny barlaň.
Spectral linting - stil, hökmany meta-maglumatlar (wersiýa, Deprecation).
Consumer-Driven Contracts (Pact) - üpjün edijiniň müşderileri bozmaýandygyny kepillendirýär.
buf breaking для protobuf.
CI MAJOR ýokarlanmazdan döwüji üýtgeşmeler bilen ýykylmalydyr.

10) Resminamalar we SDK

Spekulýatorlary wersiýa ediň: '/docs/api/v1/openapi. json`, `/docs/api/v2/…`.
SemVer we changelog bilen (npm/maven/pypi) SDK dörediň.
SDK-da köne usullary annotasiýa/Deprecated bilen belläň.

11) Wersiýalara görä observability

• RPS/gizlinlik/wersiýadaky ýalňyşlyklar ('api _ version' belligi).
• Endpointleri ulanmak kartlary: v1-de başga kim bar?
• Alertler: "> 10% 4xx due to contract mismatch", "köne müşderiler> X% T-senesinden soň".

12) Kesmek we wersiýalary

Wersiýa ýolda CDN-iň kesleşmegini gowulandyrýar.

• `Vary: Accept, X-API-Version`.
• Kesmek açarlaryny döwmek üçin MINOR-daky jogap semantikasyny üýtgetmäň.

13) Howpsuzlyk

JWT wersiýasyny şifrlemäň ýa-da tikmäň - wersiýa token däl-de, haýyş bilen kesgitlenýär.
Ýygnagyň içerki belgilerini açmaň. Daşarky habarlarda "v1/v2" ulanyň.
MAJOR-da PII-iň tassyklamasyna, çäklerine, maskalanmagyna täzeden serediň.

14) Migrasiýa we awto-kömekçiler

"Migration Guide v1 → v2": meýdan laýyklyk tablisasyny, soraglaryň/jogaplaryň mysallaryny, edge ýagdaýlaryny çap ediň.
Köne meýdanlary görkezjek müşderiler üçin linterleri (CLI) hödürleýärsiňiz.
Uly hyzmatdaşlar üçin - iki wersiýasy we synag-dataseti bolan sandbox.

15) Anti-patternler

"Baky v1": ulanyş möhletleriniň we metrikleriniň ýoklugy.
MINOR/PATCH-de gizlin bozýan üýtgeşmeler.
"Query string" ('? v = 2') - keş we okalmagy bozýar.
"Bir endpoint - baýdakyň ýüz manysy": synagdan geçirmek/resminamalaşdyrmak kyn.

16) Girizmegiň çek-sanawy

1. Daşarky we içerki müşderiler üçin model (URI/Accept/Header) saýlandy.
2. Aýratynlyklary we SDK üçin SemVer, CI-de awtomatiki breaking-check.
3. Deprecation/Sunset aragatnaşyk syýasaty we şablonlary.
4. Gateway-marşrut + kanareýkalar, wersiýalara görä daşbordlar.
5. CDC/Contract tests kritiki integrasiýa üçin (tölegler, KYC, hasabat).
6. Resminamalar/SDK/migrasiýa gollanmasy goýberilişi bilen bir wagtda çap edilýär.
7. Seneler we jogapkärler bilen EOL meýilnamasy.

17) Mysallar

17. 1 REST (URI + sözbaşylar)

GET /v2/withdrawals/12345
Accept: application/json
Idempotency-Key: 4a1c-…-9f

json
{
"id": "12345",
"status": "PENDING_REVIEW",
"amount": {"value": "100.00", "currency": "EUR"},
"limits": {"daily": "500.00"},
"created_at": "2025-10-02T10:00:00Z",
"links": [{"rel": "cancel", "href": "/v2/withdrawals/12345/cancel", "method": "POST"}]
}

Deprecation: true
Sunset: Tue, 31 Mar 2026 00:00:00 GMT
Link: </v2/docs>; rel="successor-version"

17. 2 Content Negotiation

GET /payments/987
Accept: application/vnd.company.payments.v2+json
Vary: Accept

17. 3 GraphQL (meýdanyň deprikasiýasy)

graphql type Payment {
id: ID!
amount: Money!
status: PaymentStatus!
method: PaymentMethod!
legacyCode: String @deprecated(reason: "Use field `method`")
}

17. 4 gRPC (protobuf)

proto package payments.v2;

message Withdrawal {
string id = 1;
Money amount = 2;
string status = 3; // previously enum, now string with documented values reserved 4; // legacy field removed in v1 -> v2
}

17. 5 Waka modeli

• `wallet. v1. balance. updated`
• `wallet. v2. balance. changed '(giňeldilen shema bilen täze waka)

Shemalar Registride saklanylýar, prodýuser utgaşyklygy bozýan shema bilen wakalary çap etmeýär.

18) iGaming/fintech mazmuny (tejribe)

Tölegler: 'status '/' decline _ reason' giňeldilen täze PSP üçin v2 girizmek; hasabat üçin mapping v1 → v2 şlýuzynda.
KYC: MINOR 'pep _ screening' meýdançasyny goşýar, müşderiler v1 äsgermezlik edýärler, v2 - talap edýär.
Jogapkär oýunlar/çäkler: MAJOR çäklendirmeleriň modelini üýtgedýär (gündelik/hepdelik). EOL v1 çenli hasabatlylyga goşa eksport.
Düzgünleşdirijilere hasabat: kesgitlenen wersiýa-seneler: 'reporting-2025-01'.

19) Kiçi syýasat (wiki üçin mysal)

Model: daşarky API üçin - 'URI/vN/'; içerki - 'Accept:... vN + json' ýa-da 'X-API-Wersiýa: N'.
SemVer: spesifikasiýalar we SDK 'N. hökmünde çap edilýär. minor. patch`. MAJOR RFC/ADR talap edýär.
Gabat gelmek: MINOR/PATCH - bozulýan üýtgeşmeler bolmazdan. Döwýän → diňe MAJOR arkaly.
Deprecation/EOL: ≥ 90 günüň içinde bildiriş; Başlyklarda Sunset-data; Möhüm müşderiler üçin LTS şahasy.
Gözegçilik: Esasy integrasiýa üçin CI, CDC-de OpenAPI diff/buf breaking.
Observability: 'api _ version' bellikli metrikler/loglar.
Neşirler: canary 5% ≥ 24h, soňra ýaşyl metrlerde 100% -e çenli tapgyrlaýyn.

Jemi

Wersiýalaşdyrmak "URL-de/v2" hakda däl-de, proses hakda: ewolýusiýanyň aç-açan düzgünleri, utgaşyklygy awtomatiki barlamak, dolandyrylýan goýberişler we integrasiýalara hormat goýmak. Aýdyň syýasaty giriziň, gözegçiligi we gözegçiligi awtomatlaşdyryň - üýtgeşmeler önüme howp bolup bilmez.