Un'unica API per provider: progettazione, versioning, compatibilità

Testo completo dell'articolo

💡 18+. Materiale tecnico per i comandi di integrazione e piattaforma. Non una chiamata al gioco.

1) Perché un'unica API e cos'è

Un'unica API è una specifica e un insieme di endpoint/eventi attraverso i quali qualsiasi provider di contenuti (RGS, studio live, jackpot, KYC/AML, affiliati) comunica con la piattaforma con una sola regola:

un unico modello di risorse (players, sessions, bets, settlements, bonuse, jackpots, payments), contratti comuni di eventi e ID, standard di sicurezza e compatibilità, SDK/strumenti per accelerare le integrazioni.

L'obiettivo è ridurre il time-to-integrate, ridurre gli errori sulle «vie di cassa» e fornire upgrade prevedibili.

2) Principi di progettazione

1. Domain-first. Prima il dizionario e gli invarianti (puntata, settlment, limiti RG), poi gli endpoint.

2. Compatibility by default. Qualsiasi modifica è compatibile con l'impostazione predefinita. Modifiche breaking rigorosamente in base al processo.

3. Idempotency everywhere. Tutte le squadre sono ripetute senza effetti collaterali.

4. Events are source of truth (nella distribuzione). Operazioni di recupero eventi in un pneumatico; Ascolta l'analista, non l'OLTP.

5. Least privilege & zero-trust. Token, firme, segmentazione del marchio/regione.

6. Observability. Trace _ id, modello di errore comprensibile, metriche p95/p99.

3) Modello di risorse (semplificato)

Player: pseudo-ID del giocatore sul lato piattaforma, geo/valuta/stato RG.

Sessione: il canale tra provider e piattaforma ('pression _ id', TTL, geo/vincoli).

Bet: autorizzazione/scadenza della puntata.

Il risultato del round e il prestito della vincita.

Bonus/Wager: stato del bonus/saldo del vager.

Jackpot: contributi/trigger/pagamenti.

Eventi di dominio invariati (Kafka/analoghi).

ID: «tenant _ id», «brand _ id», «region», «player _ id», «sessions _ id», «round _ id», «bet _ id», «settlement _ id». Tutti sono righe, globalmente univoci (UUID/KSUID/Snowflake), inclusi nei loghi degli eventi.

4) Appalti API: richieste, risposte, errori

4. 1 Autorizzazione e sicurezza

OAuth2 Client Credentials o mTLS + firma corpo query (HMAC/EdDSA).

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

Ogni richiesta richiede titoli:

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

4. 2 Esempi di endpoint

Creazione sessione


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"
}

Autorizzazione puntata (hold)


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 Errori (modello unico)

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

«Messaggistica» è breve per una persona.

`retryable`: `true/false`.

«trace _ id» per la ricerca nei tastieri.

Esempio:


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

5) Bus di evento e schemi

5. 1 Topic base

`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 Schema evento (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"
}

Regole: backward-compatibile evoluzione degli schemi, registry + test contrattuali.

6) Versione API: strategie e regole

6. 1 Dove memorizzare la versione

Versione path: '/v1/... '(solo cache/routing).

Versione Header: "Accept: application/vnd. platform. api+json; version=1. 2`.

Eventi: 'schema _ version'nel campo evento + registry.

Pratica: path per HTTP, schema _ variante per gli eventi, fittiflagi per le funzionalità di punteggiatura.

6. 2 SemVer e tipi di modifiche

PATCH - Retromarcia: nuovi campi opzionali, nuovi endpoint, nuovi tipi di eventi.

MAJOR - breaking - Rinomina campi, modifica semantica, rimozione. Sono consentiti solo attraverso il nuovo «/ vN/» e la deprecazione del vecchio.

6. 3 Contratti stabili (che non può essere rotto)

Nomi e tipi dei campi chiave di identificazione ('_ id', 'idempotency _ key').

Modello di moneta («amount/currency», precisione).

Semantico di stato («authorized», «credited», «perfeited», ecc.).

Idampotenza: comportamento ripetuto rigorosamente definito.

7) Compatibilità e evoluzione

7. 1 Aggiungi (safe)

Nuovi campi di default opzionali.

Nuovi eventi/endpoint senza modificare quelli esistenti.

Estensione enum con fallback in'unknown '.

7. 2 Modifiche (risky)

Modifica il tipo di campo (numero → riga).

Modifica dell'obbligatorietà (optional).

Inversione di logica aziendale («settle» prima «authorize»).

Serve una nuova versione di maggioranza e un nuovo codice migratorio.

7. 3 Deprecazione

Il campo/endpoint è contrassegnato'deprecated _ since: 1. 7`, `removed_in: 2. 0`.

Comunicazione: release note, distribuzione, deprecation-headers («Sunset», «Deprecation»).

