Einheitliche API für Anbieter: Design, Version, Kompatibilität

Vollständiger Artikel

💡 18+. Technisches Material für Integrations- und Plattformteams. Kein Aufruf zum Spiel.

1) Warum „Single API“ und was es ist

Eine einzelne API ist eine Spezifikation und eine Reihe von Endpunkten/Ereignissen, über die jeder Inhaltsanbieter (RGS, Live-Studio, Jackpot, KYC/AML, Affiliates) nach den gleichen Regeln mit der Plattform kommuniziert:

einheitliches Ressourcenmodell (Spieler, Sitzungen, Wetten, Settlements, Boni, Jackpots, Zahlungen), gemeinsame Ereignisverträge und Identifikatoren, Sicherheits- und Abwärtskompatibilitätsstandards, SDKs/Tools zur Beschleunigung von Integrationen.

Das Ziel: Zeit-zu-Integration reduzieren, Fehler auf „Geldwegen“ reduzieren und planbare Upgrades ermöglichen.

2) Gestaltungsprinzipien

1. Domain-first. Zuerst Wörterbuch und Invarianten (Wette, Settlement, RG-Limits), dann Endpunkte.

2. Compatibility by default. Jede Änderung - standardmäßig kompatibel; Breaking-Änderungen sind streng nach Prozess.

3. Idempotency everywhere. Alle Geldteams sind ohne Nebenwirkungen wiederholbar.

4. Events sind die Quelle der Wahrheit (im Vertrieb). Operationen → Ereignisse im Bus; Analytics hört auf den Bus, anstatt OLTP zu schlagen.

5. Least privilege & zero-trust. Token, Signaturen, Segmentierung nach Marke/Region.

6. Observability. Ende-zu-Ende' trace _ id', verständliches Fehlermodell, p95/p99 Metriken.

3) Ressourcenmodell (vereinfacht)

Spieler: Pseudo-ID des Spielers auf der Plattformseite, Geo/Währung/RG-Status.

Session: Kanal zwischen Anbieter und Plattform ('session _ id', TTL, Geo/Limits).

Wette: Autorisierung/Lastschrift der Wette.

Siedlung: das Ergebnis der Runde und die Gutschrift des Gewinns.

Bonus/Wager: Status des Bonus/Wager-Guthabens.

Jackpot: Beiträge/Auslöser/Auszahlungen.

Event: Unveränderliche Domain-Events (Kafka/Analoga).

Kennungen: 'tenant _ id', 'brand _ id', 'region', 'player _ id', 'session _ id', 'round _ id', 'bet _ id', 'settlement _ id'. Alle sind String, global eindeutig (UUID/KSUID/Snowflake), sind in Protokollen und Ereignissen enthalten.

4) API-Verträge: Anfragen, Antworten, Fehler

4. 1 Autorisierung und Sicherheit

OAuth2 Client Credentials oder mTLS + Signatur des Request Body (HMAC/EdDSA).

Скоупы вида: `bets:write`, `settlements:write`, `sessions:read`, `events:publish`.

In jeder Anfrage sind Überschriften erforderlich:

`X-Trace-Id`, `X-Brand-Id`, `X-Region`, `X-Idempotency-Key`.

4. 2 Beispiele für Endpunkte

Erstellen einer Sitzung


POST /v1/sessions
{
"player_id":"p_19f3",  "game_id":"studio:slot_forge_02",  "currency":"EUR",  "locale":"de-DE",  "constraints":{"max_bet":5,"rg_flags":["self_exclusion":false]}
}
→ 201
{
"session_id":"s_456",  "expires_at":"2025-10-23T19:10:00Z"
}

Wettberechtigung (halten)


POST /v1/bets/authorize
Headers: X-Idempotency-Key: bet_r_8c12_1
{
"session_id":"s_456",  "bet_id":"b_001",  "round_id":"r_8c12",  "amount":{"amount":2. 00,"currency":"EUR"}
}
→ 200 { "status":"authorized","hold_id":"h_zz1" }

Settlement


POST /v1/bets/settle
Headers: X-Idempotency-Key: settle_r_8c12_1
{
"bet_id":"b_001",  "round_id":"r_8c12",  "win":{"amount":14. 60,"currency":"EUR"},  "bonus_state":{"in_bonus":true,"freespins_left":7}
}
→ 200 { "status":"credited","settlement_id":"st_77" }

4. 3 Fehler (einheitliches Modell)

`code`: машинное имя (`RG_BLOCK`, `LIMIT_EXCEEDED`, `DUPLICATE`, `IDEMPOTENCY_MISMATCH`, `INVALID_STATE`, `AUTH_FAILED`).

