RESTful是什么？

本質(zhì)

是一種軟件架構(gòu)風(fēng)格

核心

面向資源

解決的問(wèn)題

• 降低開發(fā)的復(fù)雜性
• 提高系統(tǒng)的可伸縮性

設(shè)計(jì)概念和準(zhǔn)則

• 網(wǎng)絡(luò)上的所有事物都可以被抽象為資源（所謂“資源”，就是網(wǎng)絡(luò)上的一個(gè)實(shí)體，或者說(shuō)是網(wǎng)絡(luò)上的一個(gè)具體信息）
• 每一個(gè)資源都有唯一的資源標(biāo)識(shí)，對(duì)資源的操作不會(huì)改變這些標(biāo)識(shí)
• 所有的操作都是無(wú)狀態(tài)的

和SOAP的區(qū)別

SOAP WebService

• WebService是一種跨編程語(yǔ)言和跨操作系統(tǒng)平臺(tái)的遠(yuǎn)程調(diào)用技術(shù)。
• WebService通過(guò)HTTP協(xié)議發(fā)送請(qǐng)求和接收結(jié)果時(shí)采用XML格式封裝，并增加了一些特定的HTTp消息頭，這些特定的HTTP消息頭和XML內(nèi)容格式就是SOAP格式

在效率和易用性的區(qū)別

• SOAP由于各種需求不斷擴(kuò)充其本身協(xié)議的內(nèi)容，導(dǎo)致在SOAP處理方面的性能有所下降，同時(shí)在易用性方面以及學(xué)習(xí)成本上也有所增加
• RESTful由于其面向資源接口設(shè)計(jì)以及操作抽象簡(jiǎn)化了開發(fā)者的不良設(shè)計(jì)，同時(shí)也最大限度的利用了Http最初的應(yīng)用協(xié)議設(shè)計(jì)理念

安全性的區(qū)別

RESTful對(duì)于資源型服務(wù)接口來(lái)說(shuō)很合適，同時(shí)特別適合對(duì)于效率要求很高，但是對(duì)于安全要求不高的場(chǎng)景，
SOAP的成熟性可以給需要提供給多開發(fā)語(yǔ)言的，對(duì)于安全性要求較高的接口設(shè)計(jì)帶來(lái)便利，所以我覺(jué)得純粹說(shuō)上面設(shè)計(jì)模式將會(huì)占據(jù)主導(dǎo)地位沒(méi)有什么意義，關(guān)鍵還是看應(yīng)用場(chǎng)景。

如何設(shè)計(jì)RESTful API

資源路徑

在RESTful架構(gòu)中，每個(gè)網(wǎng)址代表一種資源，所以網(wǎng)址中不能有動(dòng)詞，只能有名詞，一般來(lái)說(shuō)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        //動(dòng)物園資源
https://api.example.com/v1/animals    //動(dòng)物資源
https://api.example.com/v1/employees  //雇員資源

HTTP動(dòng)詞

對(duì)于資源的操作（CURD），由HTTP動(dòng)詞（謂詞）表示

常見(jiàn)的幾個(gè)HTTP動(dòng)詞

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

舉例

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

過(guò)濾信息

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

舉例

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

狀態(tài)碼

服務(wù)器向用戶返回的狀態(tài)碼和提示信息，使用標(biāo)準(zhǔn)HTTP狀態(tài)碼

• 200 OK：服務(wù)器成功返回用戶請(qǐng)求的數(shù)據(jù)，該操作是冪等的
• 201 CREATED：用戶新建或修改數(shù)據(jù)成功。
• 204 NO CONTENT ：用戶刪除數(shù)據(jù)成功。
• 400 INVALID REQUEST：用戶發(fā)出的請(qǐng)求有錯(cuò)誤，該操作是冪等的。
• 401 Unauthorized ：表示用戶沒(méi)有認(rèn)證，無(wú)法進(jìn)行當(dāng)前操作（沒(méi)有提供權(quán)限認(rèn)證）。
• 403 Forbidden ： 表示用戶訪問(wèn)是被禁止的（提供了權(quán)限認(rèn)證，但是錯(cuò)誤的）。
  404 NOT FOUND ：用戶發(fā)出的請(qǐng)求針對(duì)的是不存在的記錄，服務(wù)器沒(méi)有進(jìn)行操作，該操作是冪等的
• 422 Unprocesable entity： 當(dāng)創(chuàng)建一個(gè)對(duì)象時(shí)，發(fā)生一個(gè)驗(yàn)證錯(cuò)誤。
• 500 INTERNAL SERVER ERROR ：服務(wù)器發(fā)生錯(cuò)誤，用戶將無(wú)法判斷發(fā)出的請(qǐng)求是否成功

錯(cuò)誤處理

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

返回結(jié)果

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

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