Üpjün edijiler üçin ýeke-täk API: dizaýn, wersiýa, laýyklyk

Makalanyň doly teksti

💡 18+. Integrasiýa we platforma toparlary üçin tehniki material. Oýnamaga çagyryş ýok.

1) Näme üçin "ýeke-täk API" we bu näme?

Ýeke-täk API, islendik mazmun üpjün edijisiniň (RGS, live-studiýa, jekpot, KYC/AML, affiliates) platforma bilen bir düzgün boýunça aragatnaşyk saklaýan aýratynlyklarydyr:

ýeke-täk çeşme modeli (players, sessions, bets, settlements, bonuses, jackpots, payments), wakalaryň umumy şertnamalary we kesgitleýjiler, howpsuzlyk we ters laýyklyk standartlary, SDK/integrasiýany çaltlaşdyrmak üçin gurallar.

Maksat: wagt-integrate azaltmak, "pul ýollaryndaky" ýalňyşlyklary azaltmak we öňünden aýdyp boljak täzelenmeleri üpjün etmek.

2) Dizaýn ýörelgeleri

1. Domain-first. Ilki sözlük we alternatiwalar (stawka, düzüliş, RG çäkleri), soň bolsa endpointler.

2. Compatibility by default. Islendik üýtgeşme - adaty gabat gelýär; breaking-üýtgeşmeler.

3. Idempotency everywhere. Pul buýruklarynyň hemmesi zyýanly täsirleri bolmazdan gaýtalanýar.

4. Events are source of truth (paýlanyşda). Teker amallary → wakalar; analitika ALTP-ni urman, tekeri diňleýär.

5. Least privilege & zero-trust. Bellikler, gollar, marka/sebit boýunça segmentasiýa.

6. Observability. Geçiş 'trace _ id', ýalňyşlyklaryň düşnükli modeli, metrika p95/p99.

3) Çeşme modeli (ýönekeýleşdirilen)

Oýunçy: platforma tarapynda oýunçynyň pseudo-ID, geo/walýuta/RG statuslary.

Session: üpjün ediji bilen platformanyň arasyndaky kanal ('session _ id', TTL, geo/çäklendirmeler).

Bet: awtorizasiýa/jedel debeti.

Settlement: tapgyryň netijesi we ýeňiş karzy.

Bonus/Wager: Wajer bonusynyň/balansynyň ýagdaýy.

Jackpot: goşantlar/triggerler/tölegler.

Event: üýtgemeýän domen hadysalary (Kafka/analoglar).

Identifikatorlary: 'tenant _ id', 'brand _ id', 'region', 'player _ id', 'session _ id', 'round _ id', 'bet _ id', 'settlement _ id'. Hemmeler - setirli, global taýdan üýtgeşik (UUID/KSUID/Snowflake), girelgelere we wakalara goşulýar.

4) API şertnamalary: haýyşlar, jogaplar, ýalňyşlyklar

4. 1 Ygtyýarnama we howpsuzlyk

OAuth2 Client Credentials ýa-da mTLS + haýyşnamanyň bedeniniň goly (HMAC/EdDSA).

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

Her haýyşda aşakdaky sözbaşylar hökmanydyr:

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

4. 2 Endpointleriň mysallary

Sessiýa döretmek


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

Nyrhy ygtyýarlandyrmak (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 Ýalňyşlyklar (ýekeje model)

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

'message': adam üçin gysgaça.

`retryable`: `true/false`.

'trace _ id': loglarda gözlemek üçin.

Mysal:


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

5) Waka şinasy we shemalary

5. 1 Esasy topikler

`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 Wakanyň shemasy (Ýewro/JSON Shema)

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

Düzgünler: backward-compatible ewolýusiýa shemalary, registry + şertnama synaglary.

6) API wersiýasy: strategiýalar we düzgünler

6. 1 Wersiýany nirede saklamak

Path-wersiýasy: '/v1/... '(diňe kesmek/ugrukdyrmak).

Header-wersiýasy: 'Accept: application/vnd. platform. api+json; version=1. 2`.

