Камсыздоочулар үчүн бирдиктүү API: дизайн, версия, шайкештик

Макаланын толук тексти

💡 18+. Интеграциялык жана платформалык командалар үчүн техникалык материал. оюнга чакыруу эмес.

1) Эмне үчүн "бирдиктүү API" жана бул эмне

Бирдиктүү API - бул ар кандай мазмун провайдери (RGS, Live Studio, Jackpot, KYC/AML, аффилиаттар) бир эреже боюнча платформа менен байланыша турган өзгөчөлүктөр жана иш-чаралар топтому:

бирдиктүү ресурстук модели (players, sessions, bets, settlements, bonuses, jackpots, payments), жалпы иш-чаралар келишимдер жана идентификаторлор, коопсуздук жана кайра шайкештик стандарттары, SDK/интеграцияны тездетүү үчүн куралдар.

Максаты: убакыт-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: платформа тарапта psevdo-ID оюнчу, гео/акча/RG статусу.

Session: провайдер менен платформанын ортосундагы канал ('session _ id', TTL, гео/чектөөлөр).

Bet: авторизация/дебет коюм.

Settlement: раунддун жыйынтыгы жана утуш кредити.

Bonus/Wager: бонус/Vajer калдыгы абалы.

Jackpot: салымдар/триггерлер/төлөмдөр.

Event: өзгөрүлбөс домендик окуялар (Kafka/аналогдор).

Идентификаторлор: '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"
}

Ченди авторизациялоо (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`).

'message': адам үчүн кыскача.

`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 Окуя схемасы (Euro/JSON схемасы)

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 Version: '/v1/... '(жөн гана кэш/багыттоо).

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

Окуялар: 'schema _ version' окуя талаасында + registry.

Практика: HTTP үчүн жол, окуялар үчүн schema_version, чекиттик мүмкүнчүлүктөр үчүн фичфлагдар.

6. 2 SemVer жана өзгөртүү түрлөрү

PATCH (minor) - кайра туташтыруучу: жаңы кошумча талаалар, жаңы эндпоинттер, окуялардын жаңы түрлөрү.

MAJOR - breaking: талааларды атын өзгөртүү, семантиканы өзгөртүү, алып салуу. Жаңы '/vN/' жана эскинин депрекациясы аркылуу гана уруксат берилет.

6. 3 Туруктуу келишимдер (бузууга мүмкүн эмес)

Негизги аныктоо талааларынын аттары жана түрлөрү ('_ id', 'idempotency _ key').

Акча модели ('amount/currency', тактык).

Статустардын семантикасы ('authorized', 'credited', 'forfeited' ж.б.).

Демпотенттик: кайталоодо жүрүм-турум катуу аныкталган.

7) шайкештик жана эволюция

7. 1 толуктоолор (safe)

демейки менен жаңы кошумча талаалар.

Жаңы окуялар/эндпоинттер бар өзгөрүүсүз.

'unknown' жылы fallback менен enum узартуу.

7. 2 өзгөртүүлөр (risky)

Талаанын түрүн өзгөртүү (сан → сап).

Милдеттүүлүктү өзгөртүү (optional → required).

Бизнес-логиканын бурулушу ('settle' мурда 'authorize').

→ жаңы негизги версия жана миграциялык жол талап кылынат.

7. 3 Депрекация

Талаа/эндпоинт 'deprecated _ since деп белгиленет: 1. 7`, `removed_in: 2. 0`.

Байланыш: release notes, жөнөтүү, deprecation-headers ('Sunset', 'Deprecation').

Өнөктөштөрдүн проактивдүү билдирүүлөрү үчүн "эскирген" жолдорду колдонуу.

8) Идемпотенттүүлүк жана ырааттуулук

'X-Idempotency-Key' аталышы бардык жазуу операциялары үчүн милдеттүү.

Семантика: ошол эле ачкыч менен кайталоо → ошол эле натыйжа (200 мурунку дене менен).

Ачкычтар параметрлердин композициясына байланган (мисалы, 'bet _ id + amount').

узун процесстер боюнча сагалар: 'authorize → commit/lock → settle → credit'; компенсация - окуялар 'rollback'.

9) Пагинация, чыпкалар, сорттоо

Cursor-based пагинация (чоң агымдар үчүн катуу 'page/limit' артык).

бириктирүү: '? cursor =... & limit = 200 & order = asc'.

жооп: 'next _ cursor', 'has _ more'.

