Პროვაიდერების ერთიანი API: დიზაინი, ვერსია, თავსებადობა

სტატიის სრული ტექსტი

💡 18+. ტექნიკური მასალა ინტეგრაციისა და პლატფორმის ბრძანებებისთვის. არა თამაშის მოწოდება.

1) რატომ არის „ერთი API“ და რა არის ეს

ერთი API არის ენდოინტების/მოვლენების სპეციფიკაცია და ნაკრები, რომლის მეშვეობითაც ნებისმიერი შინაარსის პროვაიდერი (RGS, ცოცხალი სტუდია, ჯეკპოტი, KYC/AML, აფილიატები) პლატფორმასთან კომუნიკაციას ახდენს ერთი წესების შესაბამისად:

ერთჯერადი რესურსების მოდელი (players, sessions, bets, settlements, bonuses, jackpots, payments), საერთო ღონისძიებების კონტრაქტები და იდენტიფიკატორები, უსაფრთხოების სტანდარტები და საპირისპირო თავსებადობა, SDK/ინსტრუმენტები ინტეგრაციის დაჩქარების მიზნით.

მიზანი: დროის შემცირება, შეცდომების შემცირება „ფულადი გზებზე“ და პროგნოზირებადი განახლება.

2) დიზაინის პრინციპები

1. Domain-first. ჯერ ლექსიკონი და ინვარიანტები (ფსონი, ნაკრები, RG ლიმიტები), შემდეგ ენდოინები.

2. Compatibility by default. ნებისმიერი ცვლილება თავსებადია; სარეკრეაციო ცვლილებები მკაცრად ხდება.

3. Idempotency everywhere. ყველა ფულადი ბრძანება განმეორებულია გვერდითი მოვლენების გარეშე.

4. Events are source of truth (განაწილებაში). ოპერაციები - მოვლენები საბურავში; ანალიტიკა უსმენს საბურავებს და არა OLTP- ს.

5. Least privilege & zero-trust. ნიშნები, ხელმოწერები, ბრენდის/რეგიონის სეგმენტი.

6. Observability. Trace _ id ', შეცდომების გასაგები მოდელი, p95/p99 მეტრიკა.

3) რესურსების მოდელი (გამარტივებული)

Player: ფსევდო-ID მოთამაშე პლატფორმის მხარეს, geo/ვალუტა/RG სტატუსები.

სესია: არხი პროვაიდერსა და პლატფორმას შორის ('session _ id', TTL, გეო/შეზღუდვები).

Bet: ავტორიზაცია/განაკვეთის დებიუტი.

Settlement: რაუნდის შედეგი და მოგების სესხი.

Bonus/Wager: ბონუსის/ვაგერის ნარჩენების მდგომარეობა.

ჯეკპოტი: შენატანები/გამომწვევი/გადახდები.

ღონისძიება: უცვლელი დომენის მოვლენები (კაფკა/ანალოგები).

იდენტიფიკატორები: 'tenant _ id', 'brand _ id', 'region', 'player _ id', 'session _ id', 'round _ id', 'bet _ id', 'settlement _ id'. ყველა - სიმებიანი, გლობალურად უნიკალური (UUID/KSUID/Snowflake), შედის ლოგოებში და მოვლენებში.

4) API კონტრაქტები: მოთხოვნები, პასუხები, შეცდომები

4. 1 საავტორო უფლებები და უსაფრთხოება

OAuth2 Client Credentials ან mTLS + მოთხოვნის სხეულის ხელმოწერა (HMAC/EdDSA).

Скоупы вида: `bets:write`, `settlements:write`, `sessions:read`, `events:publish`.

თითოეულ თხოვნას აქვს სათაურები:

`X-Trace-Id`, `X-Brand-Id`, `X-Region`, `X-Idempotency-Key`.

4. 2 ენდოინტის მაგალითები

სესიის შექმნა


