restful api接口規範

簡介：

REST：英文representational state transfer直譯爲表現層狀態轉移，或者表述性狀態轉移。

爲何須要Restful？

URL具備很強可讀性的，具備自描述性

規範化請求過程和返回結果

資源描述與視圖的鬆耦合

可提供OpenAPI，便於第三方系統集成，提升互操做性

提供無狀態的服務接口，下降複雜度，可提升應用的水平擴展性

一、版本號

命名版本號能夠解決版本不兼容問題，在設計 RESTful API 的一種實用的作法是使用版本號。通常狀況下，咱們會在 url 中保留舊版本號，並同時兼容多個版本

【GET】  /v1/users/{user_id}  // 版本 v1 的查詢用戶列表的 API 接口

【GET】  /v2/users/{user_id}  // 版本 v2 的查詢用戶列表的 API 接口

二、資源路徑

URI 不能包含動詞，只能是名詞（命名名詞的時候，要使用小寫、數字及下劃線來區分多個單詞）。

資源的路徑應該從根到子依次以下:

/{resources}/{resource_id}/{sub_resources}/{sub_resource_id}/{sub_resource_property}

【POST】  /v1/users/{user_id}/roles/{role_id} // 添加用戶的角色

 

有的時候，當一個資源變化難以使用標準的 RESTful API 來命名，能夠考慮使用一些特殊的 actions 命名。

/{resources}/{resource_id}/actions/{action}

【PUT】  /v1/users/{user_id}/password/actions/modify // 密碼修改

 

三、請求方式

【GET】          /users                # 查詢用戶信息列表

【GET】          /users/1001           # 查看某個用戶信息

【POST】         /users                # 新建用戶信息

【PUT】          /users/1001           # 更新用戶信息(所有字段)

【PATCH】        /users/1001           # 更新用戶信息(部分字段)

【DELETE】       /users/1001           # 刪除用戶信息

 

【PATCH】通常不用，用【PUT】

四、查詢參數

RESTful API 接口應該提供參數，過濾返回結果。

【GET】  /{version}/{resources}/{resource_id}?offset=0&limit=20

 

五、響應參數

JSON格式（code、data、msg）

 

六、狀態碼

使用適合的狀態碼很重要，而不該該所有都返回狀態碼 200

狀態碼，可根據如下標準按照項目擴展自身狀態碼：

200~299段 表示操做成功：

200 操做成功，正常返回

201 操做成功，已經正在處理該請求

300~399段 表示參數方面的異常

300 參數類型錯誤

301 參數格式錯誤

302 參數超出正常取值範圍

303 token過時

304 token無效

400~499段 表示請求地址方面的異常：

400 找不到地址

500~599段 表示內部代碼異常：

500 服務器代碼異常