協(xié)議

• API與用戶通信協(xié)議使用HTTPS

域名

• 盡量將API放入專有域名下

版本號(hào)

• 將版本號(hào)放入U(xiǎn)RL中

路徑

• 在RESTful架構(gòu)中，每個(gè)網(wǎng)址代表一種資源（resource），所以網(wǎng)址中不能有動(dòng)詞，只能有名詞，而且所用的名詞往往與數(shù)據(jù)庫(kù)的表格名對(duì)應(yīng)。一般來(lái)說(shuō)，數(shù)據(jù)庫(kù)中的表都是同種記錄的"集合"（collection），所以API中的名詞也應(yīng)該使用復(fù)數(shù)。

• 舉例來(lái)說(shuō)，有一個(gè)API提供動(dòng)物園（zoo）的信息，還包括各種動(dòng)物和雇員的信息，則它的路徑應(yīng)該設(shè)計(jì)成下面這樣。

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

HTTP動(dòng)詞

• GET（SELECT）：從服務(wù)器取出資源（一項(xiàng)或多項(xiàng)）。
• POST（CREATE）：在服務(wù)器新建一個(gè)資源。
• PUT（UPDATE）：在服務(wù)器更新資源（客戶端提供改變后的完整資源）。
• PATCH（UPDATE）：在服務(wù)器更新資源（客戶端提供改變的屬性）。
• DELETE（DELETE）：從服務(wù)器刪除資源。
• HEAD：獲取資源的元數(shù)據(jù)。
• OPTIONS：獲取信息，關(guān)于資源的哪些屬性是客戶端可以改變的。

過(guò)濾信息

• 如果記錄數(shù)量很多，服務(wù)器不可能都將它們返回給用戶。API應(yīng)該提供參數(shù)，過(guò)濾返回結(jié)果。
  下面是一些常見的參數(shù)。

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

狀態(tài)碼

200系列

• 200 OK 請(qǐng)求成功（其后是對(duì)GET和POST請(qǐng)求的應(yīng)答文檔。）
• 201 Created 請(qǐng)求被創(chuàng)建完成，同時(shí)新的資源被創(chuàng)建。
• 202 Accepted 供處理的請(qǐng)求已被接受，但是處理未完成。

300系列

• 300 Multiple Choices 多重選擇。鏈接列表。用戶可以選擇某鏈接到達(dá)目的地。最多允許五個(gè)地址。
• 301 Moved Permanently 所請(qǐng)求的頁(yè)面已經(jīng)轉(zhuǎn)移至新的url。
• 302 Found 所請(qǐng)求的頁(yè)面已經(jīng)臨時(shí)轉(zhuǎn)移至新的url。

400系列

• 400 Bad Request 服務(wù)器未能理解請(qǐng)求。
• 401 Unauthorized 被請(qǐng)求的頁(yè)面需要用戶名和密碼。
• 402 Payment Required 此代碼尚無(wú)法使用。
• 403 Forbidden 對(duì)被請(qǐng)求頁(yè)面的訪問被禁止。
• 404 Not Found 服務(wù)器無(wú)法找到被請(qǐng)求的頁(yè)面。

500系列

• 500 Internal Server Error 請(qǐng)求未完成。服務(wù)器遇到不可預(yù)知的情況。
• 501 Not Implemented 請(qǐng)求未完成。服務(wù)器不支持所請(qǐng)求的功能。
• 502 Bad Gateway 請(qǐng)求未完成。服務(wù)器從上游服務(wù)器收到一個(gè)無(wú)效的響應(yīng)。
• 503 Service Unavailable 請(qǐng)求未完成。服務(wù)器臨時(shí)過(guò)載或當(dāng)機(jī)。
• 504 Gateway Timeout 網(wǎng)關(guān)超時(shí)。

返回錯(cuò)誤

• 如果狀態(tài)碼是4xx，就應(yīng)該向用戶返回出錯(cuò)信息。一般來(lái)說(shuō)，返回的信息中將error作為鍵名，出錯(cuò)信息作為鍵值即可。

{
error: "Invalid API key"
}

返回結(jié)果

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

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