Analityka i metryka API

1) Dlaczego oddzielna warstwa API

Pojedyncza prawda dla KPI: wykluczyć "zoo SQL'.
Szybkość produktu: fronty, panele partnerskie, klienci mobilni otrzymują agregaty bez bezpośredniego dostępu do DWH.
Bezpieczeństwo i zgodność: tokenizacja, maski, ograniczenia geograficzne, filtry RG/AML.
Skalowanie: cache, prerenders, CDN, stabilne kontrakty.

2) Taksonomia: metryki, wymiary, fakty

Fakty: zakłady, wygrane, depozyty, wydarzenia KYC, interwencje RG.
Wymiary: data/godzina (kalendarze), gra/dostawca, marka/kraj, kanał/urządzenie, gracz (token).
Wskaźniki: GGR, NGR/NET, ARPPU, zatrzymywanie D1/D7/D30, częstotliwość wpłat, zwalczanie oszustw FPR, ryzyko RG.
Jednostki: waluta (FX), czas (TZ), objętość/liczniki (idempotent!).
Semantyka KPI: definicje w umowach BI, wersje KPI są stałe.

3) Dane i umowy BI

Schemat: pola, typy, nieważne, enum, jednostki, waluty.
Semantyka metryki: wzór, źródła, okna agregacyjne, filtry.
Kompatybilność (SEMVER): GŁÓWNE przerwy, MINOR dodaje pola, poprawki PATCH.
DQ/SLA: świeżość, kompletność, spójność, tolerancje rozbieżności.
Prywatność: 'pii: false', 'tokenized: true', zakaz detokenizacji.

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) Architektura

Zapytanie API (agregacja online na „złoto „/kostki/fichestore).
Precompute API (zaplanowane prerendery, zmaterializowane widoki).
Zdarzenia API (liczniki/sygnały strumieniowe).
Eksportuj API (podpisane przesyłki, WORM do audytu).
Cache: in-memory → Redis → CDN, key = query hash + version.
Spójność: czytaj-swoje pisma do nagrań końcowych, świeżość SLA dla agregatów.

5) Interfejs i żądania

5. 1 Filtry/agregacje/okna

„filter”: zakresy dat (od/do 'UTC, świadomość timezonu), kraje, marki, gry, kanały, urządzenia.
„group _ by”: wymiary.
„dane liczbowe”: wykaz KPI.
"window": "DAY 'WEEK' MONTH 'ROLLING _ 7D' ROLLING _ 28D'.
"wystąpienie": "sprawozdawczość 'native', strategia FX: 'eod' intraday 'txn'.
„sampling”: dla ciężkich zapytań (tylko tam, gdzie jest to dozwolone).

5. 2 Przykład żądania

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 Przykład odpowiedzi

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) Paginacja, granice, sortowanie

Paginacja: 'limit' (≤ 10k), 'cursor' (nieprzezroczysty), sortowanie według wymiarów/daty.
Timeout/partial: częściowe odpowiedzi tylko na niefinansowe KPI; finanse - P200 lub P504.
Limity stawek: globalne/według kluczy/według najemcy; odpowiedź zawiera 'X- Limit-'.

7) Idempotencja i pamięć podręczna

Idempotent GET/POST-read (z ciałem) z 'Idempotence-Key'.
Klucz pamięci podręcznej = hash (parametry + wersja schematu + rola/lokator/geo).
TTL: zależne od KPI (np. „PT15M” dla przychodów, „PT5M” dla wydarzeń), zresetować za pomocą nowego migawki.

8) Spójność i waluta czasu

Flaga podróży w czasie dla raportów retrospektywnych (wersje danych).
Zasady odcięcia (dzień/tydzień zamknięcia).
FX: ustalamy strategię, datę kursu w odpowiedzi.
Zegar: wszystkie znaczniki czasowe są ISO-8601, TZ jest wymagane.

9) Bezpieczeństwo i prywatność

