Näme üçin API durnuklylygyna gözegçilik etmek möhümdir?

API - şertnama. Onuň islendik durnuksyzlygy öwrülişikleriň, şowsuzlyklaryň, tölegleriň şowsuzlyklarynyň we gyzgyn fiksleriň çykdajylarynyň azalmagyna öwrülýär. Durnuklylyk "hiç zady üýtgetmez" däl-de, anyk kepillikler we ölçenen SLO bilen dolandyrylýan üýtgeşmeler. Aşakda - goýberilişleri, iň ýokary ýükleri we hyzmatdaş integrasiýalaryny başdan geçirýän durnukly API-leri nädip gurmaly.

1) "API durnuklylygy" näme we näme üçin pul?

Öňünden aýdylýanlygy: şol bir hereket → şol bir netije (şol bir kontekstde).

Gabat gelmek: täze wersiýalar bar bolan müşderileri bozmaýar.

Elýeterlilik we öndürijilik: pes p95/p99 gizlinlik, iň az ýalňyşlyk.

Üýtgeşmeleri dolandyrmak: "garaşylmadyk" meýilleşdirilen deprekeýtler.

Iş täsiri: az hadysalar, has ýokary öwrülişik, has çalt Time-to-Market (az razylyklar we el hatfikleri).

2) Şertnama ilki bilen

Aýratynlygy: OpenAPI/AsyncAPI + ýeke-täk hakykat çeşmesi (repo + CI-barlaglar).

Berk şertnamalar: görnüşleri, meýdanlaryň hökmanylygy, ýalňyşlyk kodlary, semantika; "asuda" üýtgeşmeleri gadagan etmek.

Gabat geliş derejeleri:

Backwards compatible (goşmaça meýdanlary, täze enum bahalaryny, täze endpointleri goşmak).
Breaking (aýyrmak/adyny üýtgetmek, görnüşini/semantikasyny üýtgetmek, tassyklamany berkitmek).
Şertnama synaglary: Pact/Swagger-based - üpjün ediji çap edilen sarp edijiniň garaşyşlaryny bozsa, çykyp bilmez.

3) SLI/SLO we nädogry býudjet

SLI: üstünlikli haýyşlaryň paýy, p95/p99 latency, kodlar boýunça 5xx/4xx paýy, idempotent gaýtalamalaryň paýy.

SLO (mysal): Üstünlik ≥ 99. 95%, p95 ≤ 100 ms (okaň) we ≤ 300 ms (write), 5xx ≤ 0. 05%.

Error Budget: üýtgeşmelere/synaglara rugsat; tükenende - durnuklylyga we töwekgelçilikli neşirleriň gadagan edilmegine ünsi jemleýär.

4) Idempotentlik, retralar we geleşikler

Write-amallar üçin idempotent açarlary (tölegler, nyrhlar, sargytlar): gaýtalamak → şol netije.

Gaýtalanýan şablonlar: eksponensial gijikdirme we jitter bilen retry, serweriň tarapynda duplikasiýa.

Idempotent adalat: 'lock → outcome → settle' (pul amallary) anyk TTL we statuslary bilen.

Hatalaryň semantikasy: 409/422 gapma-garşylyklar üçin, 429 çäklendirmeler üçin, 503/504 zaýalanmalar üçin, aýdyň 'reason _ code'.

5) Shemalaryň wersiýalaşdyrylmagy we ewolýusiýasy

Strategiýa: SDK üçin SemVer, URL/API wersiýalary üçin sözbaşylar ('/v1 ', '/v2' ýa-da 'Accept: application/vnd. api+json; v=2`).

Laýyklyk düzgünleri:

Meýdanlary goşmaça hökmünde goşuň; bar bolan meýdanyň görnüşini hiç wagt üýtgetmäň.
Enum giňeldiň, täzeden kesgitlemäň; müşderiler näbelli manylary äsgermezlik etmegi başarmalydyrlar.
Breaking-üýtgeşmeler üçin - şertnamanyň täze wersiýasy, de-fakto "fork".
Deprecation policy: bildiriş → goldaw döwri (mysal üçin 6-12 aý) → tapgyrlaýyn ýapmak; status-sahypa we changelog.

6) Hadysalara syn etmek we dolandyrmak