POST /v1/sessions
{
"player_id":"p_19f3",  "game_id":"studio:slot_forge_02",  "currency":"EUR",  "locale":"de-DE",  "constraints":{"max_bet":5,"rg_flags":["self_exclusion":false]}
}
→ 201
{
"session_id":"s_456",  "expires_at":"2025-10-23T19:10:00Z"
}

განაკვეთის დამტკიცება


POST /v1/bets/authorize
Headers: X-Idempotency-Key: bet_r_8c12_1
{
"session_id":"s_456",  "bet_id":"b_001",  "round_id":"r_8c12",  "amount":{"amount":2. 00,"currency":"EUR"}
}
→ 200 { "status":"authorized","hold_id":"h_zz1" }

Settlent


POST /v1/bets/settle
Headers: X-Idempotency-Key: settle_r_8c12_1
{
"bet_id":"b_001",  "round_id":"r_8c12",  "win":{"amount":14. 60,"currency":"EUR"},  "bonus_state":{"in_bonus":true,"freespins_left":7}
}
→ 200 { "status":"credited","settlement_id":"st_77" }

4. 3 შეცდომები (ერთი მოდელი)

`code`: машинное имя (`RG_BLOCK`, `LIMIT_EXCEEDED`, `DUPLICATE`, `IDEMPOTENCY_MISMATCH`, `INVALID_STATE`, `AUTH_FAILED`).

'მესიჯი': მოკლედ ადამიანისთვის.

`retryable`: `true/false`.

'trace _ id': ლოგებში მოსაძებნად.

მაგალითი:


409 CONFLICT
{
"code":"DUPLICATE",  "message":"Bet already authorized with a different amount",  "retryable":false,  "trace_id":"tr_a1b2c3"
}

5) მოვლენის საბურავი და სქემები

5. 1 ძირითადი ტოპიკა

`player. registered`, `session. started	ended`
`bet. authorized	settled
`bonus. issued	consumed
`wager. progress. updated`
`jackpot. contribution	triggered
`rg. limit. hit`, `rg. reality_check`
`wallet. debit.`, `wallet. credit.`

5. 2 ღონისძიების სქემა (Avro/JSON Schema)

json
{
"event_id":"uuid",  "event_type":"bet. settled",  "occurred_at":"2025-10-23T16:21:05Z",  "tenant_id":"brand-7",  "region":"EU",  "player_id":"p_19f3",  "trace_id":"tr_a1b2c3",  "payload":{
"round_id":"r_8c12",   "bet":{"amount":1. 00,"currency":"EUR"},   "win":{"amount":14. 60,"currency":"EUR"},   "in_bonus":true
},  "idempotency_key":"bet_r_8c12_1",  "schema_version":"1. 2. 0"
}

წესები: backward-compatible სქემების ევოლუცია, რეგისტრი + საკონტრაქტო ტესტები.

6) API ვერსია: სტრატეგიები და წესები

6. 1 სად უნდა შეინახოთ ვერსია?

Path ვერსია: '/v1/... '(უბრალოდ kashing/rusting).

ჯანსაღი ვერსია: 'Accept: განაცხადი/vnd. platform. api+json; version=1. 2`.

მოვლენები: 'schema _ version' ღონისძიების სფეროში + registry.

პრაქტიკა: path HTTP, schema _ version მოვლენებისთვის, ფიჩფლაგები წერტილოვანი შესაძლებლობებისთვის.

6. 2 SemVer და ტიპის ცვლილებები

PATCH (minor) - საპირისპირო: ახალი არჩევითი ველები, ახალი endpoints, მოვლენების ახალი ტიპები.

MAJOR - breaking: ველების შეცვლა, სემანტიკის შეცვლა, მოცილება. ნებადართულია მხოლოდ ახალი '/vN/' და ძველი.

6. 3 სტაბილური კონტრაქტები

ძირითადი იდენტიფიკაციის ველების სახელები და ტიპები ('_ id', 'idempotency _ key').

ფულადი მოდელი ('amount/currency', სიზუსტე).