mTLS/TLS1. 3, podpis HMAC organu żądania/odpowiedzi (ochrona MITM/powtórka).
RBAC/ABAC/ReBAC: rola + kraj + marka + cel; domyślne maski.
Multi-najemca - schematy/klucze/kwoty izolowane.
tokenizacja identyfikatorów; Zakaz PII w odpowiedziach.
Audyt: niezmienne dzienniki żądań (WORM), "trace _ id'/" actor "/" purpose".
Zgoda/DSAR: filtry dotyczące atrybutów marketingowych; flaga „przedmiot wymazany”.

10) RG/AML/Środek ograniczający

Polityka RG: zakaz wydawania „agresywnych” wskaźników dla segmentów wysokiego ryzyka; Jednostki są bezpieczne.
AML/Antifraud: ograniczony dostęp do wrażliwych KPI, zagospodarowanie przestrzenne według roli; oddzielne punkty końcowe dla dochodzeń.
Możliwość wyjaśnienia: słownik wyjaśnień KPI/sygnałów do obsługi.

11) Obserwowalność i SLO API

SLO: opóźnienie p95 (na przykład ≤ 300 ms dla trafień w pamięci podręcznej, ≤ 2 s dla ciężkich), szybkość sukcesu ≥ 99. 5%.
DQ: świeżość/kompletność/integralność; etykiety w odpowiedzi.
Użycie: QPS, cache hit-rate, hot keys, błędy walidacji.
Wpisy: degradacja świeżości, wzrost 4xx/5xx, anomalie zgodnie z KPI (nieoczekiwane zera/piki).
Odwzorowanie: 'trace _ id' end-to-end to DWH/fichestore.

12) Wersioning i kompatybilność

Ścieżki: '/v1 ', '/v2'; zdemontować za pomocą okna migracji.
Schematy: „schema _ version” w odpowiedzi; MAJOR → podwójny odczyt, przewodniki migracyjne.
Wersje KPI: w odpowiedzi 'kpi _ definitions' z linkiem w katalogu; Zapobiegaj ukrytym zmianom formuły.

13) Błędy i statusy

„400” walidacja (nieistniejąca kombinacja metryczna/pomiarowa/filtracyjna).
"401/403informacja/autoryzacja.
„49” Weryfikacja/niezgodność z polityką.
"422privacy/łamanie zgody.
"429kwota.
"5xx 'platform failures (trace_id i retry seq.).

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

14) Integracje i interfejsy

BI: wstępnie opisane modele semantyczne, złącza (Looker/Power BI/Tableau) → API jako źródło.
ML: lekkie punkty końcowe dla jednostek charakterystycznych (punkt w czasie, bez PII).
Partnerzy: ograniczone klucze/kwoty, filtry geograficzne, raporty tylko w blokach zbiorczych.
Webhook/Push: powiadomienia „migawka gotowa”, „złamany zakres SLO/KPI”.

15) Przykłady punktów końcowych zasobów

15. 1 Dochody/zwroty

„POST/v2/metrics/revenue” → GGR/NGR, zakłady/wygrane, mierzone przez „data, marka, kraj, dostawca, gra”.

15. 2 Zatrzymywanie i lejki

„POST/v2/metrics/retention” → коворта D1/D7/D30, „group _ by = [cohort _ week, brand, country]”.

15. 3 Płatności

„POST/v2/metrics/payments” → depozyty/wypłaty, średnia kontrola, stawka obciążenia zwrotnego.

15. 4 Odpowiedzialne gry

„POST/v2/metrics/rg” → liczba interwencji, odsetek wysokiego ryzyka, średni czas reakcji.

15. 5 Antyfraud

„POST/v2/metrics/antifraud” → FPR/TPR, przypadki, straty zapobiegane.

16) Testowanie i jakość

Testy kontraktowe: enum/nullable/type, currency/time zone consistency.
Testy DQ: kontrola zakresów, monotonii i integralności.
Regresja: porównanie v1/v2 w zakresie tolerancji.
Obciążenie: profile szczytowe (turnieje/imprezy dostawców).
Bezpieczeństwo: podpisy, anty-replay, żądania zamrażania, Zero-PII w dziennikach.

