Endpoints

Về Endpoint

API Chatwork được setting dựa vào nguyên tắc của REST. Với mỗi resouce chat, task của REST sẽ có một URI duy nhất cố định (gọi là endpoint). Với mỗi endpoint này có thể tiến hành thao tác delete, post bằng cách gửi các parameter thông qua method HTTP GET hoặc POST, PUT, DELETE.

URI base của endpoint có format là https://api.chatwork.com/v2. Sau v2 hãy thêm path của mỗi endpoint. (Ví dụ trong trường hợp path: /me -> https://api.chatwork.com/v2/me)

Sau này khi version của API tăng lên thì thay đổi phần /v2, API version cũ được duy trì trong thời gian chuyển sang version mới.

Request

Endpoint của API ChatWork cần phải connect bằng https. (Sẽ lỗi trong trường hợp connect bằng http)

Hơn nữa, toàn bộ các request trong HTTP request head cần phải có API token, API token này phải được set bởi key X-ChatWorkToken.

Việc xóa và update resource cần dùng method PUT và DELETE, nhưng vì client không xử lý với các method này nên có thể chỉ định method muốn dùng lên Query string là ?method=PUT?method=DELETE.

Quan trọng API token không giới hạn thời hạn mà có thể access full ở chức năng. Hãy chú ý không để lộ cho bên thứ 3. Ngoài ra, hãy gửi API token bằng HTTP Request header chứ không phải Query string của URL.

Response

Response có hình thức là JSON. Status code hiển thị success hay failure không bao gồm trong data JSON mà hãy sử dụng header response HTTP để phán định kết quả (thành công hay thất bại).

Dưới đây là ví dụ về thực thi của GET /my/status get số message chưa đọc.

Header response HTTP

Header response HTTP

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

Body response HTTP

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

Khi bị lỗi, sẽ trả về code HTTP xử lý và error message bằng JSON. Dưới đây là ví dụ về hiển thị lỗi khi API token sai.

Header response HTTP

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

Body response HTTP

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

Nếu là error, thì error message sẽ được trả về bằng format mảng là key (error).

Về giới hạn số lần sử dụng của API

Số lần request API lên đến 300 lần trong vòng 5 phút. Thời gian reset hay số lần còn lại gọi được API có thể tham khảo từ header response HTTP (Số lần sử dụng API thì sau này có thể sẽ thay đổi được).

Ví dụ về Header response HTTP

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

Mỗi parameter sẽ hiển thị như bên dưới:

X-RateLimit-Limit: Số lần call max
X-RateLimit-Remaining: Số lần call còn lại
X-RateLimit-Reset: Thời gian được reset limit lần tiếp theo (Unix time)

Trường hợp vượt quá giới hạn này API response sẽ trả về error 429 Too Many Requests.

Ví dụ về Header response HTTP

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