restful API 規范（轉）

1. URI

URI 表示資源，資源一般對應服務器端領域模型中的實體類。

URI規范

1. 不用大寫；
2. 用中杠-不用下杠_；
3. 參數列表要encode；
4. URI中的名詞表示資源集合，使用復數形式。

資源集合 vs 單個資源

URI表示資源的兩種方式：資源集合、單個資源。

資源集合：

/zoos //所有動物園 /zoos/1/animals //id為1的動物園中的所有動物

單個資源：

/zoos/1 //id為1的動物園

避免層級過深的URI

/在url中表達層級，用於按實體關聯關系進行對象導航，一般根據id導航。

過深的導航容易導致url膨脹，不易維護，如 GET /zoos/1/areas/3/animals/4(超過3層算過深)，盡量使用查詢參數代替路徑中的實體導航，如GET /animals?zoo=1&area=3；

對Composite資源的訪問

服務器端的組合實體必須在uri中通過父實體的id導航訪問。

組合實體不是first-class的實體，它的生命周期完全依賴父實體，無法獨立存在，在實現上通常是對數據庫表中某些列的抽象，不直接對應表，也無id。一個常見的例子是 User — Address，Address是對User表中zipCode/country/city三個字段的簡單抽象，無法獨立於User存在。必須通過User索引到Address：GET /user/1/addresses

Action不符合CRUD操作

利用RESTful原則像處理子資源一樣處理它。例如，Github的API讓你通過PUT /gists/:id/star 來 star a gist ，而通過DELETE /gists/:id/star來進行 unstar 。

我們統一用post操作，在url的最后增加操作，以上面Github的例子來說，分別為POST /gits/:id/star，POST /gits/:id/unstar

 

2. Request

HTTP方法

通過標准HTTP方法對資源CRUD：

GET：查詢

GET /zoos GET /zoos/1 GET /zoos/1/employees

POST：創建單個資源。POST一般向“資源集合”型uri發起

POST /animals //新增動物 POST /zoos/1/employees //為id為1的動物園雇佣員工

PUT：更新單個資源（全量），客戶端提供完整的更新后的資源。與之對應的是 PATCH，PATCH 負責部分更新，客戶端提供要更新的那些字段。PUT/PATCH一般向“單個資源”型uri發起

PUT /animals/1 PUT /zoos/1

我們用post和在url上加了“create”代替PUT，如：post: schools/create, post: schools/:id/update

DELETE：刪除

DELETE /zoos/1/employees/2 DELETE /zoos/1/employees/2;4;5 DELETE /zoos/1/animals //刪除id為1的動物園內的所有動物

我們用post和在url上加了“remove/delete”代替DELETE,  如： post:  schools/:id/remove

如果參數超過url長度限制，可以使用post代替

安全性和冪等性

1. 安全性：不會改變資源狀態，可以理解為只讀的；
2. 冪等性：執行1次和執行N次，對資源狀態改變的效果是等價的。

 

GET	√	√
POST	×	×
PUT	×	√
DELETE	×	√

安全性和冪等性均不保證反復請求能拿到相同的response。以 DELETE 為例，第一次DELETE返回200表示刪除成功，第二次返回404提示資源不存在，這是允許的。

冪等性參考：http://www.cnblogs.com/weidagang2046/archive/2011/06/04/2063696.html

復雜查詢

查詢可以捎帶以下參數：

 

過濾條件	?type=1&age=16	允許一定的uri冗余，如/zoos/1與/zoos?id=1
排序	?sort=age,desc
投影	?whitelist=id,name,email
分頁	?pageSize=10&pageNum=3
搜索	?k=關鍵字1	k表示key，關鍵字

 

Bookmarker

經常使用的、復雜的查詢標簽化，降低維護成本。

如：

GET /trades?status=closed&sort=created,desc

快捷方式：

GET /trades#recently-closed 或者 GET /trades/recently-closed

Format

只用以下常見的3種body format：

1. Content-Type: application/json

   POST /v1/animal HTTP/1.1
   Host: api.example.org
   Accept: application/json
   Content-Type: application/json
   Content-Length: 24
   
   {   
     "name": "Gir",
     "animalType": "12"
   }

2. Content-Type: application/x-www-form-urlencoded (瀏覽器POST表單用的格式)

   POST /login HTTP/1.1
   Host: example.com
   Content-Length: 31
   Accept: text/html
   Content-Type: application/x-www-form-urlencoded
   
   "username":"root"

   "password":"Zion0101"(MD5加密)

3. Content-Type: multipart/form-data; boundary=—-RANDOM_jDMUxq4Ot5 (表單有文件上傳時的格式)

Content Negotiation

資源可以有多種表示方式，如json、xml、pdf、excel等等，客戶端可以指定自己期望的格式，通常有兩種方式：

1. 1. http header Accept：

      Accept:application/xml;q=0.6,application/atom+xml;q=1.0

      q為各項格式的偏好程度

   2. url中加文件后綴：/zoo/1.json