чыпкалар: убакыт ('occurred _ at _ from/to'), 'tenant _ id', 'game _ id', 'status'.

10) Локалдар, валюталар, маалыматтардын резиденттүүлүгү

ISO-4217 валютасы; тактык схемада сакталат ('scale'), эсептөөлөр - minor-units (cents).

Жергиликтүү - BCP 47 ('en-GB', 'pt-BR').

Ар бир суроо-талапта - 'region'; PII жана акча операциялары аймактардан өтпөйт.

BI терезелерде PII жана RLS жашыруу.

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-аудит критикалык өзгөрүүлөр (лимиттер, RTP-пулдар, джекпот формулалары).

12) тестирлөө жана контракттардын сапаты

Контракттык тесттер (Pact/башкалар): провайдер Platform иш-чаралардын консюмерлери.

Жүктөө: "бороон" коюмдар/сеттлменттер; p95 максаттары.

Башаламандык учурларда: эки-жеткирүү, out-of-order, капчык кечигүү.

Sandbox '/sandbox 'жасалма акча жана сыноо' player _ id 'менен.

13) SDK, генераторлор жана документтер

OpenAPI/AsyncAPI → SDK генерациясы (TypeScript/Java/Kotlin/Go/Rust).

'authorize/settle/rollback', ретрайлер жана каталарды иштетүү үчүн коддун мисалдары.

Сурам/жооп мисалдары менен Live-док (curl + JSON), Postman/Insomnia чогултуу.

Changelog түрлөрү жана шайкештик белгилери менен.

14) Миграциянын жол картасы (мисал)

1. v1. 6 → v1. 7 (minor): 'bonus _ state' талаасын 'settle' (optional) деп кошту.

2. v1. x EOL кулактандыруу: 6 ай - кат + 'Deprecation' header + dashboard колдонуу.

3. v2. 0 (major): өзүнчө 'wallet. commit '(мурда implicit), жаңы талаа' settlement _ id 'милдеттүү.

4. Көчүрүү жол: mapping талаалар, timeline, phichflag "кош жазуу" (параллелдүү жарыялоо 'v1 '/' v2' окуялар).

5. Sunset v1: жаңы интеграциялардын бөгөт коюу, SLA өзгөчөлүктөрү боюнча гана узартуу.

15) Чек баракчалары

Платформанын архитекторлору үчүн

Домендик заттардын жана инварианттардын бирдиктүү сөздүгү бар.
OpenAPI/AsyncAPI + Schema Registry, semver, соттук териштирүүлөр.
Бардык write-операцияларында Идемпотенттүүлүк; ачкычтары документтештирилген.
Бирдиктүү ката модели жана коддору.
акча жолдорунда Сагалар жана outbox/CDC.
Rate-limits, observability, WORM-аудит.
Sandbox жана келишим тесттер өнөктөштөр үчүн жеткиликтүү.
Data residency жана RLS/жашыруу.

Провайдер үчүн

Мен ар дайым 'X-Trace-Id' жана 'X-Idempotency-Key' жөнөтүү.
Өтүнүчтөрдү кайталоо коопсуз иштетилет; Мен дубли жаратпайм.
Мен 'Deprecation/Sunset' иштеп жана Changelog окуп.
registry схемалары боюнча окуяларды жарыялоо/окуу; версиясын сактайм.
Мен тарапта retry/backoff жана deduplication бар.

16) Анти-үлгүлөрү (кызыл желектер)

БДда баланстарды/орнотууларды кол менен оңдоо.

окуяларды жарыялоо "өткөн" outbox/CDC.

idempotency → эки төлөмдөр/дебеттер жок.

аралаштыруу PII/акча ар кайсы аймактар 'region' деген белги жок.

"Тынч" жаңы версия жана депрекация жок breaking-өзгөртүү.

кол менен SDK генерациялоо (чыныгы спек менен дрейф).

Big-bang көчүрүү эч кандай fichflags жана кош жазуу окуялар.

Бирдиктүү API - бул "эндпоинттердин коллекциясы" гана эмес, экосистеманын келишими: макулдашылган сөздүк, туруктуу акча инварианттары, версиялоо окуялары, түшүнүктүү шайкештик эрежелери жана башкарылуучу депрекациялар. семантикалык нускасына таянуу менен, idempotentity, outbox/CDC, байкоо жана катуу коопсуздук, платформа тез жана оорутпай камсыз туташтырат, ал эми жаңыртуулар тобокелчиликтен күнүмдүк тартипке айланат.