哈嘍，大家好，我是指北君。

RESTful 風(fēng)格的HTTP 方法有POST,GET ,PUT ,DELETE,PATCH 等等。那么我們在開發(fā)時應(yīng)該如何寫出優(yōu)雅的RESTful接口呢。本篇就為大家?guī)硪黄赗ESTful API 實踐。

1. 前言

REST 全稱為 ：Resource Representational State Transfer. 是一種分布式超媒體系統(tǒng)(distributed hypermedia systems)架構(gòu)風(fēng)格。由Roy Fielding 提出。

REST API 也稱RESTful API， 其遵循REST架構(gòu)規(guī)范的應(yīng)用編程接口， 支持與RESTful WEB服務(wù)進(jìn)行交互。簡單來講就是：符合REST架構(gòu)風(fēng)格的 WEB API 或WEB 服務(wù)就是 REST API。

2. REST 的6大指導(dǎo)原則

REST 定義了6個原則，這些原則使得一個WEB API 成為真正的RESTful API。

• 統(tǒng)一接口(Uniform interface)

開發(fā)者一旦熟悉了你的其中一個API，那么他就可以遵循類似的結(jié)構(gòu)去使用其他API.

• 客戶端服務(wù)器(Client-server)

只要不改變他們之間的接口，服務(wù)端和客戶端可以相互替換或獨立開發(fā)。

• 無狀態(tài)(Stateless)

客戶端上下文狀態(tài)不應(yīng)該存儲在服務(wù)端，而應(yīng)該有客戶端去管理程序的狀態(tài)

• 可緩存(Cacheable)

優(yōu)秀的緩存可以部分或者完全消除客戶端和服務(wù)端的交互，最終提高應(yīng)用的伸縮性和性能。

• 分層系統(tǒng)(Layered System)

REST可以允許你使用分層架構(gòu)，讓你在服務(wù)器A上部署API， 服務(wù)器B上存儲數(shù)據(jù)，服務(wù)器C上進(jìn)行權(quán)限驗證，客戶端不知道它實際連接的是哪個服務(wù)器。

• 按需編碼(Code on demand (optional))

這些規(guī)則可以幫組你構(gòu)建真正的RESTful API ，所以盡量遵循著些規(guī)則。如果因為某些原因違反這些規(guī)則，事實上你還是在構(gòu)建RESTful API ，只是不算真正的RESTful。

3. 最佳實踐

3.1 API名稱

API的名稱應(yīng)該出現(xiàn)在URL中，API的標(biāo)題也應(yīng)該和名稱一致，所以起名子也是比較重要的一點，這決定了你的API是否容易讓人讀懂!

3.2 API的版本

API的版本應(yīng)該遵循, MAJOR.MINOR.PATCH的結(jié)構(gòu)，即主要.次要.補(bǔ)丁 。

如果有重大的改動，導(dǎo)致前后的版本不兼容應(yīng)該升級主要版本， 比如從1.0 升級到2.0。

如果只是增加了一些特性，前后的版本都是兼容話，可以升級次要版本， 比如從1.0 升級到1.1.

如果有一些小的bug修改的話，可以在補(bǔ)丁版本的上升級，比如從 1.0 升級到1.0.1

例如：

https://mysite.com/v1/...
https://mysite.com/v2/...

3.3提供準(zhǔn)確的API文檔

開發(fā)完成一個API之后，你需要讓API的使用者可以正確的使用它，那么就需要一份漂亮的API文檔了。

API文檔需要提供準(zhǔn)確的請求路徑， 請求示例， 以及各種error時的狀態(tài)碼等。 可以使用Swagger等工具。

3.4資源路徑命名

• 資源名稱使用名詞，而不要使用動詞。

比如 POST : /cars 表示創(chuàng)建cars , GET: /cars 表示查詢cars 而不應(yīng)該寫成/createCars ， /getCars 等等。

• 獲取集合資源與獲取特定資源,統(tǒng)一使用復(fù)數(shù)來表示資源。

#獲取資源集合時使用復(fù)數(shù)名詞 
例如 /schools


#獲取特定資源
例如 /schools/{school-id}  /schools/5


#獲取特定資源的子資源 
例如 /schools/{school-id}/grades  /schools/5/grades

3.5資源操作

