API unique pour les fournisseurs : conception, versioning, interopérabilité

Texte intégral de l'article

💡 18+. Matériel technique pour les équipes d'intégration et de plateforme. Pas un appel au jeu.

1) Pourquoi une « API unique » et ce qu'elle est

L'API unique est une spécification et un ensemble d'endpoints/événements par lesquels tout fournisseur de contenu (RGS, studio live, jackpot, KYC/AML, affiliés) communique avec la plate-forme selon une seule règle :

modèle de ressources unique (joueurs, sessions, bets, settlements, bonuses, jackpots, payments), contrats et identifiants d'événements généraux, normes de sécurité et de rétrocompatibilité, SDK/outils pour accélérer les intégrations.

Objectif : réduire le temps d'intégration, réduire les erreurs sur les « flux monétaires » et fournir des mises à niveau prévisibles.

2) Principes de conception

1. Domain-first. D'abord le dictionnaire et les invariants (pari, settlement, limites RG), puis les endpoints.

2. Compatibility by default. Toute modification est compatible par défaut ; breaking-change strictement par processus.

3. Idempotency everywhere. Toutes les commandes monétaires sont répétables sans effets secondaires.

4. Events are source of truth (dans la distribution). Opérations → événements dans le bus ; l'analyste écoute le pneu plutôt que de frapper l'OLTP.

5. Least privilege & zero-trust. Tokens, signatures, segmentation par marque/région.

6. Observability. "trace _ id', modèle d'erreur compréhensible, métriques p95/p99.

3) Modèle de ressources (simplifié)

Player : pseudo-ID du joueur sur le côté de la plate-forme, géo/monnaie/statuts RG.

Session : canal entre le fournisseur et la plate-forme ("session _ id', TTL, géo/restrictions).

Bet : autorisation/débit de mise.

Settlement : résultat du tour et crédit de gain.

Bonus/Wager : état du bonus/solde du vader.

Jackpot : contributions/déclencheurs/paiements.

Event : événements de domaine immuables (Kafka/équivalents).

Identifiants : 'tenant _ id', 'brand _ id', 'region', 'player _ id', 'session _ id', 'round _ id', 'bet _ id', 'settlement _ id'. Tous - chaîne, globalement unique (UUID/KSUID/Snowflake), sont inclus dans les logs et les événements.

4) Contrats API : demandes, réponses, erreurs

4. 1 Autorisation et sécurité

OAuth2 Client Credentials ou mTLS + signature du corps de requête (HMAC/EdDSA).

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

Dans chaque demande, les titres sont obligatoires :

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

4. 2 Exemples d'endpoints

Création d'une session


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

Autorisation de mise (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" }

Settlment


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 Erreurs (modèle unique)

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

« message » : bref pour l'homme.

`retryable`: `true/false`.

'trace _ id' : pour rechercher dans les logs.

Exemple :


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

5) Bus et circuits d'événements

5. 1 Tops de 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 Schéma de l'événement (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"
}

Règles : backward-compatible évolution des schémas, registry + tests contractuels.

6) La versification de l'API : stratégies et règles

6. 1 Où stocker la version

Version path : '/v1/... '(il suffit de mettre en cache/router).

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

Événements : 'schema _ version' dans le champ événement + registry.

Pratique : path pour HTTP, schema_version pour les événements, fichflags pour les capacités ponctuelles.

6. 2 BouVer et types de changements

PATCH (mineur) - rétrospective : nouveaux champs facultatifs, nouveaux endpoints, nouveaux types d'événements.

MAJOR - breaking : renommer les champs, modifier la sémantique, supprimer. Permis uniquement par le nouveau '/vN/' et la dépréciation de l'ancien.

6. 3 Contrats stables (à ne pas casser)

Noms et types de champs d'identification clés ('_ id', 'idempotency _ key').

Modèle monétaire ('amount/currency', précision).

Sémantique des statuts (« autorisé », « credited », « forfeited », etc.).

Idempotence : le comportement à répétition est strictement défini.

7) Compatibilité et évolution

7. 1 Additifs (safe)

Nouveaux champs facultatifs en défaut.

Nouveaux événements/endpoints sans changer ceux existants.

Extension enum avec fallback dans 'unknown'.

7. 2 Modifications (risky)

Modifie le type de champ (nombre → chaîne).

Modification de l'obligation (facultatif → required).

Inversion de la logique d'entreprise ('settle' avant 'authorize').

Une nouvelle version majeure et un hyde migratoire sont → nécessaires.

7. 3 Dépréciation

Le champ/endpoint est marqué par "deprecated _ since : 1. 7`, `removed_in: 2. 0`.

Communication : release notes, newsletter, deprecation-headers (« Sunset », « Deprecation »).

Tracer l'utilisation de chemins « obsolètes » pour les notifications proactives des partenaires.

