一、什么是REST
REST(Representational State Transfer)，可以翻譯成“表現(xiàn)層狀態(tài)轉(zhuǎn)化”
二、理解REST架構(gòu)
1、概念
-
資源（Resources）
"表現(xiàn)層"指的是“資源”的"表現(xiàn)層"。
資源是指網(wǎng)絡(luò)上的一個實體，比如一張圖片，一首歌曲，一種服務(wù)，每種資源對應(yīng)一個特定的URI。
要獲取這個資源，訪問它的URI就可以（URI？ http://www.lxweimin.com/p/de7e1d3d7fb6）
- 表現(xiàn)層（Representation）
"資源"是一種信息實體，它可以有多種外在表現(xiàn)形式。我們把"資源"具體呈現(xiàn)出來的形式，叫做它的"表現(xiàn)層"（Representation）。
比如，文本可以用txt格式表現(xiàn)，也可以用HTML格式、XML格式、JSON格式表現(xiàn)，甚至可以采用二進(jìn)制格式；圖片可以用JPG格式表現(xiàn)，也可以用PNG格式表現(xiàn)。
因此，資源的具體表現(xiàn)形式，即為資源的表現(xiàn)層。HTTP請求通常在頭信息中用Accept和Content-Type字段指定。
-
狀態(tài)轉(zhuǎn)化（State Transfer）
客戶端和服務(wù)的通信，通常是通過資源的表現(xiàn)層對資源狀態(tài)的改變。
互聯(lián)網(wǎng)通信協(xié)議HTTP協(xié)議，是一個無狀態(tài)協(xié)議。這意味著，所有的狀態(tài)都保存在服務(wù)器端。因此，如果客戶端想要操作服務(wù)器，必須通過某種手段，讓服務(wù)器端發(fā)生"狀態(tài)轉(zhuǎn)化"（State Transfer）。而這種轉(zhuǎn)化是建立在表現(xiàn)層之上的，所以就是"表現(xiàn)層狀態(tài)轉(zhuǎn)化"。
客戶端用到的手段，只能是HTTP協(xié)議。具體來說，就是HTTP協(xié)議里面，四個表示操作方式的動詞：GET、POST、PUT、DELETE。它們分別對應(yīng)四種基本操作：GET用來獲取資源，POST用來新建資源（也可以用于更新資源），PUT用來更新資源，DELETE用來刪除資源。
2、綜述
（1）每一個URI代表一種資源；
（2）客戶端和服務(wù)器之間，傳遞這種資源的某種表現(xiàn)層；
（3）客戶端通過四個HTTP動詞，對服務(wù)器端資源進(jìn)行操作，實現(xiàn)"表現(xiàn)層狀態(tài)轉(zhuǎn)化"。
三、RESTful API如何設(shè)計
RESTful API指在提供一種統(tǒng)一的機(jī)制，方便不同的前端設(shè)備與后端進(jìn)行通信。
1、協(xié)議
API與用戶的通信協(xié)議，總是使用HTTPs協(xié)議。
2、域名
應(yīng)該盡量將API部署在專用域名之下。
https://api.example.com
如果確定API很簡單，不會有進(jìn)一步擴(kuò)展，可以考慮放在主域名下。
https://example.org/api/
3、版本（Versioning）
應(yīng)該將API的版本號放入URL。
https://api.example.com/v1/
另一種做法是，將版本號放在HTTP頭信息中，但不如放入URL方便和直觀。Github采用這種做法。
4、路徑（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
5、HTTP動詞
對于資源的具體操作類型，由HTTP動詞表示。
常用的HTTP動詞有下面五個（括號里是對應(yīng)的SQL命令）。
GET（SELECT）：從服務(wù)器取出資源（一項或多項）。
POST（CREATE）：在服務(wù)器新建一個資源。
PUT（UPDATE）：在服務(wù)器更新資源（客戶端提供改變后的完整資源）。
PATCH（UPDATE）：在服務(wù)器更新資源（客戶端提供改變的屬性）。
DELETE（DELETE）：從服務(wù)器刪除資源。
還有兩個不常用的HTTP動詞。
HEAD：獲取資源的元數(shù)據(jù)。
OPTIONS：獲取信息，關(guān)于資源的哪些屬性是客戶端可以改變的。
6、過濾信息（Filtering）
?limit=10：指定返回記錄的數(shù)量
?offset=10：指定返回記錄的開始位置。
?page=2&per_page=100：指定第幾頁，以及每頁的記錄數(shù)。
?sortby=name&order=asc：指定返回結(jié)果按照哪個屬性排序，以及排序順序。
?animal_type_id=1：指定篩選條件
7、狀態(tài)碼（Status Codes）
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ā)出的請求是否成功。
8、錯誤處理（Error handling）
{
error: "Invalid API key"
}
9、返回結(jié)果
GET /collection：返回資源對象的列表（數(shù)組）
GET /collection/resource：返回單個資源對象
POST /collection：返回新生成的資源對象
PUT /collection/resource：返回完整的資源對象
PATCH /collection/resource：返回完整的資源對象
DELETE /collection/resource：返回一個空文檔
10、Hypermedia API
{
"link": { "rel": "collection [https://www.example.com/zoos](https://www.example.com/zoos)", "href": "[https://api.example.com/zoos](https://api.example.com/zoos)", "title": "List of zoos", "type": "application/vnd.yourformat+json"}}
轉(zhuǎn)載自阮大神的博文
http://www.ruanyifeng.com/blog/2014/05/restful_api.html
http://www.ruanyifeng.com/blog/2011/09/restful
