說明：其實沒有絕對的規範，達到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://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

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

版本控制

三種方案：

1. 在uri中加入版本： /v1/room/1
2. Accept Header：Accept: v1
3. 自定義 Header：X-Imweb-Media-Type: imweb.v1 (我們使用此方案)

自定義Media-Type參考資料github

狀態碼

成功

客戶端錯誤

服務器錯誤

以上是常見的狀態碼，完整的狀態碼列表在這狀態碼

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

HATEOAS總結

由以上例子可以看出_link就是以Hyperlink表述資源與資源之間的關系，這種方式使客戶端與服務端能很好的分離開來，只要接口的定義不變，客戶端與服務端就可以獨立的開發和演變。

RESTful API設計規範收集