Niyə API sabitliyini izləmək vacibdir

API müqavilədir. Hər hansı bir qeyri-sabitlik dönüşümlərin azalmasına, uğursuzluqların artmasına, ödənişlərin pozulmasına və isti fikslərin xərclərinə çevrilir. Sabitlik «heç nəyi dəyişmək» deyil, dəqiq zəmanət və ölçülə bilən SLO ilə idarə olunan dəyişikliklərdir. Aşağıda - buraxılışlar, pik yüklər və tərəfdaşlıq inteqrasiyaları yaşayan sabit API-ləri necə qurmaq olar.

1) «API sabitliyi» nədir və niyə puldur

Proqnozlaşdırma: eyni hərəkət → eyni nəticə (eyni kontekstdə).

Uyğunluq: Yeni versiyalar mövcud müştəriləri pozmur.

Mövcudluq və performans: aşağı p95/p99 gecikmə, minimum səhv.

Dəyişikliklərin idarə edilməsi: «sürprizlər» olmadan planlaşdırılan deprekeytlər.

Biznes effekti: daha az insident, daha yüksək dönüşüm, daha sürətli Time-to-Market (daha az koordinasiya və əl hotfix).

2) Hər şeydən əvvəl müqavilə

Spesifikasiya: OpenAPI/AsyncAPI + yeganə həqiqət mənbəyi (repo + CI-yoxlama).

Sərt razılaşmalar: tiplər, sahələrin məcburi olması, səhv kodları, semantika; «sakit» dəyişikliklərin qadağan edilməsi.

Uyğunluq səviyyələri:

Backwards compatible (isteğe bağlı sahələr, yeni enum dəyərləri, yeni end nöqtələri əlavə).
Breaking (silmə/adının dəyişdirilməsi, növlərin dəyişdirilməsi/semantika, sərtləşdirilmiş validasiya).
Müqavilə testləri: Pact/Swagger-based - provayder dərc edilmiş istehlak gözləntilərini pozarsa, çıxa bilməz.

3) SLI/SLO və səhv büdcə

SLI: uğurlu sorğuların payı, p95/p99 latency, kodlar üzrə 5xx/4xx payı, idempotent təkrarların payı.

SLO (nümunə): Uğur ≥ 99. 95%, p95 ≤ 100 ms (read) və ≤ 300 ms (write), 5xx ≤ 0. 05%.

Error Budget: dəyişikliklər/təcrübələr üçün tolerans; tükəndikdə - sabitliyə diqqət və riskli buraxılışların qadağan edilməsi.

4) İdempotentlik, retraj və əməliyyatlar

Write əməliyyatları üçün idempotent açarları (ödənişlər, dərəcələr, sifarişlər): təkrarlama → eyni nəticə.

Təkrarlanan şablonlar: eksponensial gecikmə və jitter ilə retry, server tərəfində deduplication.

İdempotent ədalət: 'lock → outcome → settle' (pul əməliyyatları) dəqiq TTL və statusları ilə.

Səhv semantikası: münaqişələr üçün 409/422, limitlər üçün 429, deqradasiyalar üçün 503/504, aydın 'reason _ code'.

5) Sxemlərin versiyalaşdırılması və təkamülü

Strategiya: SDK üçün SemVer, API versiyaları üçün URL/başlıqlar ('/v1 ', '/v2' və ya 'Accept: application/vnd. api+json; v=2`).

Uyğunluq qaydaları:

İsteğe bağlı sahələr əlavə edin; mövcud sahənin növünü heç vaxt dəyişdirməyin.
Enum genişləndirin və yenidən təyin etməyin; müştərilər bilinməyən dəyərlərə məhəl qoymamalıdır.
Breaking-dəyişikliklər üçün - müqavilənin yeni versiyası, de-fakto «fork».
Deprecation policy: elan → dəstək müddəti (məsələn, 6-12 ay) → mərhələli söndürmə; status-səhifə və changelog.

6) Hadisə müşahidə və idarəetmə

Metriklər (Prometheus/OTel): müvəffəqiyyət, latency (p50/p95/p99), RPS, saturation (CPU/heap), rate səhvləri növlərinə görə.

Trace: correlation id (məsələn, 'X-Request-ID'), span's by hops (gateway → BFF → xidmət).

Log: strukturlaşdırılmış, PII-safe, 'tenant', 'version', 'client _ id', 'idempotency _ key' sahələri ilə.

Alertlər: SLO-dejenerasiya, 5xx/429 sıçrayış, p99 böyümə, dedlock «vaxt qutuları».

Hadisələr: playbook, rabitə kanalları, action items və lazım olduqda SLO/eşik dəyişikliyi ilə postmortem.

7) Performans və sabitlik

Rate limiting / quotas: per-client/per-token; 429 'Retry-After' ilə dürüst cavablar.

Circuit breaker/bulkhead: asılılıq təcrid, yerli follbacks.

Caching: ETag/If-None-Match, 'Cache-Control' üçün; server-side isti açarları cache.

Pagination: cursor-based, səhifə ölçüsü limitləri; «Bütün dünyanı yükləyin».

Yük nəzarəti: backpressure, növbələr, write yolları parçalanması.

Koordinasiya: dəqiq read-model (strong/eventual), hadisələrin deduplikasiyası.

8) Kanarya və təhlükəsiz hesablamalar

