エンドポイントについて

Chatwork 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は一定の移行期間の間維持されます。

リクエスト

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

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

POSTメソッドやPUTメソッドを使用するエンドポイントのリクエストボディは Content-Type: application/x-www-form-urlencoded である必要があります。

リソースの更新や削除には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分あたり300回 までとなります。残りコール可能な回数やリセットされる時間は、HTTPレスポンスヘッダから参照できます（APIの利用回数は、今後変更される可能性があります）。

HTTPレスポンスヘッダの例:

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

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

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

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

HTTPレスポンスヘッダの例:

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

チャットルーム単位のメッセージ投稿回数制限について

上記のAPI利用回数制限に加え、下記のエンドポイントについては更に 10秒あたり10回 までという回数制限があります（回数はそれぞれのエンドポイントの呼び出し回数の合算です）。

チャットに新しいメッセージを追加: POST /rooms/{room_id}/messages
チャットに新しいタスクを追加: POST /rooms/{room_id}/tasks

この制限を超えた場合、APIのレスポンス・ステータスコード 429 Too Many Requests となるエラーを、下記のメッセージとともに返すようになります。

{
    "errors": ["Rate limit for message posting per room exceeded."]
}

このエラーが出た場合、10秒ほど待機していただいた後にリトライしていただくようお願いいたします。