API-Integration Checkliste

0) Schneller Überblick (wer macht was)

• Integrationseigner zugewiesen
• On-Call-Kontakte (24 × 7/Sklave. Stunden) registriert
• Vereinbarte SLOs/SLAs und Release Support Fenster
• Status-Seite und Incident Channel (Email/Slack/Webhook)

1) Zugriffe, Umgebungen, Versionen

• Zugriff auf Sandbox/Staging/Produktion erhalten
• API-Version bestätigt: '/v1 '/header 'X-API-Version'
• Allowlist IP und Netzwerkregeln sind konfiguriert
• Uhr und TZ: alle Zeiten in UTC, NTP-Synchronisation
• SDK/Client Kompatibilität nach SemVer und Versionsmatrix geprüft

2) Authentifizierung und Token

• Der Mechanismus ist konsistent: OAuth2 Client Credentials/Auth Code + PKCE/API Key/mTLS
• Lebensdauer des Access Token und Rotation des Refresh Token angepasst
• Für API Key: das Geheimnis wird einmal angezeigt, im Secret Manager gespeichert
• JWKS/JTI/' kid' geprüft, eingeschaltete Uhr skew ± 5 min
• 'Autorisierung' Titel werden nicht protokolliert (Revision)

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

3) Sicherheit und Privatsphäre

• TLS 1. 2 +/HSTS, optional mTLS
• PII-Minimierung: Wir senden nur das Richtige, Masken in Logs
• Aufbewahrungs- und Löschrichtlinie (DSGVO/DSAR) dokumentiert
• Geheime Rotation: aktiver/nächster Schlüssel, Rollover-Plan
• Anti-Missbrauch: Captcha/Geschwindigkeit der Schlüsselgenerierung/Einschränkungen der Registrierungen

4) Limits, Quoten und Backoff

• Angekündigte' X-RateLimit- '/' X-Quota- 'Titel
• Kunde respektiert 429 und „Retry-After“
• Retrays nur für 5xx/408/429, exponentieller Backoff + Jitter
• Versuchs-/Zeitlimit angegeben (z.B. ≤ 5 Versuche, ≤ 60s insgesamt)

5) Idempotenz und Konflikte

• Alle Schreibvorgänge werden mit dem 'Idempotency-Key' (TTL ≥ 24-72 h) gesendet
• Duplikatkonflikt → 409 wird IDEMP_REPLAY verarbeitet
• ETag/„ If-Match “für wettbewerbsfähige Updates aktiviert (falls vorhanden)

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

6) Pagination und inkrementelle Deltas

• Cursor/Keyset-Pagination wird verwendet ('next _ cursor', 'has _ more')
• Stabile Sortierung'(updated_at, id) 'dokumentiert
• Inkrementelle Entladungen: watermark oder change token
• Überlappende Fenster (Overlap 1-2 min) und Dedup durch'(id, version/seq) '

7) Fehlerformat und Diagnose

• Einheitliches Format „application/problem + json“ (RFC 7807)
• Feldunterstützung: 'error _ code', 'trace _ id', 'retriable', 'detail'
• Fehlerkarte und Kundenaktionen beschrieben (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: Handshake und Wiederholungen

• Erfolgsnachweis - jeder 2xx; schnelle ACK nach enqueue
• Подпись HMAC (`X-Signature: sha256=...`), `X-Webhook-Id`, `X-Retry`
• Retraypolitik: backoff + jitter, bis zu 24-72 Stunden
• DLQ + Replay: verfügbar und validiert
• Dedup-Speicher am Empfänger, TTL ≥ Retrayfenster

9) Beobachtbarkeit und Rückverfolgung

• OpenTelemetry Hooks im Client/SDK enthalten
• Korrelation 'trace _ id '/' X-Request-ID' über die gesamte Kette
• Дашборды: `requests_total`, `errors_total{status}`, `latency_p95`, `retry_count`, `429_rate`
• Alarms: 5xx/429 surge, p95 growth, success rate drop, webhooks lag

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

10) Leistung und Nachhaltigkeit

• Verbindungspools, Keep-Alive, HTTP/2/3 wo möglich
• Die Parallelität ist begrenzt (Backpressure), die Kundenwarteschlange wird nicht „aufgeblasen“
• sind die Politiker circuit-breaker/timeout/fallback gestimmt
• Belastungstests: Burst 10 ×, lange Verbindungen, Kaltstart

