協(xié)議

API 與用戶的通信協(xié)議，建議使用 HTTPs 協(xié)議术辐。

域名

應(yīng)該盡量將 API 部署在專用域名之下砚尽。

https://api.example.com

如果確定 API 很簡單，不會有進(jìn)一步擴展辉词，可以考慮放在主域名下必孤。

https://example.org/api/

版本（Versioning）

應(yīng)該將 API 的版本號放入URL。

https://api.example.com/v1/

另一種做法是瑞躺，將版本號放在 HTTP 頭信息中敷搪，但不如放入 URL 方便和直觀。Github 采用這種做法幢哨。

路徑（Endpoint）

路徑又稱"終點"（endpoint）赡勘，表示 API 的具體網(wǎng)址。

在 RESTful 架構(gòu)中捞镰，每個網(wǎng)址代表一種資源（resource）闸与，所以網(wǎng)址中不能有動詞，只能有名詞岸售，而且所用的名詞往往與數(shù)據(jù)庫的表格名對應(yīng)践樱。一般來說，數(shù)據(jù)庫中的表都是同種記錄的"集合"（collection）凸丸，所以 API 中的名詞也應(yīng)該使用復(fù)數(shù)拷邢。

舉例來說，有一個 API 提供動物園（zoo）的信息屎慢，還包括各種動物和雇員的信息瞭稼，則它的路徑應(yīng)該設(shè)計成下面這樣忽洛。

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees

HTTP 動詞

對于資源的具體操作類型，由 HTTP 動詞表示环肘。

常用的HTTP動詞有下面五個（括號里是對應(yīng)的SQL命令）脐瑰。

GET（SELECT）：從服務(wù)器取出資源（一項或多項）。
POST（INSERT）：在服務(wù)器新建一個資源廷臼。
PUT（UPDATE）：在服務(wù)器更新資源（客戶端提供改變后的完整資源）。
PATCH（UPDATE）：在服務(wù)器更新資源（客戶端提供改變的屬性）绝页。
DELETE（DELETE）：從服務(wù)器刪除資源荠商。

還有兩個不常用的 HTTP 動詞。

HEAD：獲取資源的元數(shù)據(jù)续誉。

OPTIONS：獲取信息莱没，關(guān)于資源的哪些屬性是客戶端可以改變的。

下面是一些例子酷鸦。

GET /zoos：列出所有動物園
POST /zoos：新建一個動物園
GET /zoos/ID：獲取某個指定動物園的信息
PUT /zoos/ID：更新某個指定動物園的信息（提供該動物園的全部信息）
PATCH /zoos/ID：更新某個指定動物園的信息（提供該動物園的部分信息）
DELETE /zoos/ID：刪除某個動物園
GET /zoos/ID/animals：列出某個指定動物園的所有動物
DELETE /zoos/ID/animals/ID：刪除某個指定動物園的指定動物

過濾信息（Filtering）

如果記錄數(shù)量很多饰躲，服務(wù)器不可能都將它們返回給用戶。API應(yīng)該提供參數(shù)臼隔，過濾返回結(jié)果嘹裂。

下面是一些常見的參數(shù)。

?limit=10：指定返回記錄的數(shù)量
?offset=10：指定返回記錄的開始位置摔握。
?page=2&per_page=100：指定第幾頁寄狼，以及每頁的記錄數(shù)。
?sortby=name&order=asc：指定返回結(jié)果按照哪個屬性排序氨淌，以及排序順序泊愧。
?animal_type_id=1：指定篩選條件

參數(shù)的設(shè)計允許存在冗余，即允許API路徑和URL參數(shù)偶爾有重復(fù)盛正。比如删咱，GET /zoo/ID/animals 與 GET /animals?zoo_id=ID 的含義是相同的。

狀態(tài)碼（Status Codes）

服務(wù)器向用戶返回的狀態(tài)碼和提示信息豪筝，常見的有以下一些（方括號中是該狀態(tài)碼對應(yīng)的 HTTP 動詞）痰滋。