17) Domyślna prywatność

Agregaty o progach „minimalnych zapisów N” (k-anonimowość).
Brak identyfikatorów surowych; tylko żetony/kategorie.
DSAR: API do rozładunku/usuwania przez token przez uprzywilejowaną pętlę.

18) Wskaźniki sukcesu (API KPI)

Przyjęcie: Odsetek raportów/widżetów z wykorzystaniem API zamiast bezpośredniego SQL.
Spójność - rozbieżność między BI a tolerancją ≤ API.
SLO: zgodność z opóźnieniem/sukcesem/świeżością.
Bezpieczeństwo: zero przypadków PII w odpowiedziach/dziennikach.
Koszt: szybkość trafienia pamięci podręcznej, koszt żądania,% prerenderów.

19) RACI (przykład)

Produkt/Analityka (A) - definicje KPI, wymagania.
Platforma danych (R) - wdrożenie, pamięć podręczna, SLA, obserwowalność.
Właściciele domen (R) - Źródła/Umowy.
Bezpieczeństwo/DPO (A/R) - prywatność, dostęp, audyty.
SRE (R) - kwoty, autoskale, incydenty.
Finanse (C) to semantyka finansowa GGR/NGR/NET.

20) Plan działania w zakresie wdrażania

0-30 dni (MVP)

1. Wybierz 3-5 KPI (GGR, depozyty, retencja D7).
2. Opis umów i semantyki KPI; Włącz DQ/SLA.
3. Implementacja '/v1 'Zapytanie API + cache + mTLS/HMAC.
4. Deski rozdzielcze SLO (opóźnienie/sukces/świeżość), audyt/trace _ id.

30-90 dni

1. Prekomputerowe popularne sklepy, pamięć podręczna CDN.
2. Wersioning '/v2 ', dwuliterowy, przewodnik migracji.
3. Eksportuj interfejsy API z podpisanymi przesyłkami i WORMami.
4. Integracja z BI/ML; kwoty/najemcy/geosiatki.

3-6 miesięcy

1. Ukończ taksonomię KPI i bibliotekę widżetów.
2. Inteligentne porady/filtry autokompletne, linter zapytania.
3. Automatic Release Notes KPI, kontrola tolerancji v1/v2.
4. Zewnętrzna pętla partnerska z ograniczonymi kluczami i polityką RG.

21) Anty-wzory

Ukryta zmiana formuły KPI bez nowej wersji i notatek.
Zwrot PII/surowce zamiast kruszyw/żetonów.
Brak pamięci podręcznej/prerenderów → drogie i powolne.
Twarde powiązanie z konkretną bazą danych (brak abstrakcji warstwy).
Niespójne TZ/FX → liczby rozbieżne.
Brak limitów/kwot → „własny DDOS”.

22) Szablony (gotowe do użycia)

22. 1 SLO Polityka API (snippet)

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 (snippet)

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 Lista kontrolna wydania

• Semantyka KPI zaktualizowana i uaktualniona
• Umowa/schemat w katalogu; Testy DQ/regresji zielony
• Klucze pamięci podręcznej/TTL, konfigurowane prerendery
• Dokumentacja i przykładowe wnioski/odpowiedzi
• Uwzględniono wpisy SLO i kwot
• Testowane ograniczenia RG/AML

23) Sekcje powiązane

Praktyki, audyt i weryfikacja, bezpieczeństwo i szyfrowanie, kontrola dostępu, tokenizacja danych, polityka retencji, pochodzenie i ścieżka danych, MLOp: eksploatacja modeli, etyka danych.

Razem

API analityczne i metryczne to zakontraktowana, bezpieczna i szybka warstwa dostępu do danych złota i KPI. Gwarantuje jednolitą semantykę, stabilne wersje, domyślną prywatność i wydajność na poziomie produktu - od wewnętrznych desek rozdzielczych po panele partnerskie i ML.