REST，即 REpresentational State Transfer，其主語是 Resource，但是被省略掉了，所以全稱是：Resource Representational State Transfer。按照字面意思來理解就是：資源在網絡中以某種表現形式進行狀態(tài)轉移，這樣的直譯，我相信絕大多數看了都是困惑的，用人人都能理解的話來說，就是用 URL 來定位資源，用 HTTP 來描述操作，詳細展開就是：
- 看 URL 就知道要什么
- 看 HTTP method 就知道干什么
- 看 HTTP status code 就知道結果如何
REST 是一種設計風格（不是標準），是一組架構的約束條件和原則，滿足這些約束條件和原則的應用程序或設計就是 RESTful。其次，REST 是面向資源的，而資源是通過 URL 進行暴露的。理解這兩點對認識 REST 和 RESTful 非常重要。
那我們的 API 應該如何設計，才能滿足 RESTful API 的要求呢？
HTTP 動詞
對資源的具體操作類型，應該由 HTTP 動詞表示，具體如下（括號里是對應的 SQL 命令）：
- GET（SELECT）：從服務器取出資源（一項或多項）
- POST（CREATE）：在服務器新建一個資源
- PUT（UPDATE）：在服務器更新資源（客戶端提供改變后的完整資源）
- PATCH（UPDATE）：在服務器更新資源（客戶端提供改變的屬性）
- DELETE（DELETE）：從服務器刪除資源
還有兩個不常用的 HTTP 動詞：
- HEAD：獲取資源的元數據
- OPTIONS：獲取信息，關于資源的哪些屬性是客戶端可以改變的
過濾數據
如果查詢出的數據很多，API 應該提供參數，將數據的過濾結果進行返回，常見的過濾參數如下：
- ?limit=10：指定返回記錄的數量
- ?offset=10：指定返回記錄的開始位置。
- ?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。
- ?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序。
- ?animal_type_id=1：指定篩選條件
參數的設計是允許存在冗余的。
狀態(tài)碼
服務器向用戶返回的狀態(tài)碼和提示信息，常見的有以下一些（方括號中是該狀態(tài)碼對應的HTTP動詞）：
- 200 OK - [GET]：服務器成功返回用戶請求的數據，該操作是冪等的（Idempotent）。
- 201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數據成功。
- 202 Accepted - [*]：表示一個請求已經進入后臺排隊（異步任務）
- 204 NO CONTENT - [DELETE]：用戶刪除數據成功。
- 400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發(fā)出的請求有錯誤，服務器沒有進行新建或修改數據的操作，該操作是冪等的。
- 401 Unauthorized - [*]：表示用戶沒有權限（令牌、用戶名、密碼錯誤）。
- 403 Forbidden - [*] 表示用戶得到授權（與401錯誤相對），但是訪問是被禁止的。
- 404 NOT FOUND - [*]：用戶發(fā)出的請求針對的是不存在的記錄，服務器沒有進行操作，該操作是冪等的。
- 406 Not Acceptable - [GET]：用戶請求的格式不可得（比如用戶請求JSON格式，但是只有XML格式）。
- 410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再得到的。
- 422 Unprocesable entity - [POST/PUT/PATCH] 當創(chuàng)建一個對象時，發(fā)生一個驗證錯誤。
- 500 INTERNAL SERVER ERROR - [*]：服務器發(fā)生錯誤，用戶將無法判斷發(fā)出的請求是否成功。
錯誤處理
如果狀態(tài)碼是 4xx，就應該向用戶返回出錯信息。一般來說，返回的信息中將 error 作為鍵名，出錯信息作為鍵值即可：
{
error: "Invalid API key"
}
返回結果
針對不同操作，服務器向用戶返回的結果應該符合以下規(guī)范：
- GET /collection：返回資源對象的列表（數組）
- GET /collection/resource：返回單個資源對象
- POST /collection：返回新生成的資源對象
- PUT /collection/resource：返回完整的資源對象
- PATCH /collection/resource：返回完整的資源對象
- DELETE /collection/resource：返回一個空文檔
其他
- API 的身份認證應該使用 OAuth 2.0 框架
- 服務器返回的數據格式，應該盡量使用JSON，避免使用XML
參考鏈接：
