對於一些現代化的 MVC 框架，在腳手架階段可能就會自動生成 RESTful 風格的 Controller。
資源的拆分
路由中 URI 中的資源都是名詞，即一個個實體，對於代碼而言，可以看做一個個類到 URI 的映射，比如：
- GET /repos/:owner/:repo/stargazers
- GET /organizations
對於 RESTful API 中，常用的動詞有以下幾種：
GET（SELECT）：從服務器取出資源（一項或多項）。
POST（CREATE）：在服務器新建一個資源。
PUT（UPDATE）：在服務器更新資源（客戶端提供改變後的完整資源）。
PATCH（UPDATE）：在服務器更新資源（客戶端提供改變的屬性）。
DELETE（DELETE）：從服務器刪除資源。
PUT 和 PATCH 的區別主要在於更新整個資源還是更新局部資源。
版本
當 API 可能出現重大變更，無法向後兼容時，RESTful API 提供了版本花的概念，可以保證舊版和新版的 API 的使用，有三種方法存放版本號：
- 在uri中放版本信息：GET /v1/users/1
- Accept Header：Accept: application/json+v1
- 自定義 Header：X-Api-Version: 1
過濾
API 應該提供一定的篩選條件，比如：
?limit=10：指定返回記錄的數量
?offset=10：指定返回記錄的開始位置。
?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。
?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序。
?animal_type_id=1：指定篩選條件
狀態碼
服務器返回的狀態碼應該複合 HTTP 的規範，比如：
200 OK - [GET]：服務器成功返回用戶請求的數據，該操作是冪等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數據成功。
202 Accepted - []：表示一個請求已經進入後臺排隊（異步任務）
204 NO CONTENT - [DELETE]：用戶刪除數據成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發出的請求有錯誤，服務器沒有進行新建或修改數據的操作，該操作是冪等的。
401 Unauthorized - []：表示用戶沒有權限（令牌、用戶名、密碼錯誤）。
403 Forbidden - [] 表示用戶得到授權（與401錯誤相對），但是訪問是被禁止的。
404 NOT FOUND - []：用戶發出的請求針對的是不存在的記錄，服務器沒有進行操作，該操作是冪等的。
406 Not Acceptable - [GET]：用戶請求的格式不可得（比如用戶請求JSON格式，但是隻有XML格式）。
410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 當創建一個對象時，發生一個驗證錯誤。
500 INTERNAL SERVER ERROR - [*]：服務器發生錯誤，用戶將無法判斷髮出的請求是否成功。
返回 JSON
RESTful API 應該儘可能的返回 JSON，對於錯誤的請求，需要爲用戶提供錯誤的信息。
- {
- "code": 1234,
- "message": "Something bad happened :-(",
- "description": "More details about the error here"
- }
body 只需要直接返回數據，不需要進行包裝比如：
- {
- "success": true,
- "data": {"id":1,"name":"xiaotuan"},
- }
儘管 RESTful API 的設計規範清晰可讀，但是針對一些特殊的需求，我們可能也不一定要強制遵守 RESTful API 的設計規範。比如批量刪除，DELETE 在 HTTP 規範中是沒有參數的，這就給批量刪除接口帶來了一定的麻煩，可以考慮改用 POST。
參考資料