Інтерфейси доступу до даних
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 мс, точна узгодженість offlayn↔onlayn, 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 запитів, р95/скан-байти, вартість.
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, узгодження offlayn↔onlayn; 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, розуміти поведінку гравців і виконувати вимоги регуляторів - без ручних вивантажень і нічних міграцій.