Միասնական API պրովայդերների համար 'դիզայն, տարբերակը, համատեղելիությունը

Հոդվածի ամբողջական տեքստը

💡 18+. Նշված նյութը ինտեգրալ և պլատֆորմային թիմերի համար։ Խաղի կոչը չէ։

1) Ինչու՞ «միասնական API» և ի՞ նչ է դա։

Միասնական API-ն էնդպոինտների/իրադարձությունների առանձնահատկությունն է, որի միջոցով ցանկացած բովանդակության պրովայդեր (RGS, նախկին ստուդիա, ջեքպոտ, KYC/AML, աֆֆիլիատներ) հաղորդակցվում է պլատֆորմի հետ մեկ կանոնով

միասնական ռեսուրս մոդել (players, sessions, bets, settlements, bonuses, jackpots, payments), իրադարձությունների ընդհանուր պայմանագրեր և ցուցանիշներ, անվտանգության և հետադարձ համակարգեր, SDK/գործիքներ ինտեգրումը արագացնելու համար։

Նպատակը 'կրճատել Time-to-integrate-ը, նվազեցնել սխալները «փողի ուղիների» վրա և ապահովել կանխատեսելի ապգրադներ։

2) Դիզայնի սկզբունքները

1. Domain-first. Սկզբում բառարանն ու ինվարանտները (տոկոսադրույքը, ցանցաթաղանթը, RG լիմիտները), հետո էնդպոինտները։

2. Compatibility by default. Ցանկացած փոփոխություն լռելյայն համատեղելի է։ breaking-փոփոխությունները խստորեն գործընթացով։

3. Idempotency everywhere. Բոլոր դրամական թիմերը կրկնվում են առանց կողմնակի էֆեկտների։

4. Events are source of truth (բաշխման մեջ)։ Վիրահատությունները կատարվում են անվադողերի մեջ։ վերլուծությունը լսում է անվադողը, ոչ թե OLTP-ն։

5. Least privilege & zero-trust. Տոկենները, ստորագրությունները, բրենդի/տարածաշրջանի հատվածները։

6. Observability. «Trace _ id» -ի միջոցով, հասկանալի սխալների մոդել, p95/p99 չափումներ։

3) Ռեսուրսային մոդել (պարզեցված)

Player: կեղծ-ID խաղացողը պլատֆորմի, գեո/արժույթի/RG կարգավիճակի կողմում։

Session: պրովայդերի և պլատֆորմի միջև («session _ id», TTL, geo/սահմանափակումներ)։

Bet: հեղինակային իրավունքի/տոկոսադրույքի բանավեճը։

Settlant: Մրցույթի արդյունքը և շահույթի վարկը։

Bonus/Wager ՝ բոնուսի վիճակը/վեյջերի մնացորդը։

Jackpot: 108/տրիգերներ/վճարումներ։
Event: անփոփոխ հիբրիդային իրադարձություններ (Kafka/անալոգներ)։

Ցուցիչները ՝ «tenrone _ id», «brand _ id», «region», «player _ id», «session _ id», «round _ id», «bet _ id», «settlect _ id»։ Բոլորը կառուցվածքային, գլոբալ յուրահատուկ են (UUID/KSUID/Winowflake), ներառված են լոգներում և իրադարձություններում։

4) API պայմանագրերը 'հարցումներ, պատասխաններ, սխալներ

4. 1 Հեղինակային իրավունքի և անվտանգության

OAuth2 Credentials-ը կամ mTSA + հարցման մարմնի ստորագրությունը (HMAC/EddDSA)։

Скоупы вида: `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"
}

Տոկոսադրույքի հեղինակային իրավունքը (hold)


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" }

Սեթլմենտը


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`).

"07 'հակիրճ մարդու համար։

`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-ի սխեմաների էվոլյուցիա, registry + պայմանագրային թեստեր։

6) API տարբերակը 'ռազմավարություն և կանոններ

6. 1 Որտեղ պահել տարբերակը

Path-տարբերակը '«/v1/... »(պարզապես կեշալիզացնել/ուղղել)։

Header տարբերակը '"Accept: Accept: applics/vnd. platform. api+json; version=1. 2`.

Իրադարձությունները '«schema _ version» իրադարձության դաշտում + registry։