სტატუსის სემანტიკა ('authorized', 'credited', 'forfeited' და ა.შ.).

Idempotence: ქცევა მკაცრად განისაზღვრება გამეორებისას.

7) თავსებადობა და ევოლუცია

7. 1 დამატება (safe)

ახალი არჩევითი ველები ნაგულისხმევი.

ახალი მოვლენები/ენდოინები არსებული ცვლილების გარეშე.

enum გაფართოება fallback in 'unknown'.

7. 2 ცვლილებები

ველის ტიპის ცვლილება (ნომერი - სტრიქონი).

სავალდებულო ცვლილება (optional - required).

ბიზნესის ლოგიკის შეცვლა ('settle' ადრე 'authorize').

საჭიროა ახალი მთავარი ვერსია და მიგრაციის ჰაიდი.

7. 3 დეპრესია

ველი/ენდოინტი აღინიშნება 'deprecated _ since: 1. 7`, `removed_in: 2. 0`.

კომუნიკაცია: release notes, ბიულეტენი, deprecation headers ('Sunset', 'Deprecation').

„მოძველებული“ ბილიკების გამოყენება პარტნიორების პროაქტიული შეტყობინებებისთვის.

8) Idempotence და კოორდინაცია

სათაური 'X-Idempotency-Key' სავალდებულოა ყველა ჩანაწერის ოპერაციისთვის.

სემანტიკა: იგივე გასაღებით გამეორება - იგივე შედეგი (200 იგივე სხეულით).

გასაღებები უკავშირდება პარამეტრების კომპოზიციას (მაგალითად, 'bet _ id + amount').

გრძელი პროცესების საგები: 'authorize' commit/commit- ის settle 'credit'; კომპენსაცია - „როლბაკის“ მოვლენებით.

9) პაგინაცია, ფილტრები, დახარისხება

Cursor-based pagination (მკაცრად სასურველია „page/limit“ დიდი ნაკადებისთვის).

გაერთიანება: '? cursor =... & limit = 200 & order = asc'.

პასუხში: 'შემდეგი _ cursor', 'has _ more'.

ფილტრები: დროულად ('occurred _ at _ from/to'), 'tenant _ id', 'game _ id', 'status'.

10) ლოკალი, ვალუტა, რეზიდენტობა

ვალუტა ISO-4217; სიზუსტე ინახება სქემაში ('scale'), გამოთვლები ინახება მცირე ერთეულებში (ცენტები).

ლოკალი - BCP 47 ('en-GB', 'pt-BR').

თითოეულ თხოვნაში - 'region'; PII და ფულადი ოპერაციები არ კვეთს რეგიონებს.

PII და RLS ნიღბები BI ფანჯრებში.

11) დაკვირვება და ლიმიტები

სავალდებულო სათაურები: 'X-Trace-Id', 'X-Provider-Id', კორელაცია მოვლენებთან.

მეტრიკა: p50/p95/p99 latence, error rate (კოდებით), throughput, queue lag (მოვლენებისთვის).

Rate limits: per provider / per brand; პასუხები 'Retry-After- დან'.

კრიტიკული ცვლილებების WORM აუდიტი (ლიმიტები, RTP აუზები, ჯეკპოტის ფორმულები).

12) კონტრაქტების ტესტირება და ხარისხი

საკონტრაქტო ტესტები (Pact/სხვები): პროვაიდერი - პლატფორმა - ღონისძიების კონსუტერები.

დატვირთვა: განაკვეთების/ნაკადის „ქარიშხალი“; მიზნები p95.

ქაოსის შემთხვევები: ორმაგი მიწოდება, out-of-order, საფულის შეფერხება.

ქვიშის ყუთი '/sandbox 'ფიქტიური ფულით და ტესტის' player _ id '.

13) SDK, გენერატორები და დოკუმენტაცია

OpenAPI/AsyncAPI - SDK წარმოება (TypeScript/Java/Kotlin/Go/Rust).

