APIの概要¶
冪等性¶
RESTの原則に基づきGETとPUTメソッドは冪等性があります。
そのため同一のリクエストが複数回行われてもゲーム内通貨の多重発行・消費は発生しません。
冪等キーは、例えば課金アイテム購入APIのtransactionIdになります。
XGのPUTリクエストが成功した場合、HTTPステータスは200をレスポンスします（ゲームサーバー側の処理がシンプルになるよう200、201、204のように分類せずに200に統一しています）。
初回のリクエストか、2回目以降のリクエストかは、レスポンスボディのstatusで判定（completed:新規で成功、already_done:XGで処理済み）できます。
文字コード¶
APIのリクエスト・レスポンスの文字コードはUTF-8を使用しています。
タイムアウト¶
APIのタイムアウトは30秒です。
APIを呼び出す側のタイムアウトを30秒より長くすることを推奨します。
APIを呼び出す側のタイムアウトを30秒より短くすると、APIのレスポンスを受け取ることができず、APIが正常終了しても呼び出す側がエラーになってしまいます。
API接続先¶
XGでは本番運用のための環境とは別に、APIの動作確認を行うためのサンドボックス環境と負荷試験を行うための負荷試験環境を提供しています。
環境 |
URL |
|---|---|
本番環境 |
|
サンドボックス環境 |
|
負荷試験環境 |
|
APIのパス構成¶
XGのAPIのパスは以下のキーパーツにより構成されています。
それぞれから成る基本的なパスのフォーマットは以下の通りです。
/{リソース名}/{version}/[users/{ユーザーID}]/[storeId/{ストアID}]/[その他のパラメーター]
項目 |
説明 |
|---|---|
リソース名 |
操作対象のリソースを示します。
例えば、「user」、「purchase」、「currency」がこれに該当します。
これらは、APIがどの種類のリソース（ユーザー、購入、ゲーム内通貨など）に対して動作するかを定義します。
|
version |
APIのバージョンを示します。
「v1」はAPIのバージョン1を示します。
|
users/{ユーザーID} |
特定のユーザーIDのための操作を指示します。 |
storeId/{ストアID} |
特定のストアIDを示します。
例えば、「stores/googleplay」は Google Playのストアに対するリクエストを示します。
|
その他のパラメーター |
特定のリソースに対する具体的な操作を示します。
「issue/free」、「consume」、「balance」などがこれに該当します。
これらは操作の種類や対象などを指定します。
|
バージョンと互換性¶
同じバージョンで後方互換性のない修正は行いません。
以下は後方互換性があるもとのします。
エンドポイントの追加
任意のリクエストパラメーターの追加
任意のレスポンスパラメーターの追加
未定義のレスポンスパラーメーターが存在してもエラーが発生しないよう実装をお願いいたします
リクエストパラメーターに設定する値の追加
必須のリクエストパラメーターを任意へ変更
レスポンスヘッダー¶
XGで提供するAPIではXG独自のレスポンスヘッダーを返します。
XG独自のレスポンスヘッダーは以下の通りです。
キー |
説明 |
例 |
|---|---|---|
Xg-Trace-Id |
APIリクエストごとに割り振られる一意なIDです。
XG Developer SiteのAPIログ検索ではTraceIdに一致するリクエスト/レスポンスのログを取得できます。
|
Xg-Trace-Id: 1a92ef4567890abc54d8f40b294cf634 |
Xg-Version |
APIのバージョン情報を示します。
|
Xg-Version: 1.0.0 |
