簡介:
REST:英文representational state transfer直譯爲表現層狀態轉移,或者表述性狀態轉移。
爲什麼需要Restful?
URL具有很強可讀性的,具有自描述性
規範化請求過程和返回結果
資源描述與視圖的鬆耦合
可提供OpenAPI,便於第三方系統集成,提高互操作性
提供無狀態的服務接口,降低複雜度,可提高應用的水平擴展性
1、版本號
命名版本號可以解決版本不兼容問題,在設計 RESTful API 的一種實用的做法是使用版本號。一般情況下,我們會在 url 中保留舊版本號,並同時兼容多個版本
【GET】 /v1/users/{user_id} // 版本 v1 的查詢用戶列表的 API 接口
【GET】 /v2/users/{user_id} // 版本 v2 的查詢用戶列表的 API 接口
2、資源路徑
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 // 密碼修改
3、請求方式
【GET】 /users # 查詢用戶信息列表
【GET】 /users/1001 # 查看某個用戶信息
【POST】 /users # 新建用戶信息
【PUT】 /users/1001 # 更新用戶信息(全部字段)
【PATCH】 /users/1001 # 更新用戶信息(部分字段)
【DELETE】 /users/1001 # 刪除用戶信息
【PATCH】一般不用,用【PUT】
4、查詢參數
RESTful API 接口應該提供參數,過濾返回結果。
【GET】 /{version}/{resources}/{resource_id}?offset=0&limit=20
5、響應參數
JSON格式(code、data、msg)
6、狀態碼
使用適合的狀態碼很重要,而不應該全部都返回狀態碼 200
狀態碼,可根據以下標準按照項目擴展自身狀態碼:
200~299段 表示操作成功:
200 操作成功,正常返回
201 操作成功,已經正在處理該請求
300~399段 表示參數方面的異常
300 參數類型錯誤
301 參數格式錯誤
302 參數超出正常取值範圍
303 token過期
304 token無效
400~499段 表示請求地址方面的異常:
400 找不到地址
500~599段 表示內部代碼異常:
500 服務器代碼異常