Provayderlər üçün vahid API: dizayn, versiya, uyğunluq

Məqalənin tam mətni

💡 18+. İnteqrasiya və platforma komandaları üçün texniki material. Oyuna çağırış deyil.

1) Niyə «vahid API» və bu nədir

Vahid API hər hansı bir məzmun provayderinin (RGS, canlı studiya, cekpot, KYC/AML, affiliates) platforma ilə bir qaydada ünsiyyət qurduğu spesifikasiya və son nöqtələr/hadisələr toplusudur:

vahid resurs modeli (players, sessions, bets, settlements, bonuses, jackpots, payments), ümumi hadisə müqavilələri və identifikatorları, təhlükəsizlik və əks uyğunluq standartları, SDK/inteqrasiyanı sürətləndirmək üçün alətlər.

Məqsəd: vaxt-inteqratı azaltmaq, «pul yollarında» səhvləri azaltmaq və proqnozlaşdırıla bilən yeniləmələri təmin etməkdir.

2) Dizayn prinsipləri

1. Domain-first. Əvvəlcə lüğət və invariantlar (bahis, düzəliş, RG limitləri), sonra end-pointlər.

2. Compatibility by default. Hər hansı bir dəyişiklik - default uyğun; breaking-dəyişiklik ciddi proses.

3. Idempotency everywhere. Bütün pul komandaları yan təsirləri olmadan təkrarlanır.

4. Events are source of truth (distribution). Əməliyyat → şin hadisələr; analitika təkəri dinləyir, OLTP-ni vurmur.

5. Least privilege & zero-trust. Brend/region üzrə tokenlər, imzalar, seqmentləşdirmə.

6. Observability. «trace _ id», başa düşülən səhv modeli, p95/p99 metrikası.

3) Resurs modeli (sadələşdirilmiş)

Player: platforma tərəfində psevdo-ID oyunçu, geo/valyuta/RG statusları.

Session: provayder və platforma arasında kanal ('session _ id', TTL, geo/məhdudiyyətlər).

Bet: avtorizasiya/debet dərəcəsi.

Settlement: raundun nəticəsi və qazanc krediti.

Bonus/Vaqer: Veycerin bonus/qalıq vəziyyəti.

Jackpot: töhfələr/tetikleyicilər/ödənişlər.

Event: dəyişməz domen hadisələri (Kafka/analoqlar).

Identifikatorları: 'tenant _ id', 'brand _ id', 'region', 'player _ id', 'session _ id', 'round _ id', 'bet _ id', 'settlement _ id'. Hər şey - qlobal olaraq unikaldır (UUID/KSUID/Snowflake), qeydlərə və hadisələrə daxil edilir.

4) API müqavilələri: sorğular, cavablar, səhvlər

4. 1 Avtorizasiya və təhlükəsizlik

OAuth2 Client Credentials və ya mTLS + sorğu bədən imzası (HMAC/EdDSA).

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

Hər bir sorğuda aşağıdakı başlıqlar tələb olunur:

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

4. 2 Endpoint nümunələri

Sessiyanın yaradılması


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

Dərəcənin avtorizasiyası (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 Səhvlər (vahid model)

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

'message': insan üçün qısa.

`retryable`: `true/false`.

'trace _ id': loglarda axtarış üçün.

Nümunə:


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

5) Hadisə şinası və sxemləri

5. 1 Əsas topiklər

`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 Hadisə sxemi (Avro/JSON Sxema)

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

Qaydalar: backward-compatible development sxemləri, registry + müqavilə testləri.

6) API versiyası: strategiyalar və qaydalar

6. 1 Versiyanı harada saxlamaq olar

Path versiyası: '/v1/... '(sadəcə önbelleğe almaq/marşrutlaşdırmaq).

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

Hadisələr: 'schema _ version' hadisə sahəsində + registry.

Təcrübə: HTTP üçün yol, hadisələr üçün schema_version, nöqtə imkanları üçün fichflags.

6. 2 SemVer və dəyişiklik növləri

PATCH (minor) - əks-qoşulma: yeni isteğe bağlı sahələr, yeni end-pointlər, yeni hadisələr.

MAJOR - breaking: sahələrin adının dəyişdirilməsi, semantikanın dəyişdirilməsi, silinməsi. Yalnız yeni '/vN/' və köhnə deprekasiya yolu ilə icazə verilir.

6. 3 Sabit müqavilələr (pozula bilməz)

Əsas identifikasiya sahələrinin adları və növləri ('_ id', 'idempotency _ key').

Pul modeli ('amount/currency', dəqiqlik).

Status semantikası ('authorized', 'credited', 'forfeited' və s.).

İdempotentlik: təkrarlanan davranış ciddi şəkildə müəyyən edilmişdir.

7) Uyğunluq və təkamül

7. 1 Əlavələr (safe)

Defolt ilə yeni isteğe bağlı sahələr.

Yeni hadisələr/mövcud dəyişmədən son nöqtələr.

'unknown' fallback ilə enum genişləndirilməsi.

7. 2 Dəyişikliklər (risky)

Sahə tipinin dəyişdirilməsi (sayı → sətir).

Məcburi dəyişiklik (optional → required).

Biznes məntiqinin dönüşü ('settle' əvvəl 'authorize').

→ Yeni əsas versiya və miqrasiya bələdçisi tələb olunur.

7. 3 Deprekasiya

Sahə/end point 'deprecated _ since: 1. 7`, `removed_in: 2. 0`.