11) Daten, Währungen, Zeit

• Formate: ISO-8601 UTC, Geld - Dezimalstellen/minor units, locales unabhängig von der Umgebung
• Kodierungen/Sprachen sind harmonisiert (z.B. 'Accept-Language' für Nachrichten, aber 'error _ code' ist maschinell)
• Rundungs-/Provisionspolitik dokumentiert

12) Abstimmungen und Berichterstattung (Reconciliation)

• Tägliche/stündliche Abgleiche mit Prüfsummen
• API/Uploads für Sweeps getestet (CSV/JSON, Manifeste/Hashes)
• Unstimmigkeiten - in Tickets mit Links zu 'trace _ id'

13) Compliance und rechtliche Aspekte

• API-Nutzungsbedingungen akzeptiert (faire Nutzung/Exportkontrolle)
• PII/Data Holders - Rollen und Speicherbereiche sind definiert
• Legal Hold/Audit-Log-Aktivitäten sind bei Vorfällen enthalten

14) Dokumentation und Entwicklerportal

• OpenAPI/AsyncAPI sind aktuell, Copy-Paste-Beispiele gibt es
• SDK (TS/Py/Java/Go/.NET) - Versionen harmonisiert, Cookbook verfügbar
• Try-it playground läuft, Sandschlüssel aktiv
• Changelog/Deprections/Roadmap im Portal sichtbar

15) Testen: funktional, negativ, Chaos

Funktionalen

• CRUD/Key Scripts bestanden (happy path)
• Pagination/Cursor/inkrementelle Deltas

Negativ

• 401/403/404/409/422/429/5xx und „Retry-After“ -Verarbeitung
• Falsche Webhook-Signatur, abgelaufene Token, große Körper

Chaos

• Drop 10-30% der Ereignisse, Nachbestellung, Latenz 1-10 min
• Deaktivieren von Abhängigkeiten (PSP/KYC) → korrektes Fallback/Fehler

16) Abnahme und Inbetriebnahme (go-live)

• Finale PRR (Production Readiness Review) bestanden
• Kanarische Einschlüsse: 10% → 25% → 50% → 100%
• Auto-Rollback über SLO-Signale (Fehler/Latenz/429)
• Kontaktmatrix der Vorfälle und Eskalationspfad veröffentlicht
• CAPA-Backlog nach Pilot gebildet

17) Betrieb und Unterstützung

• Runbook/Playbooks: „5xx spike“, „429 storm“, „webhook backlog“, „timeout“
• Regelmäßige Berichte zum SLO/Error Budget
• Rotierende Geheimnisse und Schlüssel nach Zeitplan
• Plan für Deprektionen/Releasemigrationen vereinbart (Sunset-Datum)

18) Artefaktmuster

env-config-Vorlage

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

Retrayrichtlinie (Pseudo)

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

19) Abschließende Checkliste „zur Unterschrift“

• Umgebungen/Versionen/Schlüssel/allowlist bereit
• Auth/JWT/keys/mTLS konfiguriert und getestet
• Limits/Quoten/Retrays/Idempotenz umgesetzt
• Pagination/Cursor/Deltas arbeiten auf Daten
• Webhooks: Signaturen, Wiederholungen, DLQ/Replay verifiziert
• Fehler 'problem + json', 'trace _ id' klebt in allen Protokollen
• Dashboards/Alerts gesammelt, OTel enthalten
• Belastungs-/Negativ-/Chaos-Tests bestanden
• Abstimmungen und Berichte konvergieren, Runbooks gestaltet
• PRR/Kanarienvogel/Rollback-Plan bereit, On-Call-Kontakte angegeben

Summe

Diese Checkliste schließt die technischen, operativen und Compliance-Aspekte der API-Integration ab. Gehen Sie die Punkte von oben nach unten durch, automatisieren Sie die Überprüfung von Limits, Idempotenz und Webhooks, aktivieren Sie die Beobachtbarkeit und den Rollback-Plan - und Ihr Start wird vorhersehbar sein, ohne „Überraschungen“ in der Produktion.