API analitika va metrika

1) Nima uchun alohida API qatlami

KPI uchun yagona haqiqat: «SQL hayvonot bog’i» ni istisno qilamiz.
Mahsulot tezligi: frontlar, hamkor panellar, mobil mijozlar DWHdan toʻgʻridan-toʻgʻri foydalanmasdan agregatlar oladi.
Xavfsizlik va komplayens: tokenizatsiya, niqoblar, geo-cheklovlar, RG/AML-filtrlar.
Kattalashtirish: kesh, prerenderlar, CDN, barqaror shartnomalar.

2) Taksonomiya: metriklar, o’lchovlar, faktlar

Faktlar: stavkalar, yutuqlar, depozitlar, KYC-hodisalar, RG-intervensiyalar.
O’lchovlar: sana/vaqt (taqvim), o’yin/provayder, brend/mamlakat, kanal/qurilma, o’yinchi (token).
Metriklar: GGR, NGR/NET, ARPPU, D1/D7/D30 ushlab qolish, depozitlar chastotasi, FPR antifrod, RG-xavf.
Birliklar: valyuta (FX), vaqt (TZ), hajm/hisoblagichlar (idempotent!).
KPI semantikasi: BI-kontraktlardagi ta’riflar, KPI versiyalari qayd etiladi.

3) API kontraktlari (Data & BI Contracts)

Schema: maydonlar, turlar, nullable, enum, birliklar, valyutalar.
Metriklarning semantikasi: formula, manbalar, agregatsiya oynalari, filtrlar.
Moslik (SEMVER): MAJOR sinadi, MINOR maydonlarni qoʻshadi, PATCH fiksit.
DQ/SLA: tazelik, to’liqlik, konsistentlik, tafovutlarga yo’l qo’yish.
Maxfiylik:’pii: false’,’tokenized: true’, detokenizatsiyani taqiqlash.

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

Query API («gold «/kub/fichestor ustidan onlayn agregatsiyalar).
Precompute API (jadval bo’yicha prerenderlar, materialized views).
Events API (oqimli hisoblagichlar/signallar).
Export API (imzolangan yuklamalar, audit uchun WORM).
Kesh: koʻp qatlamli (in-memory → Redis → CDN), kalit = xesh soʻrov + versiya.
Muvofiqlik: yakuniy yozuvlar uchun read-your-writes, agregatlar uchun yangi SLA.

5) Interfeys va so’rovlar

5. 1 Filterlar/agregatsiyalar/derazalar

’filter’: sana diapazonlari (’from/to’UTC, timezone aware), mamlakatlar, brendlar, o’yinlar, kanallar, qurilmalar.
’group _ by’: oʻlchash.
’metrics’: KPI roʻyxati.
`window`: `DAY|WEEK|MONTH|ROLLING_7D|ROLLING_28D`.
’currency’:’reporting’native’, FX strategiyasi:’eod’intraday’txn’.
’sampling’: heavy-soʻrovlar uchun (faqat mumkin boʻlgan joyda).

5. 2 So’rov misoli

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 Javob misoli

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) Paginatsiya, limitlar, saralash

Paginatsiya:’limit’(≤ 10k),’cursor’(opaque), o’lchov/sana bo’yicha saralash.
Timeout/partial: qisman javoblar faqat moliyaviy bo’lmagan KPI uchun; moliya - P200 yoki P504.
Rate limits: global/kalit boʻyicha/tenant boʻyicha; javobda’X-RateLimit-’mavjud.

7) Idempotentlik va kesh

Idempotent GET/POST-read (tana bilan) s’Idempotency-Key’.
Kesh-kalit = xash (parametrlar + sxema versiyasi + rol/tenant/geo).
TTL: KPI-bog’liq (masalan, revenue uchun’PT15M’, voqealar uchun’PT5M’), yangi snapshot paytida qayta tiklash.

8) Konsistentlik va vaqt valyutasi

Time-travel bayrog’i retrospektiv hisobotlar uchun (ma’lumotlar versiyasi).
Cut-off qoidalari (kun/haftaning yopilishi).
FX: Strategiyani, kurs sanasini javobda qayd etamiz.
Clock: barcha taymstemplar ISO-8601, TZ koʻrsatilishi shart.

9) Xavfsizlik va maxfiylik

