მონაცემთა ინტერფეისები

1) რატომ არის გააზრებული ინტერფეისი

სიჩქარე და პროგნოზირება: ბიზნეს მეტრიკა და მოხსენებები ჯდება SLA- ში, „ხელით გადმოტვირთვის“ გარეშე.
უსაფრთხოება და კონფიდენციალურობა: PII/ბიომეტრია კონტროლის ქვეშ, კ-ანონიმურობა, გეო-საზღვარი.
მოქნილობა: სხვადასხვა მომხმარებლები (BI, სერვისები, პარტნიორები, DS/ML) იღებენ ზუსტად იმას, რაც მათ სჭირდებათ.
ხელახალი გამოყენება: „მონაცემები, როგორც პროდუქტი“ კონტრაქტებითა და ვერსიებით.

2) ინტერფეისის რუკა (როდის)

SQL/ANSI + მოვაჭრე დიალექტები: ინტერაქტიული ანალიტიკა, BI, ad-hoc.
REST JSON: სტაბილური დანაყოფები და ოპერაციული მონაცემები, პარტნიორებთან ინტეგრაცია.
GraphQL: მოქნილი „ნიმუშის“ კითხვა და ნავიგაციის გრაფიკი (გაზომვები/ფაქტები).
GRPC (Protobuf): ონლაინ სერვინგის დაბალი ლატენტობა (Feature Store, Scoring).
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 უსაფრთხოება).
Vyuchi/პროგნოზები 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 ms, ზუსტი კოორდინაცია ოფლაინ ონლაინ რეჟიმში, TTL fich, LRU ქეში, პირადობის და mTLS.

7) ნაკადები და CDC

დომენის მოვლენები: 'payments. deposit_accepted`, `game. round_finished`.
CDC (OLTP- დან): სტატუსის/ლიმიტის ცვლილებები რეალურ დროში.
პარტნიორებისთვის Webhooks: გამოწერა აგრეგატებისთვის (მაგალითად, „PSP> ბარიერი“).
Retrain/მტკიცებულებების პოლიტიკოსები: 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-cash/CDN საჯარო/ნახევრად საზოგადოებრივი ერთეულებისთვის (PII გარეშე).

Budget პარამეტრები: scanned bytes ლიმიტი, მოთხოვნის ტაიმუთი, კვოტები rps/წთ

პულის პრიორიტეტი: 'bi _ hot', 'adhoc', 'partner _ ap'.

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: 256

13) ფორმატები და შეკუმშვა

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.
გასაღები ქეში: '(მეტრული, პარამსი, 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) - ონლაინ ფიჩხები from/recomender- ის სკრიპტისთვის.
'POST/v1/webhooks/psp-alerts' - შეტყობინებები „decline> ბარიერი“.

16) კონტრაქტების მაგალითები

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=arrow

17) ახალი ინტერფეისის გამოქვეყნების პროცესი

1. ADR: პრობლემა/ღირებულება/მომხმარებლები/უსაფრთხოება/ღირებულება.
2. კონტრაქტი: სქემა, ფილტრები, ლიმიტები, კონფიდენციალურობა, SLO, ვერსიები.
3. დატვირთვის მოდელირება: მოთხოვნის ტოპ-N, p95/სკანირების ბაიტი, ღირებულება.
4. ვალიდაცია/ქეში/კვოტები: ნაგულისხმევი ჩართვა.
5. დოკუმენტაცია და SDK: მაგალითები, ლიმიტები, შეცდომები, retray, imempotence.
6. არხი: მომხმარებელთა%, რეგრესიული ტესტები, ალერტები.
7. GA: მონაცემთა წარმოების კატალოგის ვერსია, ეფექტების ანგარიში.

18) ანტი შაბლონები

ყველასთვის „ნედლეულის“ გახსნა - 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 ') + ქეში + pulls' bi _ hot/adhoc '.
4. GRPC Feature Store: წაიკითხეთ 10-20 ძირითადი ონლაინ ფიგურა (p95-80 ms).

30-90 დღე

1. Strim ინტერფეისები (Kafka/Webhook) PSP ალერტებისთვის/თამაშის მოვლენებისთვის.
2. Arrow/Parquet გადმოტვირთვის presigned-URL- ით; სნაიპშოტების კატალოგი.
3. ფედერალური კარიბჭე (Trino/Presto) აშკარა პოლიტიკოსებით.
4. დაკვირვება: დაშბორდი SLI/SLO, ალერტები ღირებულებისთვის/ლატენტობისთვის/PII.

3-6 თვე

1. SDK (TypeScript/Python/Go) თხრილებით/idempotence/კვოტებით.
2. თხელი GraphQL ნაჭრები პროდუქტებისა და პარტნიორებისთვის.
3. GRPC/FS გაფართოება, ოფლაინის კოორდინაცია ონლაინ რეჟიმში; shadow - canary გამოშვებები.
4. კონფიდენციალურობის აუდიტი/DSAR; შესაბამისობის ანგარიშები წვდომის შესახებ.

20) RACI

Data Platform (R): კარიბჭეები, ქეში, კვოტები, ფედერაცია, დაკვირვება.
Data Governance (A/R): კონტრაქტები, ვერსიები, კონფიდენციალურობა/k-ანონიმურობა.
დომენის Owners (R): მინდვრის სემანტიკა, ბიზნეს ინვარიანტები, Data Products.
უსაფრთხოება/DPO (A/R): AuthN/Z, geo იზოლაცია, DSAR/Legal Hold.
SRE/Observability (C): SLO/SLI, alerty, capacity.
ანალიზები/BI/DS (C): მოთხოვნები ფორმების/აგრეგატების, SDK.

21) დაკავშირებული მონაკვეთები

ანალიტიკური საცავის ინდექსაცია, ანალიტიკური მოთხოვნების ოპტიმიზაცია, მონაცემთა სქემები და მათი ევოლუცია, მონაცემთა ვალიდაცია, DataOps პრაქტიკა, API ანალიტიკოსები და მეტრიკა, Feature Store, მონაცემთა უსაფრთხოება და დაშიფვრა, წვდომის კონტროლი, მონაცემთა შენახვის პოლიტიკა.

შედეგი

მონაცემთა წვდომის სწორად შემუშავებული ინტერფეისები საცავებს და ნაკადებს საიმედო „პროდუქტად“ აქცევს: პროგნოზირებადი SLA, კონტროლირებადი ღირებულება, კონფიდენციალურობის დაცვა და ერთი ენა პროდუქტის გუნდებისთვის, ანალიტიკოსებისთვის, შესაბამისობისთვის და პარტნიორებისთვის. IGaming- ში ეს ნიშნავს სწრაფად დაიჭიროთ PSP ჩავარდნები, გააცნობიეროს მოთამაშეთა ქცევა და შეასრულოს რეგულატორების მოთხოვნები - ხელით გადმოტვირთვისა და ღამის მიგრაციის გარეშე.