Interfaces d'accès aux données

1) Pourquoi une interface réfléchie

Rapidité et prévisibilité : les mesures et les rapports commerciaux sont empilés dans le SLA, sans « déchargement manuel ».
Sécurité et vie privée : PII/biométrie sous contrôle, k-anonymat, géo-frontières.
Flexibilité : différents clients (BI, services, partenaires, DS/ML) obtiennent exactement ce dont ils ont besoin.
Réutilisation : « données en tant que produit » avec contrats et versions.

2) Carte des interfaces (quand quoi)

SQL/ANSI + dialectes vendoriens : analyse interactive, BI, ad hoc.
REST JSON : agrégats stables et données opérationnelles, intégrations avec des partenaires.
GraphiqueQL : lecture flexible « sélective » et graphique de navigation (mesures/faits).
gRPC (protobuf) : faible latence en ligne-serving (Feature Store, scoring).
Arrow Flight/Parquet over HTTP/S3-presigned : « décharges » rapides pour DS/ML.
OData : outils d'entreprise, modèle « table comme service ».
Streams (Kafka/Pulsar) + CDC/Webhooks : événements en temps réel, intégrations réactives.
Fédération (Trino/Presto) : un point d'entrée unique vers une multitude de sources.

Règle : agrégats et tranches stables → REST/MV, requêtes arbitraires riches → SQL, faible latence/fiches en ligne → gRPC, forme flexible de réponse → GraphQL, échange binaire massif → Arrow/Parquet.

3) Contrats et versions (semver)

`MAJOR. MINOR. PATCH 'pour chaque API/schéma/événement.
MAJOR : modifications incompatibles (nouveau chemin/haut/table).
MINEUR : Ajout compatible de champs/arguments.
PATCH : orthographe des descriptions/limites.
Les contrats fixent : schéma, filtres, limites, vie privée, SLO.

yaml openapi: "3. 0. 3"
info: {title: "Analytics API", version: "2. 4. 0"}
paths:
/v2/payments/metrics:
get:
parameters:
- {name: brand, in: query, schema: {type: string}, required: true}
- {name: country, in: query, schema: {type: string}}
- {name: from, in: query, schema: {type: string, format: date-time}}
- {name: to, in: query, schema: {type: string, format: date-time}}
- {name: group_by, in: query, schema: {type: string, enum: [psp,status,day]}}
- {name: limit, in: query, schema: {type: integer, default: 500}}
responses:
"200": {description: "OK"}
x-slo: {p95_latency_ms: 1200, freshness_max: "PT5M"}
x-privacy: {pii: false, min_group_size: 20}

4) Accès à l'analyse (SQL et fédération)

passerelle SQL avec rôles/masques (row/column-level security).
Viuhi/projections sous BI : noms stables et sémantique ; les demandes heavy partent en préagrégation.
Fédération (Trino/Presto) : un point d'entrée unique, mais avec des politiques : quels répertoires et quelles fonctionnalités sont disponibles.
Lakehouse (Iceberg/Delta/Hudi) : time-travel, snapshot-extractions via SQL/REST.
Квоты: scanned bytes/query, concurrency, wall-time.

5) GraphQL (forme souple)

Nous laissons le client rassembler le bon champ, mais nous exécutons au-dessus des vues/projections préparées, avec des limites de profondeur/os.

graphql type Query {
payments(
brand: String!, country: String, from: DateTime!, to: DateTime!,
first: Int = 200, after: String
): PaymentConnection
}

Politiques : depth ≤ 5, total nodes ≤ 5k, interdire les regex/like arbitraires par ligne ; Nous avons des demandes fréquentes.

6) gRPC/Feature Store (faible latence)

Fiches en ligne pour le scoring antifrod/recommandations/RG.

proto service FeatureStore {
rpc GetFeatures (FeatureRequest) returns (FeatureResponse);
}
message FeatureRequest { string user_tok = 1; repeated string features = 2; }
message FeatureResponse { map<string, FeatureValue> values = 1; int64 ts_micros = 2; }

Exigences : p95 ≤ 50-100 ms, cohérence exacte des offlayn↔onlayn, TTL fich, cache LRU, idempotency et mTLS.

7) Flux et CDC

Événements du domaine : 'payments. deposit_accepted`, `game. round_finished`.
CDC (from OLTP) : modifications des statuts/limites dans le temps proche-réel.
Webhooks pour les partenaires : abonnement aux agrégats (par exemple, « failles PSP> seuil »).
Politiques de rétroaction/confirmation : exactly-once pour les critiques, at-least-once pour le suivi.