RESTful API 使用HTTP 方法來對資源進(jìn)行操作，相對應(yīng)的一些常用操作如下：

• 創(chuàng)建資源 POST

使用POST方法 創(chuàng)建資源，此處可以創(chuàng)建單個資源或者資源集合。創(chuàng)建成功應(yīng)該立馬返回HTTP 201， 二接受到resource并未立即添加資源則返回 HTTP 202 。

例如： 使用POST: /schools 添加多個school資源，
         /schools/{school-id}/grades 添加某個school資源的grade，

• 查詢集合資源 及單個資源

例如： 使用 GET: /schools?type=PRIMARY  查詢所有的小學(xué)
      使用 GET :/schools/{school-id}/grades 查詢某個學(xué)校的所有年級
          GET :/schools/{school-id}/grades/{grade-id}  查詢某個學(xué)校某個年級

• 更新及修改資源 PUT/PATCH

更新個修改資源包含多種情況：

一種是完全更新，使用新的資源完全替換舊的資源。

例如：PUT: /schools/{school-id}/address  更新某個客戶學(xué)校的地址信息

一種是修改局部更新，根據(jù)需求去更新修改原有的資源。

例如：PATCH: /schools/{school-id}/teachers  調(diào)整某個學(xué)校的老師

舉個例子：

原有的資源如下：

{
    "a":"A",
    "b":{
        "c":"C",
        "d":"D"
    }
}

當(dāng)PATAH請求 如下：

PATCH  HTTP/1.1
Content-Type: application/merge-patch+json
{
    "a":"Z",
    "b":{
        "d":null
    }
}

修改后的resource如下：

{
    "a":"Z",
    "b":{
        "c":"C"
    }
}

• 刪除資源

刪除資源使用DELETE方法，刪除的方法有直接刪除，或者使資源不可見。

3.6請求參數(shù)

• 其余不是資源的參數(shù)應(yīng)該出現(xiàn)在請求參數(shù)中。而且查詢參數(shù)應(yīng)該出現(xiàn)在GET請求中，不應(yīng)該出現(xiàn)在PUT，POST請求中。
• 請求參數(shù)應(yīng)該使用駝峰命名法。

例如：GET /orders?startDate=2022-01-03&endDate=2022-02-03
    DELETE /orders?status=EXPIRED

• 使用唯一查詢參數(shù)進(jìn)行過濾。

GET /orders?orderType=PAID
GET /orders?amount>100.00

• 分頁查詢

API 使用offset={resultOffset}&limit={resultsPerPage} 進(jìn)行分頁查詢，
并且以第0條數(shù)據(jù)為起始。
 
另外也可以使用 page={pageNumber}&limit={resultPerPage} 此時起始頁為第1頁

使用index={pageIndex}&limit={resultPerPage}, 每一頁可以返回上一頁或者下一頁的link
 
可以看如下例子：
    GET /orders?page=1&limit=15 第一頁的15條數(shù)據(jù)
    GET /orders?offset=0&limit=15 第一頁的15條數(shù)據(jù)
    GET /orders?page=5&limit=10 第五頁的10條數(shù)據(jù) 第51-60條
    GET /orders?offset=50&limit=10 第51到60條數(shù)據(jù)
    GET /orders?index=xxxxxxx&limit=10  同樣也可以表示第51-60條數(shù)據(jù)，
  只不過對客戶端來說可能不知道第幾頁，response中應(yīng)該包含有上一頁和下一頁的index
 

• 排序

API的排序功能是API非常重要的一個功能，可以使用sort，sort-by 即使沒有指出要排序，那么而應(yīng)該給一個默認(rèn)的排序。

例如：
    GET /orders?sort=asc(date)  /orders?sort=desc(date) 
    GET /orders?sort=+date      /orders?sort=-date
    GET /orders?sort=date.asc      /orders?sort=date.desc
    GET /orders?sort=date&order-by=asc    /orders?sort=-date&order-by=desc 
    
 多字段排序示例：
    GET /orders?sort=desc(date),asc(amount)
    GET /orders?sort=-date,+amount

3.7使用HTTP狀態(tài)碼處理錯誤

總結(jié)

本篇介紹了一些REST API的一些食用方式，我們工作中可以根據(jù)一些各自的條件，作為參考。