Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
127 lines (78 sloc) 4.31 KB

REST API

Japan Minecraft PvP APIはRESTful形式でゲームのデータをJSONレスポンスにより取得する事が出来ます。

現在Japan Minecraft PvP APIへのアクセスには Developer Console よりAPIアクセスの申請を行う必要があります。

エンドポイント

エンドポイントのベースURIは https://pvp-api.minecraft.jp/v1/ になります。

認証

全てのAPIエンドポイントへのリクエストにはアクセストークンを送信する必要があります。

利用可能な認証

認証 ユーザのプライベートデータ取得 Client Secretの使用 レート制限の上限増加
Authorization Code Yes Yes Yes
Client Credentials No Yes Yes

アクセストークンによるリクエスト

GET https://pvp-api.minecraft.jp/v1/servers HTTP/1.1
Authorization: Bearer {YOUR_ACCESS_TOKEN}

または

GET https://pvp-api.minecraft.jp/v1/servers?access_token={YOUR_ACCESS_TOKEN} HTTP/1.1

Client Credentials アクセストークンの取得例

curl https://minecraft.jp/oauth/token -d 'grant_type=client_credentials&client_id={YOUR_CLIENT_ID}&client_secret={YOUR_CLIENT_SECRET}'

アクセストークンの取得リクエストが成功すると次のようなJSONフォーマットで返却されます。

{"access_token":"03807cb390319329bdf6c777d4dfae9c0d3b3c35","expires_in":3600,"token_type":"bearer","scope":null}

レート制限 (Rate Limit)

Client Credentialsによる認証時には、アプリ単位で1時間に900リクエストを送信する事が出来ます。

Authorization Codeによる認証時には、対象のユーザ単位で1時間に900リクエストを送信する事が出来ます。

認証別のレート制限値

認証 1時間あたりのリクエスト可能数 レート制限適用対象
Authorization Code 900 User
Client Credentials 900 App
Client ID 600 IPアドレス

レート制限を超えるとステータスコード 429 Too Many Requests と下記の内容が返されます。

{
    error: "rate_limit",
    error_description: "Rate limit exceeded"
}

アプリケーションにより多くのリクエスト数が必要な場合は、必要な理由などの詳細を記載の上 info@minecraft.jp までご連絡ください。

現在のレート制限の状態はリクエスト時のレスポンスヘッダーに追加されます。

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1450580967
  • X-RateLimit-Limit 1時間あたりのリクエスト可能数
  • X-RateLimit-Remaining レート制限までのリクエスト数
  • X-RateLimit-Reset レート制限リセット時間(UNIXタイムスタンプ)

ステータスコード

このAPIでは下記のレスポンスステータスコードを使用します。

ステータスコード 説明
200 OK - リクエストは正常に成功しました。
204 No Content - リクエストは正常に成功しました。レスポンスはありません。
400 Bad Request - 不正なフォーマットでリクエストが行われました。
401 Unauthorized - Client IDまたはアクセストークンがリクエストに含まれていないか有効ではありません。
403 Forbidden - 認可されたスコープ範囲外へのリクエストです。
404 Not Found - リクエストされたリソースが見つかりませんでした。
429 Too Many Requests - レート制限が適用されました。
500 Internal Server Error - APIサーバで問題が発生しています。
502 Bad Gateway - 一時的にAPIサーバに接続出来なくなっています。
503 Server Unavailable - 一時的にAPIサーバに接続出来なくなっています。

API エンドポイント

.. toctree::
   :glob:
   :maxdepth: 1

   maps
   matches
   players
   punishments
   servers
You can’t perform that action at this time.