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 エンドポイント