エンドポイント

エンドポイントについて

チャットワークAPIはRESTの原則に基づいてAPI設計されています。RESTではチャット、タスクといったそれぞれのリソースに対して固有の一意なURIが与えられており(エンドポイントと呼ぶ)、そのエンドポイントに対してGETやPOST、PUT、DELETEといったHTTPメソッドでパラメータを送ることで投稿や削除などリソースの操作を行います。

エンドポイントのベースURIは、https://api.chatwork.com/v2 となっています。このあとに、各エンドポイントのパスを記述してください。(例:/me の場合は https://api.chatwork.com/v2/me)

今後、APIのバージョンが上がった場合は/v2のバージョン部分が変更され、旧バージョンのAPIは一定の移行期間の間維持されます。

リクエスト

チャットワークAPIのエンドポイントへは、必ず https で接続する必要があります。(http では接続エラーになります)

また、すべてのリクエストには必ずAPIトークンを含める必要があり、APIトークンはHTTPリクエストヘッダに X-ChatWorkToken というキーでセットする必要があります。

リソースの更新や削除にはPUTやDELETEメソッドを用いる必要がありますが、それらのメソッドに対応していないクライアントのため、URLのクエリストリングに ?method=PUT?method=DELETE と指定することで使用したいメソッドを明示することもできます。

重要 APIトークンは有効期限がなく、機能にフルアクセスが可能なものになっています。第三者へ開示しないよう取り扱いには十分ご注意ください。また、APIトークンはURLのクエリストリングではなく必ずHTTPリクエストヘッダで送信するようにしてください。

レスポンス

レスポンスはJSON形式となります。成功や失敗などを表すステータスコードはJSONデータには含まれておらず、成否判定にはHTTPレスポンスヘッダを利用してください。

下記は自分の未読数などを取得する GET /my/status の実行例です。

HTTPレスポンスヘッダ

HTTP/1.1 200 OK
Content-Type: application/json

HTTPレスポンスボディ

{
  "unread_room_num": 2,
  "mention_room_num": 1,
  "mytask_room_num": 3,
  "unread_num": 12,
  "mention_num": 1,
  "mytask_num": 8
}

エラーの場合は、対応するHTTPコードと、エラーメッセージをJSONで返します。下記はAPIトークンが間違っていた場合のエラー例です。

HTTPレスポンスヘッダ

HTTP/1.1 401 Unauthorized
Content-Type: application/json

HTTPレスポンスボディ

{
  "errors": ["Invalid API token"]
}

エラーの場合はerrorsというキーに配列形式で、エラーメッセージが返却されます。

APIの利用回数制限について

APIのリクエスト数は、5分あたり100回までとなります。残りコール可能な回数やリセットされる時間は、HTTPレスポンスヘッダから参照できます。(APIの利用回数は、今後変更される可能性があります)

HTTPレスポンスヘッダの例

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 44
X-RateLimit-Reset: 1390941626

それぞれのパラメータは、

X-RateLimit-Limit: 最大コール回数
X-RateLimit-Remaining: 残りコール回数
X-RateLimit-Reset: 次に制限がリセットされる時間(Unix time)

を表しています。この制限を超えた場合、APIのレスポンスが 429 Too Many Requests エラーを返すようになります。

HTTPレスポンスヘッダの例

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1390941626