Feature flags: buraxılış olmadan daxil nəzarət; problemli funksionallığı söndürə bilərsiniz.

Canary/Blue-Green: yeni versiyası qismən trafik, SLI müqayisə; deqradasiya zamanı avtomatik geri çəkilmə.

Shadow traffic: «quru» qaçış üçün yeni versiyada sorğuları dublyaj.

Schema-migrations: iki mərhələli - əvvəlcə genişləndirin (backfill), sonra dəyişdirin, sonra təmizləyin.

9) Sənədləşmə və DX (Developer Experience)

Vahid portal: interaktiv sənədlər, nümunələr, SDK, Postman/Insomnia kolleksiyaları.

Changelog və status-səhifə: RSS/Webhook/poçt dəyişikliklər və hadisələr haqqında.

Guides səhvlər: kart 'reason _ code → müştəriyə nə etmək lazımdır'.

Sabit sandbox/mock: versiyalar, fiksturlar, deqradasiya ssenariləri (429/5xx), tərəfdaşların avtostestləri üçün müqavilələr.

10) Təhlükəsizlik vs sabitlik

Autentifikasiya: qısa ömürlü tokenlər, downtime olmadan açar rotasiyası (JWKS, kid).

Giriş hüquqları: RBAC/ABAC; siyasət dəyişikliyi müştəriləri pozmamalıdır → «dry-run» edin və əvvəlcədən uğursuzluqları qeyd edin.

Sui-istifadədən qorunma: WAF, bot filtrləri, anomaliyalar; dəqiq səhv və xidmət «düşməsi» deyil.

PII-minimallaşdırma: log maskalanması, anonimləşdirmə üçün sabit sxemlər (analitikanın pozulmaması üçün).

11) Cavab və səhv nümunələri

Vahid format:

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

Statuslar: 2xx - uğur; 4xx - dəqiq kodlu müştərinin səhvi; 5xx - server problemi (detalları sızdırmadan).

İdempotent statusları: təkrar üçün orijinal 'resource _ id '/' transaction _ id' qaytarın.

Səhv versiyası: köhnə semantikanı dəyişmədən yeni 'reason _ code' əlavə edin.

12) Tez-tez səhvlər və onlardan necə qaçmaq olar

Sakit breaking-changes (sahənin adının dəyişdirilməsi/silinməsi) → müştərilərdə düşmə. Həll: müqavilə testləri + sxem linterləri.

Retraj əməliyyatlarının təsadüfi dublikatları. Həll: İdempotent açarları və nəticə izinin saxlanması.

«Dolğun» cavablar → p95 artır. Həll :/' fields = '/kompakt formatlar, gzip/br.

Müştərilərdə sərt enum 's → yeni dəyərlərdə enum. Həll: «ignore unknown» siyasəti.

Audit və telemetriyanın qarışması → yük və qarışıqlıq. Həll: müxtəlif kanallar/anbarlar.

Xarici asılılığın tək uğursuzluq nöqtəsi. Həll: Cash, CB, funksionallığın deqradasiyası, timeouts.

13) Mini stabillik çek siyahısı API

Müqavilə və uyğunluq

OpenAPI/AsyncAPI yeganə həqiqət mənbəyi kimi
Uyğunluq qaydaları və deprecation policy sənədləşdirilmişdir
CI-də müqavilə testləri (consumer-driven)

Etibarlılıq və perf

Write əməliyyatlarının idempotentliyi (açarlar, TTL, deduplikasiya)
Rate limiting, retry-policy cursors
Circuit breaker/bulkhead, cache, taymaut

Müşahidə

SLI/SLO, error budget, alertlər
correlation id ilə Trace, struktur log
Dashboard p95/p99/end və versiyalar üzrə müvəffəqiyyət

Hesablamalar

Canary/Blue-Green, feature flags, auto catch
İki mərhələli sxem miqrasiyası, shadow-traffic
Hadisə planı və postmortem

DX və kommunikasiyalar

Sənədləşmə/SDK/kolleksiyaları, changelog, status-səhifə
Sabit sandbox və test data dəsti
Səhv kodları və tövsiyələr «müştəri nə etmək lazımdır»

14) Nümunələrin qısa nümunələri

İdempotent ödənişi


POST /payments
Idempotency-Key: u123    order456

→ 201 { "payment_id": "p789", "status": "pending" }
Təkrar → 200 {"payment_id": "p789", "status": "pending"}

Sxemin təhlükəsiz təkamülü

Addım 1: Yeni 'customer _ email' (optional) sahəsi əlavə edin.

Addım 2: Serverdə doldurmağa başlayın; hazır olan müştərilər - oxuyun.

Addım 3: tarixi ilə köhnə 'email' deprecation elan.

Addım 4: N ay sonra - '/v2 'tərcümə və' email 'yalnız orada silin.

Jitter retrayları


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

API sabitliyi idarə olunan mühəndislikdir: müqavilə + uyğunluq + ölçülə bilən hədəflər + buraxılış intizamı. SLO/səhv büdcə, idempotentlik, müqavilə testləri, müşahidə və kanaryaları tətbiq edən komandalar funksionallığı daha sürətli və təhlükəsiz buraxırlar və tərəfdaşlar onlara etibar edirlər. Bu gün birbaşa pul və sabah proqnozlaşdırıla bilər.