Web API 入門系列 - RESTful API 設計指南

參考：https://developer.github.com/v3/  https://github.com/bolasblack/http-api-guide

HTTP 協議

目前使用HTTP1.1協議，爲了通訊安全，建議使用https協議

域名

儘可能使用專業域名，如 https://api.github.com
也可使用主域名，如 https://www.github.com/api

API版本

放在請求頭裏,如Accept: application/vnd.github.v3+json 這種方案URL比較優雅，表示同一資源，github api 推薦這樣使用。

URL地址

在RESTful架構中，每一個網址表明一種資源，用名稱複數形式，不要用動詞。
如應該使用： https://api.github.com/books 不該該使用：https://api.github.com/getbooks

過濾分頁

分頁：?page=2&per_page=100： 如：https://api.github.com/user/repos?page=2&per_page=100 若是沒有傳遞時，使用默認配置。排序：?sortby=name&order=asc： 如：https://api.github.com/user/repos?page=2&per_page=100&sortby=name&order=asc 若是沒有傳遞時，使用默認配置。
過濾：?username=1 如：https://api.github.com/user/repos?username=1

HTTP 動詞

Restful 風格的程序推薦使用 http verbs 來操做服務器資源，讓資源發生狀態轉變。

關於方法語義的說明：

GET： 用於從服務器獲取某個資源的信息
完成請求後返回狀態碼 200 OK
完成請求後須要返回被請求的資源詳細信息

POST： 用於建立新資源
建立完成後返回狀態碼 201 Created
完成請求後須要返回被建立的資源詳細信息

PUT： 用於完整的替換資源或者建立指定身份的資源，好比建立 id 爲 123 的某個資源
若是是建立了資源，則返回 201 Created
若是是替換了資源，則返回 200 OK
完成請求後須要返回被修改的資源詳細信息

PATCH： 用於局部更新資源
完成請求後返回狀態碼 200 OK
完成請求後須要返回被修改的資源詳細信息

DELETE： 用於刪除某個資源
完成請求後返回狀態碼 204 No Content

異常處理

在調用接口的過程當中，可能出現下列幾種錯誤狀況：

服務器維護中，503 狀態碼

HTTP/1.1 503 Service Unavailable
Retry-After: 3600
Content-Length: 41

{"message": "Service In the maintenance"}
發送了沒法轉化的請求體，400 狀態碼

HTTP/1.1 400 Bad Request
Content-Length: 35

{"message": "Problems parsing JSON"}
服務到期（好比付費的增值服務等）， 403 狀態碼

HTTP/1.1 403 Forbidden
Content-Length: 29

{"message": "Service expired"}
由於某些緣由不容許訪問（好比被 ban ），403 狀態碼

HTTP/1.1 403 Forbidden
Content-Length: 29

{"message": "Account blocked"}
權限不夠，403 狀態碼

HTTP/1.1 403 Forbidden
Content-Length: 31

{"message": "Permission denied"}
須要修改的資源不存在， 404 狀態碼

HTTP/1.1 404 Not Found
Content-Length: 32

{"message": "Resource not found"}
缺乏了必要的頭信息，428 狀態碼

HTTP/1.1 428 Precondition Required
Content-Length: 35

{"message": "Header User-Agent is required"}
發送了非法的資源，422 狀態碼

HTTP/1.1 422 Unprocessable Entity
Content-Length: 149

{
"message": "Validation Failed",
"errors": [
{
"resource": "Issue",
"field": "title",
"code": "required"
}
]
}
全部的 error 哈希表都有 resource, field, code 字段，以便於定位錯誤，code 字段則用於表示錯誤類型：

missing： This means a resource does not exist.
missing_field： This means a required field on a resource has not been set.
invalid： This means the formatting of a field is invalid. The documentation for that resource should be able to give you more specific information.
already_exists：This means another resource has the same value as this field. This can happen in resources that must have some unique key (such as Label names).

身份認證

使用OAuth 2.0驗證，參考 http://www.ruanyifeng.com/blog/2014/05/oauth_2_0.html