API integrasiýa barlagy

0) Çalt syn (kim näme edýär)

• Integrasiýa eýesi bellendi
• On-call aragatnaşyklary (24 × 7/gul. sagat) hasaba alyndy
• Ylalaşylan SLO/SLA we goýberiş goldaw penjiresi
• Ýagdaý sahypasy we waka kanaly (email/Slack/Webhook)

1) Elýeterliligi, gurşawy, wersiýalary

• Sandbox/staging/production bar
• API wersiýasy tassyklandy: '/v1 '/sözbaşy 'X-API-Wersiýa'
• Allowlist IP we tor düzgünleri sazlandy
• Sagat we TZ: UTC-de ähli döwürler, NTP sinhronizasiýasy
• SemVer we wersiýa matrisi boýunça SDK/müşderileriň laýyklygy barlandy

2) Tassyklamak we bellikler

• Mehanizm ylalaşyldy: OAuth2 Client Credentials/Auth Code + PKCE/API Key/mTLS
• Access Token ömri we Refresh Token aýlawy sazlandy
• API Key üçin: syr bir gezek görkezilýär, gizlin dolandyryjyda saklanýar
• JWKS/JTI/' kid 'barlanýar, açylýar clock skew ± 5 min
• 'Authorization' sözbaşy girilmedi (redaksiýa)

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

3) Howpsuzlyk we gizlinlik

• TLS 1. 2 +/HSTS, goşmaça mTLS
• PII-minimalizasiýa: Diňe zerur zatlary iberýäris, bloglarda maskalar
• Saklamak we aýyrmak syýasaty (GDPR/DSAR) resminamalaşdyryldy
• Secret rotation: Aktiw/indiki açar, rollover meýilnamasy
• Hyýanatçylyga garşy: kapça/açar döretmek tizligi/hasaba alyş çäklendirmeleri

4) Çäkler, kwotalar we bekoff

• 'X-RateLimit- '/' X-Quota-' sözbaşylar yglan edildi
• Müşderi 429 we 'Retry-After' -e hormat goýýar
• Diňe 5xx/408/429 üçin retrailer, eksponensial backoff + jitter
• Synanyşyk/wagt çäkleri kesgitlenildi (mysal üçin 5 synanyşykdan ≤, jemi 60s ≤)

5) Idempotentlik we gapma-garşylyklar

• Ähli write amallary 'Idempotency-Key' -den iberilýär (TTL ≥ 24-72 sagat)
• Dublikat gapma-garşylygy → 409 IDEMP_REPLAY gaýtadan işlenilýär
• ETag/' If-Match 'bäsdeşlik täzelenmeleri üçin goşuldy (bar bolsa)

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

6) Paginasiýa we inkremental deltalar

• cursor/keyset pagination ('next _ cursor', 'has _ more')
• Durnukly sortlama '(updated_at, id)' resminamalaşdyryldy
• Içki ýükler: watermark ýa-da change token
• Örtüji penjireler (1-2 minut) we '(id, version/seq)'

7) Ýalňyşlyklaryň formaty we diagnostika

• Ýeke-täk format 'application/problem + json' (RFC 7807)
• Meýdan goldawy: 'error _ code', 'trace _ id', 'retriable', 'detail'
• Hata kartoçkasy we müşderiniň hereketleri beýan edildi (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) Webhuklar: kwitirlemek we gaýtalamak

• Üstünligi tassyklamak - islendik 2xx; enqueue-den soň çalt ACK
• Подпись HMAC (`X-Signature: sha256=...`), `X-Webhook-Id`, `X-Retry`
• Retraý syýasaty: backoff + jitter, 24-72 sagada çenli
• DLQ + Replay: elýeterli we barlandy
• Kabul ediji, TTL ≥ retraý penjirelerindäki ammar

9) Gözegçilik etmek we yzarlamak

• Müşderide/SDK-da OpenTelemetry Hook bar
• Tutuş zynjyr boýunça 'trace _ id '/' X-Request-ID' baglanyşygy
• Дашборды: `requests_total`, `errors_total{status}`, `latency_p95`, `retry_count`, `429_rate`
• Duýduryş: 5xx/429 bökmek, p95 beýikligi, success rate güýji, webhook lag

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

10) Öndürijilik we durnuklylyk

• Baglanyşyk howuzlary, keep-alive, mümkin bolan HTTP/2/3
• Paralellik çäklidir (backpressure), müşderiniň nobaty "çişmeýär"
• circuit-breaker/timeout/fallback syýasatlary sazlandy
• Ýük synaglary: burst 10 ×, uzyn baglanyşyklar, sowuk başlangyç