Պրակտիկա 'path HTP, schema _ version իրադարձությունների համար, ֆիչֆլագներ կետային հնարավորությունների համար։

6. 2 SemVer-ը և փոփոխության տեսակները

PATCH (minor) - հակադարձող դաշտեր, նոր էնդպոինտներ, նոր տեսակի իրադարձություններ։

MAJOR-breaking-ը 'դաշտերի փոխակերպումը, սեմանտիկայի փոփոխությունը, հեռացումը։ Թույլատրված է միայն նոր '/vN/' և հին։

6. 3 Կայուն պայմանագրեր (որը չի կարելի կոտրել)

Հայտնաբերման հիմնական դաշտերի անունները և տեսակները («_ id», «idempotency _ key»)։

Դրամական մոդել («amount/currency», ճշգրտությունը)։
Կարգավիճակների սեմանտիկան («authorized», «credited», «forfeited» և այլն)։
Idempotention 'վարքը կրկնելիս խստորեն որոշվում է։

7) Համատեղելիություն և էվոլյուցիա

7. 1 Ավելացում (safe)

Նոր միգրացիոն դաշտեր դեֆոլտներով։

Նոր իրադարձություններ/էնդպոինտներ առանց գոյություն ունեցող փոփոխությունների։
Enum-ից fallback-ի ընդլայնումը «unknown» -ում։

7. 2 Փոփոխություն (risky)

Դաշտի տեսակի փոփոխությունը (երկարաժամկետ տողի քանակը)։

Պարտավորության փոփոխությունը (optional no required)։
Բիզնեսի տրամաբանության զարգացումը («settle» նախկինում «authorize»)։
պետք է նոր մաժոր տարբերակ և միգրացիոն դելդ։

7. 3 Դեպրեսիա

Դաշտը/էնդպոինտը տեղադրվում է "deprecated _ since: 1։ 7`, `removed_in: 2. 0`.

Հաղորդակցություն ՝ rele.notes, ուղարկում, deprecation-headers («Sunset», «Deprecation»)։

«Հնացած» ճանապարհների օգտագործման ուղին գործընկերների ակտիվ ծանուցումների համար։

8) Գաղափարախոսություն և ներդաշնակություն

«X-Idempotency-Key» վերնագիրը պարտավորված է բոլոր ձայնագրող վիրահատությունների համար։

Սեմանտիկան 'նույն բանալին կիսողը նույն արդյունքն է (200-ը նախկին body-ով)։
Բանալիները կապված են կոմպոզիցիայի հետ (օրինակ ՝ «bet _ id + amount»)։
Սագին երկար գործընթացների վրա '«authorize no commit/wwww.k settle no credit»; փոխհատուցումը «rollback» իրադարձություններն են։

9) Պագինացիա, ֆիլտրեր, տեսակավորում

Cursor-based (խիստ նախընտրելի է «page/limit» մեծ հոսքերի համար)։

Միավորում: ։
Պատասխանը '«next _ cursor», «has _ more»։
Ֆիլտրեր ՝ ժամանակի ընթացքում («occurred _ at _ from/to»), «tenom _ id», «game _ id», «status»։

10) Լոկալին, արժույթը, տվյալների նստավայրը

Արժույթը RF-2417-ում; ճշգրտությունը պահվում է սխեմայում («scale»), հաշվարկները 'minor-units (cents)։

Lokali-BCP 47 («en-GB», «pt-III»)։

Յուրաքանչյուր հարցում '«region»; PII-ը և դրամական վիրահատությունները չեն հատում տարածքները։

PII և RFC-ի դիմակավորում BI վիտրիններում։

11) Դիտողությունն ու սահմանները

Պարտադիր վերնագրերը ՝ «X-Trace-Id», «X-Provider-Id», հարաբերակցությունը իրադարձությունների հետ։

Մետրիկները ՝ p50/p95/p99 latency, error rate (կոդերով), throughput, queue lag (իրադարձությունների համար)։
Rate limits: per provider / per brand; պատասխաններ '«Retry-After»։
Քննադատական փոփոխությունների WORM-աուդիտը (limits, RTP-puls, ջեքպոտի բանաձևը)։

12) Փորձարկումներ և շարժիչների որակը

Պայմանագրային թեստերը (Pact/այլ) 'պրովայդեր տեխնոլոգիական պլատֆորմը։

