Restful
2000年，Roy Thomas Fielding博士在他的博士論文《Architectural Styles and the Design of Network-based Software Architectures》中提出了幾種軟件應(yīng)用的架構(gòu)風(fēng)格，REST作為其中的一種架構(gòu)風(fēng)格在這篇論文中進行了概括性的介紹养交。
REST:Representational State Transfer的縮寫翠语，翻譯：“具象狀態(tài)傳輸”嚎杨。一般解釋為“表現(xiàn)層狀態(tài)轉(zhuǎn)換”座云。
REST是設(shè)計風(fēng)格而不是標(biāo)準(zhǔn)袒炉。是指客戶端和服務(wù)器的交互形式旁理。我們需要關(guān)注的重點是如何設(shè)計REST風(fēng)格的網(wǎng)絡(luò)接口。
- REST的特點：
- 具象的我磁。一般指表現(xiàn)層孽文，要表現(xiàn)的對象就是資源。比如夺艰，客戶端訪問服務(wù)器芋哭，獲取的數(shù)據(jù)就是資源。比如文字郁副、圖片减牺、音視頻等。
- 表現(xiàn)：資源的表現(xiàn)形式存谎。txt格式拔疚、html格式、json格式既荚、jpg格式等稚失。瀏覽器通過URL確定資源的位置，但是需要在HTTP請求頭中恰聘，用Accept和Content-Type字段指定句各，這兩個字段是對資源表現(xiàn)的描述。
- 狀態(tài)轉(zhuǎn)換：客戶端和服務(wù)器交互的過程憨琳。在這個過程中诫钓，一定會有數(shù)據(jù)和狀態(tài)的轉(zhuǎn)化旬昭，這種轉(zhuǎn)化叫做狀態(tài)轉(zhuǎn)換篙螟。其中，GET表示獲取資源问拘，POST表示新建資源遍略，PUT表示更新資源惧所，DELETE表示刪除資源。HTTP協(xié)議中最常用的就是這四種操作方式绪杏。
- RESTful架構(gòu)：
- 每個URL代表一種資源下愈；
- 客戶端和服務(wù)器之間，傳遞這種資源的某種表現(xiàn)層蕾久；
- 客戶端通過四個http動詞势似，對服務(wù)器資源進行操作，實現(xiàn)表現(xiàn)層狀態(tài)轉(zhuǎn)換僧著。
如何設(shè)計符合RESTful風(fēng)格的API：
一履因、域名：
將api部署在專用域名下：
http://api.example.com
或者將api放在主域名下：
http://www.example.com/api/
二、版本：
將API的版本號放在url中盹愚。
http://www.example.com/app/1.0/info
http://www.example.com/app/1.2/info
三栅迄、路徑：
路徑表示API的具體網(wǎng)址。每個網(wǎng)址代表一種資源皆怕。 資源作為網(wǎng)址毅舆，網(wǎng)址中不能有動詞只能有名詞，一般名詞要與數(shù)據(jù)庫的表名對應(yīng)愈腾。而且名詞要使用復(fù)數(shù)憋活。
錯誤示例：
http://www.example.com/getGoods
http://www.example.com/listOrders
正確示例：
#獲取單個商品
http://www.example.com/app/goods/1
#獲取所有商品
http://www.example.com/app/goods
四、使用標(biāo)準(zhǔn)的HTTP方法：
對于資源的具體操作類型顶滩，由HTTP動詞表示余掖。 常用的HTTP動詞有四個。
GET SELECT ：從服務(wù)器獲取資源礁鲁。
POST CREATE ：在服務(wù)器新建資源盐欺。
PUT UPDATE ：在服務(wù)器更新資源。
DELETE DELETE ：從服務(wù)器刪除資源仅醇。
示例：
#獲取指定商品的信息
GET http://www.example.com/goods/ID
#新建商品的信息
POST http://www.example.com/goods
#更新指定商品的信息
PUT http://www.example.com/goods/ID
#刪除指定商品的信息
DELETE http://www.example.com/goods/ID
五冗美、過濾信息：
如果資源數(shù)據(jù)較多，服務(wù)器不能將所有數(shù)據(jù)一次全部返回給客戶端析二。API應(yīng)該提供參數(shù)粉洼，過濾返回結(jié)果。 實例：
#指定返回數(shù)據(jù)的數(shù)量
http://www.example.com/goods?limit=10
#指定返回數(shù)據(jù)的開始位置
http://www.example.com/goods?offset=10
#指定第幾頁叶摄，以及每頁數(shù)據(jù)的數(shù)量
http://www.example.com/goods?page=2&per_page=20
六属韧、狀態(tài)碼：
服務(wù)器向用戶返回的狀態(tài)碼和提示信息，常用的有：
200 OK ：服務(wù)器成功返回用戶請求的數(shù)據(jù)
201 CREATED ：用戶新建或修改數(shù)據(jù)成功蛤吓。
202 Accepted：表示請求已進入后臺排隊宵喂。
400 INVALID REQUEST ：用戶發(fā)出的請求有錯誤。
401 Unauthorized ：用戶沒有權(quán)限会傲。
403 Forbidden ：訪問被禁止锅棕。
404 NOT FOUND ：請求針對的是不存在的記錄拙泽。
406 Not Acceptable ：用戶請求的的格式不正確。
500 INTERNAL SERVER ERROR ：服務(wù)器發(fā)生錯誤裸燎。
七顾瞻、錯誤信息：
一般來說，服務(wù)器返回的錯誤信息德绿，以鍵值對的形式返回荷荤。
{
error:'Invalid API KEY'
}
八、響應(yīng)結(jié)果：
針對不同結(jié)果移稳，服務(wù)器向客戶端返回的結(jié)果應(yīng)符合以下規(guī)范梅猿。
#返回商品列表
GET http://www.example.com/goods
#返回單個商品
GET http://www.example.com/goods/cup
#返回新生成的商品
POST http://www.example.com/goods
#返回一個空文檔
DELETE http://www.example.com/goods
九、使用鏈接關(guān)聯(lián)相關(guān)的資源：
在返回響應(yīng)結(jié)果時提供鏈接其他API的方法秒裕，使客戶端很方便的獲取相關(guān)聯(lián)的信息袱蚓。
十、其他：
服務(wù)器返回的數(shù)據(jù)格式几蜻，應(yīng)該盡量使用JSON喇潘，避免使用XML。
