API İnteqrasiya Cek siyahısı

0) Tez baxış (kim nə edir)

• İnteqrasiya sahibi təyin
• On-call əlaqə (24 × 7/qul. saat) təyin
• Razılaşdırılmış SLO/SLA və buraxılış dəstək pəncərəsi
• Status-səhifə və hadisə kanalı (email/Slack/Webhook)

1) Access, mühit, versiyası

• Giriş sandbox/staging/production əldə
• API versiyası təsdiqləndi: '/v1 '/başlıq 'X-API-Version'
• Allowlist IP və şəbəkə qaydaları xüsusi
• Saat və TZ: UTC bütün vaxt, NTP sinxronizasiya
• SemVer və matris versiyalarında SDK/müştəri uyğunluğu yoxlanıldı

2) Autentifikasiya və tokenlər

• Mexanizm razılaşdırılmışdır: OAuth2 Client Credentials/Auth Code + PKCE/API Key/mTLS
• Access Token ömrü və Refresh Token rotasiyası xüsusi
• Üçün API Key: sirr bir dəfə göstərilir, sirr menecerində saxlanılır
• JWKS/JTI/' kid 'yoxlanılır, aktiv clock skew ± 5 min
• 'Authorization' başlıqları daxil deyil (redaktə)

bash curl -sS -H "Authorization: Bearer $TOKEN" https://api. example. com/v1/ping

3) Təhlükəsizlik və məxfilik

• TLS 1. 2 +/HSTS, isteğe bağlı mTLS
• PII-Minimallaşdırma: Yalnız lazımi göndərin, log maskaları
• Saxlama və silmə siyasəti (GDPR/DSAR) sənədləşdirilmişdir
• Secret rotation: aktiv/növbəti açar, rollover planı
• Anti-sui-istifadə: Capcha/açar yaradılması sürəti/qeydiyyat məhdudiyyətləri

4) Limitlər, kvotalar və backoff

• 'X-RateLimit- '/' X-Quota-' başlıqları açıqlandı
• Müştəri 429 və 'Retry-After' hörmət edir
• Yalnız 5xx/408/429 üçün retrailer, eksponent backoff + jitter
• Göstərilən cəhd/vaxt həddi (məsələn, ≤ 5 cəhd, ≤ 60s ümumi)

5) İdempotentlik və münaqişələr

• Bütün write əməliyyatları 'Idempotency-Key' ilə göndərilir (TTL ≥ 24-72 saat)
• Təkrarlanan münaqişə → 409 IDEMP_REPLAY emal
• Rəqabətli yeniləmələr üçün ETag/' If-Match 'daxildir (varsa)

bash curl -X POST /v1/payments \
-H "Idempotency-Key: pay-<uuid>" \
-d '{"amount":"12. 34","currency":"EUR"}'

6) Paginasiya və inkremental deltalar

• cursor/keyset pagination istifadə olunur ('next _ cursor', 'has _ more')
• Sabit çeşidləmə '(updated_at, id)' sənədləşdirilmişdir
• Daxili boşaltmalar: watermark və ya change token
• Üst-üstə düşən pəncərələr (1-2 dəq) və dedup '(id, version/seq)'

7) Səhv formatı və diaqnostika

• Vahid 'application/problem + json' formatı (RFC 7807)
• Sahə dəstəyi: 'error _ code', 'trace _ id', 'retriable', 'detail'
• Səhv kartı və müştəri hərəkətləri təsvir (runbook)

json
{
"type":"https://docs. example. com/errors/validation_failed",
"title":"Validation failed",
"status":422,
"error_code":"VAL_001",
"trace_id":"a1b2c3",
"retriable":false
}

8) Vebhuke: kvitasiya və təkrar

• Uğur təsdiqi - hər hansı bir 2xx; enqueue sonra sürətli ACK
• Подпись HMAC (`X-Signature: sha256=...`), `X-Webhook-Id`, `X-Retry`
• Retraj siyasəti: backoff + jitter, 24-72 saata qədər
• DLQ + Replay: mövcud və yoxlanılır
• Dedup-saxlama qəbuledici, TTL ≥ pəncərə retras

9) Müşahidə və izləmə

• Daxil OpenTelemetry Hook Müştəri/SDK
• Bütün zəncir boyunca 'trace _ id '/' X-Request-ID' korrelyasiyası
• Дашборды: `requests_total`, `errors_total{status}`, `latency_p95`, `retry_count`, `429_rate`
• Alarms: 5xx/429 sıçrayış, p95 böyümə, success rate, lag webhook

promql rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m])

10) Performans və sabitlik