კოდის მაგალითები 'authorize/settle/rollback', retrays და შეცდომების დამუშავება.

მოთხოვნა/პასუხის მაგალითებით Live Doc (curl + JSON), Postman/Insomnia კოლექციები.

Changelog ტიპის ცვლილებებით და თავსებადობის ეტიკეტებით.

14) მიგრაციის გზის რუკა (მაგალითი)

1. v1. 6 → v1. 7 (მცირე): დაამატეთ ველი 'bonus _ state' in 'settle' (optional).

2. v1. x EOL განცხადება: 6 თვის განმავლობაში - წერილი + 'Deprecation' header + dashboard.

3. v2. 0 (მაიორი): ცალკე 'wallet. commit '(ყოფილი implicit), ახალი ველი' settlement _ id 'აუცილებელია.

4. მიგრაციის ჰაიდი: ველების მაპინგი, timeline, „ორმაგი წერილის“ ფიჩფლაგი (მოვლენების პარალელური გამოცემა 'v1 '/' v2').

5. Sunset v1: ახალი ინტეგრაციების დაბლოკვა, გახანგრძლივება მხოლოდ SLA გამონაკლისით.

15) ჩეკის ფურცლები

პლატფორმის არქიტექტორებისთვის

არსებობს დომენის ერთჯერადი ლექსიკონი და ინვარიანტები.
OpenAPI/AsyncAPI + Schema Registry, semver, process დეპრესიები.
Idempotention ყველა write ოპერაციაში; კლავიშები დოკუმენტირებულია.
ერთი შეცდომა მოდელი და კოდი.
საგები და გარე/CDC ფულადი გზებზე.
უფლებები-ლიმიტები, observability, WORM აუდიტი.
ქვიშის ყუთი და საკონტრაქტო ტესტები ხელმისაწვდომია პარტნიორებისთვის.
მონაცემთა აღდგენა და RLS/შენიღბვა.

პროვაიდერისთვის

ყოველთვის გამოგიგზავნით 'X-Trace-Id' და 'X-Idempotency-Key'.

უსაფრთხოდ ვმუშაობ მოთხოვნის გამეორებას; დუბლები არ ვქმნი.

ვამუშავებ 'დეპრესიას/Sunset- ს და ვკითხულობ Changelog- ს.
საზოგადოებას/ვკითხულობ მოვლენებს რეგისტრის სქემების მიხედვით; ვერსიას შევინახავ.
მაქვს retry/backoff და ჩემს მხარეს დედუპლიკაცია.

16) ანტი-ნიმუშები (წითელი დროშები)

ბალანსების/settlement- ის ხელით რედაქტირება მონაცემთა ბაზაში.

მოვლენების გამოქვეყნება outbox/CDC.

იდემპოტენციის არარსებობა - გადახდების/დებატების დუბლირება.

PII/სხვადასხვა რეგიონის ფულის ნაზავი ეტიკეტირების 'გარეშე.

„მშვიდი“ საბურღი ცვლილებები ახალი ვერსიისა და დეპრესიის გარეშე.

SDK წარმოება ხელით (დრიფტი რეალური სპეკიდან).

დიდი ბანგის მიგრაცია ფიჩფლაგების გარეშე და მოვლენების ორმაგი წერა.

ერთი API არა მხოლოდ „ენდოინების კოლექციაა“, არამედ ეკოსისტემის ხელშეკრულება: შეთანხმებული ლექსიკონი, სტაბილური ფულადი ინვარიანტები, ვერსიით მოვლენები, თავსებადობის გასაგები წესები და კონტროლირებადი დეპრესიები. სემანტიკურ ვერსიაზე დაყრდნობით, idempotence, outbox/CDC, დაკვირვება და მკაცრი უსაფრთხოება, პლატფორმა პროვაიდერებს სწრაფად და უმტკივნეულოდ აკავშირებს, ხოლო განახლება რისკის ქვეშ გადაიქცევა რუტინად.