Rabitə: release notes, poçt, deprecation-headers ('Sunset', 'Deprecation').

Tərəfdaşların proaktiv bildirişləri üçün «köhnəlmiş» yolların istifadəsini izləmək.

8) İdempotentlik və uyğunluq

'X-Idempotency-Key' başlığı bütün qeyd əməliyyatları üçün tələb olunur.

Semantika: eyni açar ilə təkrar → eyni nəticə (əvvəlki body ilə 200).

Açarlar parametrlərin kompozisiyasına bağlıdır (məsələn, 'bet _ id + amount').

Uzun proseslərdə saqalar: 'authorize → commit/lock → settle → credit'; kompensasiya - hadisələr 'rollback'.

9) Paginasiya, filtrlər, çeşidləmə

Cursor-based pagination (böyük axınlar üçün ciddi üstünlük 'page/limit').

Unifikasiya: '? cursor =... & limit = 200 & order = asc'.

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

Filtrlər: ('occurred _ at _ from/to'), 'tenant _ id', 'game _ id', 'status'.

10) Lokallar, valyutalar, məlumatların rezidentliyi

Valyuta ISO-4217; dəqiqlik sxemdə saxlanılır ('scale'), hesablamalar - minor-units (cents).

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

Hər bir sorğuda - 'region'; PII və pul əməliyyatları regionları keçmir.

BI vitrinlərində PII və RLS maskalanması.

11) Müşahidə və limitlər

Məcburi başlıqlar: 'X-Trace-Id', 'X-Provider-Id', hadisələrlə korrelyasiya.

Metriklər: p50/p95/p99 latency, error rate (kodlara görə), throughput, queue lag (hadisələr üçün).

Rate limits: per provider / per brand; «Retry-After» ilə cavablar.

Kritik dəyişikliklərin WORM auditi (limitlər, RTP-hovuzlar, cekpot formulları).

12) Testlər və müqavilələrin keyfiyyəti

Müqavilə testləri (Pact/başqaları): provayder, platforma, platforma, hadisə konsumerləri.

Yükləmə: «fırtına» dərəcələri/settlement; p95 hədəfləri.

Xaos-cases: ikiqat çatdırılma, out-of-order, cüzdan gecikmələri.

Qum qutusu '/sandbox 'saxta pul və test' player _ id 'ilə.

13) SDK, generatorlar və sənədləşmə

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

'authorize/settle/rollback', retray və səhv emalı üçün kod nümunələri.

Sorğu/cavab nümunələri ilə Live-doc (curl + JSON), Postman/Insomnia kolleksiyası.

Changelog dəyişmə növləri və uyğunluq nişanları ilə.

14) Miqrasiya yol xəritəsi (nümunə)

1. v1. 6 → v1. 7 (minor): 'bonus _ state' sahəsi 'settle' (optional).

2. v1. x EOL elanı: 6 ay ərzində - məktub + 'Deprecation' header + dashboard istifadə.

3. v2. 0 (major): ayrıca 'wallet. commit '(əvvəllər implicit), yeni' settlement _ id 'sahəsi tələb olunur.

4. Miqrasiya bələdçisi: sahələrin mappinqi, timeline, «qoşa məktub» fichflag (paralel nəşr 'v1 '/' v2' hadisələri).

5. Sunset v1: yeni inteqrasiyaların bloklanması, yalnız SLA istisnaları ilə uzadılması.

15) Çek vərəqləri

Platforma memarları üçün

Domen varlıqları və invariantların vahid lüğəti var.
OpenAPI/AsyncAPI + Schema Registry, semver, depreksiya prosesi.
Bütün write əməliyyatlarında idempotentlik; açarları sənədləşdirilmişdir.
Vahid səhv model və kodlar.
pul yollarında dastanlar və outbox/CDC.
Rate-limits, observability, WORM-audit.
Qum qutusu və müqavilə testləri tərəfdaşlar üçün mövcuddur.
Data residency və RLS/maskalama.

Provayder üçün

Göndərirəm 'X-Trace-Id' və 'X-Idempotency-Key' həmişə.
Təkrar sorğular təhlükəsiz emal; Mən dubli yaratmıram.
«Deprecation/Sunset» emal və Changelog oxuyur.
registry sxemləri üzrə hadisələr dərc/oxumaq; versiyasını saxlayıram.
Mənim tərəfimdə retry/backoff və deduplication var.

16) Anti-nümunələr (qırmızı bayraqlar)

DB-də balansların/düzəlişlərin əl ilə düzəldilməsi.

Outbox/CDC tərəfindən «keçmiş» hadisələrin yayımlanması.

idempotency → iki ödəniş/debet yoxdur.

'region' işarəsi olmadan müxtəlif bölgələrin PII/pul qarışdırılması.

Yeni versiya və depreqasiya olmadan «sakit» breaking-dəyişikliklər.

Əl ilə SDK Generation (real sinterleme ilə drift).

Big-bang miqrasiyası fichflags və ikili yazı hadisələri olmadan.

Vahid API yalnız «end-point kolleksiyası» deyil, ekosistemin müqaviləsidir: razılaşdırılmış lüğət, sabit pul invariantları, versiyalaşdırma hadisələri, anlaşılan uyğunluq qaydaları və idarə edilə bilən deprekasiya. Semantik versiyaya, idempotentliyə, outbox/CDC, müşahidə və ciddi təhlükəsizliyə əsaslanaraq, platforma provayderləri tez və ağrısız birləşdirir və yeniləmələr riskdən rutinə çevrilir.