RESTful API?是目前比較成熟的一套互聯(lián)網(wǎng)應(yīng)用程序的API設(shè)計(jì)理論

一、協(xié)議

API與用戶的通信協(xié)議，總是使用HTTPs協(xié)議。 應(yīng)用層協(xié)議

二、域名

應(yīng)該盡量將API部署在專用域名之下。并SSL 加密

https://api.example.com

三、版本（Versioning）

應(yīng)該將API的版本號(hào)放入U(xiǎn)RL。

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

?另一種做法是，將版本號(hào)放在HTTP頭信息中，但不如放入U(xiǎn)RL方便和直觀。Github采用這種做法。

四、路徑（Endpoint）

路徑又稱"終點(diǎn)"（endpoint），表示API的具體網(wǎng)址。 見(jiàn)名知意

在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)詞

對(duì)于資源的具體操作類型，由HTTP動(dòng)詞表示。

常用的HTTP動(dòng)詞有下面五個(gè)（括號(hào)里是對(duì)應(yīng)的SQL命令）。

• GET（SELECT）：從服務(wù)器取出資源（一項(xiàng)或多項(xiàng)）。
• POST（CREATE）：在服務(wù)器新建一個(gè)資源。
• PUT（UPDATE）：在服務(wù)器更新資源（客戶端提供改變后的完整資源）。
• PATCH（UPDATE）：在服務(wù)器更新資源（客戶端提供改變的屬性）。
• DELETE（DELETE）：從服務(wù)器刪除資源。

下面是一些例子。

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

?

六、過(guò)濾信息（Filtering）

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

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

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

?

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

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

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

• 200 OK - [GET]：服務(wù)器成功返回用戶請(qǐng)求的數(shù)據(jù)，該操作是冪等的（Idempotent）。
• 201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數(shù)據(jù)成功。
• 202 Accepted - [*]：表示一個(gè)請(qǐng)求已經(jīng)進(jìn)入后臺(tái)排隊(duì)（異步任務(wù)）
• 204 NO CONTENT - [DELETE]：用戶刪除數(shù)據(jù)成功。
• 400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發(fā)出的請(qǐng)求有錯(cuò)誤，服務(wù)器沒(méi)有進(jìn)行新建或修改數(shù)據(jù)的操作，該操作是冪等的。
• 401 Unauthorized - [*]：表示用戶沒(méi)有權(quán)限（令牌、用戶名、密碼錯(cuò)誤）。
• 403 Forbidden - [*] 表示用戶得到授權(quán)（與401錯(cuò)誤相對(duì)），但是訪問(wèn)是被禁止的。
• 404 NOT FOUND - [*]：用戶發(fā)出的請(qǐng)求針對(duì)的是不存在的記錄，服務(wù)器沒(méi)有進(jìn)行操作，該操作是冪等的。
• 406 Not Acceptable - [GET]：用戶請(qǐng)求的格式不可得（比如用戶請(qǐng)求JSON格式，但是只有XML格式）。
• 410 Gone -[GET]：用戶請(qǐng)求的資源被永久刪除，且不會(huì)再得到的。
• 422 Unprocesable entity - [POST/PUT/PATCH] 當(dāng)創(chuàng)建一個(gè)對(duì)象時(shí)，發(fā)生一個(gè)驗(yàn)證錯(cuò)誤。
• 500 INTERNAL SERVER ERROR - [*]：服務(wù)器發(fā)生錯(cuò)誤，用戶將無(wú)法判斷發(fā)出的請(qǐng)求是否成功。

八、錯(cuò)誤處理（Error handling）

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

{
    error: "Invalid API key"
}

九、返回結(jié)果

針對(duì)不同操作，服務(wù)器向用戶返回的結(jié)果應(yīng)該符合以下規(guī)范。文章來(lái)源地址http://www.zghlxwxcb.cn/news/detail-467387.html

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

到了這里，關(guān)于RESTful API 設(shè)計(jì)指南的文章就介紹完了。如果您還想了解更多內(nèi)容，請(qǐng)?jiān)谟疑辖撬阉鱐OY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！