'message': kurz für den Menschen.

`retryable`: `true/false`.

'trace _ id': für die Suche in den Protokollen.

Beispiel:


409 CONFLICT
{
"code":"DUPLICATE",  "message":"Bet already authorized with a different amount",  "retryable":false,  "trace_id":"tr_a1b2c3"
}

5) Ereignisbus und Schaltungen

5. 1 Basis-Topics

`player. registered`, `session. started	ended`
`bet. authorized	settled
`bonus. issued	consumed
`wager. progress. updated`
`jackpot. contribution	triggered
`rg. limit. hit`, `rg. reality_check`
`wallet. debit.`, `wallet. credit.`

5. 2 Ereignisdiagramm (Avro/JSON Schema)

json
{
"event_id":"uuid",  "event_type":"bet. settled",  "occurred_at":"2025-10-23T16:21:05Z",  "tenant_id":"brand-7",  "region":"EU",  "player_id":"p_19f3",  "trace_id":"tr_a1b2c3",  "payload":{
"round_id":"r_8c12",   "bet":{"amount":1. 00,"currency":"EUR"},   "win":{"amount":14. 60,"currency":"EUR"},   "in_bonus":true
},  "idempotency_key":"bet_r_8c12_1",  "schema_version":"1. 2. 0"
}

Regeln: backward-kompatible Entwicklung von Schemata, Registry + Vertragstests.

6) API-Version: Strategien und Regeln

6. 1 Wo die Version zu speichern

Pfadversion: '/v1/...'(einfach zwischenspeichern/routen).

Header-Version: 'Accept: application/vnd. platform. api+json; version=1. 2`.

Ereignisse: 'schema _ version' im Ereignisfeld + Registrierung.

Übung: Pfad für HTTP, schema_version für Ereignisse, Fichflags für Punktfunktionen.

6. 2 SemVer und Änderungsarten

PATCH (minor) - Reverse-Docking: neue optionale Felder, neue Endpunkte, neue Ereignistypen.

MAJOR - breaking: Felder umbenennen, Semantik ändern, löschen. Nur erlaubt durch neue '/vN/' und deprection der alten.

6. 3 Stabile Verträge (die nicht gebrochen werden können)

Die Namen und Typen der Schlüsselidentifikationsfelder ('_ id', 'idempotency _ key').

Geldmodell ('amount/currency', Genauigkeit).

Die Semantik der Zustände ('authorized', 'credited', 'forfeited' usw.).

Idempotenz: Wiederholungsverhalten ist streng definiert.

7) Kompatibilität und Evolution

7. 1 Ergänzungen (sicher)

Neue optionale Felder mit Standardwerten.

Neue Events/Endpoints ohne Änderung bestehender.

Erweiterung enum mit fallback in 'unknown'.

7. 2 Änderungen (riskant)

Ändern Sie den Feldtyp (Zahl → Zeichenfolge).

Änderung der Verbindlichkeit (optional → erforderlich).

Umkehrung der Geschäftslogik ('settle' vor 'authorize').

→ ist eine neue Hauptversion und eine Migrationshyde erforderlich.

7. 3 Deprection

