API integration checklist

0) Quick review (who does what)

• Integration Owner Assigned
• On-call contacts (24 × 7/work hours) are prescribed
• Agreed SLO/SLA and Release Support Window
• Status page and incident channel (email/slack/webhook)

1) Accesses, environments, versions

• sandbox/staging/production accessed
• API version confirmed: '/v1 '/header 'X-API-Version'
• Allow IP and network rules configured
• Clock and TZ: all times in UTC, NTP synchronization
• SemVer SDK/Client Compatibility and Version Matrix Verified

2) Authentication and tokens

• Mechanism agreed OAuth2 Client Credentials/Auth Code + PKCE/API Key/mTLS
• Access Token Lifetime and Refresh Token Rotation Configured
• For API Key: secret is shown once, stored in the secret manager
• JWKS/JTI/' kid 'checked, clock skew on ± 5 min
• 'Authorization' headers not logged (revision)

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

3) Security and privacy

• TLS 1. 2 +/HSTS, optional mTLS
• PII minimization: we send only what we need, masks in the logs
• Retention and Disposition Policy (GDPR/DSAR) documented
• Secret rotation: active/next key, rollover plan
• Anti-Abuse: Captcha/Keying Speed/Registration Restrictions

4) Limits, quotas and backoff

• Declared'X-RateLimit- '/' X-Quota-' headers
• Customer respects 429 and 'Retry-After'
• Retrays for 5xx/408/429 only, exponential backoff + jitter
• Retry/time limit set (e.g. ≤ 5 retries, ≤ 60c total)

5) Idempotence and conflicts

• All write operations are sent with'Idempotency-Key '(TTL ≥ 24-72 h)
• Duplicate Conflict → 409 IDEMP_REPLAY Handled
• ETag/' If-Match 'enabled for competitive updates (if available)

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

6) Pagination and incremental deltas

• cursor/keyset pagination used ('next _ cursor', 'has _ more')
• Stable sort '(updated_at, id)' documented
• Incremental uploads: watermark or change token
• Overlaps (overlap 1-2 min) and dedup by '(id, version/seq)'

7) Error format and diagnostics

• Uniform format 'application/problem + json' (RFC 7807)
• Field support: 'error _ code', 'trace _ id', 'retriable', 'detail'
• Error map and client actions described (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: acknowledgements and replays

• Confirmation of success - any 2xx; fast ACK after enqueue
• Подпись HMAC (`X-Signature: sha256=...`), `X-Webhook-Id`, `X-Retry`
• Retray policy: backoff + jitter, up to 24-72 hours
• DLQ + Replay: Available and Validated
• Dedup storage at the receiver, TTL ≥ retray windows

9) Observability and tracing

• OpenTelemetry hooks enabled in client/SDK
• Chain-wide trace _ id/X-Request-ID correlation
• Дашборды: `requests_total`, `errors_total{status}`, `latency_p95`, `retry_count`, `429_rate`
• Alarms: 5xx/429 spike, p95 rise, success rate drop, webhook lag

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

10) Performance and stability

• Connection pools, keep-alive, HTTP/2/3 where possible
• Backpressure, client queue is not "inflated"
• circuit-breaker/timeout/fallback policies configured
• Load tests: burst 10 ×, long connections, cold start

11) Data, currencies, time

• Formats: ISO-8601 UTC, money - decimal strings/minor units, locales do not depend on the environment
• Encodings/languages are consistent (e.g. 'Accept-Language' for messages but 'error _ code' for machine)
• Rounding/commission policy documented

12) Reconciliation

• Daily/hourly reconciliation with checksums
• API/uploads for reconciliations tested (CSV/JSON, manifests/hashes)
• Discrepancies - in tickets with references to 'trace _ id'

13) Compliance and legal aspects

• API Terms of Use Accepted (fair use/export control)
• PII/Data Holders - Roles and Storage Areas Defined
• Legal Hold/Audit Log Actions Enabled for Incidents

14) Documentation and Developer Portal

• OpenAPI/AsyncAPI are relevant, there are examples of "copy-paste"
• SDK (TS/Py/Java/Go/.NET) - versions are consistent, Cookbook is available
• Try-it playground works, sand keys are active
• Changelog/decrements/roadmap are visible in the portal

15) Testing: functional, negative, chaos

Functional

• CRUD/key scenarios passed (happy path)
• Pagination/Cursor/Incremental Deltas

Negative

• 401/403/404/409/422/429/5xx and 'Retry-After' processing
• Incorrect webhook signature, expired tokens, large bodies

Chaos

• Drop 10-30% events, reorder, 1-10 min delays
• Disable dependencies (PSP/KYC) → correct fallback/errors

16) Acceptance and launch (go-live)

• Final PRR (Production Readiness Review) passed
• Canary inclusion: 10% → 25% → 50% → 100%
• Auto-rollback on SLO signals (errors/latency/429)
• Incident Contact Matrix and Escalation Path Published
• CAPA backlog after pilot generated

17) Operation and support

• Runbook/playbooks: "5xx spike," "429 storm," "webhook backlog," "timeout"
• Regular SLO/Error Budget Reports
• Rotating secrets and keys on a schedule
• Version Depressions/Migrations Plan agreed (sunset date)

18) Artifact patterns

Env-config template

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

Retray policy (pseudo)

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

19) Final checklist "for signature"

• Environments/versions/keys/allowlist ready
• Auth/JWT/keys/mTLS configured and tested
• Limits/quotas/retrays/idempotency implemented
• Pagination/cursor/deltas work on data
• Webhooks: Signatures, Replays, DLQ/Replay Verified
• Errors' problem + json ',' trace _ id'sticks to all logs
• Dashboards/alerts collected, OTel enabled
• Load/negative/chaos tests passed
• Reconciliations and reports converge, runbooks are formalized
• PRR/canary/rollback-plan ready, on-call contacts indicated

Total

This checklist covers the technical, operational and compliance aspects of API integration. Go through items from top to bottom, automate checking limits, idempotency and webhooks, enable observability and rollback plan - and your launch will be predictable, without "surprises" in production.