Wakalar: 'schema _ version' waka meýdançasynda + registry.

Amal: HTTP üçin path, wakalar üçin schema_version, nokat mümkinçilikleri üçin fiçflaglar.

6. 2 SemVer we üýtgeşmeleriň görnüşleri

PATCH (minor) - tersine birikdirilen: täze goşmaça meýdanlar, täze endpointler, wakalaryň täze görnüşleri.

MAJOR - breaking: meýdanlary üýtgetmek, semantikany üýtgetmek, aýyrmak. Diňe täze '/vN/' we köne deprekasiýa arkaly rugsat berilýär.

6. 3 Durnukly şertnamalar (näme bozmaly däl)

Kesgitleýiş meýdançalarynyň atlary we görnüşleri ('_ id', 'idempotency _ key').

Pul modeli ('amount/currency', takyklyk).

Status semantikasy ('authorized', 'credited', 'forfeited' we ş.m.).

Idempotentlik: gaýtalananda özüni alyp barşy berk kesgitlenendir.

7) Gabat gelmek we ewolýusiýa

7. 1 Goşmaçalar (safe)

Defoltly täze goşmaça meýdanlar.

Bar bolan wakalary üýtgetmezden täze wakalar/endpointler.

'unknown' -da fallback bilen enum giňeldildi.

7. 2 Üýtgeşmeler (risky)

Meýdanyň görnüşini üýtget (san → setir).

Borçlylygy üýtgetmek (optional → required).

Iş logikasynyň tersi ('settle' öň 'authorize').

→ Täze esasy wersiýa we migrasiýa gollanmasy talap edilýär.

7. 3 Deprekasiýa

Meýdan/endpoint 'deprecated _ since: 1. 7`, `removed_in: 2. 0`.

Aragatnaşyk: release notes, iberiş, deprecation-headers ('Sunset', 'Deprecation').

Hyzmatdaşlaryň proaktiw habarnamalary üçin "köne" ýollaryň ulanylyşyny yzarlamak.

8) Idempotentlik we ylalaşyklylyk

"X-Idempotency-Key" sözbaşysy ýazga alýan ähli amallar üçin hökmanydyr.

Semantika: şol bir açar bilen gaýtalamak → şol bir netije (öňki body bilen 200).

Açarlar parametrleriň kompozisiýasyna birikdirildi (mysal üçin 'bet _ id + amount').

Saglar: 'authorize → commit/lock → settle → credit'; öwezini dolmak - 'rollback' wakalary.

9) Paginasiýa, süzgüçler, sortlamak

Cursor-based pagination (uly akymlar üçin 'page/limit' -den has gowy).

Birleşdirmek: '? cursor =... & limit = 200 & order = asc'.

Jogap: 'next _ cursor', 'has _ more'.

Süzgüçler: Wagt boýunça ('occurred _ at _ from/to'), 'tenant _ id', 'game _ id', 'status'.

10) Lokallar, walýutalar, maglumatlaryň rezidentligi

Pul ISO-4217; takyklygy shemada saklanýar ('scale'), hasaplamalar - minor-units (cents).

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

Her soragnamada - 'region'; PII we pul amallary sebitlerden geçmeýär.

BI penjirelerinde PII we RLS gizlemek.

11) Gözegçilik etmek we çäklendirmeler

Hökmany sözbaşylar: 'X-Trace-Id', 'X-Provider-Id', wakalar bilen baglanyşyk.

Metrikler: p50/p95/p99 latency, error rate (kodlar boýunça), throughput, queue lag (wakalar üçin).

Rate limits: per provider / per brand; 'Retry-After' -den jogaplar.

Möhüm üýtgeşmeleriň WORM-barlagy (çäkler, RTP-howuzlar, jekpot formulalary).

