REST, gRPC və iGaming webhucks: nümunələr və anti-nümunələr

Məqalənin tam mətni

💡 18+. iGaming məhsul və mühəndislik komandaları üçün texniki material. Oyuna çağırış deyil. «Platforma» dedikdə PAM/cüzdan/kassa/RG bonusları nəzərdə tutulur. «Provayder» - RGS/live/cekpotlar/aqreqatorlar.

1) Protokol xəritəsi: kim nəyə cavabdehdir

REST - HTTP/JSON vasitəsilə universal sinxron sorğular. Şəffaf önbellək, sadə hata ayıklama, B2B inteqrasiyası və admin-API üçün rahatdır.

gRPC - HTTP/2 üzərində yüksək performanslı ikili RPC: aşağı gecikmə, axınlar, sərt sxemlər. İsti pul yolları (wallet/settle), daxili xidmətlər və uzun ömürlü axınlar (live) üçün yaxşıdır.

Webhucks - alıcıdan göndəriciyə əks zənglər (callback). Hadisələr üçün istifadə olunur («pul düşdü», «limit işlədi»), burada təşəbbüskar həmişə nəticəni gözləyən deyil.

Qızıl qayda:

Pul ciddi invariantlar və idempotentlik ilə sinxron RPC (REST/gRPC) üzrə gedir. Telemetriya və biznes hadisələri - asinxron (vebhuk + şina hadisələri).

2) Tipik yollar və tövsiyə olunan kanallar

Yol	Tövsiyə olunur	Niyə
`bets. authorize` (hold)	gRPC (daxili )/REST (B2B)	minimum gecikmə, ciddi SLA
`bets. settle` → `wallet. credit`	gRPC sinxron + şin hadisəsi	pul = ACID; hadisələr = müşahidə
`cashier. deposit/withdraw`	REST + idempotentlik	PSP ilə inteqrasiya, Trace
`RG check / stop`	gRPC/REST sinxron	stop siqnalları dərhal işləməlidir
`bonus. issue/consume`	REST sinxron	biznes məntiqi, orta SLA
`jackpot. trigger/payout`	gRPC/REST + hadisə	pul müqaviləsi + audit
Telemetriya, analitika, alertlər	Vebhuki + şina (Kafka/Pulsar)	sabitlik və miqyas
Canlı status/kataloqlar	gRPC streaming / Server-Sent Events	sorğuların və laqların minimuma endirilməsi

3) Müqavilə yönümlü dizayn

3. 1 REST (fraqmentlər)


POST /v1/bets/authorize
Headers: X-Idempotency-Key: bet_r_8c12_1, X-Trace-Id: tr_a1b2
{
"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"}

Səhvlər (vahid sxem):


409
{"code":"DUPLICATE","message":"Bet already authorized","retryable":false,"trace_id":"tr_a1b2"}

3. 2 gRPC (protobuf, sadələşdirilmiş)

proto syntax = "proto3";
package wallet. v1;

message Money { int64 minor_units = 1; string currency = 2; } // cents message AuthorizeBetReq { string session_id=1; string bet_id=2; string round_id=3; Money amount=4; string idempotency_key=5; }
message AuthorizeBetRes { string status=1; string hold_id=2; }

service Wallet {
rpc AuthorizeBet(AuthorizeBetReq) returns (AuthorizeBetRes);
rpc SettleBet(SettleReq) returns (SettleRes);
}

3. 3 Webhucks (abunə nümunəsi)


POST https://provider. example/webhooks
{
"topic":"wallet. credit. ok",  "callback_url":"https://rgs. example/journal",  "secret":"", "version":"1. 2"
}

Çatdırılma:


POST https://rgs. example/journal
Headers: X-Signature: sha256=..., X-Trace-Id: tr_a1b2
{
"event_type":"wallet. credit. ok",  "schema_version":"1. 2. 0",  "event_id":"uuid",  "payload":{"player_id":"p_19f3","amount":{"minor_units":1460,"currency":"EUR"}}
}

4) İdempotentlik və uyğunluq

Hər zaman write əməliyyatlarında 'X-Idempotency-Key' tələb edin (REST/gRPC metadata). təkrar → eyni cavab.

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

Uzun proseslər üçün dastanlar (authorize → commit/lock → settle → credit).

Outbox/CDC: Hadisələr əməliyyatın yanında atomik olaraq qeydə alınır və kənardan yayımlanır.

5) Version və uyğunluq

REST - '/v1/... '+' Deprecation/Sunset '-başlıqlar; gRPC — `package wallet. v1`; hadisələr - 'schema _ version' cisimlərdə + sxemlərin reyestri.

SemVer: minor - sahələr optional/yeni endpoints; major - yeni yol/paket, miqrasiya hadisələrinin «ikiqat məktubu».

Major versiyası olmadan pul statuslarının semantikasını heç vaxt dəyişdirməyin.

6) Nəqliyyat təhlükəsizliyi

mTLS bütün S2S; vebhuk üçün - bədən imzası (HMAC/EdDSA) + timestamp və etibarlılıq pəncərələri.

Satınalmaların məhdudlaşdırılması (OAuth2 CC) və per brand/region açarlarının seqmentləşdirilməsi.

