API analitiklər və metriklər
1) Niyə ayrı bir API təbəqəsi
KPI üçün vahid həqiqət: «SQL zoopark» istisna.
Məhsul sürəti: ön tərəflər, tərəfdaş panellər, mobil müştərilər DWH birbaşa giriş olmadan aqreqatlar almaq.
Təhlükəsizlik və uyğunluq: tokenizasiya, maskalar, geo məhdudiyyətlər, RG/AML filtrləri.
Ölçmə: cache, prerenders, CDN, sabit müqavilələr.
2) Taksonomiya: metriklər, ölçmələr, faktlar
Faktlar: dərəcələr, uduşlar, depozitlər, KYC hadisələri, RG müdaxilələri.
Ölçülər: tarix/vaxt (təqvimlər), oyun/provayder, marka/ölkə, kanal/cihaz, oyunçu (token).
Metriklər: GGR, NGR/NET, ARPPU, D1/D7/D30 saxlama, depozit tezliyi, FPR antifrod, RG riski.
Vahidlər: valyuta (FX), vaxt (TZ), həcm/sayğaclar (idempotent!).
KPI semantikası: BI müqavilələrindəki təriflər, KPI versiyaları qeydə alınır.
3) API müqavilələri (Data & BI Contracts)
Schema: sahələr, növləri, nullable, enum, vahidlər, valyutalar.
Metrik semantika: formula, mənbələr, aqreqasiya pəncərələri, filtrlər.
Uyğunluq (SEMVER): MAJOR qırır, MINOR sahələr əlavə edir, PATCH sabit.
DQ/SLA: təzəlik, dolğunluq, tutarlılıq, uyğunsuzluq tolerantları.
Gizlilik: 'pii: false', 'tokenized: true', detokenizasiya qadağası.
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) Memarlıq
Query API («gold «/kub/fichestor üzərində onlayn aqreqasiya).
Precompute API (prerenderlər, materialized views).
Events API (axın sayğacları/siqnalları).
Export API (imzalanmış boşaltmalar, audit üçün WORM).
Cache: çox qatlı (in-memory → Redis → CDN), açar = hash sorğu + versiyası.
Uyğunluq: son qeydlər üçün read-your-writes, aqreqatlar üçün SLA təravət.
5) Interface və sorğular
5. 1 Filtrlər/aqreqasiya/pəncərə
'filter': tarix diapazonları ('from/to' UTC, timezone aware), ölkələr, markalar, oyunlar, kanallar, cihazlar.
'group _ by': ölçmə.
'metrics': KPI siyahısı.
`window`: `DAY|WEEK|MONTH|ROLLING_7D|ROLLING_28D`.
'currency': 'reporting' native ', FX strategiyası:' eod 'intraday' txn '.
'sampling': heavy-sorğular üçün (yalnız icazə verilən yerlərdə).
5. 2 Sorğu nümunəsi
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 Cavab nümunəsi
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) Paginasiya, limitlər, çeşidləmə
Paginasiya: 'limit' (≤ 10k), 'cursor' (opaque), ölçmə/tarix üzrə çeşidləmə.
Timeout/partial: qismən cavablar yalnız qeyri-maliyyə KPI üçün; maliyyə - ya P200, ya da P504.
Rate limits: qlobal/açar/tenant; cavabda 'X-RateLimit-' var.
7) İdempotentlik və cache
Idempotent GET/POST-read (bədən ilə) ilə 'Idempotency-Key'.
Cash açarı = hash (parametrlər + sxem versiyası + rol/tenant/geo).
TTL: KPI-asılı (məsələn, revenue üçün 'PT15M', hadisələr üçün 'PT5M'), yeni snapshot ilə sıfırlama.
8) Konsistentlik və vaxt valyutası
retrospektiv hesabatlar üçün Time-travel bayrağı (məlumat versiyası).
Cut-off qaydaları (gün/həftənin bağlanması).
FX: Strategiyanı, kurs tarixini cavablandırırıq.
Clock: Bütün vaxt tamponları ISO-8601, TZ göstərişi tələb olunur.
9) Təhlükəsizlik və məxfilik
mTLS/TLS1. 3, HMAC-imza sorğu/cavab bədən (MITM/replay qarşı müdafiə).
RBAC/ABAC/ReBAC: rol + ölkə + marka + hədəf; maskalar default.
Multi-tenant (multi-tenant): sxemlərin/açarların/kvotaların izolyasiyası.
Identifikatorların tokenizasiyası; cavablarda PII qadağası.
Audit: dəyişməz sorğu qeydləri (WORM), 'trace _ id '/' actor '/' purpose'.
Consent/DSAR: marketinq atributlarına filtrlər; «subject erased» bayrağı.
10) RG/AML/Antifrod məhdudiyyətləri
RG siyasəti: yüksək riskli seqmentlər üçün «aqressiv» göstəricilərin verilməsinin qadağan edilməsi; aqreqatlar təhlükəsizdir.
AML/Antifrod: həssas KPI-yə məhdud giriş, rolların rayonlaşdırılması; araşdırmalar üçün ayrı-ayrı end nöqtələri.
Explainability: KPI izahat lüğəti/sapport üçün siqnallar.
11) Müşahidə və SLO API
SLO: p95 latency (məsələn, cash hitlər üçün 300 ms ≤; ağır ≤ üçün 2 ms), success-rate ≥ 99. 5%.
DQ: təzəlik/tamlıq/bütövlük; cavabında işarələr.
Usage: QPS, hit-rate cache, qaynar açarlar, validasiya səhvləri.
Alertlər: təzəlik deqradasiyası, böyümə 4xx/5xx, KPI anomaliyaları (unexpected zeros/peaks).
Tracing: 'trace _ id' DWH/fichestor keçir.
12) Version və uyğunluq
Yollar: '/v1 ', '/v2'; miqrasiya pəncərəsi ilə deprekeyt.
Sxemlər: cavabda 'schema _ version'; MAJOR → dual-read, miqrasiya qaydaları.
KPI versiyası: kataloqdakı linklə 'kpi _ definitions' cavabında; gizli düstur dəyişikliklərinin qadağan edilməsi.
13) Səhvlər və statuslar
'400' validasiya (mövcud olmayan metrika/ölçmə/filtr kombinasiyası).
'401/403' autentifikasiya/avtorizasiya.
'409' versiyaların/siyasətlərin uyğunsuzluğu.
'422' məxfilik pozuntusu/consent.
'429' kvotalar.
'5xx' platforma uğursuzluqları (trace_id və retry-nl ilə) .
json
{
"error":"VALIDATION_FAILED",
"message":"Unknown metric: ngrx",
"hint":"metrics allowed: ggr, net_revenue,...",
"trace_id":"..."
}14) Inteqrasiya və interfeys
BI: əvvəlcədən təsvir semantic modellər, bağlayıcılar (Looker/Power BI/Tableau) → mənbə kimi API.
ML: Fich aqreqatları üçün lightweight endpoints (point-in-time, PII olmadan).
Tərəfdaşlar: məhdud açarlar/kvotalar, geo-filtrlər, hesabatlar yalnız aqreqat blokları ilə.
Webhook/Push: «snapshot hazır», «SLO/KPI diapazonu pozuldu» notifikasiyaları.
15) Resurs end nöqtələrinin nümunələri
15. 1 Gəlir/gəlir
'POST/v2/metrics/revenue' → GGR/NGR, bahislər/qazanclar, 'date, brand, country, provider, game' ölçmələrinə görə.
15. 2 Saxlama və huni
`POST /v2/metrics/retention` → когорты D1/D7/D30, `group_by=[cohort_week, brand, country]`.
15. 3 Ödənişlər
'POST/v2/metrics/payments' → depozitlər/nəticələr, orta çek, chargeback rate.
15. 4 Responsible Gaming
'POST/v2/metrics/rg' → müdaxilələrin sayı, yüksək risk payı, orta reaksiya vaxtı.
15. 5 Antifrod
'POST/v2/metrics/antifraud' → FPR/TPR, hallar, itkilərin qarşısı alınıb.
16) Test və keyfiyyət
Müqavilə testləri: enum/nullable/növü, valyuta/saat kəmərlərinin uyğunluğu.
DQ testləri: diapazon, monotonluq və bütövlük nəzarəti.
Reqress: tolerans üzrə v1/v2 müqayisə.
Yükləmə: pik profillər (turnirlər/provayder tədbirləri).
Təhlükəsizlik: imzalar, anti-replay, fuzzing sorğular, log Zero-PII.
17) Privacy default
«Minimum N qeydlər» (k-anonimlik) həddi olan aqreqatlar.
Heç bir raw identifikatorları; yalnız tokenlər/kateqoriyalar.
DSAR: imtiyazlı konturdan tokenlə boşaltmaq/çıxarmaq üçün API.
18) Uğur metrikası (KPI API)
Adoption: birbaşa SQL deyil, API istifadə hesabat/widget payı.
Consistency: BI və API ≤ tolerantlar arasında uyğunsuzluq.
SLO: latency/success/freshness riayət.
Security: cavablarda/loqlarda sıfır PII halları.
Cost: hit-rate cache, sorğu dəyəri,% prerender.
19) RACI (nümunə)
Product/Analytics (A) - KPI tərifləri, ehtiyaclar.
Data Platform (R) - realizasiya, cache, SLA, observability.
Domain Owners (R) - mənbələr/müqavilələr.
Security/DPO (A/R) - gizlilik, giriş, audit.
SRE (R) - kvotalar, avtoskeyl, insidentlər.
Finance (C) - GGR/NGR/NET maliyyə semantikası.
20) Tətbiqi yol xəritəsi
0-30 gün (MVP)
1. 3-5 KPI seçin (GGR, depozitlər, D7 saxlama).
2. Müqavilələri və KPI semantikasını təsvir edin; DQ/SLA daxil edin.
3. Həyata '/v1 'Query API + cache + mTLS/HMAC.
4. Dashbord SLO (latency/success/freshness), audit/trace _ id.
30-90 gün
1. Prerenders (Precompute) məşhur vitrinlər, CDN cache.
2. Version '/v2 ', dual-read, miqrasiya bələdçisi.
3. İmzalı boşaltmalar və WORM ilə API ixracı.
4. BI/ML ilə inteqrasiya; kvotalar/tenantlar/geo-izolyatorlar.
3-6 ay
1. Tam KPI taksonomiyası və widget kitabxanası.
2. Smart İpuçları/Avtomatik Kompüter Filter, Linter Sorğu.
3. Avtomatik Release Notes KPI, tolerans nəzarəti v1/v2.
4. Məhdud açarlar və RG siyasətçiləri ilə xarici tərəfdaşlıq konturu.
21) Anti-nümunələr
Yeni versiya və buraxılış notları olmadan gizli KPI düsturu dəyişikliyi.
aqreqatlar/tokenlər əvəzinə PII/xammal qaytarılması.
Cache/Prerender → yoxdur bahalı və yavaş.
Spesifik DB-yə sərt bağlama (təbəqənin abstraksiyası yoxdur).
Razılaşdırılmamış TZ/FX → müqayisə olunmayan rəqəmlər.
No rate limits/kvota → «DDOS öz».
22) Şablonlar (istifadəyə hazır)
22. 1 SLO API siyasəti (fraqment)
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: false22. 2 OpenAPI (fraqment)
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 Buraxılış çek siyahısı
- KPI semantikası yeniləndi və versiyası artırıldı
- Kataloqdakı müqavilə/sxem; DQ/regress yaşıl testlər
- Cache açarları/TTL, Prirenders xüsusi
- Sənədləşmə və sorğu/cavab nümunələri
- SLO və kvotalar üzrə alertlər daxildir
- RG/AML məhdudiyyətləri yoxlanılır
23) Əlaqəli bölmələr
DataOps-Practices, Audit və Version, Təhlükəsizlik və Şifrələmə, Access Control, Data Tokenization, Saxlama Siyasəti, Verilənlərin mənşəyi və yolu, MLOps: Modellərin istismarı, Verilənlərin etikası.
Yekun
API analitiklər və metriklər «qızıl» məlumatlara və KPI-yə müqaviləli, təhlükəsiz və sürətli giriş qatıdır. Bu vahid semantika, sabit versiyalar, privacy və məhsul səviyyəsində performans təmin edir - daxili dashboard partnyor panelləri və ML.