Metrikler (Prometheus/OTel): üstünlik, latency (p50/p95/p99), RPS, saturation (CPU/heap), rate hatalary görnüşlerine görä.

Söwda: correlation id (mysal üçin 'X-Request-ID'), span's by hops (gateway → BFF → service).

Loglar: gurluşly, PII-safe, 'tenant', 'version', 'client _ id', 'idempotency _ key'.

Aladalar: SLO-dejenerasiýasy, 5xx/429 köpelmegi, p99 beýikligi, "wagt gutulary".

Wakalar: pleýbuk, aragatnaşyk kanallary, action items bilen postmortem we zerur bolsa SLO/bosagalaryň üýtgemegi.

7) Öndürijilik we durnuklylyk

Rate limiting / quotas: per-client/per-token; dogruçyl jogaplar 429 'Retry-After'.

Circuit breaker/bulkhead: endikleriň izolýasiýasy, ýerli follbekler.

Kesmek: ETag/If-None-Match, 'Cache-Control' üçin; server-side gyzgyn açarlardaky keş.

Paginasiýa: cursor-based, sahypanyň ululygy boýunça çäkler; "bütin dünýäni aşa ýükläň".

Ýük gözegçiligi: backpressure, nobatlar, write-ýollaryň bölünmegi.

Utgaşyklyk: okalýan modeli (strong/eventual), wakalaryň duplikasiýasyny anyk görkezmek.

8) Kanareýa we howpsuz hasaplamalar

Feature flags: goýberilmezden açmagy dolandyrýarys; problemaly funksiýany öçürip bolýar.

Canary/Blue-Green: täze wersiýa bölekleýin trafik, SLI deňeşdirme; pese gaçanda awtomatiki jogap.

Shadow traffic: "gury" geçmek üçin täze wersiýa haýyşlary köpeltmek.

Schema-migrations: iki basgançakly - ilki giňelt (backfill), soň geçiň, soň arassalaň.

9) Resminamalar we DX (Developer Experience)

Bir portal: interaktiw resminamalar, mysallar, SDK, Postman/Insomnia kolleksiýalary.

Changelog we status-sahypa: RSS/Webhook/poçta barada üýtgeşmeler we wakalar.

Hata boýunça gollanmalar: 'reason _ code →' kartoçkasy.

Durnukly sandbox/mock: wersiýalar, fiksturalar, zaýalanma ssenarileri (429/5xx), hyzmatdaşlaryň awtostestleri üçin şertnamalar.

10) Howpsuzlyk vs durnuklylyk

Autentification: gysga ömürli bellikler, downteimsiz açarlaryň aýlanmagy (JWKS, kid).

Giriş hukugy: RBAC/ABAC; Syýasatyň üýtgemegi müşderileri bozmaly däldir → "dry-run" ýerine ýetiriň we şowsuzlyklary öňünden ýazga alyň.

Hyýanatçylykly peýdalanmakdan goramak: WAF, bot-süzgüçler, anomaliýalar; hyzmatyň "ýykylmagy" däl.

PII-minimalizasiýa: bloglarda gizlenmek, adynyň aýdylmazlygy üçin durnukly shemalar (analitikanyň bozulmazlygy üçin).

11) Jogaplaryň we ýalňyşlyklaryň nusgalary

Bitewi format:

json
{ "error": { "code": "rate_limit", "message": "Too many requests", "retry_after_ms": 1200, "details": {...} } }