Das Feld/Endpunkt ist mit 'deprecated _ since: 1' gekennzeichnet. 7`, `removed_in: 2. 0`.

Kommunikation: release notes, mailing, deprecation-headers ('Sunset', 'Deprecation').

Verfolgung der Verwendung von „veralteten“ Pfaden für proaktive Partnerbenachrichtigungen.

8) Idempotenz und Konsistenz

Der Header 'X-Idempotency-Key' ist für alle Schreibvorgänge obligatorisch.

Semantik: Eine Wiederholung mit dem gleichen Schlüssel → das gleiche Ergebnis (200 mit dem gleichen Körper).

Die Schlüssel sind an die Zusammensetzung der Parameter gebunden (z.B. 'bet _ id + amount').

„Authorize → commit/lock → settle → credit“ Entschädigung durch „Rollback“ -Ereignisse.

9) Paginierung, Filter, Sortierung

Cursor-basierte Paginierung (streng bevorzugt 'page/limit' für große Ströme).

Vereinheitlichung:'? cursor =... & limit = 200 & order = asc'.

In der Antwort: 'next _ cursor', 'has _ more'.

Filter: nach Zeit ('occurred _ at _ from/to'), 'tenant _ id', 'game _ id', 'status'.

10) Standorte, Währungen, Datenresidenz

Währung in ISO-4217; Die Genauigkeit wird im Schema ('scale') gespeichert, die Berechnungen in minor units (cents).

Lokali - BCP 47 („en-GB“, „pt-BR“).

In jeder Abfrage ist 'region'; PII und monetäre Transaktionen überschneiden sich nicht mit Regionen.

Maskierung von PII und RLS in BI-Vitrinen.

11) Beobachtbarkeit und Grenzen

Erforderliche Überschriften: 'X-Trace-Id', 'X-Provider-Id', Korrelation mit Ereignissen.

Metriken: p50/p95/p99 Latenz, Fehlerrate (durch Codes), throughput, queue lag (für Ereignisse).

Rate limits: per provider / per brand; Antworten mit 'Retry-After'.

WORM-Audit kritischer Änderungen (Limits, RTP-Pools, Jackpot-Formeln).

12) Prüfung und Qualität der Verträge

Vertragstests (Pact/andere): Anbieter ↔ Plattform ↔ Eventkonsumenten.

Last: „Sturm“ von Wetten/Settlements; Ziele p95.

Chaos-Fälle: Double-Delivery, Out-of-Order, Wallet-Verzögerungen.

Sandbox '/sandbox' mit fiktivem Geld und Test 'player _ id'.

13) SDKs, Generatoren und Dokumentation

OpenAPI/AsyncAPI → SDK-Generierung (TypeScript/Java/Kotlin/Go/Rust).

Codebeispiele für 'authorize/settle/rollback', Retrays und Fehlerbehandlung.

Live-Dock mit Beispielen für Anfrage/Antwort (curl + JSON), Postman/Insomnia Kollektionen.

Changelog mit Änderungstypen und Kompatibilitätsbeschriftungen.

14) Migrationsfahrplan (Beispiel)

1. v1. 6 → v1. 7 (minor): Das Feld 'bonus _ state' wurde zu 'settle' (optional) hinzugefügt.

2. v1. x EOL Ankündigung: 6 Monate im Voraus - E-Mail + 'Deprecation' Header + Dashboard verwenden.

3. v2. 0 (Major): separates' Wallet. commit'(früher implicit), das neue Feld 'settlement _ id' ist erforderlich.

4. Migration hyde: mapping fields, timeline, fichflag „double letter“ (parallele Veröffentlichung von 'v1 '/' v2' Veranstaltungen).

5. Sunset v1: Blockierung neuer Integrationen, Verlängerung nur durch SLA-Ausnahmen.

15) Checklisten

Für Plattformarchitekten

Es gibt ein einziges Wörterbuch von Domäneneinheiten und Invarianten.
OpenAPI/AsyncAPI + Schema Registry, semver, process deprecations.
Idempotenz bei allen Write-Operationen; Schlüssel sind dokumentiert.
Einheitliches Fehler-Modell und Codes.
Sagas und Outbox/CDC auf Geldwegen.
Rate-limits, observability, WORM-Audit.
Sandbox und Vertragstests stehen den Partnern zur Verfügung.
Datenresidenz und RLS/Masking.

Für den Anbieter

Ich sende immer 'X-Trace-Id' und 'X-Idempotency-Key'.
Wiederholungen von Anfragen verarbeite ich sicher; Ich schaffe keine Takes.
Ich bearbeite' Deprecation/Sunset 'und lese Changelog.
Ich veröffentliche/lese Ereignisse nach Registry-Schemata; Ich behalte die Version.
Ich habe Retry/Backoff und Deduplizierung auf meiner Seite.

16) Anti-Muster (rote Fahnen)

Manuelle Korrekturen von Waagen/Settlementen in der DB.

Publizieren von Outbox/CDC-Ereignissen.

Keine idempotency → doppelte Auszahlungen/Belastungen.

Mischung von PII/Geld verschiedener Regionen ohne Kennzeichnung „Region“.

„Stille“ Breaking-Änderungen ohne neue Version und Deprection.

Generieren Sie das SDK manuell (Drift von der realen Speck).

Big-Bang-Migration ohne Fichflags und doppeltes Schreiben von Ereignissen.

Eine einzige API ist nicht nur eine „Sammlung von Endpunkten“, sondern ein Ökosystemvertrag: ein harmonisiertes Vokabular, stabile monetäre Invarianten, Ereignisse mit Versionierung, verständliche Kompatibilitätsregeln und überschaubare Deprections. Basierend auf semantischer Version, Idempotenz, Outbox/CDC, Beobachtbarkeit und strenger Sicherheit verbindet die Plattform Anbieter schnell und schmerzlos und Upgrades werden von Risiko zu Routine.