8) Idempotence et cohérence

L'en-tête « X-Idempotency-Key » est obligatoire pour toutes les opérations d'enregistrement.

Sémantique : répétition avec la même clé → le même résultat (200 avec l'ancien body).

Les clés sont liées à la composition des paramètres (par exemple, "bet _ id + amount').

Sagas sur les processus longs : 'autorize → commit/lock → settle → credit' ; compensations - événements « rollback ».

9) Pagination, filtres, triage

Pagination à base de curseurs (strictement préférable à 'page/limit' pour les grands flux).

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

Dans la réponse : 'next _ cursor', 'has _ more'.

Filtres : Par temps ('occurred _ at _ from/to'), 'tenant _ id', 'game _ id', 'status'.

10) Localités, devises, résidence de données

Monnaie en ISO-4217 ; la précision est stockée dans le schéma ('scale'), les calculs dans les unités mineures (cents).

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

Dans chaque requête, « région » ; L'IPI et les transactions monétaires ne traversent pas les régions.

Masquage PII et RLS dans les vitrines BI.

11) Observabilité et limites

Titres obligatoires : 'X-Trace-Id', 'X-Provider-Id', corrélation avec les événements.

Métriques : p50/p95/p99 latency, error rate (par code), throughput, queue lag (pour les événements).

Rate limits: per provider / per brand; réponses avec « Retry-After ».

Audit WORM des changements critiques (limites, pools RTP, formules jackpot).

12) Test et qualité des contrats

Tests contractuels (Pact/autres) : le fournisseur ↔ la plate-forme ↔ les consumers d'événements.

Charge : « tempête » de paris/settlements ; objectifs p95.

Cas de chaos : prise-livraison, out-of-order, portefeuille retard.

Bac à sable '/sandbox 'avec argent fictif et test' player _ id '.

13) SDK, générateurs et documentation

OpenAPI/AsyncAPI → génération de SDK (TypeScript/Java/Kotlin/Go/Rust).

Exemples de code pour 'authorize/settle/rollback', retraits et gestion des erreurs.

Live-dock avec des exemples de demande/réponse (curl + JSON), collection Postman/Insomnia.

Changelog avec les types de modification et les étiquettes de compatibilité.

14) Feuille de route pour les migrations (exemple)

1. v1. 6 → v1. 7 (mineur) : ont ajouté le champ 'bonus _ state' dans 'settle' (facultatif).

2. v1. Annonce x EOL : 6 mois à l'avance - lettre + 'Deprecation' header + dashboard d'utilisation.

3. v2. 0 (major) : un 'wallet séparé. commit '(anciennement implicit), le nouveau champ "settlement _ id'est obligatoire.

4. Hyde migratoire : mapping de champs, timeline, fichiflag « double écriture » (publication parallèle des événements 'v1 '/' v2').

5. Sunset v1 : blocage des nouvelles intégrations, extension uniquement sur les exceptions SLA.

15) Chèques-feuilles

Pour les architectes de plateforme

Il existe un dictionnaire unique des entités de domaine et des invariants.
OpenAPI/AsyncAPI + Schema Registry, semver, process de dépressions.
Idempotence sur toutes les opérations d'écriture ; les clés sont documentées.
Un seul modèle d'erreur et des codes.
Sagas et outbox/CDC sur les trajets monétaires.
Taux-limites, observabilité, audit WORM.
Le bac à sable et les tests contractuels sont à la disposition des partenaires.
Data residency et RLS/masquage.

Pour le fournisseur

J'envoie toujours 'X-Trace-Id' et 'X-Idempotency-Key'.
Je traite les demandes répétées en toute sécurité ; Je ne produis pas de prises.
Je traite 'Deprecation/Sunset'et je lis Changelog.
Je publie/lis des événements sur les schémas de registry ; Je garde la version.
J'ai retry/backoff et déduplication de mon côté.

16) Anti-modèles (drapeaux rouges)

Édition manuelle des balances/réseaux dans la base de données.

Publier les événements « passé » outbox/CDC.

Absence d'idempotentialité → prise de paiement/débits.

Mélange PII/argent de différentes régions sans marquage « région ».

Des modifications « silencieuses » sans nouvelle version et dépréciation.

Génération de SDK manuellement (dérive à partir d'un spot réel).

Migration Big-bang sans fichflags et double écriture d'événements.

L'API unique n'est pas seulement une « collection d'endpoints », mais un contrat d'écosystème : un dictionnaire cohérent, des invariants monétaires stables, des événements de versioning, des règles de compatibilité compréhensibles et des dépressions gérables. En s'appuyant sur la version sémantique, l'idempotence, l'outbox/CDC, l'observabilité et la sécurité stricte, la plate-forme relie les fournisseurs rapidement et sans douleur, et les mises à niveau se transforment en routine.