• Bağlantı hovuzları, keep-alive, mümkün olan HTTP/2/3
• Paralellik məhduddur (backpressure), müştəri növbəsi «şişirilmir»
• circuit-breaker/timeout/fallback siyasətləri xüsusi
• Yük testləri: burst 10 ×, uzun birləşmələr, soyuq başlanğıc

11) Məlumatlar, valyutalar, vaxt

• Formatlar: ISO-8601 UTC, pul - onluq sətirlər/minor units, yerli mühit asılı deyil
• Kodlamalar/dillər razılaşdırılır (məsələn, mesajlar üçün 'Accept-Language', lakin 'error _ code' - maşın)
• Yuvarlaqlaşdırma/komissiya siyasəti sənədləşdirilmişdir

12) Yoxlama və hesabat (reconciliation)

• Nəzarət məbləğləri ilə gündəlik/saatlıq yoxlamalar
• API/boşaltma yoxlanılır (CSV/JSON, manifestlər/hash)
• Uyğunsuzluqlar - 'trace _ id' linkləri olan biletlərə

13) Uyğunluq və hüquqi aspektlər

• API istifadə şərtləri qəbul (fair use/export control)
• PII/data sahibləri - rolları və saxlama zonaları müəyyən
• Legal Hold/audit log hadisələr zamanı daxil

14) Sənədləşmə və tərtibatçılar portalı

• OpenAPI/AsyncAPI aktualdır, «kopyala-yapışdır» nümunələri mövcuddur
• SDK (TS/Py/Java/Go/.NET) - razılaşdırılmış versiyalar, Cookbook mövcuddur
• Try-it playground işləyir, qum açarları aktiv
• Changelog/deprekasiya/roadmap portalda görünür

15) Test: funksional, mənfi, xaos

Funksional

• CRUD/açar ssenariləri keçdi (happy path)
• Pagination/kursor/incremental delta

Mənfi

• 401/403/404/409/422/429/5xx və emal 'Retry-After'
• Səhv imza webhook, vaxtı keçmiş tokenlər, böyük cisimlər

Xaos

• Drop 10-30% hadisə, reorder, gecikmə 1-10 dəq
• Asılılığın dayandırılması (PSP/KYC) → düzgün fallback/səhvlər

16) Qəbul və başlanğıc (go-live)

• Son PRR (Production Readiness Review) keçdi
• Kanarya daxil: 10% → 25% → 50% → 100%
• SLO siqnalları ilə avtomatik geri dönüş (səhvlər/gecikmə/429)
• Hadisə əlaqə matrisi və eskalasiya yolu dərc
• CAPA Beaclog pilot formalaşdıqdan sonra

17) Əməliyyat və dəstək

• Runbook/playbook: «5xx spike», «429 storm», «webhook backlog», «timeout»
• SLO/Error Budget haqqında müntəzəm hesabatlar
• Cədvələ görə sirlərin və açarların rotasiyası
• Depreksiya/miqrasiya versiyası planı razılaşdırıldı (tarix sunset)

18) Artefakt şablonları

Env-konfiqa şablonu

yaml api:
base_url: https://api. example. com/v1 timeout_ms: 10000 retries: { max: 5, strategy: expo-jitter }
auth:
kind: oauth2 token_url: https://auth. example. com/oauth2/token scopes: [wallet:read, wallet:write]
webhooks:
secret_ref: secret/webhook-hmac parallelism: 10 max_body_kb: 256

Retraj siyasəti (psevdo)

json
{"initial":1,"max":60,"factor":2. 0,"jitter":0. 2,"retriable":["5xx","408","429"]}

19) «imza üçün» yekun çek siyahısı

• Mühit/versiyalar/açarlar/allowlist hazır
• Auth/JWT/keys/mTLS xüsusi və test
• Limitlər/kvotalar/retralar/idempotentlik həyata keçirildi
• Pagination/kursor/Delta data üzərində işləyir
• Vebhook: imzalar, təkrar, DLQ/Replay yoxlanılır
• 'problem + json', 'trace _ id' səhvləri bütün qeydlərə yapışır
• Daşbordlar/Alerts yığılmış, OTel daxil
• Yükləmə/mənfi/xaos testləri keçdi
• Uyğunlaşma və hesabatlar birləşir, runbooks tərtib
• PRR/kanarya/rollback planı hazırdır, on-call əlaqə göstərilir

Yekun

Bu çek siyahısı API inteqrasiyasının texniki, əməliyyat və komplayens aspektlərini bağlayır. Yuxarıdan aşağı nöqtələri keçin, limitlərin, idempotantlığın və vebhukların yoxlanılmasını avtomatlaşdırın, müşahidə və geri dönüş planını işə salın - və buraxılışınız proqnozlaşdırıla bilər, istehsalda «sürprizlər» olmadan.