トレントギア

プロバイダ用の単一のAPI：設計、バージョン、互換性

完全な記事

💡 18+.統合およびプラットフォームチームのための技術的な材料。再生する呼び出しではありません。

1）なぜ「単一のAPI」であり、それが何であるか

単一のAPIは、すべてのコンテンツプロバイダ（RGS、ライブスタジオ、ジャックポット、KYC/AML、アフィリエイト）が同じルールに従ってプラットフォームと通信するエンドポイント/イベントのセットです：

統合リソースモデル（プレイヤー、セッション、ベット、決済、ボーナス、ジャックポット、決済）、共通イベント契約と識別子、セキュリティと後方互換性の標準、統合を高速化するSDK/ツール。

目標：統合までの時間を短縮し「、マネーパス」のエラーを削減し、予測可能なアップグレードを提供します。

2）設計原則

1.ドメインファースト。最初に、辞書と不変量（レート、設定、RG制限）、次にエンドポイント。

2.デフォルトで互換性があります。任意の変更はデフォルトで互換性があります。プロセスによって厳しく変更を壊して下さい。

3.どこでもidempotency。すべてのマネーコマンドは副作用なしで再現可能です。

4.事象は真理の源です。バスへの操作→イベント；アナリティクスはバスに耳を傾け、OLTPを打つことはありません。

5.少なくとも特権とゼロトラスト。トークン、署名、ブランド/地域別のセグメンテーション。

6.観測可能性。エンドツーエンドの'trace_id'、わかりやすいエラーモデル、p95/p99メトリック。

3）リソースモデル（簡略化）

プレーヤー：プラットホームの側面プレーヤー擬似ID、地理/通貨/RGの状態。

セッション：プロバイダとプラットフォーム間のチャネル（'session_id'、 TTL、 geo/restrictions）。

Bet： bet authorization/debit。

決済：ラウンド結果と勝利クレジット。

ボーナス/賭け：ボーナス/ベージャーの残高ステータス。

ジャックポット：寄付/トリガー/支払い。

イベント：変更のないドメインイベント（Kafka/analogues）。

識別子：'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+Request Body Signature （HMAC/EdDSA）。

'bets： write'、'決済：write'、 'sessions： read'、 'events： publish'。

ヘッダーはリクエストごとに必要です：

'X-Trace-Id'、 'X-Brand-Id'、 'X-Region'、 'X-Idempotency-Key'。

4.2エンドポイントの例

セッションの作成


