Берилиштерге жетүү интерфейстери
1) Эмне үчүн ойлонулган интерфейс
Ылдамдыгы жана алдын ала: бизнес-метрика жана отчеттор SLAга туура келет, "кол менен түшүрүү" жок.
Коопсуздук жана купуялык: PII/биометрия көзөмөлдө, k-анонимдүүлүк, гео-чек.
Ийкемдүүлүк: Ар кандай кардарлар (BI, кызматтар, өнөктөштөр, DS/ML) так аларга керектүү нерсени алышат.
Кайталап колдонуу: келишимдер жана версиялар менен "продукт катары маалыматтар".
2) Карта Interface (качан)
SQL/ANSI + вендордук диалектилер: интерактивдүү аналитика, BI, ad-hoc.
REST JSON: туруктуу агрегаттар жана иш маалыматтар, өнөктөштөр менен бириктирүү.
GraphQL: ийкемдүү "тандап" окуу жана тилке багыттоо (өлчөө/фактылар).
gRPC (protobuf): төмөн жашыруун онлайн Serving (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).
Wuhi/BI проекциялары: туруктуу ысымдар жана семантика; heavy-суроолор алдын ала агымдарга кетет.
Federation (Trino/Presto): бирдиктүү кирүү чекити, бирок саясатчылар менен: кандай каталогдор жана кандай функциялар бар.
Lakehouse (Iceberg/Delta/Hudi): убакыт-саякат, SQL/REST аркылуу snapshot-алуу.
Квоты: 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, жалпы 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 мс, так ырааттуулук offline онлайн, TTL fich, LRU кэш, idempotency жана mTLS.
7) Агымдар жана CDC
Домендик окуялар: 'payments. deposit_accepted`, `game. round_finished`.
CDC (АЛТПдан): near-real-time статусун/лимиттерин өзгөртүү.
Өнөктөштөр үчүн Webhooks: агрегаттарга жазылуу (мисалы, "PSP мүчүлүштүктөрү> босого").
Retray/ырастоо саясаты: сынчыл үчүн exactly-once, мониторинг үчүн at-least-once.
8) Көлдөр жана ири үлгүлөрү
Arrow Flight DS/ML тез колонна жүктөө үчүн.
Parquet/Feather боюнча Presigned-URL, кыска TTL жана кол коюлган суроо менен.
Chunked которуу жана файлдын өлчөмүн көзөмөлдөө; жүктөө журналы (WORM-аудит).
9) чыпкалар, пагинация, сорттоо
Keyset-pagination (курсор) ордуна 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 for services, PKCE for people).
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 хит, квота/лимиттер, катылган колонкалардын үлүшү, авторизациядан баш тартуулардын үлүшү.
SLO: p95 жашыруун, маалыматтардын сергектиги,% ийгиликтүү суроо, жооп боюнча min-group-size.
Alerty: 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 өзгөчөлүктөрү - даяр EndPoints
'GET/v2/payments/metrics' - 7/30d терезелери менен PSP/өлкө/бренд боюнча мүчүлүштүктөр/апрустар.
'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/scan-байт, наркы.
4. Валидация/кэш/квота: демейки.
5. Документация жана SDK: мисалдар, лимиттер, каталар, ретра, демпотенттик.
6. Canary: кардарлардын%, регресс тесттер, Алерт.
7. GA: Data Products каталогундагы версия, эффекттер боюнча отчет.
18) Анти-үлгүлөрү
Ачуу "чийки" SQL бардык - PII агып, күтүүсүз наркы.
OFFSET-пагинация жана 'SELECT' - жашыруун жана эсеп оорусу.
GraphQL тереңдик/наркы чектөөсүз.
'fields =...' жок өтө көп колонкаларды кайтарган REST.
Агрегаттарда k-анонимдүүлүктүн жана min-group-size жоктугу.
Нөлдүк квота/лимиттер жана өчүрүлгөн кэш.
Версиялоо/келишимдер жок - ар бир өзгөрүүдө кардарларды "сындырабыз".
Бардык өлкөлөр/бренддер үчүн бир эле интерфейс - аймактык эрежелердин игнору.
19) Ишке ашыруунун жол картасы
0-30 күн (MVP)
1. Data Products каталогу (метриктер/тилкелер) жана алардын OpenAPI/GraphQL келишимдери.
2. RLS/CLS менен SQL-шлюз, k-жашыруун агрегаттар, негизги квоталар.
3. Бир REST-метрикалык endpoint ('/payments/metrics ') + кэш + пулалар' bi _ hot/adhoc '.
4. gRPC Feature Store: 10-20 негизги онлайн сүрөт окуу (p95 ≤ 80 ms).
30-90 күн
1. Stream Interfaces (Kafka/Webhook) PSP/оюн окуялар үчүн.
2. Arrow/Parquet жүктөө presigned-URL менен; снапшоттордун каталогу.
3. Федерация-шлюз (Trino/Presto) ачык саясатчылар менен.
4. Байкоо: dashboard SLI/SLO, наркы/жашыруун/PII боюнча алерт.
3-6 ай
1. SDK (TypeScript/Python/Go) retras/idempotentity/квота менен.
2. азыктары жана өнөктөштөр үчүн Ince GraphQL тилкелери.
3. gRPC/FS кеңейтүү, онлайн offline макулдашуу; shadow → canary релиздери.
4. Купуялык аудит/DSAR; жеткиликтүүлүк боюнча комплаенс отчеттор.
20) RACI
Data Platform (R): шлюздар, кэш, квоталар, федерация, байкоо.
Data Governance (A/R): келишимдер, версиялар, купуялык/k-анонимдүүлүк.
Domain Owners (R): талаа семантикасы, бизнес инварианттар, маалыматтар Products.
Security/DPO (A/R): AuthN/Z, гео-изоляция, DSAR/Legal Hold.
SRE/Observability (C): SLO/SLI, alerty, capacity.
Analytics/BI/DS (C): формалар/агрегаттар үчүн талаптар, SDK.
21) Байланыштуу бөлүмдөр
Аналитикалык кампаларды индекстөө, Аналитикалык суроо-талаптарды оптималдаштыруу, Маалыматтар схемалары жана алардын эволюциясы, Маалыматтарды валидациялоо, DataOps практикалары, Аналитика жана метрика API, Feature Store, Маалымат коопсуздугу жана шифрлөө, Жеткиликтүүлүктү көзөмөлдөө, Маалыматтарды сактоо саясаты.
Жыйынтык
Туура иштелип чыккан берилиштерге жетүү интерфейстери сактагычтарды жана агымдарды ишенимдүү "продуктка" айландырат: болжолдонгон SLA, контролдонуучу нарк, купуялуулукту сактоо жана продукт буйруктары, аналитика, комплаенс жана өнөктөштөр үчүн бирдиктүү тил. iGaming бул тез PSP кемчиликтерин кармоо, оюнчулардын жүрүм-турумун түшүнүү жана жөнгө салуучу органдардын талаптарын аткаруу дегенди билдирет - кол менен түшүрүү жана түнкү миграция жок.