苫小牧API 移行マニュアル

これは、第31回苫小牧大会（2020）競技部門「雪降る大地ミんなでクるっと囲みマス」のAPI（以下、プロコンAPI）と囲みマス苫小牧API（以下、囲みマスAPI）との違いを記したドキュメントです。

囲みマス苫小牧API ドキュメント：https://kakomimasu.com/docs/api/tomakomai

過去に作成したプログラムをできるだけ変更せずに参加してもらうため、基本的にプロコンAPIの仕様に沿って実装しておりますが、サーバで扱うデータの関係上、異なる仕様になっている部分があります。

以下に変更点を示します。

①認証の違い

Queryによる認証には対応しておりません。HTTP Headerによる認証を使用してください。

プロコンAPIでは、事前に運営側からトークンが配られます。

一方、囲みマスAPIでは公式サイトからトークン（BearerToken）が取得できます。→ BearerTokenの取得方法

このBearerTokenは試合一覧取得取得API、チーム情報取得API、試合一覧取得API(チーム)の認証に使用します。

また、試合状態取得API、行動更新APIでは各ゲームに割り振られた参加者のPICと呼ばれるBearerTokenとは別のトークンが必要になります。

PICは、事前情報取得APIのteamIDからゲーム別に得られます。（BearerTokenが使用できない理由はPICのページをご覧ください。）

②試合一覧取得API

試合一覧取得APIで得られるデータの型が一部異なります。

matchID(試合のID)：integerがstring(UUID)に変更

また、各フィールドの仕様が以下のように変更になります。

teamID：チームIDではなくPICに変更。自分以外のチーム情報の場合は0になります。

③試合状態取得API

試合状態取得APIで得られるデータの各フィールドの仕様が以下のように変更になります。

teamID：チームIDではなくPICに変更。自分以外のチーム情報の場合は0になります。

walls、areas：城壁・陣地以外のマスの場合、チームIDではなくteams[]配列のインデックス+1になります。

agentID：エージェントIDは以下の計算にて算出されます。

エージェントID = teamIdx * agentNum + agentIdx

teamIdx：teams[]配列のインデックス

agentNum：総エージェント数

agentIdx：teams[].agents[]配列のインデックス

例（総エージェント数6で、teams[1]のチームの3番目(teams[1].agents[2])のエージェントのID）：$ 1 \times 6 + 2 = 8

④行動更新API

行動更新APIで送受信するデータの各フィールドの仕様が以下のように変更になります。

agentID：試合状態取得APIのteams[].agents[].agentIDと同じ計算式にて算出されます。

⑤チーム情報取得API

チーム情報取得APIで得られるデータの各フィールドの仕様が以下のように変更になります。

teamID(チームID)：0に固定になります。（ドキュメント上ではPICが返されると書いてありますが、ゲームが特定できないため0になります。）

⑥試合一覧取得API

②試合一覧取得APIと同一の内容が得られるため、変更点も同じになります。