POST/v1/セッション
{
"player_id":"p_19f3," "game_id":"studio:slot_forge_02,""通貨"："EUR""、ロケール"："DE""、制約"：{"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
ヘッダー：X-Idempotency-Key： bet_r_8c12_1
{
「session_id":"s_456,」 「bet_id":"b_001,」 「round_id":"r_8c12,」「量「：{」量」：2。00、 「currency」：」 EUR」}
}
→200 {「status「：「authorized」、」 hold_id」：」 h_zz1」}

決済について


POST/v1/bets/settle
ヘッダー：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 FAAILILED'）。

'message'：人のための短い。

'retryable'： 'true/false'。

'trace_id'：ログを検索します。

例：


409競合
{
「code「：「DUPLICATE」、 「message」：」すでに別の金額で許可されている賭け」、「retryable」： false「、trace_id":"tr_a1b2c3」
}

5）イベントバスと回路

5.1基本的なトピック

「プレイヤー」登録されている'、'セッション。開始しました	終了しました'
'ベット。認可された	決済された
「ボーナス」発行された	消費される
「賭け金」進歩しています。更新されました'
'jackpot。コントリビュート	トリガーされた
'RG。限界。'、'rgを押してください。reality_check'
'wallet。デビット。'、'財布。「クレジット」

5.2イベントスキーマ（Avro/JSONスキーマ）

json
{
「event_id":"uuid,」 「event_type":"bet」。決済"、"occurred_at":"2025-10-23T16:21:05Z,""tenant_id":"brand-7,"地域"："EU"、 "player_id":"p_19f3," trace_id":"tr_a1b2c3,""ペイロード"：{
"round_id":"r_8c12," "bet"： {"amount'： 1。00、 "currency"： "EUR"}、 "win"： {"amount'： 14。60、 "currency"：" EUR"}、 "in_bonus":true
}、「 」  。2.0"
}

ルール：スキームの後方互換性のある進化、レジストリ+契約テスト。

6） APIバージョン： 戦略とルール

6.1バージョンを保存する場所

パスのバージョン：'/v1/……'（単にキャッシュ/ルート）。

ヘッダーのバージョン： 'Accept： application/vnd。プラットホーム。api+json；バージョン=1。2`.

イベント：イベントフィールド+レジストリの'schema_version'。

練習：HTTPのパス、イベントのschema_version、ポイント機能のフィーチャーフラグ。

6.2 SemVerと変更タイプ

PATCH （minor）-リバースドッキング：新しいオプションフィールド、新しいエンドポイント、新しいタイプのイベント。

MAJOR-breaking：フィールドの名前変更、セマンティクスの変更、削除。新しい'/vN/'と古いの枯渇によってのみ許可されます。

6.3安定した契約（破棄できない契約）

キー識別フィールドの名前とタイプ（'_id'、 'idempotency_key'）。

通貨モデル（「金額/通貨」、精度）。

ステータスの意味（'authorized'、 'credited'、 'forfeited'など）。

Idempotency：繰り返し動作は厳密に定義されています。

7）互換性と進化

7.1追加（安全）

デフォルトの新しいオプションフィールド。

既存のイベント/エンドポイントを変更することなく、新しいイベント/エンドポイントを作成できます。

'unknown'でフォールバックを持つ列挙拡張。

7.2変更（危険）

フィールドタイプ（数値→行）を変更します。

任意→必須。

ビジネスロジックの逆転（'authorize'の前に'settle'）。

→新しいメジャーバージョンと移行ガイドが必要です。

7.3減価償却費

フィールド/エンドポイントには'deprecated_since： 1。7'、'削除された_in： 2。0`.

コミュニケーション：リリースノート、ニュースレター、減価償却ヘッダー（'Sunset'、 'Deprecation'）。

プロアクティブなパートナー通知のための「古い」パスの使用をトレースします。

8） Idempotencyおよび一貫性

すべての録音操作には「X-Idemotency-Key」ヘッダが必要です。

意味：同じキー→同じ結果（同じボディで200）で繰り返します。

キーはパラメータのコンポジションにバインドされます（例：'bet_id+amount'）。

長いプロセスのサガ：'authorize→commit/lock→settle→credit'；補償-'rollback'イベント。

9）ペジネーション、フィルター、分類

カーソルベースのページネーション（大きなスレッドでは'page/limit'を厳密に好む）。

統一：'？cursor=……&limit=200&order=asc'。

答え：'next_cursor'、 'has_more'。

フィルタ：時間ごとに（'occured_at_from/to'）、 'tenant_id'、 'game_id'、 'status'。

10）ロケール、通貨、データ常駐

ISO-4217の通貨；精度はスキーム（'scale'）、計算-マイナーユニット（セント）に格納されます。

Locali-BCP 47 （'en-GB'、 'pt-BR'）。

各リクエスト-'region'；PIIと現金取引は地域を横断しません。

BIショーケースでのPIIとRLSマスキング。

11）観測可能性と限界

必要な見出し：'X-Trace-Id'、 'X-Provider-Id'、イベントとの相関。

メトリクス：p50/p95/p99レイテンシ、エラー率（コード別）、スループット、キューラグ（イベント用）。

料金制限：プロバイダごと/ブランドごと；responses from 'Retry-After'。

重要な変更のWORM監査（制限、RTPプール、ジャックポット式）。

12）契約のテストと品質

契約テスト（協定/その他）：プロバイダ↔プラットフォーム↔イベント消費者。

負荷：料金/決済の「嵐」；p95の目標。

混乱の場合：ダブル配達、アウトオブオーダー、財布の遅延。

架空のお金でサンドボックス'/sandbox'とテスト'player_id'。

13） SDK、ジェネレータ、ドキュメント

OpenAPI/AsyncAPI→SDK生成（TypeScript/Java/Kotlin/Go/Rust）

'authorize/settle/rollback'、リトレイ、エラー処理のコード例。

リクエスト/レスポンス（curl+JSON）、 Postman/Insomniaコレクションの例があるライブドック。

変更タイプと互換性ラベルのあるチェンジログ。

14）移行ロードマップ（例）

1.v1。6→v1。7（マイナー）'settle'に'bonus_state'フィールドを追加しました（オプション）。

2.v1。x EOL発表：6ヶ月間-letter+'Deprecation'ヘッダー+使用のダッシュボード。

3.v2。0（メジャー）：individual 'wallet。commit'（以前は暗黙）、新しいフィールド'settlement_id'が必要です。

4.移行ガイド：フィールドマッピング、タイムライン、「double writing」のfichflag （'v1'/'v2'イベントの並行公開）。

5.Sunset v1：新しいインテグレーションをブロックし、SLA例外のみに拡張します。

15）チェックリスト

プラットフォームアーキテクト向け

ドメインエンティティと不変量の1つの辞書があります。
OpenAPI/AsyncAPI+スキーマレジストリ、semver、デクリメントのプロセス。
すべての書き込み操作に対するIdempotency；キーは文書化されています。
シングルエラーモデルとコード。
お金の方法のSagasそしてoutbox/CDC。
レート制限、オブザビリティ、WORM監査。
サンドボックスと契約テストはパートナーが利用できます。
データレジデンシーとRLS/マスキング。

プロバイダの場合

常に「X-Trace-Id」と「X-Idempotency-Key」を送信します。
私は安全に要求の繰り返しを処理します；ダブルスは作らない。
「廃止/日没」を処理し、Changelogを読む。
私はレジストリスキームに従ってイベントを公開/読み取ります。私はバージョンを保持します。
私は私の側に再試行/バックオフと重複除外を持っています。

16）アンチパターン（赤旗）

データベース内の残高/決済の手動編集。

イベントの公開「過去」アウトボックス/CDC。

idempotency→duplicate payment/debitなし。

「地域」をマークせずに異なる地域のPII/お金を混合します。

「静か」新しいバージョンとデクリメントなしで変更を破る。

SDKを手動で生成する（実際の仕様でドリフトする）。

機能フラグとダブルイベントライティングのないビッグバン移行。

単一のAPIは「エンドポイントの集まり」だけでなく、一貫した辞書、安定した通貨不変量、バージョンイベント、明確な互換性ルール、管理可能なデクリメントなどのエコシステム契約です。セマンティックバージョン、idempotency、 outbox/CDC、観測性と強力なセキュリティに依存して、プラットフォームはプロバイダを迅速かつ痛みなく接続し、アップグレードはリスクからルーチンに変わります。