6. Response

1. 不要包裝： 
   response 的 body 直接就是數據，不要做多余的包裝，示例：

   {
       "code":10000, "data":{"id":1,"name":"xiaotuan"} }

   失敗樣例：

   {
       "code":10103, "message":"" }

2. 各HTTP方法成功處理后的數據格式：

    

2. GET	單個對象、集合
   POST	新增成功的對象
   PUT/PATCH	更新成功的對象
   DELETE	空

3. json格式的約定：

   1. 時間用長整形(毫秒數)，客戶端自己按需解析（moment.js）
   2. 不傳null字段

分頁response

{
       "code":10000
       "data":{
                   "pageNum": 3,
                   "pageSize": 10,
                   "totalCount": 100,
                   "totalPage": 10,
                   "items":[{},{},{}...]
       }

}

7. 錯誤處理

1. 不要發生了錯誤但給2xx響應，客戶端可能會緩存成功的http請求；
2. 正確設置http狀態碼，不要自定義；
3. Response body 提供 1) 錯誤的代碼（日志/問題追查）；2) 錯誤的描述文本（展示給用戶）。

對第三點的實現稍微多說一點：

Java 服務器端一般用異常表示 RESTful API 的錯誤。API 可能拋出兩類異常：業務異常和非業務異常。業務異常由自己的業務代碼拋出，表示一個用例的前置條件不滿足、業務規則沖突等，比如參數校驗不通過、權限校驗失敗。非業務類異常表示不在預期內的問題，通常由類庫、框架拋出，或由於自己的代碼邏輯錯誤導致，比如數據庫連接失敗、空指針異常、除0錯誤等等。

業務類異常必須提供2種信息：

1. 1. 如果拋出該類異常，HTTP 響應狀態碼應該設成什么；
   2. 異常的文本描述；

在Controller層使用統一的異常攔截器：

1. 1. 設置 HTTP 響應狀態碼；
   2. Response Body 的錯誤碼：對業務類異常，用自定義的其他狀態碼；對非業務類異常，統一用10103
   3. Response Body 的錯誤描述：對業務類異常，用它指定的錯誤文本；對非業務類異常，線上可以統一文案如“服務器端錯誤，請稍后再試”，開發或測試環境中用異常的 stacktrace，服務器端提供該行為的開關。

常用的http狀態碼及使用場景(這里我們統一返回200，在消息體中使用自定義的狀態碼來處理)：

 

400 bad request	常用在參數校驗
401 unauthorized	未經驗證的用戶，常見於未登錄。如果經過驗證后依然沒權限，應該 403（即 authentication 和 authorization 的區別）。
403 forbidden	無權限
404 not found	資源不存在
500 internal server error	非業務類異常
503 service unavaliable	由容器拋出，自己的代碼不要拋這個異常

 

8. 服務型資源

除了資源簡單的CRUD，服務器端經常還會提供其他服務，這些服務無法直接用上面提到的URI映射。如：

1. 1. 按關鍵字搜索；
   2. 計算地球上兩點間的距離；
   3. 批量向用戶推送消息

可以把這些服務看成資源，計算的結果是資源的presentation，按服務屬性選擇合適的HTTP方法。

例：

GET /search?q=filter?category=file  搜索
GET /distance-calc?lats=47.480&lngs=-122.389&late=37.108&lnge=-122.448 POST /batch-publish-msg [{"from":0,"to":1,"text":"abc"},{},{}...]

9. 異步任務

對耗時的異步任務，服務器端接受客戶端傳遞的參數后，應返回創建成功的任務資源，其中包含了任務的執行狀態。客戶端可以輪訓該任務獲得最新的執行進度。

提交任務：
POST /batch-publish-msg
[{"from":0,"to":1,"text":"abc"},{},{}...] 返回： {"taskId":3,"createBy":"Anonymous","status":"running"} GET /task/3 {"taskId":3,"createBy":"Anonymous","status":"success"}

如果任務的執行狀態包括較多信息，可以把“執行狀態”抽象成組合資源，客戶端查詢該狀態資源了解任務的執行情況。

提交任務：
POST /batch-publish-msg
[{"from":0,"to":1,"text":"abc"},{},{}...] 返回： {"taskId":3,"createBy":"Anonymous"} GET /task/3/status {"progress":"50%","total":18,"success":8,"fail":1}

10. API的演進

版本

常見的三種方式：

1. 1. 在uri中放版本信息：GET /v1/users/1
   2. Accept Header：Accept: application/json+v1
   3. 自定義 Header：X-Api-Version: 1

用第一種，雖然沒有那么優雅，但最明顯最方便。

URI失效

隨着系統發展，總有一些API失效或者遷移，對失效的API，返回404 not found 或 410 gone；對遷移的API，返回 301 重定向。

 

來源：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

參考內容：https://github.com/aisuhua/restful-api-design-references