SpringBoot系列: 設計Restful風格的API
RESTful 架構
REST 並非一種技術或規範, 而是一種架構風格, 如果一個架構符合Rest的約束條件和原則, 就可以稱作是 RESTful 架構.
REST全稱是Representational State Transfer, 省略了定語 Resource, 完整的講法是"資源表現性狀態轉移", 要設計符合RESTful風格的關鍵是, 應始終圍繞資源來分析問題.
-------------------------
1. 使用 api 作為上下文
-------------------------
上下文path建議加上 api
http://192.168.1.1/api
或者使用api作為二級域名
http://api.xxxx.com
-------------------------
2. 增加一個版本標識
-------------------------
推薦在 url 增加版本標識, 也有做法是將版本加到 http 頭上
http://192.168.1.1/api/v1.1
-------------------------
3. 確定 Http method
-------------------------
[安全]特性: 1次或多次操作都不會有副作用.
[冪等]: 多次操作的結果和1次操作的結果是一致的.
GET, [安全且冪等] 代表查詢資源, 相當於資料庫CRUD中的 Retrieve.
GET 動作應該是冪等操作, 也就是說多次 GET 操作, 結果應該是一致的, 理論上, 我們可以使用GET完成資源建立動作, 但這樣違反了GET的冪等屬性.
POST, [不安全且不冪等], 代替新增資源, 相當於資料庫CRUD中的 Create.
PUT, [不安全但冪等], 代表更改資源, 客戶端需要提供"完整"的資源屬性. 相當於資料庫CRUD中全欄位的Update.
PATCH, [不安全但冪等], 代表更改資源, 客戶端僅提供"需要更改"的資源屬性. 相當於資料庫CRUD中的 Update.
DELETE, [不安全但冪等], 代表刪除資源, 因為要求冪等性, 所以這裡的刪除應該以邏輯刪除方式實現. 相當於資料庫CRUD中的 Update.
-------------------------
4. 返回結果
-------------------------
針對不同操作, 伺服器向用戶返回的結果應該符合以下規範.
GET /collection: 返回資源物件的列表(陣列)
GET /collection/resource: 返回單個資源物件
POST /collection: 返回新生成的資源物件
PUT /collection/resource: 返回完整的資源物件
PATCH /collection/resource: 返回完整的資源物件
DELETE /collection/resource: 返回一個空文件
-------------------------
5. 狀態碼 和 錯誤處理
-------------------------
伺服器向用戶返回的狀態碼和提示資訊，常見的有以下一些（方括號中是該狀態碼對應的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 - [*]：伺服器發生錯誤，使用者將無法判斷髮出的請求是否成功。
如果狀態碼是4xx, 就應該向使用者返回出錯資訊. 一般來說, 返回的資訊中將error作為鍵名, 出錯資訊作為鍵值即可.
{
error: "Invalid API key"
}
-------------------------
6. url 規範和示例
-------------------------
總則:
1. 儘量使用/來表示資源的層級關係, 比如 GET /zoos/ID/animals
2. 使用?追加控制引數, 而不是資源id
3. url中複合單詞引數應該使用中劃線或下劃線, url儘量都是小寫字母, 不推薦使用 lowerUpperCase 這樣的寫法.
4. url資源應該是名詞, 操作應該由Http method指明, 而不是在url中使用 delete-user 或 create-user 字樣.
5. url資源名詞應該使用複數形式.
新增一個使用者
POST http://192.168.1.1/api/v1.1/depts/1/users
查詢使用者, id為451
GET http://192.168.1.1/api/v1.1/depts/1/users/451
查詢所有的使用者
GET http://192.168.1.1/api/v1.1/depts/1/users
查詢所有被禁的使用者, 使用 ? 做過濾條件
GET http://192.168.1.1/api/v1.1/depts/1/users?disable=1
翻頁查詢, 增加 offset/limit 等控制引數
GET http://192.168.1.1/api/v1.1/depts/1/users?offset=1&limit=20&desc=created_at,id&asc=grade,updated_at
查詢指定型別的使用者
GET http://192.168.1.1/api/v1.1/depts/1/users?use-type=1
更新使用者,id為451
PUT http://192.168.1.1/api/v1.1/depts/1/users/451
刪除使用者,id為451
DELETE http://192.168.1.1/api/v1.1/depts/1/users/451
查詢兩個使用者, id為451和254
GET http://192.168.1.1/api/v1.1/depts/1/users/451,452
或
GET http://192.168.1.1/api/v1.1/depts/1/users/451;452
=============================
參考
=============================
http://www.ruanyifeng.com/blog/2014/05/restful_api.html
http://www.cnblogs.com/ajianbeyourself/p/3751831.html