Lista de verificare a integrării API

0) Revizuire rapidă (cine ce face)

• Proprietar de integrare atribuit
• Contactele de gardă (24 × 7/program de lucru) sunt prescrise
• A fost de acord SLO/SLA și fereastra de sprijin de lansare
• Pagina de stare și canalul incident (e-mail/slack/webhook)

1) Accesuri, medii, versiuni

• sandbox/staging/producție accesată
• Versiunea API confirmată: '/v1 '/header 'X-API-Version'
• Permiteți configurarea regulilor IP și de rețea
• Ceas și TZ: toate timpurile în UTC, sincronizare NTP
• Compatibilitatea SemVer SDK/Client și versiunea matrice verificată

2) Autentificare și jetoane

• Mecanism convenit OAuth2 acreditările clienților/Codul Auth + Cheie PKCE/API/mTLS
• Accesați durata de viață a tokenului și reîmprospătați rotația tokenului configurată
• Pentru API Key: secretul este afișat o dată, stocat în managerul secret
• JWKS/JTI/' kid 'bifat, ceas înclinare pe ± 5 min
• Anteturile de „autorizare” care nu sunt înregistrate (revizuire)

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

3) Securitate și confidențialitate

• TLS 1. 2 +/HSTS, mTLS opţional
• PII minimizare: trimitem doar ceea ce avem nevoie, măști în jurnalele
• Politica de păstrare și dispunere (GDPR/DSAR) documentată
• Rotație secretă: activ/următoarea cheie, plan de rollover
• Anti-Abuz: Captcha/Keying Viteza/Restricții de înregistrare

4) Limite, cote și backoff

• Anteturi declarate 'X-RateLimit- '/' X-Cota-'
• Clientul respectă 429 și 'Retry-Aftery'
• Retractări numai pentru 5xx/408/429, backoff exponențial + jitter
• Încercați din nou/limita de timp stabilită (de exemplu, ≤ 5 retries, ≤ 60c total)

5) Idempotența și conflictele

• Toate operațiunile de scriere sunt trimise cu 'Idempotency-Key' (TTL ≥ 24-72 h)
• Duplicat conflict → 409 IDEMP_REPLAY manipulate
• ETag/' If-Match 'activat pentru actualizări competitive (dacă este disponibil)

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

6) Paginare și delte incrementale

• cursor/keyset pagination folosit ('next _ cursor', 'has _ more')
• Sortare stabilă '(updated_at, id)' documentat
• Încărcări incrementale: filigran sau schimbați jetonul
• Suprapuneri (suprapunere 1-2 min) și dedup cu '(id, versiune/seq)'

7) Formatul de eroare și diagnosticarea

• Format uniform 'aplicare/problemă + json' (RFC 7807)
• Suport pentru câmp: 'error _ code', 'trace _ id',' retriable ',' details'
• Harta erorilor și acțiunile clientului descrise (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) Webhooks: recunoașteri și reluări

• Confirmarea succesului - orice 2xx; ACK rapid după solicitare
• Подпись HMAC ('X-Signature: sha256 = "...),' X-Webhook-Id', 'X-Retry'
• Politica de retractare: backoff + jitter, până la 24-72 ore
• DLQ + Replay: Disponibil și validat
• Dedup de stocare la receptor, TTL ≥ Retray ferestre

9) Observabilitate și urmărire

• Cârlige OpenTelemetry activate în client/SDK
• Lanț-wide trace _ id/X-Request-ID corelație
• Дашборды: 'requests _ total', 'errors _ total {status}', 'latency _ p95', 'retry _ count',' 429 _ ratee '
• Alarme: 5xx/429 spike, creșterea p95, scăderea ratei de succes, lag webhook

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

10) Performanță și stabilitate

• Piscine de conectare, păstrați-viu, HTTP/2/3 acolo unde este posibil
• Backpressure, coada clientului nu este „umflată”
• circuit-breaker/timeout/rezervă politici configurate
• Teste de încărcare: sparge 10 ×, conexiuni lungi, pornire la rece

11) Date, valute, timp

• Formate: ISO-8601 UTC, bani - șiruri zecimale/unități minore, localizările nu depind de mediu
• Codificările/limbile sunt consecvente (de ex. „Accept-Language” pentru mesaje, dar „error _ code” pentru mașină)
• Politica de rotunjire/comisie documentată

12) Reconciliere

• Reconcilierea zilnică/orară cu sumele de control
• API/încărcări pentru reconcilieri testate (CSV/JSON, manifeste/hashes)
• Discrepanțe - în bilete cu referințe la 'trace _ id'

13) Respectarea și aspectele legale

• Termeni de utilizare API acceptați (utilizarea corectă/controlul exportului)
• PII/Titularii de date - Roluri și zone de stocare definite
• Legal Hold/Audit Log Acțiuni activate pentru incidente

14) Documentație și Developer Portal

• OpenAPI/AsyncAPI sunt relevante, există exemple de „copy-paste”
• SDK (TS/Py/Java/Go/.NET) - versiunile sunt consecvente, Cartea de bucate este disponibilă
• Încercați-it locuri de joacă lucrări, chei de nisip sunt active
• Changelog/decrements/foaia de parcurs sunt vizibile în portal

15) Testarea: funcțional, negativ, haos

Funcțional

• Scenariile CRUD/cheie au trecut (calea fericită)
• Paginare/Cursor/Incremental Deltas

Negativ

• 401/403/404/409/422/429/5xx și procesarea „Retry-After”
• Semnătură incorectă a cârligului web, jetoane expirate, corpuri mari

Haos

• Picătură 10-30% evenimente, reordonare, 1-10 min întârzieri
• Dezactivați dependențele (PSP/KYC) → corectați rezerva/erorile

16) Acceptarea și lansarea (go-live)

• Final PRR (Production Readiness Review) a trecut
• Incluziune canară: 10% → 25% → 50% → 100%
• Auto-rollback pe semnale SLO (erori/latență/429)
• Incident Matricea de contact și calea de escaladare Publicat
• Restanțe CAPA după generarea pilotului

17) Funcționare și suport

• Runbook/playbook-uri: „5xx spike”, „429 storm”, „webhook restlog”, „timeout”
• Rapoarte regulate SLO/Eroare Buget
• Rotirea secretelor și cheilor pe un program
• Versiunea Depresiuni/Migrații Planul a fost de acord (data de apus)

18) Modele artefact

Șablon de configurare env

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

Politica de retractare (pseudo)

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

19) Lista finală de verificare „pentru semnătură”

• Medii/versiuni/chei/lista de permise gata
• Auth/JWT/chei/mTLS configurat și testat
• Limite/cote/retribuții/idempotență implementate
• Paginare/cursor/delta de lucru pe date
• Webhooks: Semnături, Reluări, DLQ/Replay verificat
• Erori 'problemă + json', 'trace _ id' sticks la toate jurnalele
• Tablouri de bord/alerte colectate, OTel activat
• Testele de încărcare/negative/haos au trecut
• Reconcilieri și rapoarte converg, runbooks sunt formalizate
• PRR/canar/rollback-plan gata, contactele de gardă indicate

Total

Această listă de verificare acoperă aspectele tehnice, operaționale și de conformitate ale integrării API. Treceți prin elemente de sus în jos, automatizați limitele de verificare, idempotența și cărțile web, permiteți observabilitatea și planul rollback - iar lansarea dvs. va fi previzibilă, fără „surprize” în producție.