11) Maglumatlar, walýutalar, wagt

• Formatlar: ISO-8601 UTC, pul - onluk setirler/minor units, lokallary daşky gurşawa bagly däl
• Kodlamalar/diller ylalaşyldy (mysal üçin, 'Accept-Language' habarlar üçin, ýöne 'error _ code' - maşyn)
• Tegeleklemek/komissiýa syýasaty dokumentleşdirildi

12) Deňeşdirmeler we hasabatlylyk (reconciliation)

• Gözegçilik pullary bilen gündelik/sagatlyk deňeşdirmeler
• Barlamak üçin API/boşatmalar synagdan geçirildi (CSV/JSON, manifestler/hastalar)
• Gapma-garşylyklar - 'trace _ id' baglanyşyklary bolan biletlere

13) Komplayens we hukuk taraplary

• API ulanmagyň şertleri kabul edildi (fair use/export control)
• PII/data eýeleri - rollar we ammar zolaklary kesgitlenildi
• Legal Hold/audit-log hereketler hadysalarda goşulýar

14) Işläp taýýarlaýjylaryň resminamalary we portaly

• OpenAPI/AsyncAPI aktual, "göçürmek-goýmak" mysallary bar
• SDK (TS/Py/Java/Go/.NET) - wersiýalary ylalaşyldy, Cookbook elýeterli
• Try-it playground işleýär, kum açarlary işjeň
• Changelog/deprekasiýa/roadmap portalda görünýär

15) Synag: funksional, negatiw, bulam-bujarlyk

Funksional

• CRUD/esasy ssenariler geçdi (happy path)
• Paginasiýa/kursor/içerki deltalar

Negatiw

• 401/403/404/409/422/429/5xx we gaýtadan işlemek 'Retry-After'
• Nädogry webhuk goly, möhleti geçen bellikler, uly jisimler

Bulam-bujarlyk

• Drop 10-30% wakalar, reorder, gijikdirmeler 1-10 minut
• Endikleri öçürmek (PSP/KYC) → dogry fallback/ýalňyşlyklar

16) Kabul etmek we işe girizmek (go-live)

• Soňky PRR (Production Readiness Review) geçdi
• Kanareýanyň açylmagy: 10% → 25% → 50% → 100%
• SLO signallary boýunça awto-yza gaýdyp gelmek (ýalňyşlyklar/gizlinlik/429)
• Wakalaryň aragatnaşyk matrisi we eskalasiýa ýoly çap edildi
• CAPA Beaclog pilotdan soň döredildi

17) Peýdalanmak we goldamak

• Runbook/playbook: "5xx spike", "429 storm", "webhook backlog", "timeout"
• SLO/Error Budget boýunça yzygiderli hasabatlar
• Programma boýunça syrlary we açarlary aýlamak
• Wersiýalaryň deprekasiýa/migrasiýa meýilnamasy ylalaşyldy (senesi sunset)

18) Artefaktlaryň şablonlary

Env-konfiga şablony

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

Retraý syýasaty (psevdo)

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

19) "Gol çekmek üçin" jemleýji çek-listi

• Gurşaw/wersiýalar/açarlar/allowlist taýýar
• Auth/JWT/keys/mTLS sazlandy we synagdan geçirildi
• Çäklendirmeler/kwotalar/retralar/idempotentlik amala aşyryldy
• Paginasiýa/kursor/deltalar
• Webhook: gollar, gaýtalanmalar, DLQ/Replay barlandy
• 'problem + json', 'trace _ id' hatalary ähli ýazgylara ýapyşýar
• Daşbordlar/alertler ýygnaldy, OTel goşuldy
• Ýük/negatiw/bulam-bujarlyk synaglary geçdi
• Deňeşdirmeler we hasabatlar birleşýär, runbooks resmileşdirildi
• PRR/kanareýa/rollback-plan taýýar, on-call aragatnaşyklary görkezilýär

Jemi

Bu barlag sanawy API integrasiýasynyň tehniki, operasiýa we laýyklyk taraplaryny ýapýar. Nokatlary ýokardan aşak geçiň, çäkleri, idempotentligi we webhuklary barlamagy awtomatlaşdyryň, gözegçilik we yza gaýdyp geliş meýilnamasyny açyň - we önümçilikde "garaşylmadyk" bolmazdan, işe girizişiňiz öňünden bolar.