API analitikleri we metrikleri

1) Näme üçin aýratyn gatlak API

KPI üçin bir hakykat: "SQL haýwanat bagyny" aýyrýarys.
Önümiň tizligi: frontlar, hyzmatdaş paneller, ykjam müşderiler DWH-e göni girip bilmän agregatlar alýarlar.
Howpsuzlyk we laýyklyk: tokenizasiýa, maskalar, geo-çäklendirmeler, RG/AML-süzgüçler.
Masştab: nagt, prerenderler, CDN, durnukly şertnamalar.

2) Taksonomiýa: metrikler, ölçegler, faktlar

Faktlar: nyrhlar, ýeňişler, goýumlar, KYC-wakalar, RG-gatyşmalar.
Ölçegler: senesi/wagty (senenamalary), oýun/üpjün ediji, marka/ýurt, kanal/enjam, oýunçy (belgi).
Metrikler: GGR, NGR/NET, ARPPU, D1/D7/D30 saklamak, goýumlaryň ýygylygy, antifrod FPR, RG-töwekgelçiligi.
Birlikler: walýuta (FX), wagt (TZ), göwrüm/hasaplaýjylar (idempotent!).
KPI semantikasy: BI-şertnamalardaky kesgitlemeler, KPI wersiýalary ýazylýar.

3) API şertnamalary (Data & BI Contracts)

Schema: meýdanlar, görnüşler, nullable, enum, birlikler, walýutalar.
Metrikleriň semantikasy: formula, çeşmeler, agregasiýa penjireleri, süzgüçler.
Gabat gelmek (SEMVER): MAJOR döwýär, MINOR meýdanlary goşýar, PATCH düzedýär.
DQ/SLA: täzelik, dolulyk, yzygiderlilik, gapma-garşylyklara ýol bermek.
Gizlilik: 'pii: false', 'tokenized: true', detokenizasiýa gadaganlygy.

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) Binagärlik

Query API ("gold "/kub/fichestoryň üstünde onlaýn agregasiýa).
Precompute API (programma boýunça prerenderler, materialized views).
Events API (akym hasaplaýjylary/signallary).
Export API (gol çekilen düşürmeler, audit üçin WORM).
Kesh: köp gatlakly (in-memory → Redis → CDN), açar = hash soragy + wersiýa.
Utgaşyklyk: soňky ýazgylar üçin read-your-writes, agregatlar üçin tazelik SLA.

5) Interfeýs we haýyşlar

5. 1 Süzgüçler/agregasiýalar/penjireler

'filter': seneler diapazonlary ('from/to' UTC, timezone aware), ýurtlar, markalar, oýunlar, kanallar, enjamlar.
'group _ by': ölçemek.
'metrics': KPI sanawy.
`window`: `DAY|WEEK|MONTH|ROLLING_7D|ROLLING_28D`.
'currency': 'reporting' native ', FX strategiýasy:' eod 'intraday' txn '.
'sampling': heavy-soraglar üçin (diňe mümkin bolan ýerlerde).

5. 2 Soragyň mysaly

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 Jogap mysaly

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) Paginasiýa, çäkler, sortlamak

Paginasiýa: 'limit' (≤ 10k), 'cursor' (opaque), ölçeg/sene boýunça sortlamak.
Timeout/partial: bölekleýin jogaplar diňe maliýe däl KPI üçin; maliýe - ýa-da P200 ýa-da P504.
Rate limits: global/açar boýunça/tenant boýunça; Jogapda 'X-RateLimit-' bar.

7) Idempotentlik we nagt pul

Idempotent GET/POST-read (beden bilen) c 'Idempotency-Key'.
Keş açary = heş (parametrler + shema wersiýasy + rol/tenant/geo).
TTL: KPI-garaşly (mysal üçin, 'PT15M' revenue, 'PT5M' wakalar üçin), täze snapshot wagtynda täzeden başlamak.

8) Yzygiderlilik we wagt walýutasy

Retrospektiv hasabatlar üçin Time-travel baýdagy (maglumatlaryň wersiýasy).
Kut-off düzgünleri (gün/hepdäniň ýapylmagy).
FX: Strategiýany belleýäris, jogap berýäris.
Clock: ähli wagtlar - ISO-8601, TZ görkezmesi hökmanydyr.

9) Howpsuzlyk we gizlinlik