mTLS/TLS1. 3. So’rov/javob tanasining HMAC-imzosi (MITM/replay himoyasi).
RBAC/ABAC/ReBAC: rol + mamlakat + brend + maqsad; Andoza niqoblar.
Ko’p ijara (multi-tenant): sxemalar/kalitlar/kvotalarni izolyatsiya qilish.
Identifikatorlarni tokenlashtirish; javoblarda PII taqiqlash.
Audit: oʻzgarmas soʻrovlar (WORM),’trace _ id ’/’ actor ’/’ purpose’.
Consent/DSAR: marketing atributlariga filtrlar; «subject erased» bayrog’i.

10) RG/AML/Antifrod cheklovlar

RG-siyosati: high-risk segmentlari uchun «tajovuzkor» ko’rsatkichlarni berishni taqiqlash; agregatlar xavfsiz.
AML/Antifrod: sezgir KPIdan cheklangan foydalanish, rollar bo’yicha zonalash; tekshirishlar uchun alohida endpointlar.
Explainability: sapport uchun KPI/signallarni tushuntirish lug’ati.

11) Kuzatuv va SLO API

SLO: p95 latency (masalan, ≤ 300 ms kesh-xit uchun; ≤ 2 s og’ir xit uchun), success-rate ≥ 99. 5%.
DQ: yangilik/to’liqlik/yaxlitlik; javobdagi belgilar.
Usage: QPS, hit-rate kesh, issiq kalitlar, validatsiya xatolari.
Alertlar: yangilik degradatsiyasi, bo’yi 4xx/5xx, KPI bo’yicha anomaliyalar (unexpected zeros/peaks).
Tracing:’trace _ id’DWH/fichestorgacha.

12) Versiyalash va muvofiqlik

Yo’llar: ’/v1’, ’/v2’; migratsiya oynasi bo’lgan deprekeyt.
Sxemalar: javobda’schema _ version’; MAJOR → dual-o’qish, migratsiya gaydalari.
KPI-versiyasi: «kpi _ definitions» javobida katalogdagi havola bilan; formulalarning yashirin o’zgarishlarini taqiqlash.

13) Xatolar va maqomlar

’400’ validatsiya (mavjud bo’lmagan metrika/o’lchov/filtrlar kombinatsiyasi).
’401/403’ autentifikatsiya/avtorizatsiya.
’409’ versiyalar/siyosatlarning nomuvofiqligi.
’422’ maxfiylikni buzish/consent.
’429’ kvotalar.
’5xx’ platforma uzilishlari (trace_id va retry-posl bilan) .

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

14) Integratsiya va interfeyslar

BI: oldindan tavsiflangan semantik modellar, konnektorlar (Looker/Power BI/Tableau) → manba sifatida API.
ML: lightweight endpoints fich-agregatlar uchun (point-in-time, PIIsiz).
Hamkorlar: cheklangan kalitlar/kvotalar, geo-filtrlar, hisobotlar faqat agregat bloklari bilan.
Webhook/Push: «snapshot tayyor», «SLO/KPI diapazoni buzilgan» notifikatsiyalari.

15) Resurs endpointlari namunalari

15. 1 Tushum/daromadlilik

’POST/v2/metrics/revenue’ → GGR/NGR, stavkalar/yutuqlar, o’lchovlar bo’yicha’date, brand, country, provider, game’.

15. 2 Ushlab turish va huni

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

15. 3 To’lovlar

’POST/v2/metrics/payments’ → depozitlar/xulosalar, o’rtacha chek, chargeback rate.

15. 4 Responsible Gaming

’POST/v2/metrics/rg’ → intervensiyalar soni, high-risk ulushi, o’rtacha reaktsiya vaqti.

15. 5 Antifrod

’POST/v2/metrics/antifraud’ → FPR/TPR, keyslar, bartaraf etilgan yo’qotishlar.

16) Test sinovi va sifat

Kontrakt testlari: enum/nullable/turi, valyuta/soat mintaqalarining muvofiqligi.
DQ-testlar: diapazonlar, monotonlik va yaxlitlikni nazorat qilish.
Regress: tolerans bo’yicha v1/v2 taqqoslash.
Yuklama: cho’qqilar profillari (turnirlar/provayder tadbirlari).
Xavfsizlik: imzolar, anti-replay, fuzzing so’rovlar, loglarda Zero-PII.

