Operationen über API-Schnittstelle

(Abschnitt: Operationen und Management)

1) Zweck und Grundsätze

Die API ist die „operative Schicht“ des Ökosystems: Alles, was nicht durch einen Vertrag automatisiert wird, wird zu Handarbeit und Risiken.

• Contract-first: erst Spezifikation (OpenAPI/JSON Schema/AsyncAPI), dann Implementierung.
• Secure-by-default: minimale Skopes, kurze TTLs, mutual-TLS/Signaturen.
• Observable: Ende-zu-Ende-Trace und SLA-Metriken.
• Idempotent: Die Wiederholung ist sicher.
• Backwards-kompatibel: Evolution ohne „Breaking“ -Änderungen.
• Auditable: kryptographisch bestätigte Fakten (Belege).

2) Vertrag und Modelle (Referenz)

OpenAPI für Sync-Abfragen; AsyncAPI für Ereignisse/Webhooks.
Erforderliche Felder in jeder Ressource: 'id', 'version', 'created _ at', 'updated _ at', 'tenant', 'region', 'trace _ id'.

Beispiel für ein Vertragsfragment

yaml paths:
/payments/payouts:
post:
operationId: createPayout requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutRequest'
responses:
"202": { $ref: '#/components/responses/AcceptedWithReceipt' }
headers:
Idempotency-Key:
schema: { type: string }
required: true components:
responses:
AcceptedWithReceipt:
description: Accepted, processing asynchronously headers:
Receipt-Hash: { schema: { type: string } }

3) Authentifizierung, Autorisierung, Scopes

OAuth2/OIDC für Benutzer/Partner; client-credentials/JWT для S2S.
Scopes/Ressourcen Rollen: 'Zahlungen. write`, `catalog. read`, `audit. export`.
ReBAC: Zugang „durch Besitz“ (Tenant/Account/Sub-Account).
JIT-Geheimnisse: kurzlebige Token, Bindung an das Gerät/Subnetz/Region.
Geräteposture & mTLS für kritische Transaktionen (Auszahlungen, Schlüssel).

4) Idempotenz und „genau einmal“

Idempotency-Key (header) + dedup by'(key, account, route) 'im TTL-Fenster.
Outbox/CDC zur Veröffentlichung von Ereignissen - garantierte Lieferung.
Exactly-once-effects: Nebenwirkungen werden über das Transaktionsprotokoll erfasst; eine Wiederholung führt zu derselben „Quittung“ ('receipt _ hash').
Retry-Policies: exponentielle Backoffs, Jitter, maximale Fenster.

5) Limits, Quoten, Priorisierung

Rate limits: per-key/tenant/route/region; „weich“ (429) und „hart“ (cut-off).
Kontingente/Budgets: Monatlicher/täglicher Mundschutz, Webhooks „QuotaCapReached“.
Fair-use: Priorität der Tenanten nach Service-Level (Gold/Silber/Bronze).
Burst-Puffer: kurze Ausbrüche ohne Verschlechterung der Nachbarn.

6) Pagination, Filter, Proben

Cursor-based (stable ordering по `created_at,id`), `page_size` ≤ 1000.
Time-sliced Samples ('from', 'to', 'watermark') für Protokolle/Transaktionen.
Filtering DSL: whitelisted поля, `?status=...&tenant=...&region=...`.
Consistency hints: 'snapshot _ at '/' as _ of' für Reporting-APIs.

7) Versionierung und Kompatibilität

