API ანალიტიკოსები და მეტრიკი

1) რატომ არის API ცალკეული ფენა

KPI- სთვის ერთი ჭეშმარიტება: გამორიცხეთ „SQL ზოოპარკი“.
პროდუქტის სიჩქარე: ფრონტები, პარტნიორი პანელები, მობილური მომხმარებლები იღებენ დანაყოფებს DWH- ზე პირდაპირი წვდომის გარეშე.
უსაფრთხოება და შესაბამისობა: ტოკენიზაცია, ნიღბები, გეო შეზღუდვები, RG/AML ფილტრები.
სკალირება: ქეში, წინამორბედები, CDN, სტაბილური კონტრაქტები.

2) ტაქსონომია: მეტრიკა, გაზომვები, ფაქტები

ფაქტები: განაკვეთები, მოგება, ანაბრები, KYC მოვლენები, RG ჩარევა.
გაზომვები: თარიღი/დრო (კალენდარი), თამაში/პროვაიდერი, ბრენდი/ქვეყანა, არხი/მოწყობილობა, მოთამაშე (ნიშანი).
მეტრიკა: GGR, NGR/NET, ARPU, 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: ნამდვილი ", დეტოკენიზაციის აკრძალვა.

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 (ონლაინ აგრეგაციები „ოქროს „/კუბის/მეწამულის თავზე).
Precompute API (გრაფიკის წინამორბედები, materialized views).
Events API (ნაკადის მრიცხველები/სიგნალები).
Export API (ხელმოწერილი გადმოტვირთვის, WORM აუდიტისთვის).
კეში: მრავალ ფენიანი (სამახსოვრო - Redis - CDN), გასაღები = მოთხოვნის ჰაში + ვერსია.
კოორდინაცია: საბოლოო ჩანაწერების read-your-writes, SLA ახალი აგრეგატები.

5) ინტერფეისი და მოთხოვნები

5. 1 ფილტრები/აგრეგაციები/ფანჯრები

'filter': თარიღების დიაპაზონი ('from/to' UTC, timezone aware), ქვეყნები, ბრენდები, თამაშები, არხები, მოწყობილობები.
'ჯგუფი _ by': გაზომვები.
'metrics': KPI სია.
`window`: `DAY|WEEK|MONTH|ROLLING_7D|ROLLING_28D`.
'currency': 'reporting' native ', FX სტრატეგია:' eod 'intraday' txn '.
'sampling': მძიმე მოთხოვნებისთვის (მხოლოდ იქ, სადაც დასაშვებია).

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) Idempotence და ქეში

Idempotent GET/POST-read (სხეულით) ერთად 'Idempotency-Key'.
ქეში გასაღები = ჰაში (პარამეტრი + სქემის ვერსია + როლი/ტენანტი/გეო).
TTL: KPI დამოკიდებული (მაგ., 'PT15M' მოვლენებისთვის, 'PT5M'), ჩამოაგდეს ახალი სნაიპშოტით.

8) დროის თანმიმდევრულობა და ვალუტა

რეტროსპექტული მოხსენებების დროშა (მონაცემთა ვერსიები).
Cut-off წესები (დღის/კვირის დახურვა).
FX: ჩვენ ვაფიქსირებთ სტრატეგიას, კურსის თარიღს პასუხში.
კლოკი: ყველა დრო - ISO-8601, TZ მითითება აუცილებელია.

9) უსაფრთხოება და კონფიდენციალურობა

mTLS/TLS1. 3, მოთხოვნის/პასუხის სხეულის HMAC ხელმოწერა (დაცვა MITM/replay- დან).
RBAC/ABAC/ReBAC: როლი + ქვეყანა + ბრენდი + მიზანი; ნაგულისხმები ნიღბები.
მრავალფუნქციურობა (მრავალფუნქციური): სქემების/გასაღებების/კვოტების იზოლაცია.
იდენტიფიკატორის ტოქსიკაცია; აკრძალვა PII პასუხებში.
აუდიტი: მოთხოვნის უცვლელი ლოგოები (WORM), 'trace _ id '/' actor '/' purpose'.
Consent/DSAR: ფილტრები მარკეტინგის ატრიბუტებზე; დროშა „subject erased“.

10) RG/AML/შეზღუდვის ანტიფროდი

RG პოლიტიკა: მაღალი დონის სეგმენტებისთვის „აგრესიული“ ინდიკატორების გაცემის აკრძალვა; დანაყოფები უსაფრთხოა.
AML/ანტიფროდი: შეზღუდული წვდომა მგრძნობიარე KPI- ზე, როლების ზონირება; გამოძიების ცალკეული ენდოინტები.
Explainability: ახსნა-განმარტებების ლექსიკონი KPI/სიგნალები საფორტეპიანო.

11) დაკვირვება და SLO API

SLO: p95 latence (მაგალითად, 300 ms ქეშის ჰიტებისთვის; 2 - დან მძიმე), success-rate-99. 5%.
DQ: სიახლე/სისრულე/მთლიანობა; პასუხის ნიშნები.
Usage: QPS, hit-rate ქეში, ცხელი გასაღებები, ვალიდაციის შეცდომები.
ალერტები: სიახლის დეგრადაცია, ზრდა 4xx/5xx, ანომალიები KPI- სთვის (unexpected zeros/peaks).
Tracing: 'trace _ id' გადის DWH/fichestor- ით.

12) ვერსიები და თავსებადობა

ბილიკები: '/v1 ', '/v2'; დეპრესია მიგრაციის ფანჯრით.
სქემები: 'schema _ version' საპასუხოდ; MAJOR - dual-read, მიგრაციის ჰაიდები.
KPI ვერსიები: პასუხში 'kpi _ definitions' კატალოგში მითითებით; ფარული ცვლილებების აკრძალვა ფორმულებში.

