Analyse- und Metrik-APIs

1) Warum eine separate API-Schicht

Eine einzige Wahrheit für KPIs: Wir schließen den „SQL Zoo“ aus.
Produktgeschwindigkeit: Fronten, Affiliate-Panels, mobile Kunden erhalten Aggregate ohne direkten Zugriff auf DWH.
Sicherheit und Compliance: Tokenisierung, Masken, Geo-Restriktionen, RG/AML-Filter.
Skalierung: Cache, Prerender, CDN, stabile Verträge.

2) Taxonomie: Metriken, Dimensionen, Fakten

Fakten: Wetten, Gewinne, Einzahlungen, KYC-Events, RG-Interventionen.
Maße: Datum/Uhrzeit (Kalender), Spiel/Anbieter, Marke/Land, Kanal/Gerät, Spieler (Token).
Metriken: GGR, NGR/NET, ARPPU, D1/D7/D30, Depothäufigkeit, FPR-Betrugsbekämpfung, RG-Risiko.
Einheiten: Währung (FX), Zeit (TZ), Volumen/Zähler (idempotent!).
KPI-Semantik: Definitionen in BI-Verträgen, KPI-Versionen werden erfasst.

3) API-Verträge (Daten- & BI-Verträge)

Schema: Felder, Typen, nullbar, enum, Einheiten, Währungen.
Semantik der Metriken: Formel, Quellen, Aggregationsfenster, Filter.
Kompatibilität (SEMVER): MAJOR bricht, MINOR fügt Felder hinzu, PATCH fixiert.
DQ/SLA: Frische, Vollständigkeit, Konsistenz, Toleranzen von Abweichungen.
Privatsphäre: 'pii: false', 'tokenized: true', Verbot der Entgiftung.

yaml api: analytics. v2 resource: /metrics/revenue kpi: GGR schema_version: 2. 1. 0 dimensions: [date, brand, country, provider, game]
metrics: [ggr, stakes, wins, bets_count]
sla: {freshness: PT15M, completeness: ">=99. 9%"}
privacy: {pii: false, tokenized: true}

4) Architektur

Abfrage-API (Online-Aggregationen über „Gold „/Würfel/Fichester).
Precompute API (Prerender nach Zeitplan, materialisierte Ansichten).
Events API (Streaming-Zähler/Signale).
Export API (signierte Uploads, WORM für Audit).
Cache: mehrschichtig (In-Memory → Redis → CDN), Schlüssel = Hash der Anfrage + Version.
Konsistenz: Read-your-writes für die endgültigen Einträge, SLA Frische für Aggregate.

5) Schnittstelle und Anfragen

5. 1 Filter/Aggregationen/Fenster

'filter': Datumsbereiche ('from/to' UTC, timezone aware), Länder, Marken, Spiele, Kanäle, Geräte.
'group _ by': Messungen.
„metrics“: Liste der KPIs.
`window`: `DAY|WEEK|MONTH|ROLLING_7D|ROLLING_28D`.
"currency": "reporting" native ", FX-Strategie:" eod "intraday" txn ".
'sampling': für heavy-requests (nur wo zulässig).

5. 2 Beispiel für eine Abfrage

json
POST /v2/metrics/revenue
{
"range": {"from":"2025-10-01","to":"2025-10-31","tz":"Europe/Kyiv"},
"group_by": ["date","brand","country"],
"metrics": ["ggr","bets_count","net_revenue"],
"filters": {"country":["EE","LT","LV"],"brand":["alpha","beta"]},
"currency": "reporting",
"window": "DAY"
}

5. 3 Beispiel für eine Antwort

json
{
"schema_version":"2. 1. 0",
"kpi_definitions":["ggr@1. 7. 0","net_revenue@1. 3. 2"],
"range":{"from":"2025-10-01","to":"2025-10-31","tz":"Europe/Kyiv"},
"data":[
{"date":"2025-10-01","brand":"alpha","country":"EE","ggr":12450. 72,"bets_count":182342,"net_revenue":10732. 11},
{"date":"2025-10-01","brand":"beta","country":"EE","ggr":...}
],
"fx":{"strategy":"eod","rate_date":"2025-10-31"},
"dq":{"freshness_sec":420,"completeness":0. 9992},
"trace_id":"3d1a-...-c79"
}

6) Paginierung, Grenzen, Sortierung

Paginierung: 'limit' (≤10k), 'cursor' (opaque), Sortierung nach Maß/Datum.
Timeout/partial: Teilantworten nur für nicht-finanzielle KPIs; Finanzen - entweder P200 oder P504.
Rate limits: global/nach Schlüssel/nach Tenant; Antwort enthält 'X-RateLimit-'.

7) Idempotenz und Cache

