RESTful API 規范 v1.0

RESTful API 規范 v1.0

[toc]

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：局部更新資源（僅提供改變的屬性）
  </li>

• DELETE：刪除資源

</ul>

安全性與冪等性

• 安全性：任意多次對同一資源操作，都不會導致資源的狀態變化
• 冪等性：任意次對同一資源操作，對資源的改變是一樣的 |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

狀態碼

成功

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表述資源與資源之間的關系，這種方式使客戶端與服務端能很好的分離開來，只要接口的定義不變，客戶端與服務端就可以獨立的開發和演變。

來自： http://imweb.io/topic/5707561f06f2400432c139a5