8) Lacs et grands échantillons

Arrow Flight pour déchargement rapide de colonnes en DS/ML.
Presigned-URL sur Parquet/Feather, avec un court TTL et une demande signée.
Transfert chunked et contrôle de la taille du fichier ; journal de téléchargement (audit WORM).

9) Filtres, pagination, tri

Keyset-pagination (curseur) au lieu de OFFSET pour les grands ensembles.
Filtres : whitelists par champs, types et opérateurs ('=, IN, BETWEEN, prefix').
Trier : liste limitée des champs, ordre par défaut.
Réponse partielle : 'fields = brand, country, amount'réduit la charge utile.

http
GET /v2/game-rounds? brand=X&from=...&to=...&first=1000&after=eyJkYXRlIjoi...

10) Mise en cache et coût

Result cache pour les demandes de modèle, nous invalidons par le jeton de fraîcheur (snapshot id).
Cache Edge/CDN pour les unités publiques/semi-publiques (sans PII).

Paramètres de budget : Limite scannée bytes, délai de requête, quotas rps/min

Priorité des pools : 'bi _ hot', 'adhoc', 'partner _ api'.

11) Sécurité et vie privée

AuthN : OAuth2/OIDC (client credentials pour les services, PKCE pour les personnes).
AuthZ : RBAC + ABAC (attributs : marque, pays, licence, rôle).
mTLS entre les services, TLS 1. 2 + dehors.
Hygiène PII : masques/tokenization sur la couche API, masques de colonne, anonymat k des agrégats.
Géo/tenant-isolation : acheminer les demandes vers la région de licence ; clés de cryptage par marque/région.
DSAR/Legal Hold : recherche par jeton sujet, secrets pour geler les ensembles.

12) Observabilité (SLI/SLO) et protection

SLI : p50/p95/p99 lat, taux d'erreur, rps, bytes scannés, cache hit, quotas/limites, proportion de colonnes masquées, proportion de refus d'autorisation.
SLO : p95 latence, fraîcheur des données, % de demandes réussies, min-group-size sur les réponses.
Alertes : croissance scannée bytes, chute hit-rate, surtension 429/5xx, tentatives d'accès PII, fuites de curseurs.

yaml slo:
p95_latency_ms: 1200 success_rate: 0. 995 freshness_max: "PT5M"
privacy:
pii_allowed: false min_group_size: 20 quotas:
rps: 50 max_scanned_mb: 256

13) Formats et compressions

JSON pour la compatibilité ; CSV - seulement pour les petites et simples exportations.
Parquet/Arrow est la valeur par défaut pour les décharges volumineuses.
Compression : gzip/zstd (négociation via 'Accept-Encoding').
Content-negotiation: `Accept: application/x-parquet`.

14) Métriques comme API (passerelle analytique/OLAP)

Métriques de niveau supérieur : GGR/NET, CR, rétention, incidents RG - comme ressources avec les paramètres 'brand, country, window, group _ by'.
Approx (HLL/TDigest) для distinct/percentiles.
Cache avec clé : '(metric, params, snapshot_id)'.

15) Spécificités iGaming - endpoints prêts

'GET/v2/payments/metrics 'est un défaut/aprouve par PSP/pays/marque avec 7/30d fenêtres.
'GET/v2/game-rounds/metrics '- top games/fournisseurs, p95 durées, fenêtres RTP.
'GET/v2/rg/cases '- Restrictions actives/auto-exclusions (agrégats k-anonymes).
'POST/v1/features : get '(gRPC) est une fiche de scoring frod/recommander en ligne.
« POST/v1/webhooks/psp-alerts » - notifications « decline rate> seuil ».

