2015年10月29日 星期四

Endpoints (資料傳輸接點)

  • このエントリーをはてなブックマークに追加

關於Endpoints 

ChatWork API 是根據 REST 原則架構而成的一套設計。
在 REST 原則裡,交談、工作等等的 resource 個別有一個對應的 URL 網址(即 endpoints ),您可以運用 GET、POST、PUT、DELETE 等等 HTTP Method 傳遞參數以進行發文或是刪除的操作。

Endpoints 的基本URL為 https://api.chatwork.com/v1
請於基本URL後面加上各 Endpoints 對應的路徑(path)。
(例:若路徑為 /me 其對應URL即 https://api.chatwork.com/v1/me

系統版本更新時,/v1 部分將會變更,並保留舊版本一段緩衝時間。




Request


ChatWork API 必須使用 https 連接。
(使用 http 連接的話會得到連接錯誤的訊息)

所有的request都須包含 API token,
並且必須在 HTTP request header 內 X-ChatWorkToken 中設置 API token 。

您必須使用 PUT 或 DELETE 的方法(method)來做資源的更新或刪除,
您必須使用 PUT 或 DELETE 的方法(method)才能進行資源的更新或刪除,
若不支援上述方法(method)的客戶,可以在URL使用 ?method=PUT 或是 ?method=DELETE指定所需要的操作。

[重要] API token 永不過期,並且可以擁有完整的存取權,因此請勿揭露予第三人並妥善保管。API token 請務必藉由 http request header 傳送,不要用 URL 的方式傳送。


Response 


回傳資料使用JSON格式,JSON資料不包含成功或失敗等等的狀態碼,成功與否請使用HTTP response header判斷。

以下用取得自己的未讀訊息數 GET /my/status 作為範例

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

HTTP response body
{
  "unread_room_num": 2,
  "mention_room_num": 1,
  "mytask_room_num": 3,
  "unread_num": 12,
  "mention_num": 1,
  "mytask_num": 8
}
若發生錯誤,將以JSON的格式回傳HTTP對照碼與錯誤訊息。
以下為API token不正確回應的錯誤訊息範例。

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

HTTP response body
{
  "errors": ["Invalid API token"]
}
發生錯誤時將以 errors 這個鍵值所帶的的陣列提供錯誤訊息

API利用次數與限制


API的要求數以每5分鐘100次為上限,剩餘可呼叫次數與重置時間可以從http response header參考。(未來有可能改變API可使用次數)

HTTP response header的範例
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的時間格式儲存)

超過該限制時,將會收到429 Too Many Request的錯誤訊息。


以下為超過限制會收到的訊息範例
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1390941626




【相關資料】
ChatWork使用導引
API認證方法
ChatWork API 的 Endpoints 項目
ChatWork表示法
RAML
  • このエントリーをはてなブックマークに追加