mTLS/TLS1. 3, HMAC-haýyş/jogap jisiminiň goly (MITM/replaydan goramak).
RBAC/ABAC/ReBAC: rol + ýurt + marka + maksat; maskalar.
Köp kärende (multi-tenant): shemalaryň/açarlaryň/kwotalaryň izolýasiýasy.
Kesgitleýjileriň belligi; jogaplarda PII gadaganlygy.
Audit: üýtgemeýän soraglar (WORM), 'trace _ id '/' actor '/' purpose'.
Consent/DSAR: marketing atributlaryna süzgüçler; "subject erased" baýdagy.

10) RG/AML/Antifrod çäklendirmeleri

RG-syýasatlar: ýokary töwekgelçilikli segmentler üçin "agressiw" görkezijileriň berilmegini gadagan etmek; agregatlar howpsuz.
AML/Antifrod: duýgur KPI-e çäkli giriş, rollar boýunça sebitleşdirmek; derňew üçin aýratyn endpointler.
Explainability: KPI düşündiriş sözlügi/sapport üçin signallar.

11) Syn etmek we SLO API

SLO: p95 latency (mysal üçin, keş-hitler üçin 300 ms ≤; agyr hitler üçin 2 ms ≤), success-rate ≥ 99. 5%.
DQ: täzelik/dolulyk/bitewilik; Jogapdaky bellikler.
Ulanyş: QPS, hit-rate kesiş, gyzgyn açarlar, tassyklama ýalňyşlyklary.
Alertler: täzeligiň pese gaçmagy, 4xx/5xx beýikligi, KPI boýunça anomaliýalar (unexpected zeros/peaks).
Tracing: 'trace _ id' DWH/fichestora çenli.

12) Wersiýalaşdyrmak we gabat gelmek

Ýollar: '/v1 ', '/v2'; göçmek penjiresi bolan deprekeýt.
Shemalar: 'schema _ version' jogapda; MAJOR → dual-read, migrasiýa gaýdylary.
KPI-wersiýalary: katalogdaky baglanyşyk bilen 'kpi _ definitions' jogabynda; formulalaryň gizlin üýtgemelerini gadagan etmek.

13) Ýalňyşlyklar we statuslar

'400' tassyklama (ýok metrika/ölçeg/süzgüçleriň utgaşmasy).
'401/403' tassyklamak/ygtyýarlandyrmak.
'409' wersiýalaryň/syýasatlaryň gabat gelmezligi.
'422' Gizlinligiň bozulmagy/consent.
'429' kwotalar.
'5xx' platforma şowsuzlyklary (trace_id we retry-posl.) .

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

14) Integrasiýa we interfeýslar

BI: öňünden beýan edilen semantik modeller, konnektorlar (Looker/Power BI/Tableau) → API çeşme hökmünde.
ML: lightweight endpoints for fich-agregatlar (point-in-time, PII-siz).
Hyzmatdaşlar: çäkli açarlar/kwotalar, geo-süzgüçler, hasabatlar diňe agregat bloklary bilen.
Webhook/Push: "snapshot taýýar", "SLO/KPI aralygy bozuldy" bellikleri.

15) Resurs endpointleriniň mysallary

15. 1 Girdeji/girdeji

'POST/v2/metrics/revenue' → GGR/NGR, nyrhlar/ýeňişler, 'date, brand, country, provider, game' ölçegleri boýunça.

15. 2 Saklamak we huniler

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

15. 3 Tölegler

'POST/v2/metrics/payments' → depozitler/netijeler, ortaça çek, chargeback rate.

15. 4 Responsible Gaming

'POST/v2/metrics/rg' → interwensiýalaryň sany, ýokary töwekgelçiligiň paýy, reaksiýanyň ortaça wagty.

15. 5 Antifrod

'POST/v2/metrics/antifraud' → FPR/TPR, halatlar, ýitgileriň öňüni aldy.

16) Synag we hil

Şertnama synaglary: enum/nullable/görnüşi, walýutalaryň/wagt zolaklarynyň sazlaşygy.
DQ-synaglary: diapazonlara, monotonlyga we bitewilige gözegçilik etmek.
Regress: çydamlylyk boýunça v1/v2 deňeşdirmesi.
Iş ýüki: pik profilleri (ýaryşlar/üpjün ediji wakalary).
Howpsuzlyk: gollar, anti-replay, fuzzing soraglary, loglarda Zero-PII.