200 OK - [GET]：服務(wù)器成功返回用戶請求的數(shù)據(jù)，該操作是冪等的（Idempotent）续崖。
201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數(shù)據(jù)成功即寡。
202 Accepted - [*]：表示一個請求已經(jīng)進(jìn)入后臺排隊（異步任務(wù)）
204 NO CONTENT - [DELETE]：用戶刪除數(shù)據(jù)成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發(fā)出的請求有錯誤袜刷，服務(wù)器沒有進(jìn)行新建或修改數(shù)據(jù)的操作聪富，該操作是冪等的。
401 Unauthorized - [*]：表示用戶沒有權(quán)限（令牌著蟹、用戶名墩蔓、密碼錯誤）梢莽。
403 Forbidden - [*] 表示用戶得到授權(quán)（與401錯誤相對），但是訪問是被禁止的奸披。
404 NOT FOUND - [*]：用戶發(fā)出的請求針對的是不存在的記錄昏名，服務(wù)器沒有進(jìn)行操作，該操作是冪等的阵面。
406 Not Acceptable - [GET]：用戶請求的格式不可得（比如用戶請求JSON格式轻局，但是只有XML格式）。
410 Gone -[GET]：用戶請求的資源被永久刪除样刷，且不會再得到的仑扑。
422 Unprocesable entity - [POST/PUT/PATCH] 當(dāng)創(chuàng)建一個對象時，發(fā)生一個驗證錯誤置鼻。
500 INTERNAL SERVER ERROR - [*]：服務(wù)器發(fā)生錯誤镇饮，用戶將無法判斷發(fā)出的請求是否成功。

狀態(tài)碼的完全列表參見這里箕母。

錯誤處理（Error handling）

如果狀態(tài)碼是4xx储藐，就應(yīng)該向用戶返回出錯信息。一般來說嘶是，返回的信息中將error作為鍵名钙勃，出錯信息作為鍵值即可。

{
    error: "Invalid API key"
}

返回結(jié)果

針對不同操作聂喇，服務(wù)器向用戶返回的結(jié)果應(yīng)該符合以下規(guī)范肺缕。

GET /collection：返回資源對象的列表（數(shù)組）
GET /collection/resource：返回單個資源對象
POST /collection：返回新生成的資源對象
PUT /collection/resource：返回完整的資源對象
PATCH /collection/resource：返回完整的資源對象
DELETE /collection/resource：返回一個空文檔

Hypermedia API

RESTful API 最好做到 Hypermedia，即返回結(jié)果中提供鏈接授帕，連向其他 API 方法同木，使得用戶不查文檔，也知道下一步應(yīng)該做什么跛十。

比如彤路，當(dāng)用戶向 api.example.com 的根目錄發(fā)出請求，會得到這樣一個文檔芥映。

{"link": {
  "rel":   "collection https://www.example.com/zoos",
  "href":  "https://api.example.com/zoos",
  "title": "List of zoos",
  "type":  "application/vnd.yourformat+json"
}}

上面代碼表示洲尊，文檔中有一個link屬性，用戶讀取這個屬性就知道下一步該調(diào)用什么API了奈偏。

rel 表示這個 API 與當(dāng)前網(wǎng)址的關(guān)系（collection 關(guān)系坞嘀，并給出該 collection 的網(wǎng)址），href 表示 API 的路徑惊来，title 表示 API 的標(biāo)題丽涩，type 表示返回類型。

Hypermedia API 的設(shè)計被稱為 HATEOAS。Github 的 API 就是這種設(shè)計矢渊，訪問api.github.com會得到一個所有可用API的網(wǎng)址列表穷绵。

{
  "current_user_url": "https://api.github.com/user",
  "authorizations_url": "https://api.github.com/authorizations",
  // ...
}

從上面可以看到狸相，如果想獲取當(dāng)前用戶的信息刮吧，應(yīng)該去訪問api.github.com/user承边，然后就得到了下面結(jié)果。

{
  "message": "Requires authentication",
  "documentation_url": "https://developer.github.com/v3"
}

上面代碼表示毡鉴，服務(wù)器給出了提示信息崔泵，以及文檔的網(wǎng)址。