Provayderlar uchun yagona API: dizayn, versiya, moslik

Maqolaning to’liq matni

💡 18+. Integratsiya va platforma jamoalari uchun texnik material. O’yinga chaqirish emas.

1) «Yagona API» nima uchun va bu nima

Yagona API - bu har qanday kontent provayderi (RGS, live-studiya, jekpot, KYC/AML, affiliatlar) platforma bilan bitta qoidalar bo’yicha muloqot qiladigan o’ziga xos xususiyatlar va endpoint/voqealar to’plamidir:

yagona resurs modeli (players, sessions, bets, settlements, bonuses, jackpots, payments), hodisalarning umumiy kontraktlari va identifikatorlari, xavfsizlik va teskari muvofiqlik standartlari, SDK/integratsiyani tezlashtirish uchun vositalar.

Maqsad: vaqt-to-integratni qisqartirish, «pul yo’llari» dagi xatolarni kamaytirish va oldindan aytib bo’ladigan yangilanishlarni ta’minlash.

2) Dizayn prinsiplari

1. Domain-first. Avval lugʻat va invariantlar (stavka, settlment, RG limitlari), keyin endpointlar.

2. Compatibility by default. Har qanday oʻzgarish andoza; breaking-o’zgarishlar qat’iy jarayon bo’yicha.

3. Idempotency everywhere. Barcha pul buyruqlari nojo’ya ta’sirlarsiz takrorlanadi.

4. Events are source of truth (distributsiyada). Shina operatsiyalari → voqealar; tahlilchi OLTPni emas, balki shinani tinglaydi.

5. Least privilege & zero-trust. Brend/mintaqa bo’yicha tokenlar, imzolar, segmentatsiya.

6. Observability. ’trace _ id’ orqali, xatolarning tushunarli modeli, p95/p99 metrikasi.

3) Resurs modeli (soddalashtirilgan)

Player: platforma tomonidagi psevdo-ID o’yinchisi, geo/valyuta/RG maqomlari.

Session: provayder va platforma orasidagi kanal (’session _ id’, TTL, geo/cheklovlar).

Bet: avtorizatsiya/debet stavkasi.

Settlement: raund natijasi va yutuq krediti.

Bonus/Wager: veyjer bonus/qoldiq holati.

Jackpot: badallar/triggerlar/to’lovlar.

Event: oʻzgarmas domen hodisalari (Kafka/analoglar).

Identifikatorlar:’tenant _ id’,’brand _ id’,’region’,’player _ id’,’session _ id’,’round _ id’,’bet _ id’,’settlement _ id’. Hamma - butun dunyo bo’ylab noyob (UUID/KSUID/Snowflake), loglar va hodisalarga kiritiladi.

4) API kontraktlari: so’rovlar, javoblar, xatolar

4. 1 Avtorizatsiya va xavfsizlik

OAuth2 Client Credentials yoki mTLS + soʻrov tanasining imzosi (HMAC/EdDSA).

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

Har bir so’rovda quyidagi sarlavhalar bo’lishi shart:

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

4. 2 Endpoint namunalari

Sessiyani yaratish


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

Avtorizatsiya stavkasi (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" }

Settlement


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 Xatolar (yagona model)

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

’message’: odam uchun qisqacha.

`retryable`: `true/false`.

’trace _ id’: qidirish uchun.

Misol:


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

5) Hodisa shinasi va sxemalari

5. 1 Asosiy topiklar

`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 Hodisa sxemasi (Euro/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"
}

Qoidalar: sxemalarning backward-compatible evolyutsiyasi, registry + kontrakt testlari.

6) API versiyasi: strategiya va qoidalar

6. 1 Versiyani qayerda saqlash kerak

Path versiyasi: ’/v1/...’(shunchaki kesh/yoʻnaltirish).

Header versiyasi:’Accept: application/vnd. platform. api+json; version=1. 2`.

Hodisalar:’schema _ version’hodisa maydonida + registry.

Amaliyot: HTTP uchun path, voqealar uchun schema_version, nuqta imkoniyatlari uchun fichflaglar.

6. 2 SemVer va oʻzgarishlar turlari

PATCH (minor) - teskari ulanish: yangi ixtiyoriy maydonlar, yangi endpointlar, yangi hodisa turlari.

MAJOR - breaking: maydonlarning nomini oʻzgartirish, semantikasini oʻzgartirish, olib tashlash. Faqat yangi ’/vN/’ va eskisini deprekatsiya qilish orqali ruxsat etiladi.

6. 3 Barqaror shartnomalar (nimani buzish mumkin emas)

Identifikatsiyaning asosiy maydonlari nomi va turlari (’_ id’,’idempotency _ key’).

Pul modeli (’amount/currency’, aniqlik).

Maqomlar semantikasi (’authorized’,’credited’,’forfeited’va boshqalar).

Idempotentlik: takrorlanishdagi xulq-atvor qat’iy belgilangan.

7) Muvofiqlik va evolyutsiya

7. 1 Qoʻshiqlar (safe)

Defoltli yangi ixtiyoriy maydonlar.

Mavjudlarini oʻzgartirmasdan yangi voqealar/endpointlar.

’unknown’ uchun fallback bilan enumni kengaytirish.

7. 2 Oʻzgarishlar (risky)

Maydon turini oʻzgartirish (raqam → satr).

Majburiyatni oʻzgartirish (optional → required).

Biznes mantiqining burilishi (’settle’oldin’authorize’).

→ Yangi major versiyasi va migratsiya g’oyasi talab etiladi.

7. 3 Deprekatsiya

