1. 什麼是restful
REST——Representational State Transfer，表現層狀態轉移。它被Roy Felding提出（在他的”基於網絡的軟件架構“論文中第五章）。REST的核心原則是將API拆分爲邏輯上的資源。這些資源通過http被操作（GET ,POST,PUT,DELETE）。
如果一個架構符合rest原則，就稱它爲restful架構。
理解restful架構，首先要理解rest
- resources 資源是指網絡上的一個實體，或者說一個具體信息。而表現層實際上就是資源的表現層
- representation 把”資源”具體呈現出來的形式，叫做它的”表現層”。
state transfer 訪問一個網站，一定涉及到客戶端和服務端的交互，也就一定存在數據和狀態的變化，這就是狀態轉化
rest風格的特徵
客戶端服務端分離
- 無狀態
- 緩存
- 分層部署
- 統一接口
- 支持按需代碼
綜述：什麼是restful架構
- 每一個URI代表一種資源
- 客戶端和服務器之間，傳遞這種資源的某種表現層
- 客戶端通過http動詞，對服務器端資源進行操作，實現“表現層狀態轉化”。
（就是用URL定位資源，用HTTP描述操作。
看Url就知道要什麼
看http method就知道幹什麼
看http status code就知道結果如何）
2. restful 實例及誤區
restful 架構典型設計誤區
- URI 包含動詞
/posts/show/1 X
/posts/1 √
使用get方法實現show
3. restful API設計規範
協議
API與用戶的通信協議，總是使用HTTPs協議域名
應該儘量將API部署在專用域名之下。
如果確定API很簡單，不會有進一步擴展，可以考慮放在主域名下。URI規範
不用大寫；
用連字符’-’ 不用下劃線 ‘_’ ；
參數列表要encode；HTTP動詞
| 動詞 | 說明 |
|---|---|
| GET（SELECT） | 從服務器取出資源（一項或多項）。 |
| POST（CREATE） | 在服務器新建一個資源。 |
| PUT（UPDATE） | 在服務器更新資源（客戶端提供改變後的完整資源）。 |
| PATCH（UPDATE） | 在服務器更新資源（客戶端提供改變的屬性）。 |
| DELETE（DELETE） | 從服務器刪除資源。 |
| HEAD | 獲取資源的元數據。 |
| OPTIONS | 獲取信息，關於資源的哪些屬性是客戶端可以改變的。 |
安全性和冪等性
安全性：不會改變資源狀態，可以理解爲只讀的；
冪等性：執行1次和執行N次，對資源狀態改變的效果是等價的。
| 方法 | 安全性 | 冪等性 |
|---|---|---|
| GET | √ | √ |
| POST | × | × |
| PUT | × | √ |
| DELETE | × | √ |
安全性和冪等性均不保證反覆請求能拿到相同的response。以 DELETE 爲例，第一次DELETE返回200表示刪除成功，第二次返回404提示資源不存在，這是允許的。
5. 錯誤處理
不要發生了錯誤但給2xx響應，客戶端可能會緩存成功的http請求；
正確設置http狀態碼，不要自定義；
提供 a. 錯誤的代碼（日誌/問題追查）；b. 錯誤的描述文本（展示給用戶）
常用狀態碼
| 狀態碼 | error | 使用場景 |
|---|---|---|
| 200 | OK | 服務器成功返回用戶請求的數據，該操作是冪等的（Idempotent）。 |
| 201 | create - [POST/PUT/PATCH] | 用戶新建或修改數據成功。 |
| 202 | accepted | 表示一個請求已經進入後臺排隊（異步任務） |
| 204 | no conflict - [DELETE] | 用戶刪除數據成功。 |
| 400 | bad request | 常用在參數校驗 |
| 401 | unauthorized | 未經驗證的用戶，常見於未登錄。 |
| 403 | forbidden | 無權限 |
| 404 | not found | 資源不存在 |
| 500 | internal server error | 非業務類異常 |
| 503 | service unavaliable | 由容器拋出，自己的代碼不要拋這個異常 |
6. API的演進
常見的三種方式：
在uri中放版本信息：GET /v1/users/1
Accept Header：Accept: application/json+v1
自定義 Header：X-Api-Version: 1
用第一種，雖然沒有那麼優雅，但最明顯最方便。
參考文章：
http://novoland.github.io/%E8%AE%BE%E8%AE%A1/2015/08/17/Restful%20API%20%E7%9A%84%E8%AE%BE%E8%AE%A1%E8%A7%84%E8%8C%83.html
http://www.ruanyifeng.com/blog/2011/09/restful.html
http://www.ruanyifeng.com/blog/2014/05/restful_api.html