Zero-trust: şəbəkə siyasətçiləri, qısa ömürlü tokenlər, Vault/HSM, kritik hərəkətlərin WORM auditi.

7) Müşahidə və SLO

REST, gRPC metadata və vebhuklarda 'trace _ id' vasitəsilə.

Metriklər: p50/p95/p99 latency, error rate kodları, throughput, lag növbələri.

SLO minimum:

Wallet p95 '<150 ms' (Authorize/Settle), REST Public B2B p95 '<300 ms', Vebhuks çatdırıldı '<5 dəq' 99-cu percentil, «İtirilmiş/dublaj settlements» = 0.

8) Retray, backoff və çatdırılma qaydası

REST/gRPC: eksponensial backoff, jitter, vaxt məhdudiyyəti (deadline/timeout).

Vebhuki: '2xx' qədər təkrar çatdırılma; açar qaydası ('player _ id/round _ id') və ya qəbuledicidə duplikasiya.

Anti-fırtına: paralel retras limiti, circuit breaker, rate limit.

9) İnteqrasiya nümunələri

Pattern A: «Pul sinxron, hadisələr asinxron»

1. RGS → Wallet (gRPC/REST) `authorize` → `settle/credit`.

2. Paralel olaraq 'bet. settled 'şin və provayder vebhuk qəbzini alır.

Plus: sürətli pul, müşahidə. Mənfi: iki kontur lazımdır.

Pattern B: «Streaming live»

gRPC streaming vasitəsilə Live Bridge nüvəsi (masa statusları, bahis pəncərəsi).

Pul əməliyyatları - fərdi unary RPC; hadisələr - şin/vebhuk.

Plus: canlı statusların minimum gecikməsi.

Pattern C: «B2B açıq REST»

Kataloqlar/bonuslar/affiliates/hesabatlar - REST cursor-pagination, filters, ETag.

Plus: tərəfdaşların sadə inteqrasiyası.

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

Pul əməliyyatları yalnız vebhuk vasitəsilə (sinxron təsdiq olmadan).

Yox 'Idempotency-Key' → iki debet/kredit.

Outbox/CDC keçərək hadisələrin yayımlanması (hadisələr itirilir).

Vebhuke imzasız/vaxt etiketi → dəyişdirmə.

Bir kanalda 'region/tenant' etiketsiz müxtəlif bölgələrin PII/pullarının qarışdırılması.

Vebhuklarda böyük binary payload (retrai və limitləri pozur).

Sıfır deqradasiya: vebhukların düşməsi pulun hesablanmasına mane olur.

gRPC deadline və backoff olmadan - asma bağlantılar, resursların tükənməsi.

11) Çek vərəqləri

Memar/platforma

İdempotluq ilə gRPC/REST pul, hadisələr - vebhuk/şin.
Bütün pul yollarında Outbox/CDC.
`/vN` и schema registry; Deprecation/Sunset prosesi.
mTLS + vebhuk imzaları; secrets per brand/region.
SLO dashboard p95/p99, error rate, webhook-lag.
DR/xaoc-təlimlər: ikiqat çatdırılma, out-of-order, bölgənin çöpü.

Provayder/RGS

Göndərirəm 'X-Trace-Id' və 'X-Idempotency-Key'.
Backoff və duplication ilə retrai; vebhukların yenidən çatdırılmasına hazırdır.
Müqavilələrin versiyalarını yeniləyirəm; "Deprecation/Sunset 'ə cavab verirəm.
Səhv və vaxt kodlarına görə qeydlər/metriklər.

12) Kəskin hallar üçün mini həllər

Safari/ITP və third-party məhdudiyyətləri: pul - hostda (REST/gRPC), iFrame məzmunu 'postMessage' vasitəsilə ünsiyyət qurur; Veb host, iFrame deyil.

Multibrend: başlıqlarda və hadisələrdə 'tenant _ id/brand _ id/license' etiketləri; açarları/sertifikatları ayrı.

Böyük sıçrayışlar (turnirlər): vebhuklardan əvvəl - DLQ ilə bufer/növbə; həddindən artıq yükləndikdə - «no new sessions »/» pause non-core hooks».

13) SLO yönümlü alertlərin nümunələri

Wallet. Authorize p95> 150 ms ardıcıl 5 dəq.

Səhvlər 'DUPLICATE/IDEMPOTENCY _ MISMATCH'> 0. 10 dəqiqə ərzində 5%.

Webhook lag p99> 180 c mövzu üzrə 'bet. settled`.

Kafka Consumer lag> 30 s üçün 'wallet. credit.`.

14) Nəticə

REST, gRPC və iGaming vebhukları dəyişdirilə bilən texnologiya deyil, eyni əməliyyat modelinin hissələridir.

REST/gRPC pul variantı saxlayır: aşağı gizli, idempotent, ciddi SLA.

Vebhuke/şin şəffaflıq və miqyas təmin edir: hadisələr, telemetri, inteqrasiya.

Outbox/CDC, versiyalaşdırma, imza və müşahidə əlavə edin - və pulun sürətli və təhlükəsiz hərəkət etdiyi, hadisələrin itirilmədiyi və yenilənmələrin ağrısız olduğu bir memarlıq əldə edin.