17) Gizlinlik

"Iň az N ýazgy" bosagasy bolan agregatlar (k-anonimlik).
Raw identifikatorlary ýok; diňe bellikler/kategoriýalar.
DSAR: artykmaç konturyň üsti bilen belgi boýunça düşürmek/aýyrmak üçin API.

18) Üstünlik metrikleri (KPI API)

Adoption: gönüden-göni SQL däl-de, API ulanýan hasabatlaryň/widjetleriň paýy.
Consistency: BI bilen API arasyndaky tapawut ≤ rugsat.
SLO: latency/success/freshness.
Howpsuzlyk: jogaplarda/bloglarda PII-iň nol halatlary.
Cost: hit-rate kesiş, soragyň bahasy, prerenderleriň%.

19) RACI (mysal)

Product/Analytics (A) - KPI kesgitlemeleri, zerurlyklar.
Data Platform (R) - durmuşa geçirmek, nagt pul, SLA, observability.
Domain Owners (R) - çeşmeler/şertnamalar.
Howpsuzlyk/DPO (A/R) - gizlinlik, elýeterlilik, auditler.
SRE (R) - kwotalar, awtoskeýl, hadysalar.
Maliýe (C) - GGR/NGR/NET maliýe semantikasy.

20) Durmuşa geçirmegiň ýol kartasy

0-30 gün (MVP)

1. 3-5 KPI saýlaň (GGR, goýumlar, D7 saklamak).
2. Şertnamalary we KPI-semantikany beýan etmek; DQ/SLA.
3. '/v1 'Query API + keş + mTLS/HMAC.
4. Daşbordlar SLO (latency/success/freshness), audit/trace _ id.

30-90 gün

1. Meşhur penjireleriň prerenderleri (Precompute), CDN keş.
2. Wersiýalanma '/v2 ', dual-read, migrasiýa gollanmasy.
3. ABI eksporty we WORM.
4. BI/ML bilen integrasiýa; kwotalar/tenantlar/geo-izolýatorlar.

3-6 aý

1. KPI-nyň doly taksonomiýasy we widjet kitaphanasy.
2. Akylly maslahatlar/süzgüçleriň awtokompletleri, soraglaryň linteri.
3. Awtomatiki Release Notes KPI, çydamlylyga gözegçilik v1/v2.
4. Çäkli açarlary we RG syýasatlary bolan daşarky hyzmatdaş kontury.

21) Anti-patternler

Täze wersiýasyz KPI formulasyny gizlin üýtgetmek.
Agregatlaryň/bellikleriň ýerine PII/çig malyň yzyna gaýtarylmagy.
Keshiň/prerenderiň ýoklugy → gymmat we haýal.
Belli bir DB-e berk baglanyşyk (gatlak abstraksiýasy ýok).
Ylalaşylmadyk TZ/FX → deňeşdirip bolmajak sanlar.
rate limits/kwotalar ýok → "DDOS öz".

22) Şablonlar (ulanmaga taýýar)

22. 1 SLO API syýasaty (bölek)

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 (bölek)

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 Goýberilişiň çek-sanawy

• KPI semantikasy täzelendi we wersiýasy täzelendi
• Katalogdaky şertnama/shema; DQ/regress synaglary ýaşyl
• Nagt açarlar/TTL, prerenderler sazlandy
• Resminamalar we haýyşlaryň/jogaplaryň mysallary
• SLO we kwotalar boýunça aladalar girizildi
• RG/AML çäklendirmeleri barlandy

23) Baglanyşykly bölümler

DataOps-practices, Audit we wersiýa, Howpsuzlyk we şifrlemek, Giriş gözegçiligi, Maglumatlary bellemek, Saklaýyş syýasaty, Maglumatlaryň gelip çykyşy we ýoly, MLOps: modelleri ulanmak, Maglumatlaryň etikasy.

Jemi

Analitikleriň we metrikleriň API-leri "altyn" maglumatlara we KPI-e girmegiň şertnama baglaşylan, ygtybarly we çalt gatlagy. Içerki dashbordlardan başlap, hyzmatdaş panellere we ML-e çenli önüm derejesinde ýeke-täk semantikany, durnukly wersiýalary, gizlinligi we öndürijiligi kepillendirýär.