API аналітики і метрик

1) Навіщо окремий шар API

Єдина істина для KPI: виключаємо «зоопарк SQL».
Швидкість продукту: фронти, партнерські панелі, мобільні клієнти отримують агрегати без прямого доступу до DWH.
Безпека та комплаєнс: токенізація, маски, гео-обмеження, RG/AML-фільтри.
Масштабування: кеш, пререндери, CDN, стабільні контракти.

2) Таксономія: метрики, вимірювання, факти

Факти: ставки, виграші, депозити, KYC-події, RG-інтервенції.
Вимірювання: дата/час (календарі), гра/провайдер, бренд/країна, канал/девайс, гравець (токен).
Метрики: GGR, NGR/NET, ARPPU, утримання D1/D7/D30, частота депозитів, FPR антифрода, RG-ризик.
Одиниці: валюта (FX), час (TZ), обсяг/лічильники (idempotent!).
Семантика KPI: визначення в BI-контрактах, версії KPI фіксуються.

3) Контракти API (Data & BI Contracts)

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 (онлайн агрегації поверх «gold «/кубів/фічестора).
Precompute API (пререндери за розкладом, materialized views).
Events API (потокові лічильники/сигнали).
Export 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`: для heavy-запитів (тільки там, де допустимо).

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) Пагінація, ліміти, сортування

Пагінація: 'limit'( ≤10k),'cursor'( opaque), сортування за вимірами/датою.
Timeout/partial: часткові відповіді тільки для нефінансових KPI; фінанси - або P200, або P504.
Rate limits: глобальні/по ключу/по тенанту; відповідь містить «X-RateLimit-».

7) Ідемпотентність і кеш

Ідемпотентні GET/POST-read (з тілом) з'Idempotency-Key'.
Кеш-ключ = хеш (параметри + версія схеми + роль/тенант/гео).
TTL: KPI-залежний (напр.,'PT15M'для revenue,'PT5M'для подій), скидання при новому снапшоті.

8) Консистентність і валюта часу

Time-travel прапор для ретроспективних звітів (версії даних).
Cut-off правила (закриття дня/тижня).
FX: фіксуємо стратегію, дата курсу у відповіді.
Clock: всі таймстемпи - 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/Антифрод обмеження

RG-політики: заборона видачі «агресивних» показників для high-risk сегментів; агрегати безпечні.
AML/Антифрод: обмежений доступ до чутливих KPI, зонування за ролями; роздільні ендпоінти для розслідувань.
Explainability: словник пояснень KPI/сигналів для саппорту.

11) Спостережуваність і SLO API

SLO: p95 latency (наприклад, ≤ 300 мс для кеш-хітів; ≤ 2 с для важких), success-rate ≥ 99. 5%.
DQ: свіжість/повнота/цілісність; мітки у відповіді.
Usage: QPS, hit-rate кеша, гарячі ключі, помилки валідації.
Алерти: деградація свіжості, зростання 4xx/5xx, аномалії по KPI (unexpected zeros/peaks).
Tracing: 'trace _ id'наскрізний до DWH/фічестора.

12) Версіонування та сумісність

Шляхи: `/v1`, `/v2`; депрекейт з вікном міграції.
Схеми: 'schema _ version'у відповіді; MAJOR → dual-read, міграційні гайди.
KPI-версії: у відповіді'kpi _ definitions'з посиланням в каталозі; заборона прихованих змін формул.

13) Помилки і статуси

'400'валідація (неіснуюча метрика/вимірювання/комбінація фільтрів).
'401/403'автентифікація/авторизація.
'409'несумісність версій/політик.
«422» порушення конфіденційності/consent.
'429'квоти.
'5xx'збої платформи (з trace_id і retry-посл.) .

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

14) Інтеграції та інтерфейси

BI: заздалегідь описані semantic-моделі, конектори (Looker/Power BI/Tableau) → API як джерело.
ML: lightweight endpoints для фіч-агрегатів (point-in-time, без PII).
Партнери: обмежені ключі/квоти, гео-фільтри, звіти тільки агрегатними блоками.
Webhook/Push: нотифікації «снапшот готовий», «порушений SLO/діапазон KPI».

15) Приклади ресурсних ендпоінтів

15. 1 Виручка/прибутковість

'POST/v2/metrics/revenue'→ GGR/NGR, ставки/виграші, за вимірами'date, brand, country, provider, game'.

15. 2 Утримання і воронки

`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'→ кількість інтервенцій, частка high-risk, середній час реакції.

15. 5 Антифрод

'POST/v2/metrics/antifraud'→ FPR/TPR, кейси, втрати відвернені.

16) Тестування та якість

Контрактні тести: enum/nullable/тип, узгодженість валют/часових поясів.
DQ-тести: контроль діапазонів, монотонності і цілісності.
Регрес: порівняння v1/v2 за толерансами.
Навантажувальні: профілі піків (турніри/провайдерські івенти).
Безпека: підписи, анти-replay, fuzzing запитів, Zero-PII в логах.

17) Приватність за замовчуванням

Агрегати з порогами «мінімум N записів» (k-анонімність).
Ніяких raw-ідентифікаторів; тільки токени/категорії.
DSAR: API для вивантаження/видалення по токену через привілейований контур.

18) Метрики успіху (KPI API)

Adoption: частка звітів/віджетів, що використовують API, а не прямий SQL.
Consistency: розбіжність між BI і API ≤ допусків.
SLO: дотримання latency/success/freshness.
Security: нульові випадки PII у відповідях/логах.
Cost: hit-rate кеша, вартість запиту,% пререндерів.

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 + кеш + мTLS/HMAC.
4. Дашборди SLO (latency/success/freshness), аудит/trace _ id.

30-90 днів

1. Пререндери (Precompute) популярних вітрин, CDN кеш.
2. Версіонування '/v2', dual-read, міграційний гайд.
3. Експорт API з підписаними вивантаженнями і WORM.
4. Інтеграції з BI/ML; квоти/тенанти/гео-ізолятори.

3-6 місяців

1. Повна таксономія KPI і бібліотека віджетів.
2. Розумні підказки/автокомпліт фільтрів, лінтер запитів.
3. Автоматичні Release Notes KPI, контроль толерансів v1/v2.
4. Зовнішній партнерський контур з обмеженими ключами і RG-політиками.

21) Анти-патерни

Прихована зміна формули KPI без нової версії і реліз-нот.
Повернення PII/сировини замість агрегатів/токенів.
Відсутність кешу/пререндерів → дорого і повільно.
Жорстка прив'язка до конкретної БД (немає абстракції шару).
Неузгоджені 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: false

22. 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, пререндери налаштовані
• Документація та приклади запитів/відповідей
• Алерти по SLO і квотах включені
• RG/AML обмеження перевірені

23) Пов'язані розділи

DataOps-практики, Аудит і версійність, Безпека і шифрування, Контроль доступу, Токенізація даних, Політики зберігання, Походження і шлях даних, MLOps: експлуатація моделей, Етика даних.

Підсумок

API аналітики і метрик - це контрактований, безпечний і швидкий шар доступу до «золотих» даних і KPI. Він гарантує єдину семантику, стабільні версії, приватність за замовчуванням і продуктивність на рівні продукту - від внутрішніх дашбордів до партнерських панелей і ML.