Idempotente GET/POST-read (mit Körper) mit 'Idempotency-Key'.
Cache-Schlüssel = Hash (Parameter + Schema-Version + Rolle/Tenant/Geo).
TTL: KPI-abhängig (z.B. 'PT15M' für Revenue, 'PT5M' für Events), Reset bei neuem Snapshot.

8) Konsistenz und die Währung der Zeit

Zeitreise-Flag für retrospektive Berichte (Datenversionen).
Cut-off-Regeln (Tag/Woche Schließung).
FX: Wir fixieren die Strategie, das Kursdatum in der Antwort.
Clock: Alle Zeitstempel sind ISO-8601, die Angabe von TZ ist obligatorisch.

9) Sicherheit und Privatsphäre

mTLS/TLS1. 3, HMAC-Signatur des Request/Response-Body (Schutz vor MITM/replay).
RBAC/ABAC/ReBAC: Rolle + Land + Marke + Ziel; Standardmasken.
Multi-Leasing (Multi-Tenant): Isolierung von Schemata/Schlüsseln/Quoten.
Tokenisierung von IDs; Verbot von PII in den Antworten.
Audit: Unveränderliche Anforderungsprotokolle (WORM), 'trace _ id '/' actor '/' purpose'.
Consent/DSAR: Filter für Marketing-Attribute; „Betreff erased“ -Flag.

10) RG/AML/Anti-Betrug Einschränkungen

RG-Politik: Verbot der Ausgabe von „aggressiven“ Indikatoren für hochriskante Segmente; Die Geräte sind sicher.
AML/Fraud: eingeschränkter Zugriff auf sensible KPIs, Zonierung nach Rolle; getrennte Endpunkte für Untersuchungen.
Erklärbarkeit: Erklärungswörterbuch der KPIs/Signale für den Sapport.

11) Beobachtbarkeit und SLO API

SLO: p95 Latenz (z. B. ≤ 300 ms für Cache-Hits; ≤ 2 s für schwere Hits), Erfolgsrate ≥ 99. 5%.
DQ: Frische/Vollständigkeit/Integrität; Beschriftungen in der Antwort.
Verwendung: QPS, Cache-Hit-Rate, Hot Keys, Validierungsfehler.
Alerts: Abbau der Frische, 4xx/5xx Wachstum, Anomalien durch KPIs (unexpected zeros/peaks).
Tracing: 'trace _ id' durch bis DWH/Fichester.

12) Versionierung und Kompatibilität

Pfade: '/v1', '/v2'; Deprecate mit Migrationsfenster.
Schemas: 'schema _ version' in der Antwort; MAJOR → Dual-Read, Migrationsbewegungen.
KPI-Versionen: in der Antwort 'kpi _ definitions' mit einem Link im Verzeichnis; ausgeblendete Formeländerungen verhindern.

13) Fehler und Status

„400“ Validierung (nicht vorhandene Metrik/Messung/Filterkombination).
„401/403“ Authentifizierung/Autorisierung.
'409' Inkompatibilität von Versionen/Richtlinien.
„422“ eine Verletzung der Vertraulichkeit/consent.
„429“ Quoten.
'5xx' Plattform abstürzt (mit trace_id und retry-post.) .

json
{
"error":"VALIDATION_FAILED",
"message":"Unknown metric: ngrx",
"hint":"metrics allowed: ggr, net_revenue,...",
"trace_id":"..."
}

14) Integrationen und Schnittstellen

BI: Vordefinierte semantic-Modelle, Konnektoren (Looker/Power BI/Tableau) → API als Quelle.
ML: Leichtgewichtige Endpunkte für Fich-Aggregate (Point-in-Time, ohne PII).
Partner: eingeschränkte Schlüssel/Kontingente, Geo-Filter, Berichte nur in Aggregatblöcken.
Webhook/Push: Meldung „Snapshot bereit“, „SLO/KPI Bereich gestört“.

15) Beispiele für Ressourcenendpunkte

15. 1 Umsatz/Ertrag

„POST/v2/metrics/revenue“ → GGR/NGR, Wetten/Gewinne, gemessen als „Datum, Marke, Land, Anbieter, Spiel“.

15. 2 Halten und Trichter

`POST /v2/metrics/retention` → когорты D1/D7/D30, `group_by=[cohort_week, brand, country]`.

15. 3 Zahlungen

„POST/v2/metrics/payments“ → Einzahlungen/Auszahlungen, durchschnittlicher Scheck, Chargeback-Rate.

15. 4 Responsible Gaming

'POST/v2/metrics/rg' → Anzahl der Interventionen, High-Risk-Anteil, durchschnittliche Reaktionszeit.

15. 5 Betrugsbekämpfung

"POST/v2/metrics/antifraud' → FPR/TPR, Fälle, Verluste verhindert.

16) Prüfung und Qualität