Traccia l'utilizzo di percorsi «obsoleti» per le notifiche proattive dei partner.

8) Idampotenza e coerenza

Il titolo X-Idempotency-Key è obbligatorio per tutte le operazioni di registrazione.

Semantica: ripetizione con la stessa chiave per ottenere lo stesso risultato (200 con il precedente body).

Le chiavi sono collegate alla composizione dei parametri (ad esempio, 'bet _ id + amount').

Le saghe nei processi lunghi sono "authorize" commit/lock "settle" credit "; risarcimenti con eventi «rollback».

9) Paginazione, filtri, ordinamento

Paginazione cursor-based (rigorosamente preferibile à page/limit "per i flussi più grandi).

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

La risposta è «next _ cursor», «ha _ more».

Filtri: «occurred _ at _ from/to», «tenant _ id», «game _ id», «status».

10) Locali, valute, residenza dei dati

Valuta ISO-4217; la precisione viene memorizzata in un diagramma ('scale'), calcoli in minor-units (cents).

Locali - BCP 47 ('en-GB', 'pt-BR').

Ogni richiesta è region; Il PII e le transazioni non attraversano le regioni.

Maschera PII e RLS nelle vetrine BI.

11) Osservabilità e limiti

Intestazioni obbligatorie: 'X-Trace-ID', 'X-Provider-ID', correlazione con gli eventi.

Metriche: p50/p95/p99 latency, error rate (codici), throughput, queue lag (eventi).

Rate limits: per provider / per brand; risposte con Retry-After.

Controllo WORM delle modifiche critiche (limiti, pool RTP, formule jackpot).

12) Test e qualità dei contratti

Test contrattuali (Pact/altri) - Il provider ↔ la piattaforma di ↔ degli eventi.

Carico: «tempesta» di scommesse/settlement; Obiettivi p95.

Le valigette di caos sono riprese-consegne, out-of-order, ritardo del portafoglio.

Cassetta di sabbia «/sandbox »con soldi fittizi e test« player _ id ».

13) SDK, generatori e documentazione

Generazione SDK ( ).

Esempi di codice per «authorize/settle/rollback», retrai e gestione degli errori.

Live doc con esempi di richiesta/risposta (curl + JSON), raccolte Postman/Insomnia.

Changelog con tipi di modifiche e etichette di compatibilità.

14) Road map delle migrazioni (esempio)

1. v1. 6 → v1. 7 (minore) - Hanno aggiunto il campo bonus _ state à settle '(optional).

2. v1. x annuncio EOL - 6 mesi - lettera + «Deprecation» header + dashboard d'uso.

3. v2. 0 (major) - singolarmente "wallet. commit '(precedentemente implicit), il nuovo campo è obbligatorio.

4. Migration Hyde: mapping dei campi, timeline, phichflag «doppia lettera» (pubblicazione parallela «v1 »/« v2» eventi).

5. Sunset v1 - Blocca le nuove integrazioni e estende solo con eccezioni SLA.

15) Assegno fogli

Per gli architetti della piattaforma

C'è un unico dizionario di entità di dominio e invarianti.
OpenAPI/AsyncAPI + Schema Registry, semver, process deprecation.
Idampotenza su tutte le operazioni write; le chiavi sono documentate.
Unico errore modello e codici.
Saghe e outbox/CDC in contanti.
Rate-limits, osservabilità, controllo WORM.
Arenaria e test contrattuali sono disponibili per i partner.
Data residency e RLS/Masking.

Per il provider

Invio «X-Trace-Id» e «X-Idempotency-Key» sempre.
Le ricorrenze di query sono sicure; Non faccio riprese.
Sto elaborando Deprecation/Sunset e leggo Changelog.
Pubblico/leggo gli eventi sui circuiti registry; Conservo la versione.
Ho retry/backoff e deduplicazione sul mio lato.

16) Anti-pattern (bandiere rosse)

Modifica manuale dei bilanci/settlement nel database.

Pubblicare gli eventi oltre outbox/CDC.

La mancanza di idempotency è una ripresa di pagamenti/debiti.

Miscelare PII/denaro di diverse regioni senza etichettatura «region».

Modifiche breaking silenziose senza nuova versione e deprecazione.

Generazione manuale di SDK (deriva dallo specchio reale).

Migrazioni big-bang senza fitsflag e doppia scrittura degli eventi.

Un'unica API non è solo una «collezione di endpoint», ma un contratto di un ecosistema: dizionario coerente, invarianti monetari stabili, eventi di versioning, regole di compatibilità comprensibili e deprecazioni gestite. Basandosi su versioni semantiche, idampotenza, outbox/CDC, osservabilità e sicurezza rigorosa, la piattaforma connette i provider in modo rapido e indolore, mentre gli upgrade vengono trasformati da rischi a routine.