13) შეცდომები და სტატუსები

'400' შესაბამისობა (არარსებული მეტრიკა/გაზომვა/ფილტრების ერთობლიობა).
'401/403' ავთენტიფიკაცია/ავტორიზაცია.
'409' ვერსიების შეუთავსებლობა/პოლიტიკოსი.
'422' კონფიდენციალურობის დარღვევა/კონსულტაცია.
'429' კვოტები.
'5xx' პლატფორმის გაუმართაობა (trace _ id და retry.). .

json
{
"error":"VALIDATION_FAILED",
"message":"Unknown metric: ngrx",
"hint":"metrics allowed: ggr, net_revenue,...",
"trace_id":"..."
}

14) ინტეგრაცია და ინტერფეისი

BI: წინასწარ აღწერილი სემანტიკური მოდელები, კონექტორები (Looker/Power BI/Tableau) API, როგორც წყარო.
ML: lightweight endpoints წინსვლის ერთეულებისთვის (წერტილოვანი დრო, PII- ის გარეშე).
პარტნიორები: შეზღუდული გასაღებები/კვოტები, გეო ფილტრები, მოხსენებები მხოლოდ აგრეგატის ბლოკებით.
Webhook/Push: ნოტიფიკაცია „Snapshot მზად“, „დაირღვა SLO/KPI დიაპაზონი“.

15) რესურსების endpoints- ის მაგალითები

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' - ინტერვენციების რაოდენობა, მაღალი რანგის წილი, რეაქციის საშუალო დრო.

15. 5 ანტიფროდი

'POST/v2/metrics/antifraud', FPR/TPR, შემთხვევები, ზარალის თავიდან აცილება.

16) ტესტირება და ხარისხი

საკონტრაქტო ტესტები: enum/nullable/ტიპი, ვალუტების/დროის ზონების კოორდინაცია.
DQ ტესტები: დიაპაზონის კონტროლი, ერთფეროვნება და მთლიანობა.
რეგრესი: შედარება v1/v2 ტოლერანტებისთვის.
დატვირთვა: მწვერვალების პროფილები (ტურნირები/პროვაიდერები).
უსაფრთხოება: ხელმოწერები, ანტი-replay, fuzzing მოთხოვნა, Zero-PII ლოგოებში.

17) კონფიდენციალურობა

აგრეგატები „მინიმალური N ჩანაწერების“ ბარიერებით (კ-ანონიმურობა).
არა იდენტიფიკატორი; მხოლოდ ნიშნები/კატეგორიები.
DSAR: API ტოქსინის გადმოტვირთვის/ამოღებისთვის პრივილეგირებული კონტურის საშუალებით.

18) წარმატების მეტრიკა (KPI API)

Adoption: API- ს გამოყენებით მოხსენებების/ვიჯეტების წილი და არა პირდაპირი SQL.
Consistence: განსხვავება BI- სა და API- ს შორის.
SLO: latence/success/freshness.
უსაფრთხოება: PII ნულოვანი შემთხვევები პასუხებში/ლოგოებში.
Cost: hit-rate ქეში, მოთხოვნის ღირებულება, თანატოლების%.

19) RACI (მაგალითი)

Product/Analytics (A) - KPI განმარტება, საჭიროებები.
Data Platform (R) - განხორციელება, ქეში, SLA, observability.
დომენის ომერები (R) - წყაროები/კონტრაქტები.
უსაფრთხოება/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 + ქეში + mTLS/HMAC.
4. დაშბორდები SLO (latency/success/freshness), აუდიტი/trace _ id.

30-90 დღე

1. Predenders (Precompute) პოპულარული ფანჯრები, CDN ქეში.
2. ვერსია '/v2 ', ორმაგი read, მიგრაციის ჰაიდი.
3. API- ს ექსპორტი ხელმოწერილი გადმოტვირთვებით და WORM.
4. ინტეგრაცია BI/ML- სთან; კვოტები/ტენანტები/გეო-იზოლატორები.

3-6 თვე

1. სრული ტაქსონომია KPI და ვიჯეტის ბიბლიოთეკა.
2. ჭკვიანი რჩევები/მანქანის ფილტრები, მოთხოვნის ლინტერი.
3. ავტომატური Release Notes KPI, ტოლერანტული კონტროლი v1/v2.
4. გარე პარტნიორობის წრე შეზღუდული კლავიშებით და RG პოლიტიკოსები.

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

KPI ფორმულის ფარული ცვლილება ახალი ვერსიისა და გამოცემის ნოტების გარეშე.
PII/ნედლეულის დაბრუნება აგრეგატების/ტოქსინების ნაცვლად.
ქეში/წინამორბედების ნაკლებობა ძვირი და ნელა.
კონკრეტული DD- ს მკაცრი მითითება (არ არსებობს ფენის აბსტრაქცია).
არაკოორდინირებული 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/regress მწვანე
• Cash კლავიშები/TTL, წინამორბედები
• დოკუმენტაცია და მოთხოვნის/პასუხების მაგალითები
• ალერტები SLO და კვოტებში შედის
• RG/AML შეზღუდვები შემოწმებულია

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

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

შედეგი

API ანალიტიკოსები და მეტრიკი არის კონტრაქტის, უსაფრთხო და სწრაფი ფენა ოქროს მონაცემებზე და KPI- ზე წვდომისთვის. იგი გარანტიას უწევს ერთ სემანტიკას, სტაბილურ ვერსიებს, ნაგულისხმევი კონფიდენციალურობას და პროდუქტიულობას პროდუქტის დონეზე - შიდა დაშბორდებიდან პარტნიორულ პანელებამდე და ML.