Vertragstests: enum/nullable/type, Währungs-/Zeitzonenkonsistenz.
DQ-Tests: Kontrolle der Bereiche, Monotonie und Integrität.
Regression: Vergleich v1/v2 nach Toleranten.
Last: Spitzenprofile (Turniere/Anbieter-Events).
Sicherheit: Signaturen, Anti-Replay, Fuzzing-Anfragen, Zero-PII in Protokollen.

17) Standard-Datenschutz

Aggregate mit Schwellenwerten von „mindestens N Einträgen“ (k-Anonymität).
Keine RAW-IDs; Nur Token/Kategorien.
DSAR: API zum Entladen/Löschen per Token über einen privilegierten Pfad.

18) Erfolgsmetriken (API KPIs)

Adoption: Anteil der Berichte/Widgets, die APIs anstelle von Direct SQL verwenden.
Consistency: Diskrepanz zwischen BI und API ≤ Toleranzen.
SLO: Einhaltung der Latenz/Erfolg/Frische.
Sicherheit: Null PII-Fälle in Antworten/Protokollen.
Kosten: Cache-Trefferquote, Anforderungskosten,% Prerender.

19) RACI (Beispiel)

Product/Analytics (A) - KPI-Definitionen, Bedarf.
Data Platform (R) - Implementierung, Cache, SLA, Observability.
Domain Owners (R) - Quellen/Verträge.
Sicherheit/DSB (A/R) - Datenschutz, Zugriffe, Audits.
SRE (R) - Quoten, Autoscale, Vorfälle.
Finance (C) ist die Finanzsemantik von GGR/NGR/NET.

20) Fahrplan für die Umsetzung

0-30 Tage (MVP)

1. Wählen Sie 3-5 KPIs (GGR, Einlagen, D7 Retention).
2. Verträge und KPI-Semantik beschreiben; DQ/SLA aktivieren.
3. Implementieren Sie '/v1 'Query API + Cache + mTLS/HMAC.
4. SLO Dashboards (latency/success/freshness), audit/trace _ id.

30-90 Tage

1. Prerender (Precompute) von beliebten Schaufenstern, CDN-Cache.
2. Versionierung '/v2', Dual-Read, Migrationshyde.
3. API-Export mit signierten Uploads und WORM.
4. Integration mit BI/ML; Quoten/Tenanten/Geo-Isolatoren.

3-6 Monate

1. Vollständige KPI-Taxonomie und Widget-Bibliothek.
2. Intelligente Hinweise/Auto-Set-Filter, Abfrage Linter.
3. Automatische Release Notes KPIs, Steuerung der Toleranzen v1/v2.
4. Externe Partnerschleife mit eingeschränkten Schlüsseln und RG-Richtlinien.

21) Anti-Muster

Versteckte Änderung der KPI-Formel ohne neue Version und Release-Note.
Rückgabe von PII/Rohstoffen anstelle von Aggregaten/Token.
Kein Cache/Prerender → teuer und langsam.
Starre Bindung an eine bestimmte DB (keine Schichtabstraktion).
Inkonsistente TZ/FX → nicht vergleichbare Zahlen.
Keine rate limits/Quoten → „DDOS eigenen“.

22) Vorlagen (gebrauchsfertig)

22. 1 SLO-API-Richtlinie (Ausschnitt)

yaml api: analytics. v2 slo:
p95_latency_ms: 300 success_rate: 0. 995 freshness_sec_max: 900 quotas:
per_key_qps: 50 burst: 200 privacy:
min_group_size: 25 pii_in_response: false

22. 2 OpenAPI (Fragment)

yaml paths:
/v2/metrics/revenue:
post:
requestBody:
content:
application/json:
schema: {$ref: '#/components/schemas/RevenueQuery'}
responses:
'200': {description: 'OK', content: {application/json: {schema: {$ref:'#/components/schemas/RevenueResponse'}}}}
'422': {description:'Privacy/Consent violation'}

22. 3 Release Checkliste

• KPI-Semantik aktualisiert und Version erhöht
• Vertrag/Schema im Katalog; DQ/Regressionstests grün
• Cache-Schlüssel/TTL, Prerenner konfiguriert
• Dokumentation und Beispiele für Anfragen/Antworten
• Alerts für SLO und Quoten enthalten
• RG/AML Einschränkungen geprüft

23) Verwandte Abschnitte

DataOps-Praktiken, Audit und Versionsfähigkeit, Sicherheit und Verschlüsselung, Zugangskontrolle, Datentokenisierung, Aufbewahrungsrichtlinien, Datenherkunft und -pfad, MLOps: Modellausnutzung, Datenethik.

Summe

Die Analytics & Metrics API ist eine vertraglich vereinbarte, sichere und schnelle Schicht für den Zugriff auf „goldene“ Daten und KPIs. Es garantiert einheitliche Semantik, stabile Versionen, Standard-Datenschutz und Leistung auf Produktebene - von internen Dashboards über Affiliate-Panels bis hin zu ML.