Maydon/endpoint’deprecated _ since: 1 bilan belgilanadi. 7`, `removed_in: 2. 0`.

Kommunikatsiya: release notes, tarqatish, deprecation-headers («Sunset», «Deprecation»).

Sheriklarni proaktiv xabardor qilish uchun «eskirgan» yoʻllardan foydalanish.

8) Idempotentlik va kelishuv

’X-Idempotency-Key’ sarlavhasi barcha yozuvchi operatsiyalar uchun majburiydir.

Semantika: bir xil kalit bilan takrorlash → bir xil natija (avvalgi body bilan 200).

Kalitlar moslamalar tarkibiga bogʻlangan (masalan,’bet _ id + amount’).

’authorize → commit/lock → settle → credit’; kompensatsiyalar - «rollback» hodisalari bilan.

9) Paginatsiya, filtrlar, saralash

Cursor-based paginatsiya (katta oqimlar uchun’page/limit’dan qat’iy afzal).

Unifikatsiya:’? cursor =... & limit = 200 & order = asc’.

Javobda:’next _ cursor’,’has _ more’.

Filterlar: vaqt boʻyicha (’occurred _ at _ from/to’),’tenant _ id’,’game _ id’,’status’.

10) Lokallar, valyutalar, ma’lumotlarning rezidentligi

Valyuta ISO-4217; aniqlik sxemada (’scale’), hisob-kitoblar minor-units (cents) da saqlanadi.

Lokallar - BCP 47 (’en-GB’,’pt-BR’).

Har bir so’rovda -’region’; PII va pul operatsiyalari hududlarni kesib o’tmaydi.

BI vitrinalarida PII va RLS niqoblash.

11) Kuzatuvchanlik va limitlar

Majburiy sarlavhalar:’X-Trace-Id’,’X-Provider-Id’, voqealar bilan bog’lanish.

Metriklar: p50/p95/p99 latency, error rate (kodlar boʻyicha), throughput, queue lag (hodisalar uchun).

Rate limits: per provider / per brand; ’Retry-After’ bilan javoblar.

Muhim o’zgarishlarning WORM auditi (limitlar, RTP-pullar, jekpot formulalari).

12) Test sinovlari va kontraktlarning sifati

Kontrakt testlari (Pact/boshqalar): provayder, platforma, konsumerlar.

Yuklamali: stavkalar/settlementlar «bo’roni»; p95 maqsadlari.

Xaos-keyslar: dubl-yetkazib berish, out-of-order, hamyonni kechiktirish.

Qum qutisi ’/sandbox’soxta pul va test’player _ id’bilan.

13) SDK, generatorlar va hujjatlar

OpenAPI/AsyncAPI → SDK (TypeScript/Java/Kotlin/Go/Rust).

’authorize/settle/rollback’, retraylar va xatolarni qayta ishlash uchun kod namunalari.

So’rov/javob (curl + JSON), Postman/Insomnia to’plami namunalarini o’z ichiga olgan Live-doc.

Changelog o’zgarishlar turi va moslik belgilari bilan.

14) Migratsiyaning yo’l xaritasi (misol)

1. v1. 6 → v1. 7 (minor):’bonus _ state’ga’settle’(optional) qoʻshilgan.

2. v1. x EOL e’lon: 6 oy uchun - xat +’Deprecation’header + foydalanish dashbordi.

3. v2. 0 (major): alohida’wallet. commit’(ilgari implicit), yangi’settlement _ id’maydoni majburiy.

4. Migratsiya gidi: maydonlarning mappingi, timeline, «ikki xat» fichflagi («v1 »/« v2» voqealarni parallel ravishda e’lon qilish).

5. Sunset v1: yangi integratsiyalarni blokirovka qilish, faqat SLA istisnolari boʻyicha uzaytirish.

15) Chek-varaqlar

Platforma arxitektorlari uchun

Domen mavjudotlari va invariantlarning yagona lug’ati mavjud.
OpenAPI/AsyncAPI + Schema Registry, semver, process depreksiya.
Barcha write-operatsiyalarda idempotentlik; kalitlar hujjatlashtirilgan.
Yagona xato modeli va kodlari.
Pul yo’llarida saga va outbox/CDC.
Rate-limits, observability, WORM-audit.
Qum qutisi va shartnoma testlari hamkorlar uchun mavjud.
Data residency va RLS/maskalash.

Provayder uchun

Men’X-Trace-Id’va’X-Idempotency-Key’ni doimo yuboraman.
Takroriy so’rovlarni xavfsiz qayta ishlayman; dubli yaratmayman.
Men’Deprecation/Sunset’ni qayta ishlayman va Changelog’ni o’qiyman.
Registry sxemalari bo’yicha voqealarni e’lon qilaman/o’qiyman; versiyasini saqlayman.
Men retry/backoff va deduplikatsiyam bor.

16) Anti-patternlar (qizil bayroqlar)

DBda balanslar/settlementlarni qo’lda tuzatish.

outbox/CDC «oʻtib ketgan» voqealarni nashr etish.

idempotency → ikki baravar to’lov/debet yo’qligi.

«region» belgisiz turli mintaqalarning PII/pullarini aralashtirish.

«Jim» breaking-oʻzgarishlar yangi versiyasiz va deprekatsiyasiz.

SDKni qo’lda ishlab chiqarish (haqiqiy spekadan dreyf).

Big-bang migratsiyasi fichflaglarsiz va ikki marta xatsiz.

Yagona API - bu nafaqat «endpointlar to’plami», balki ekotizim kontrakti: kelishilgan lug’at, barqaror pul invariantlari, versiyalashtirilgan voqealar, tushunarli muvofiqlik qoidalari va boshqariladigan depreksiya. Semantik versiya, idempotentlik, outbox/CDC, kuzatuv va qat’iy xavfsizlik asosida platforma provayderlarni tez va og’riqsiz ulaydi, yangilanishlar esa xavfdan odatiy holga aylanadi.