說明:其實沒有絕對的規范,達到90%即可。
理解RESTful架構:http://www.ruanyifeng.com/blog/2011/09/restful.html
RESTful API 設計指南:http://www.ruanyifeng.com/blog/2014/05/restful_api.html
GitHub標准RESTful API:https://api.github.com/
教程收集:
http://imweb.io/topic/5707561f06f2400432c139a5(以下內容轉自此篇文章)
http://www.coderli.com/translate-restful-standard-resolved/
http://blog.csdn.net/yue7603835/article/details/52536497
http://blog.csdn.net/u013731455/article/details/56278168
https://www.zhihu.com/question/28557115
URI
URI規范
- 不要用大寫
- 單詞間使用下划線'_'
- 不使用動詞,資源要使用名詞復數形式,如:user、rooms、tickets
- 層級
>=
三層,則使用'?'帶參數users/1/address/2/citys(bad) /citys?users=1&address=2; (good)
Request
Method
- GET:查詢資源
- POST:創建資源
-
PUT/PATCH
- PUT:全量更新資源(提供改變后的完整資源)
- PATCH:局部更新資源(僅提供改變的屬性)
-
DELETE:刪除資源
安全性與冪等性
- 安全性:任意多次對同一資源操作,都不會導致資源的狀態變化
- 冪等性:任意次對同一資源操作,對資源的改變是一樣的
-
Method 安全性 冪等性 GET √ √ POST × × PUT × √ PATCH × √ DELETE × √
兼容
很多客戶只支持GET/POST請求,一般有兩種方式模擬PUT等請求
- 添加_method參數
/users/1?_method=put&name=111
- 添加X-HTTP-Method-Override請求頭 (我們使用這種方式)
X-HTTP-Method-Override: PUT
參數
Method
GET
- 非id的參數使用'?'方式傳輸
/users/1?state=closed
POST、PATCH、PUT、DELETE
- 非id的參數使用body傳輸,並且應該encode
過濾
?type=1&state=closed
排序
+
升序,如?sort=+create_time,根據id升序-
降序,如?sort=-create_time,根據id降序
分頁
?limit=10&offset=10
- limit:返回記錄數量
- offset:返回記錄的開始位置
單參數多字段
使用,
分隔,如
/users/1?fields=name,age,city
版本控制
三種方案:
- 在uri中加入版本: /v1/room/1
- Accept Header:Accept: v1
- 自定義 Header:X-Imweb-Media-Type: imweb.v1 (我們使用此方案)
自定義Media-Type參考資料github
狀態碼
成功
Code | Method | Describe |
---|---|---|
200 | ALL | 請求成功並返回實體資源 |
201 | POST | 創建資源成功 |
客戶端錯誤
Code | Method | Describe |
---|---|---|
400 | ALL | 一般是參數錯誤 |
401 | ALL | 一般用戶驗證失敗(用戶名、密碼錯誤等) |
403 | ALL | 一般用戶權限校驗失敗 |
404 | ALL | 資源不存在(github在權限校驗失敗的情況下也會返回404,為了防止一些私有接口泄露出去) |
422 | ALL | 一般是必要字段缺失或參數格式化問題 |
服務器錯誤
CODE | METHOD | DESCRIBE |
---|---|---|
500 | ALL | 服務器未知錯誤 |
以上是常見的狀態碼,完整的狀態碼列表在這狀態碼
HATEOAS
在介紹HATEOAS之前,先介紹一下REST的成熟度模型
在介紹 HATEOAS 之前,先介紹一下 Richardson 提出的 REST 成熟度模型。該模型把 REST 服務按照成熟度划分成 4 個層次:
- 第一個層次(Level 0)的 Web 服務只是使用 HTTP 作為傳輸方式,實際上只是遠程方法調用(RPC)的一種具體形式。
- 第二個層次(Level 1)的 Web 服務引入了資源的概念。每個資源有對應的標識符和表達。
- 第三個層次(Level 2)的 Web 服務使用不同的 HTTP 方法來進行不同的操作,並且使用 HTTP 狀態碼來表示不同的結果。如 HTTP GET 方法來獲取資源,HTTP DELETE 方法來刪除資源。
- 第四個層次(Level 3)的 Web 服務使用 HATEOAS。在資源的表達中包含了鏈接信息。客戶端可以根據鏈接來發現可以執行的動作。
簡述
HATEOAS(Hypermedia as the engine of application state)是 REST 架構風格中最復雜的約束,也是構建成熟 REST 服務的核心。它的重要性在於客戶端和服務器之間的解耦。
例子
分頁
request請求,查詢user,每頁顯示10條,從第10條開始顯示(第二頁)
/users?limit=10&offset=10
response
{ data: { xxxx }, meta: { _link: [ {rel: 'self', href: 'xxx/users?limit=10&offset=10'}, {rel: 'first', href: 'xxx/users?limit=10&offset=0', title: 'first page'}, {rel: 'last', href: 'xxx/users?limit=10&offset=50', title: 'last page'}, {rel: 'prev', href: 'xxx/users?limit=10&offset=0', title: 'prev page'}, {rel: 'next', href: 'xxx/users?limit=10&offset=20', title: 'next page'} ] } }
_link
返回了5個資源
- rel: 'self',資源本身
- rel: 'first',第一頁資源
- rel: 'last',最后一頁資源
- rel: 'prev',上一頁資源
- rel: 'next',下一頁資源
權限相關
如用戶查詢一個訂單
普通用戶
request
/orders/1
response
{ data: { xxx }, meta: { _link: [ {rel: 'self', href: 'xxx/orders/1'}, {rel: 'related', href: 'xxx/orders/1/payment', title: 'pay the order'} ] } }
_link
返回兩個資源
- rel: 'self',資源本身
- rel: 'related',與當前資源相關的資源,
/order/1/payment
用戶可以使用此資源進行支付
權限用戶
request
/orders/1
response
{ data: { xxx }, meta: { _link: [ {rel: 'self', href: 'xxx/orders/1'}, {rel: 'edit', href: 'xxx/orders/1', title: 'edit the order'}, {rel: 'delete', href: 'xxx/orders/1', title: 'delete the order'} ] } }
此用戶擁有修改與刪除訂單的權限,因此返回了3個資源
- rel: 'self',資源本身
- rel: 'edit',此用戶可修改該資源
- rel: 'delete',此用戶可刪除該資源
常用rel
rel | describe |
---|---|
self | 資源本身,每個資源表述都一個包含此關系 |
edit | 指向一個可以編輯當前資源的鏈接 |
delete | 指向一個可以刪除當前資源的鏈接 |
item | 如果當前資源表示的是一個集合,則用來指向該集合中的單個資源 |
collection | 如果當前資源包含在某個集合中,則用來指向包含該資源的集合 |
related | 指向一個與當前資源相關的資源 |
first、last、prev、next | 分別用來指向第一個、最后一個、上一個和下一個資源 |
HATEOAS總結
由以上例子可以看出_link
就是以Hyperlink表述資源與資源之間的關系,這種方式使客戶端與服務端能很好的分離開來,只要接口的定義不變,客戶端與服務端就可以獨立的開發和演變。