16) Exemples de contrats

graphql query {
payments(brand:"X", country:"TR", from:"2025-10-01", to:"2025-10-31", first:500) {
edges { node { day totalAmount declines psp } cursor }
pageInfo { hasNextPage endCursor }
}
}

json
{"event_id":"...","occurred_at":169..., "brand":"X","psp":"Papara","status":"declined","amount":"100. 00","currency":"TRY"}

/flight/v1/query? dataset=gold. payments&from=...&to=...&brand=X&format=arrow

17) Processus de publication de la nouvelle interface

1. ADR : problème/valeur/clients/sécurité/coût.
2. Contrat : schéma, filtres, limites, vie privée, SLO, versions.
3. Simulation de charge : top-N requêtes, p95/scan-octets, coût.
4. Validation/cache/quotas : activer par défaut.
5. Documentation et SDK : exemples, limites, erreurs, retraits, idempotence.
6. Canary :% de clients, tests de régression, alertes.
7. GA : version dans le catalogue Data Products, rapport sur les effets.

18) Anti-modèles

Ouvrir « brut » SQL à tout le monde - fuites PII, coût imprévisible.
La pagination OFFSET et 'SELECT' sont des douleurs de latence et de comptage.
GraphQL sans limites de profondeur/coût.
REST qui renvoie trop de colonnes sans 'fields =...'.
Manque d'anonymat k et min-group-size dans les agrégats.
Quotas/limites nuls et cache désactivé.
Pas de versioning/contrats - « casser » les clients à chaque changement.
La même interface pour tous les pays/marques - ignorer les règles régionales.

19) Feuille de route pour la mise en œuvre

0-30 jours (MVP)

1. Le catalogue Data Products (métriques/tranches) et leurs contrats OpenAPI/GraphQL.
2. passerelle SQL avec RLS/CLS, anonymat k des agrégats, quotas de base.
3. Une métrique REST endpoint ('/payments/metrics') + cache + pools 'bi _ hot/adhoc'.
4. gRPC Feature Store : lecture 10-20 fiches clés en ligne (p95 ≤ 80 ms).

30-90 jours

1. Interfaces stream (Kafka/Webhook) pour les alertes PSP/événements de jeu.
2. Arrow/Parquet de déchargement avec l'URL presignée ; catalogue de snapshots.
3. Federation-Gateway (Trino/Presto) avec des politiques explicites.
4. Observabilité : dashboard SLI/SLO, alertes de coût/latence/PII.

3-6 mois

1. SDK (TypeScript/Python/Go) avec retraits/idempotence/quotas.
2. Fines tranches GraphQL pour les produits et les partenaires.
3. Extension de gRPC/FS, harmonisation des offlayn↔onlayn ; shadow→canary les versions.
4. Audit de la vie privée/DSAR ; Rapports de conformité sur les accès.

20) RACI

Data Platform (R) : passerelles, cache, quotas, fédération, observabilité.
Data Governance (A/R) : contrats, versions, confidentialité/k-anonymat.
Domain Owners (R) : sémantique des champs, invariants d'affaires, produits de données.
Sécurité/DPO (A/R) : AuthN/Z, géo-isolation, DSAR/Legal Hold.
SRE/Observability (C) : SLO/SLI, alertes, capacity.
Analytics/BI/DS (C) : exigences relatives aux formulaires/agrégats, SDK.

21) Sections connexes

Indexation des référentiels analytiques, Optimisation des requêtes analytiques, Schémas et évolution des données, Validation des données, Pratiques DataOps, API Analytics and Metrics, Feature Store, Sécurité des données et cryptage, Contrôle d'accès, Stratégies de stockage.

Résultat

Des interfaces d'accès aux données bien conçues transforment le stockage et les flux en un « produit » fiable : SLA prédictible, coût contrôlé, respect de la vie privée et langage unique pour les équipes de produits, les analystes, les collaborateurs et les partenaires. Dans iGaming, cela signifie attraper plus rapidement les pannes PSP, comprendre le comportement des joueurs et répondre aux exigences des régulateurs - sans déchargement manuel et migrations nocturnes.