SemVer: `v1`, `v1. 1'(Erweiterungen), 'v2' - nur über neue Pfade/Neuspaces.
Evolutionsregeln: nur Felder/Werte hinzufügen, „deprecate → remove“ durch das Fenster.
Kompatibilitätstests: „contracts-as-tests“ (verbrauchergetriebene Tests).

8) Veranstaltungen, Webhooks und Quittungen

Die AsyncAPI beschreibt die Themen/payload/Signaturen.
Bildunterschrift: HMAC/EdDSA, Überschriften „X-Signatur“, „X-Nonce“, „X-Timestamp“ (schmales Fenster).
Quittungen (receipts): 'receipt _ hash' und DSSE-Signatur bei kritischen Ereignissen (Zahlungen, RTP/Limitänderungen, Preislisten).
Retrays und Dedup: idempotency durch 'idempotency _ key '/' event _ id'.
DLQ/Quarantäne: Nicht-valide/wiederholte Meldungen mit Ursachen.

9) Beobachtbarkeit und Qualität

Traces: obligatorische' trace _ id/span _ id 'über Gateway/Business Events/Webhooks.
Metrics: Verfügbarkeit, p50/p95/p99, error-rate, retry-rate, Kosten pro 1k.
Logs: strukturiert, keine Geheimnisse/PII; Beschriftungen 'tenant/region/version'.
SLO/alert: SLO-orientierte Bedingungen und Auto-Runen (Pause/Re-Route/Rollback).

10) Fehler und Semantik der Zustände

2xx - Erfolg (202 für asynchrone Operationen).
4xx - Kundenfehler (422 - Validierung, 409 - Konflikt/Idempotenz, 429 - Grenzen).
5xx - temporäre Probleme.
Fehlerkörper: 'code', 'message', 'trace _ id', 'hint', 'retry _ after?'.
UX für Partner: Tabelle „was zu tun ist“ für jeden Fehler.

11) Policies-as-Code (OPA/ABAC)

Zentrale Autorisierung: „wer/was/wo/wann/warum“.
Politiker in Git, Code-Revue, CI-Tests (Vorflug: "Wird die Politik zulassen? »).
SoD-Check: „Zahlung erstellen“ ≠ „genehmigen“.

12) Sicherheit, Privatsphäre, Compliance

PII-Minimierung: Tokenisierung/Masken, Zugang zum Primus nur über zugelassene Jobs.
Geheimnisse: Vault/KMS, kurze TTL, Rotationen; Verbot von geteilten Geheimnissen.
Verschlüsselung: mTLS/TLS 1. 3, AES-GCM at-rest, HSTS/PKP, wo relevant.
Jurisdiction-aware: Lokalisierung von Daten/Schlüsseln pro Region.
Prüfprotokolle: WORM, Merkle-Slices, DSSE-Signaturen.

13) Betrieb: SLI/SLO und Dashboards

• Verfügbarkeit per-route/region.
• Latenz p95 (lesen/schreiben).
• Erfolg von Webhooks (Quittungen), Lieferung lag.
• Error-rate/Retry-rate.
• Kosten pro 1k Anfragen und egress.

SLO (Beispiel): 99. 95% Verfügbarkeit; p95 ≤ 120/250 ms; Webhooks ≥ 99. 5 %/5-min; P1 MTTR ≤ 60 min.

14) Änderungsmanagement (Releases/Rollbacks)

Blue-Green/Canary für Schleusen und kritische Routen.
Ficheflagi für Verhalten ohne Freigabe.
Expand→Migrate→Contract für Schaltungen und Payload.
Руны: Rollback Release, Disable Flag, Re-route, Flush Cache.
Artefakte: signierte Bilder/Manifeste, Versionsregister.

15) SDK, Kunden, „Sandboxes“

Offizielle SDKs (TS/Java/Python/Go) mit der gleichen Semantik von Bugs und Retrains.
Sandbox-Umgebungen mit Testschlüsseln/Zertifikaten und PSP/KYC/Content Provider Simulatoren.
Vertragstests sind im CI SDK enthalten, nightly-compatibility.

16) Datenmodell (vereinfacht)

`api_key` `{id, tenant, scopes[], ttl, created_by}`

`rate_plan` `{tenant, quotas{route→cap}, burst, priority}`

`request_log` `{trace_id, route, actor, idempotency_key?, status, latency_ms, region, cost_unit}`

`webhook_receipt` `{event_id, endpoint, status, attempts, receipt_hash, signature}`

`policy` `{version, rules, signer, dsse}`

17) RACI

18) Qualitätsmetriken

Vertrag Drift: 0 „breaking“ Änderungen ohne deprecate.
Idempotency Error Rate: ≤ 0. 01%.
Webhook Success: ≥ 99. 5%, lag p95 ≤ 60 s.
Auth Fail vs Abuse: Anteil bösartiger Blöcke, Rauschen ≤ Zielniveau.
Cost/1k: Kontrolle nach Routen und Regionen (Budgets/Cap-Alerts).
Adoption SDK: Anteil des Datenverkehrs über offizielle SDKs.

19) Playbooks der Vorfälle

Spike 429/Limits: Heben Sie die Kappe für Gold, drosseln Sie die „lauten“ Schlüssel, kommunizieren Sie mit Ihrem Partner.
WebhookLag: Workers/Batches erhöhen, Warteschlangen priorisieren, optionale Webhooks vorübergehend ausschalten.
PriceMismatch (Katalog/FX/Tax): Versionsabgleich, höhere Behinderung des Caches, Artefakt-Rollback, Entschädigung.
PSP Outage: Routenumschaltung, Quarantäne von „grauen“ Transaktionen, Replikationen.
Compromise API-key: sofortiger Rückruf, Rotation, Audit der letzten 30 Tage.

20) Besonderheiten von iGaming/Fintech

RTP/Limits API: nur Aggregate und Profilversionen; Änderungen - mit Quittungen.
Zahlungen/Auszahlungen: 202 + Webhooks mit Unterschriften; Idempotenz auf dem Auftragsschlüssel.
Affiliates: Dedup Conversions, Treuhandkonto für Streitigkeiten, signierte Berichte.
Verantwortungsvolles Spielen: Stellen Sie die „guardrails API“ für Limits und RG-Events aus.

21) Checkliste Umsetzung

• Vertrag (OpenAPI/AsyncAPI), CI-Validierung und Verbrauchertests beschrieben.
• Konfiguriert OAuth2/OIDC, Scopes, JIT-Geheimnisse und mTLS für kritische Routen.
• Idempotenz, Retrays, DLQ und Quarantäne wurden eingeführt.
• Limits/Quoten/Prioritäten und Alerts per Cap.
• Cursor-Paginierung, konsistente Stichproben 'as _ of'.
• Versionierung und Deprecation-Politik.
• Webhooks mit Unterschriften/Quittungen, Repliken und Dedup.
• Trace/Metriken/Logs, SLOs und Runen.
• WORM-Zeitschriften, DSSE-Signaturen, Merkle-Slices.
• SDK, Sandbox, Simulatoren, Codebeispiele und „How-to“.

22) FAQ

Warum 202 für lange Operationen?
Um die Verbindung nicht zu halten und eine zuverlässige Rücknahme/Quittung per Webhook zu gewährleisten.

Brauche ich beides: OpenAPI und AsyncAPI?
Ja: sync für Befehle/Abfragen, async für Ereignisse/Zustandsaushandlung.

Wie vermeidet man brechende Veränderungen?
Regel „nur hinzufügen“, deprecate → observe → remove, Vertragstests von Kunden.

Wo kann ich Quittungen aufbewahren?
In der WORM-Zone mit Signaturen; 'receipt _ hash' wird dem Kunden zurückgegeben und auf Wunsch überprüft.

Zusammenfassung: Operationen über APIs sind die Disziplin von Vertrag und Betrieb: strenges Zugriffsmodell und Idempotenz, Grenzen und Versionen, Beobachtbarkeit und SLO, Signaturen und Quittungen. Fügen Sie Sandboxes und SDKs hinzu - und die Partner werden schnell, sicher und vorhersehbar integriert, während das Unternehmen ohne Qualitäts- und Compliance-Verluste skaliert.