Բեռները ՝ «փոթորիկ» 108/ցանցաթաղանթի; նպատակներ p95։
Քաոս Քեյս 'դուբլ առաքում, out-of-order, դրամապանակի ուշացում։
Ավազը '/sandbox 'ֆիքսված փողերով և թեստային «player _ id»։

13) MSK, գեներատորներ և կոմպոզիցիաներ

OpenAPI/AsyncAPI-ը նկարագրում է SDK (WindoScript/Java/Kotlin/Go/Rust)։

Կոդի օրինակները 'authorize/settle/rollback ", ռելսերի և սխալների մշակման համար։
Օրինակ, Pro-dook-ը/պատասխանը (curl + JSON), Postman/Insomnia հավաքածուները։
Changelog տեսակի փոփոխություններով և պիտակներով։

14) Միգրացիայի ճանապարհային քարտեզը (օրինակ)

1. v1. 6 → v1. 7 (minor) 'ավելացրեցինք «bonus _ state» դաշտը «settle» (optional)։

2. v1. X EOL-ի հայտարարությունը '6 ամսվա ընթացքում + Deprecation 'header + dashbord։

3. v2. 0 (major) 'առանձին' wallet։ commit '(նախկինում implicit), նոր դաշտ' settlection _ id 'պարտադիր։

4. Միգրացիոն դելդ 'դաշտերի, timeline, ficflag «կրկնակի նամակի» (զուգահեռ «v1 »/« v2» իրադարձությունների)։

5. Sunset v1 'նոր ինտեգրիաների արգելափակում, միայն SLA բացառություններով երկարացում։

15) Չեկ թերթերը

Պլատֆորմի ճարտարապետների համար

Գոյություն ունի հիբրիդային էակների և ինվարանտների մի բառարան։
OpenAPI/AsyncAPI + Schema Registry, semver, դեպրեսիայի process։
Idempotenty բոլոր write վիրահատություններում; բանալիները փաստաթղթավորված են։
Մեկ սխալ մոդել և կոմպոզիցիա։
Սագին և www.box/CDC դրամական ճանապարհների վրա։
Rate-limits, observability, WORM-աուդիտ։
Ավազը և պայմանագրային թեստերը հասանելի են գործընկերներին։
Diresidency և RFC/դիմակավորում։

Պրովայդերի համար

Ես գնում եմ "X-Trace-Id 'և" X-Idempotency-Key "միշտ։
Հարցումների կրկնությունը անվտանգ է. դուբլի չեմ ստեղծում։
Ես մշակում եմ «Deprecation/Sunset» և կարդում եմ Changelog։
Հանդիսատեսը/կարդում եմ իրադարձությունները ըստ registry սխեմաների։ պահում եմ տարբերակը։
Ես ունեմ retry/backoff և deduplication իմ կողմում։

16) Anti-patterns (կարմիր դրոշներ)

Հավասարակշռությունների/ցանցաթաղանթի ձեռքով ուղղությունները BD-ում։

Իրադարձությունների հրապարակումը «անցնելով» www.box/CDC-ն։
Idempotency-ի բացակայությունը բացատրում է 2019/բանավեճերի դուբլները։
PII/տարբեր տարածաշրջանների փողի խառնուրդը առանց «region» մակնշման։
«Հանգիստ» breaking-փոփոխությունը առանց նոր տարբերակի և տեղաբաշխման։
MSK-ի գեներացիան ձեռքով (իրական սպեկուլյացիայից)։
Box-bang-ը պատրաստված է առանց ֆիչֆլագների և իրադարձությունների կրկնակի նամակի։

Միասնական API-ն ոչ միայն «էնդպոինտների հավաքածու» է, այլ էկոհամակարգի պայմանագիրը 'համաձայնեցված բառարան, կայուն դրամական ինվարանտներ, իրադարձություններ տարբերակման, հասկանալի կանոնների և կառավարվող ավանդների հետ։ Հիմնվելով սեմանտիկ տարբերակի վրա, գաղափարախոսությունը, box/CDC-ն, դիտարկումը և խիստ անվտանգությունը, պլատֆորմը միացնում է պրովայդերներին արագ և ցավալի, իսկ դեղագործները վերածվում են ռիսկի։