12) Synagdan geçirmek we şertnamalaryň hili

Şertnamalaýyn synaglar (Pact/başgalar): Üpjün edijiniň platformasydyr.

Ýükleýiş: stawkalaryň/settlementleriň "tupany"; p95 maksatlary.

Bulam-bujarlyk: goşa eltip bermek, out-of-order, gapjygyň gijikdirilmegi.

Sandbox '/sandbox 'toslama pul we test' player _ id '.

13) SDK, generatorlar we resminamalar

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

'authorize/settle/rollback', retrailer we ýalňyşlyklary bejermek üçin kod mysallary.

Haýyş/jogap (curl + JSON), Postman/Insomnia kolleksiýalarynyň mysallary bilen Live-dok.

Changelog üýtgeýiş görnüşleri we gabat geliş bellikleri bilen.

14) Migrasiýa ýol kartasy (mysal)

1. v1. 6 → v1. 7 (minor): 'bonus _ state' -ni 'settle' -a (optional) goşduk.

2. v1. x EOL bildiriş: 6 aý üçin - hat + 'Deprecation' header + ulanyş daşbordy.

3. v2. 0 (major): aýratyn 'wallet. commit '(öň implicit), täze' settlement _ id 'meýdany hökmanydyr.

4. Migrasiýa gollanmasy: meýdan mapping, timeline, "goşa hat" fiçflagy ('v1 '/' v2' wakalarynyň paralel çap edilmegi).

5. Sunset v1: täze integrasiýalary bloklamak, diňe SLA kadadan çykmalar boýunça uzaltmak.

15) Çek-listler

Platforma arhitektorlary üçin

Domen jandarlarynyň we üýtgeşiklikleriniň ýekeje sözlügi bar.
OpenAPI/AsyncAPI + Schema Registry, semver, kazyýet işi.
Ähli write-amallarda görelde; açarlar resminamalaşdyryldy.
Bir hata-model we kodlar.
Pul ýollarynda saglar we outbox/CDC.
Rate-limits, observability, WORM-audit.
Gum gutusy we şertnama synaglary hyzmatdaşlar üçin elýeterlidir.
Data residency we RLS/gizlemek.

Üpjün ediji üçin

Iberýärin 'X-Trace-Id' we 'X-Idempotency-Key' hemişe.
Haýyşlaryň gaýtalanmagyny howpsuz gaýtadan işleýärin; dubli döretmeýärin.
'Deprecation/Sunset' -i bejerýärin we Changelog okaýaryn.
Registry shemalary boýunça wakalary çap edýärin/okaýaryn; wersiýasyny saklaýaryn.
Öz tarapymda retry/backoff we de duplikasiýa bar.

16) Anti-pattern (gyzyl baýdaklar)

DB-daky balanslaryň/settlementleriň el bilen düzedilmegi.

Outbox/CDC "öňünden" wakalary çap etmek.

idempotency → iki gezek tölegleriň/debetleriň ýoklugy.

Dürli sebitleriň PII/pullaryny 'region' belligi bolmazdan garyşdyrmak.

Täze wersiýa we deprekasiýa bolmazdan "sessiz" breaking-üýtgeşmeler.

El bilen SDK döretmek (hakyky spekadan süýşmek).

Big-bang göçmek fichflag we goşa hat hadysasyz.

Ýeke-täk API diňe bir "endpointleriň ýygyndysy" däl, eýsem ekosistemanyň şertnamasy: ylalaşylan sözlük, durnukly pul üýtgemeleri, wersiýalaşdyryş wakalary, düşnükli laýyklyk düzgünleri we dolandyrylyp bilinýän deprekasiýa. Semantik wersiýa, idempotentlik, outbox/CDC, gözegçilik we berk howpsuzlyk esasynda platforma üpjün edijileri çalt we agyrysyz birikdirýär we täzelenmeler töwekgelçilikden adaty ýagdaýa öwrülýär.