API аналитика жана метрика
1) Эмне үчүн өзүнчө API катмары
KPI үчүн бир чындык: "SQL зоопарк".
Продукт ылдамдыгы: Frontes, өнөктөш панелдер, мобилдик кардарлар DWH түздөн-түз жетүү жок агрегаттарды алуу.
Коопсуздук жана комплаенс: токенизация, маскалар, гео-чектөөлөр, RG/AML чыпкалар.
Масштабдоо: кэш, prerenders, CDN, туруктуу келишимдер.
2) Таксономия: метрика, өлчөө, фактылар
Фактылар: коюмдар, утуштар, депозиттер, KYC-окуялар, RG-интервенциялар.
Өлчөө: датасы/убактысы (календарлар), оюн/провайдер, бренд/өлкө, канал/аппарат, оюнчу (токен).
Метрика: GGR, NGR/NET, ARPPU, D1/D7/D30 сактоо, депозиттердин жыштыгы, FPR antifrod, RG-тобокелдик.
Бирдиктер: валюта (FX), убакыт (TZ), көлөм/эсептегичтер (idempotent!).
KPI семантикасы: BI-контракттардагы аныктамалар, KPI версиялары белгиленет.
3) API келишимдер (Маалыматтар & BI келишимдер)
Schema: талаалар, түрлөрү, nullable, enum, бирдиктер, акча.
Метриканын семантикасы: формула, булактар, агрегация терезелери, чыпкалар.
шайкештиги (SEMVER): MAJOR бузат, MINOR талааларды кошот, PATCH бекитет.
DQ/SLA: сергектик, толуктугу, консистенттүүлүк, айырмачылыктар.
Купуялык: 'pii: false', 'tokenized: true', детокенизацияга тыюу салуу.
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) Архитектура
Query API ("алтын "/куб/fichestor үстүнөн онлайн топтоо).
Precompute API (график боюнча prerenders, materialized views).
Events API (агымы эсептегичтер/сигналдар).
Экспорт API (кол коюлган жүктөр, аудит үчүн WORM).
Кэш: көп катмарлуу (in-memory → Redis → CDN), ачкыч = хэш сурам + версия.
Ырааттуулук: акыркы жазуулар үчүн read-your-writes, агрегаттар үчүн SLA сергектик.
5) Интерфейс жана суроолор
5. 1 чыпкалар/агрегациялар/терезелер
'filter': даталар диапазондору ('from/to' UTC, timezone aware), өлкөлөр, бренддер, оюндар, каналдар, түзмөктөр.
'group _ by': өлчөө.
'metrics': KPI тизмеси.
`window`: `DAY|WEEK|MONTH|ROLLING_7D|ROLLING_28D`.
'currency': 'reporting' native ', FX стратегиясы:' eod 'intraday' txn '.
'sampling': оор суроолор үчүн (уруксат берилген жерде гана).
5. 2 Мисал суроо
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 жооп мисал
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) Пагинация, лимиттер, сорттоо
Pagination: 'limit' (≤ 10k), 'cursor' (opaque), өлчөө/датасы боюнча сорттоо.
Timeout/partial: жарым-жартылай жооптор гана каржылык эмес KPI үчүн; каржы - же P200, же P504.
Rate limits: глобалдуу/негизги/тенант боюнча; жооп 'X-RateLimit-'.
7) Idempotentity жана кэш
Idempotent GET/POST-окуу (дене менен) менен 'Idempotency-Key'.
Кэш-ачкыч = хэш (параметрлери + схема версия + ролу/тенант/гео).
TTL: KPI-көз каранды (мисалы, 'PT15M' үчүн revenue, 'PT5M' үчүн окуялар), жаңы snapshot менен калыбына келтирүү.
8) Консистенттүүлүк жана убакыт валютасы
Убакыт-саякат желеги үчүн retrospective отчеттор (маалыматтар нускасы).
Cut-off эрежелери (күн/жума жабылышы).
FX: Биз жооп стратегиясын, курсунун датасы жазылган.
Clock: бардык TimeStamps - ISO-8601, TZ көрсөтмөсү милдеттүү болуп саналат.
9) Коопсуздук жана купуялык
mTLS/TLS1. 3, HMAC кол дене суроо/жооп (MITM/replay коргоо).
RBAC/ABAC/ReBAC: ролу + өлкө + бренд + максаты; демейки маска.
Көп ижара (multi-tenant): схемаларды/ачкычтарды/квоталарды изоляциялоо.
Идентификаторлорду токендештирүү; жооп PII тыюу салуу.
Аудит: өзгөрүлбөс суроо-талап логдору (WORM), 'trace _ id '/' actor '/' purpose'.
Consent/DSAR: маркетинг атрибуттарына чыпкалар; желеги "subject erased".
10) RG/AML/Antifrod чектөөлөр
RG-саясат: жогорку-тобокелдик сегменттер үчүн "агрессивдүү" көрсөткүчтөрдү берүүгө тыюу салуу; агрегаттар коопсуз.
AML/Антифрод: сезгич KPI чектелген жетүү, ролдорду зоналаштыруу; тергөө үчүн өзүнчө эндпоинттерди.
Explainability: KPI түшүндүрмө сөздүгү/саппорт үчүн сигналдар.
11) Байкоо жана SLO API
SLO: p95 latency (мисалы, кэш-хит үчүн ≤ 300 ms; оор үчүн ≤ 2 с), success-rate ≥ 99. 5%.
DQ: сергектик/толуктугу/бүтүндүгү; жооп белгилер.
Usage: QPS, hit-rate кэш, ысык ачкычтар, validation каталар.
Алерталар: сергектиктин бузулушу, 4xx/5xx өсүшү, KPI боюнча аномалиялар (unexpected zeros/peaks).
Tracing: 'trace _ id' DWH/fichestor аркылуу.
12) Версия жана шайкештиги
Жолдор: '/v1 ', '/v2'; көчүрүү терезеси менен депрекейт.
Схемалар: жооп 'schema _ version'; MAJOR → dual-read, миграциялык гайддар.
KPI-версия: жооп 'kpi _ definitions' каталогдо шилтеме менен; жашыруун формулаларды өзгөртүүгө тыюу салуу.
13) Каталар жана статустар
'400' валидация (жок метрика/өлчөө/фильтрлердин айкалышы).
'401/403' аутентификация/авторизация.
'409' версияларынын/саясаттарынын шайкештиги.
'422 '/consent.
'429' квота.
'5xx' платформанын бузулушу (trace_id жана retry-posl менен) .
json
{
"error":"VALIDATION_FAILED",
"message":"Unknown metric: ngrx",
"hint":"metrics allowed: ggr, net_revenue,...",
"trace_id":"..."
}14) Интеграция жана интерфейстер
BI: алдын ала сүрөттөлгөн семантикалык моделдер, коннекторлор (Looker/Power BI/Tableau) → булак катары API.
ML: lightweight endpoints for fich-agregations (point-in-time, PII жок).
Өнөктөштөр: чектелген ачкычтар/квоталар, гео-чыпкалар, агрегаттык блоктор менен гана отчеттор.
Webhook/Push: ноталар "snapshot даяр", "SLO/KPI диапазону бузулган".
15) Ресурстук эндпоинттердин мисалдары
15. 1 Киреше/кирешелүүлүк
'POST/v2/metrics/revenue' → GGR/NGR, коюмдар/утуштар, өлчөөлөр боюнча 'date, brand, country, provider, game'.
15. 2 кармоо жана Huni
`POST /v2/metrics/retention` → когорты D1/D7/D30, `group_by=[cohort_week, brand, country]`.
15. 3 Төлөмдөр
'POST/v2/metrics/payments' → депозиттер/корутундулар, орточо чек, chargeback rate.
15. 4 Responsible Gaming
'POST/v2/metrics/rg' → интервенциялардын саны, жогорку тобокелдик үлүшү, реакциянын орточо убактысы.
15. 5 Антифрод
'POST/v2/metrics/antifraud' → FPR/TPR, учурларда, алдын алуу жоготуулар.
16) тестирлөө жана сапаты
Контракттык тесттер: enum/nullable/түрү, валюталардын/убакыт алкактарынын шайкештиги.
DQ-тесттер: диапазондорду, монотондукту жана бүтүндүктү көзөмөлдөө.
Регресс: v1/v2 толеранттуулук боюнча салыштыруу.
Жүктөө: чокуларынын профилдери (турнирлер/провайдердик иш-чаралар).
Коопсуздук: кол тамгалар, анти-реплика, fuzzing суроолор, Логин Zero-PII.
17) демейки купуялык
"Минималдуу N жазуулар" босогосу бар агрегаттар (k-анонимдүүлүк).
Эч кандай чийки идентификаторлор; гана токендер/категориялар.
DSAR: API артыкчылыктуу контур аркылуу токен жүктөө/алып салуу үчүн.
18) Ийгиликтин көрсөткүчтөрү (KPI API)
Adoption: түз SQL эмес, API колдонгон отчеттордун/виджеттердин үлүшү.
Consistency: BI жана API ≤ уруксат ортосундагы айырмачылык.
SLO: latency/success/freshness сактоо.
Security: жооптордо/блогдордо нөлдүк PII учурлары.
Cost: hit-rate кэш, суроо наркы,% prerenders.
19) RACI (мисал)
Product/Analytics (A) - KPI аныктамалары, муктаждыктары.
Data Platform (R) - ишке ашыруу, кэш, SLA, observability.
Domain Owners (R) - булактар/келишимдер.
Security/DPO (A/R) - купуялык, жеткиликтүүлүк, аудит.
SRE (R) - квота, автоскейл, инциденттер.
Finance (C) - GGR/NGR/NET финансылык семантикасы.
20) Ишке ашыруунун жол картасы
0-30 күн (MVP)
1. Тандоо 3-5 KPI (GGR, депозиттер, D7 кармап калуу).
2. Контракттарды жана KPI-семантиканы сүрөттөө; DQ/SLA кирет.
3. Ишке ашыруу '/v1 'Query API + кэш + mTLS/HMAC.
4. Dashbord SLO (latency/success/freshness), аудит/trace _ id.
30-90 күн
1. Prerenders (Precompute) популярдуу терезелер, CDN кэш.
2. Версиялоо '/v2 ', dual-reading, миграциялык жол.
3. Кол коюлган жүктөөлөр жана WORM менен API экспорттоо.
4. BI/ML менен бириктирүү; квоталар/тенанттар/гео-изоляторлор.
3-6 ай
1. Толук KPI таксономиясы жана widget китепканасы.
2. Акылдуу такталар/автокомпоненттер чыпкалар, Линтер суроолор.
3. Automatic Release Notes KPI, толеранттуулук контролдоо v1/v2.
4. чектелген ачкычтар жана RG-саясатчылар менен тышкы өнөктөш контур.
21) Анти-үлгүлөрү
Жаңы версиясы жана релиз ноталары жок жашыруун KPI формуласын өзгөртүү.
Агрегаттардын/токендердин ордуна PII/чийки затты кайтаруу.
Жок кэш/prerender → кымбат жана жай.
Белгилүү бир БДга катуу шилтеме (катмар абстракциясы жок).
Координацияланбаган TZ/FX → салыштырылгыс сандар.
Жок rate limits/квота → "DDOS өзүнүн".
22) Шаблондор (колдонууга даяр)
22. 1 SLO API саясаты (үзүндү)
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 (фрагмент)
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 Чек релиз тизмеси
- KPI семантика такташты жана нускасы жогорулатылды
- каталогдогу келишим/схема; DQ/регресс жашыл тесттер
- Кэш-ачкычтар/TTL, Prirenders орнотулган
- Документтер жана суроолор/жооптор мисалдар
- SLO жана квота боюнча алерттар камтылган
- RG/AML чектөөлөр текшерилди
23) Байланыштуу бөлүмдөр
DataOps-практикалар, Аудит жана версиялуулук, Коопсуздук жана шифрлөө, Кирүү көзөмөлү, Маалыматтарды токенизациялоо, Сактоо саясаты, Маалыматтардын келип чыгышы жана жолу, MLOps: моделдерди иштетүү, Маалыматтардын этикасы.
Жыйынтык
API аналитика жана метрика "алтын" маалыматтар жана KPI үчүн келишим, коопсуз жана тез жетүү катмары болуп саналат. Бул продукт денгээлде бир семантика, туруктуу нускалары, купуялык жана аткаруу кепилдик берет - өнөктөш панелдер жана ML үчүн ички dashboard.