Интерфейсы доступа к данным
1) Зачем продуманный интерфейс
Скорость и предсказуемость: бизнес-метрики и отчеты укладываются в SLA, без «ручных выгрузок».
Безопасность и приватность: PII/биометрия под контролем, k-анонимность, гео-границы.
Гибкость: разные клиенты (BI, сервисы, партнеры, DS/ML) получают ровно то, что им нужно.
Повторное использование: «данные как продукт» с контрактами и версиями.
2) Карта интерфейсов (когда что)
SQL/ANSI + вендорные диалекты: интерактивная аналитика, BI, ad-hoc.
REST JSON: стабильные агрегаты и операционные данные, интеграции с партнерами.
GraphQL: гибкое «выборочное» чтение и граф навигации (измерения/факты).
gRPC (protobuf): низкая латентность online-сервинга (Feature Store, скоринг).
Arrow Flight / Parquet over HTTP/S3-presigned: быстрые столбцовые «дампы» для DS/ML.
OData: enterprise-инструменты, модель «таблица как сервис».
Streams (Kafka/Pulsar) + CDC/Webhooks: события в реальном времени, реактивные интеграции.
Federation (Trino/Presto): единая точка входа к множеству источников.
Правило: агрегаты и стабильные срезы → REST/MV, богатые произвольные запросы → SQL, низкая латентность/онлайн-фичи → gRPC, гибкая форма ответа → GraphQL, массовый двоичный обмен → Arrow/Parquet.
3) Контракты и версии (semver)
`MAJOR.MINOR.PATCH` для каждого API/схемы/события.
MAJOR: несовместимые изменения (новый путь/топик/таблица).
MINOR: совместимые добавления полей/аргументов.
PATCH: правки описаний/лимитов.
Контракты фиксируют: схему, фильтры, лимиты, приватность, SLO.
yaml openapi: "3. 0. 3"
info: {title: "Analytics API", version: "2. 4. 0"}
paths:
/v2/payments/metrics:
get:
parameters:
- {name: brand, in: query, schema: {type: string}, required: true}
- {name: country, in: query, schema: {type: string}}
- {name: from, in: query, schema: {type: string, format: date-time}}
- {name: to, in: query, schema: {type: string, format: date-time}}
- {name: group_by, in: query, schema: {type: string, enum: [psp,status,day]}}
- {name: limit, in: query, schema: {type: integer, default: 500}}
responses:
"200": {description: "OK"}
x-slo: {p95_latency_ms: 1200, freshness_max: "PT5M"}
x-privacy: {pii: false, min_group_size: 20}4) Доступ к аналитике (SQL и федерация)
SQL-шлюз с ролями/масками (row/column-level security).
Вьюхи/проекции под BI: стабильные имена и семантика; heavy-запросы уходят на предагрегации.
Federation (Trino/Presto): единая точка входа, но с политиками: какие каталоги и какие функции доступны.
Lakehouse (Iceberg/Delta/Hudi): time-travel, snapshot-извлечения через SQL/REST.
Квоты: scanned bytes/query, concurrency, wall-time.
5) GraphQL (гибкая форма)
Даем клиенту собрать нужное поле, но исполняем поверх подготовленных вьюх/проекций, с лимитами глубины/костей.
graphql type Query {
payments(
brand: String!, country: String, from: DateTime!, to: DateTime!,
first: Int = 200, after: String
): PaymentConnection
}Политики: depth ≤ 5, total nodes ≤ 5k, запрещаем произвольные regex/like по строкам; кешируем частые запросы.
6) gRPC / Feature Store (низкая латентность)
Онлайн-фичи для скоринга антифрода/рекомендаций/RG.
proto service FeatureStore {
rpc GetFeatures (FeatureRequest) returns (FeatureResponse);
}
message FeatureRequest { string user_tok = 1; repeated string features = 2; }
message FeatureResponse { map<string, FeatureValue> values = 1; int64 ts_micros = 2; }Требования: p95 ≤ 50–100 мс, точная согласованность оффлайн↔онлайн, TTL фич, кэш LRU, idempotency и mTLS.
7) Потоки и CDC
События домена: `payments.deposit_accepted`, `game.round_finished`.
CDC (из OLTP): изменения статусов/лимитов в near-real-time.
Webhooks для партнеров: подписка на агрегаты (например, «отказы PSP>порог»).
Политики ретраев/подтверждений: exactly-once для критичных, at-least-once для мониторинга.
8) Озера и крупные выборки
Arrow Flight для быстрых колонночных выгрузок в DS/ML.
Presigned-URL на Parquet/Feather, с коротким TTL и подписанным запросом.
Chunked transfer и контроль размера файла; журнал скачиваний (WORM-аудит).
9) Фильтры, пагинация, сортировки
Keyset-пагинация (курсор) вместо OFFSET для больших наборов.
Фильтры: whitelists по полям, типам и операторам (`=, IN, BETWEEN, prefix`).
Сортировка: ограниченный список полей, default порядок.
Partial response: `fields=brand,country,amount` уменьшает полезную нагрузку.
http
GET /v2/game-rounds? brand=X&from=...&to=...&first=1000&after=eyJkYXRlIjoi...10) Кэширование и стоимость
Result cache для шаблонных запросов, инвалидируем по токену свежести (snapshot id).
Edge-кэш/CDN для публичных/полупубличных агрегатов (без PII).
Budget-параметры: лимит scanned bytes, таймаут запроса, квоты rps/мин.
Приоритизация пулов: `bi_hot`, `adhoc`, `partner_api`.
11) Безопасность и приватность
AuthN: OAuth2/OIDC (client credentials для сервисов, PKCE для людей).
AuthZ: RBAC + ABAC (атрибуты: бренд, страна, лицензия, роль).
mTLS между сервисами, TLS 1.2+ наружу.
PII-гигиена: маски/токенизация на API-слое, колоночные маски, k-анонимность агрегатов.
Geo/tenant-изоляция: маршрутизация запросов в регион лицензии; ключи шифрования на бренд/регион.
DSAR/Legal Hold: поиск по токену субъекта, секреты для заморозки наборов.
12) Наблюдаемость (SLI/SLO) и защита
SLI: p50/p95/p99 lat, error-rate, rps, bytes scanned, cache hit, квоты/лимиты, доля маскированных колонок, доля отказов по авторизации.
SLO: p95 латентности, свежесть данных, % успешных запросов, min-group-size на ответах.
Алерты: рост scanned bytes, падение hit-rate, всплеск 429/5xx, попытки доступа к PII, утечки курсоров.
yaml slo:
p95_latency_ms: 1200 success_rate: 0. 995 freshness_max: "PT5M"
privacy:
pii_allowed: false min_group_size: 20 quotas:
rps: 50 max_scanned_mb: 25613) Форматы и компрессия
JSON для совместимости; CSV — только для небольших и несложных экспортов.
Parquet/Arrow — по умолчанию для больших выгрузок.
Compression: gzip/zstd (переговоры через `Accept-Encoding`).
Content-negotiation: `Accept: application/x-parquet`.
14) Метрики как API (Analytics/OLAP-шлюз)
Метрики верхнего уровня: GGR/NET, CR, удержание, RG-инциденты — как ресурсы с параметрами `brand,country,window,group_by`.
Approx (HLL/TDigest) для distinct/percentiles.
Кэш с ключом: `(metric, params, snapshot_id)`.
15) Специфика iGaming — готовые эндпоинты
`GET /v2/payments/metrics` — отказы/апрувы по PSP/стране/бренду с 7/30d окнами.
`GET /v2/game-rounds/metrics` — топ-игры/провайдеры, p95 длительности, RTP-окна.
`GET /v2/rg/cases` — активные ограничения/самоисключения (k-анонимные агрегаты).
`POST /v1/features:get` (gRPC) — онлайн-фичи для скоринга фрода/рекоммендера.
`POST /v1/webhooks/psp-alerts` — уведомления «decline rate > порога».
16) Примеры контрактов
GraphQL запрос тонкий срез:graphql query {
payments(brand:"X", country:"TR", from:"2025-10-01", to:"2025-10-31", first:500) {
edges { node { day totalAmount declines psp } cursor }
pageInfo { hasNextPage endCursor }
}
}json
{"event_id":"...","occurred_at":169..., "brand":"X","psp":"Papara","status":"declined","amount":"100. 00","currency":"TRY"}
/flight/v1/query? dataset=gold. payments&from=...&to=...&brand=X&format=arrow17) Процесс публикации нового интерфейса
1. ADR: проблема/ценность/клиенты/безопасность/стоимость.
2. Контракт: схема, фильтры, лимиты, приватность, SLO, версии.
3. Нагрузочное моделирование: top-N запросов, p95/скан-байты, стоимость.
4. Валидация/кеш/квоты: включить по умолчанию.
5. Документация и SDK: примеры, лимиты, ошибки, ретраи, идемпотентность.
6. Canary: % клиентов, регресс-тесты, алерты.
7. GA: версия в каталоге Data Products, отчет по эффектам.
18) Анти-паттерны
Открыть «сырой» SQL всем — утечки PII, непредсказуемая стоимость.
OFFSET-пагинация и `SELECT ` — боль по латентности и счету.
GraphQL без ограничений глубины/стоимости.
REST, который возвращает слишком много колонок без `fields=...`.
Отсутствие k-анонимности и min-group-size в агрегатах.
Нулевые квоты/лимиты и отключенный кэш.
Нет версионирования/контрактов — «ломаем» клиентов при каждом изменении.
Один и тот же интерфейс для всех стран/брендов — игнор региональных правил.
19) Дорожная карта внедрения
0–30 дней (MVP)
1. Каталог Data Products (метрики/срезы) и их OpenAPI/GraphQL контракты.
2. SQL-шлюз с RLS/CLS, k-анонимность агрегатов, базовые квоты.
3. Один REST-метрик эндпоинт (`/payments/metrics`) + кэш + пулы `bi_hot/adhoc`.
4. gRPC Feature Store: чтение 10–20 ключевых онлайн-фич (p95 ≤ 80 мс).
30–90 дней
1. Стрим-интерфейсы (Kafka/Webhook) для PSP-алертов/игровых событий.
2. Arrow/Parquet выгрузки с presigned-URL; каталог снапшотов.
3. Federation-шлюз (Trino/Presto) с явными политиками.
4. Наблюдаемость: дашборд SLI/SLO, алерты на стоимость/латентность/PII.
3–6 месяцев
1. SDK (TypeScript/Python/Go) с ретраями/идемпотентностью/квотами.
2. Тонкие GraphQL-срезы для продуктов и партнеров.
3. Расширение gRPC/FS, согласование оффлайн↔онлайн; shadow→canary релизы.
4. Аудит приватности/DSAR; отчеты комплаенса по доступам.
20) RACI
Data Platform (R): шлюзы, кэш, квоты, федерация, наблюдаемость.
Data Governance (A/R): контракты, версии, приватность/k-анонимность.
Domain Owners (R): семантика полей, бизнес-инварианты, Data Products.
Security/DPO (A/R): AuthN/Z, geo-изоляция, DSAR/Legal Hold.
SRE/Observability (C): SLO/SLI, алерты, capacity.
Analytics/BI/DS (C): требования к формам/агрегатам, SDK.
21) Связанные разделы
Индексация аналитических хранилищ, Оптимизация аналитических запросов, Схемы данных и их эволюция, Валидация данных, DataOps-практики, API аналитики и метрик, Feature Store, Безопасность данных и шифрование, Контроль доступа, Политики хранения данных.
Итог
Правильно спроектированные интерфейсы доступа к данным превращают хранилища и потоки в надежный «продукт»: предсказуемые SLA, контролируемая стоимость, соблюдение приватности и единый язык для команд продукта, аналитики, комплаенса и партнеров. В iGaming это значит быстрее ловить сбои PSP, понимать поведение игроков и выполнять требования регуляторов — без ручных выгрузок и ночных миграций.