17) Andoza maxfiylik

«Minimal N yozuvlar» ostonali agregatlar (k-anonimlik).
Hech qanday raw identifikatorlari mavjud emas; faqat tokenlar/toifalar.
DSAR: imtiyozli kontur orqali tokenni tushirish/olib tashlash uchun API.

18) Muvaffaqiyat metrikasi (KPI API)

Adoption: toʻgʻridan-toʻgʻri SQL emas, balki APIdan foydalanuvchi hisobotlar/vidjetlar ulushi.
Consistency: BI va API ≤ ruxsatnomalar o’rtasidagi tafovut.
SLO: latency/success/freshness.
Security: javoblardagi nol PII holatlari.
Cost: hit-rate kesh, soʻrov qiymati, prerenderlar%.

19) RACI (misol)

Product/Analytics (A) - KPI, ehtiyojlarni aniqlash.
Data Platform (R) - amalga oshirish, kesh, SLA, observability.
Domain Owners (R) - manbalar/shartnomalar.
Security/DPO (A/R) - maxfiylik, kirish, auditlar.
SRE (R) - kvotalar, avtoskeyl, hodisalar.
Finance (C) - GGR/NGR/NET moliyaviy semantikasi.

20) Joriy etish yo’l xaritasi

0-30 kun (MVP)

1. 3-5 KPI tanlang (GGR, depozitlar, D7 ushlab qolish).
2. Kontraktlar va KPI-semantikani tavsiflash; DQ/SLA kiritiladi.
3. ’/v1’Query API + kesh + mTLS/HMAC amalga oshirish.
4. Dashbordlar SLO (latency/success/freshness), audit/trace _ id.

30-90 kun

1. Prerenderlar (Precompute) mashhur vitrinalar, CDN kesh.
2. Version ’/v2’, dual-o’qish, migratsiya g’oyasi.
3. Imzolangan yuklar va WORM bilan API eksport qilish.
4. BI/ML bilan integratsiyalash; kvotalar/tenantlar/geo-izolyatorlar.

3-6 oy

1. KPIning toʻliq taksonomiyasi va vidjetlar kutubxonasi.
2. Aqlli maslahatlar/avtokompletlar, so’rovlar linteri.
3. Avtomatik Release Notes KPI, toleranslarni nazorat qilish v1/v2.
4. Cheklangan kalitlar va RG siyosati bilan tashqi sheriklik konturi.

21) Anti-patternlar

Yangi versiyasiz KPI formulasini yashirin oʻzgartirish va not chiqarish.
Agregatlar/tokenlar o’rniga PII/xomashyoni qaytarish.
Kesh/prerenderlarning yo’qligi → qimmat va sekin.
Muayyan DBga qattiq bogʻlash (qatlamning mavhumligi yoʻq).
Kelishilmagan TZ/FX → taqqoslanmaydigan raqamlar.
rate limits/kvota yo’q → «DDOS o’z».

22) Shablonlar (foydalanishga tayyor)

22. 1 SLO API siyosati (parcha)

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

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 Reliz chek-varaqasi

• KPI semantikasi yangilandi va versiyasi oshirildi
• Katalogdagi kontrakt/sxema; DQ/regress yashil testlar
• Kesh/TTL, prerenderlar sozlandi
• Hujjatlar va so’rovlar/javoblar namunalari
• SLO va kvotalar bo’yicha alertlar kiritilgan
• RG/AML cheklovlari tekshirildi

23) Bog’liq bo’limlar

DataOps-amaliyotlar, Audit va versiya, Xavfsizlik va shifrlash, Kirish nazorati, Ma’lumotlarni tokenlashtirish, Saqlash siyosati, Ma’lumotlarning kelib chiqishi va yo’li, MLOps: modellardan foydalanish, Ma’lumotlar etikasi.

Jami

Tahlillar va metriklarning API - bu «oltin» ma’lumotlar va KPIlarga kirishning kontraktlangan, xavfsiz va tezkor qatlami. U yagona semantika, barqaror versiyalar, maxfiylik va mahsulot darajasidagi samaradorlikni kafolatlaydi - ichki dashbordlardan tortib, sherik panellari va MLgacha.