Statuslar: 2xx - üstünlik; 4xx - anyk kody bolan müşderiniň ýalňyşlygy; 5xx - serwer meselesi (jikme-jiklikler syzmazdan).

Idempotent statuslary: gaýtalamak üçin asyl 'resource _ id '/' transaction _ id' -ni yzyna beriň.

Hatalaryň wersiýasy: täze 'reason _ code' köne semantikleri üýtgetmeden goşuň.

12) Ýygy-ýygydan ýalňyşlyklar we olardan nädip gaça durmaly

Sessiz breaking-changes (meýdançanyň adyny üýtgetmek/aýyrmak) → müşderiler üçin düşmek. Çözgüt: şertnama synaglary + shemalaryň linterleri.

Retralarda amallaryň tötänleýin dublikatlary. Çözgüt: idempotent açarlary we netijäniň yzyny saklamak.

"Doldurylan" jogaplar → p95 ösýär. Çözgüt: proýeksiýalar/' fields = '/ykjam formatlar, gzip/br.

Müşderilerdäki berk enum 'lar → täze bahalarda düşýär. Çözgüt: "ignore unknown" syýasaty.

Auditiň we telemetriýanyň garyşmagy → ýük we bulaşyklyk. Çözgüt: dürli kanallar/ammar.

Daşarky garaşlylygyň ýeke-täk ret ediş nokady. Çözgüt: keş, CB, funksiýanyň pese gaçmagy, timeouts.

13) API durnuklylygynyň kiçi çek sanawy

Şertnama we gabat gelmek

Hakykatyň ýeke-täk çeşmesi hökmünde OpenAPI/AsyncAPI
Laýyklyk we deprecation policy düzgünleri resminamalaşdyryldy
CI-de şertnama synaglary (consumer-driven)

Ygtybarlylyk we perf

Write amallarynyň meňzeşligi (açarlar, TTL, duplikasiýa)
Rate limiting, retry-policy with jitter, pagination cursors
Circuit breaker/bulkhead, kesh, wagt

Syn ediliş

SLI/SLO, error budget, alerts
correlation id, gurluş ýazgylary bilen söwda etmek
Dashbordlar p95/p99/endpointler we wersiýalar boýunça üstünlik

Hasaplamalar

Canary/Blue-Green, feature flags, awtookat
Shemalaryň iki basgançakly göçmegi, shadow-traffic
Wakalar we postmortem meýilnamasy

DX we aragatnaşyk

Resminamalar/SDK/kolleksiýalar, changelog, status-sahypa
Durnukly sandbox we synag maglumatlary toplumy
Ýalňyşlyk kodlary we "müşderi näme etmeli" maslahatlary

14) Patternleriň gysga mysallary

Idempotent tölegi


POST /payments
Idempotency-Key: u123    order456

→ 201 { "payment_id": "p789", "status": "pending" }
Gaýtalamak → 200 {"payment_id": "p789", "status": "pending"}

Shemanyň howpsuz ewolýusiýasy

1-nji ädim: Täze 'customer _ email' (optional) meýdançasyny goşuň.

2-nji ädim: Ony serwerde dolduryp başlamak; taýýar bolan müşderiler okaýarlar.

3-nji ädim: Köne 'email' depressiýasyny senesi bilen yglan et.

4 ädim: N aýdan soň - '/v2 '-e geçirmek we' email '-y diňe şol ýerde aýyrmak.

Jitter bilen retrailer


delay = base (2^attempt) + random(0, base)

API durnuklylygy - dolandyrylýan in engineeringenerçilik: şertnama + gabat gelmek + ölçelýän maksatlar + goýberilişleriň tertibi. SLO/nädogry býudjet, idempotentlik, şertnamalaýyn synaglar, gözegçilik we kanareýalary girizýän toparlar funksionallygy has çalt we ygtybarly çykarýarlar, hyzmatdaşlar bolsa olara ynanýarlar. Şu gün göni pul we ertir öňünden aýdyp bolar.