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.