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

RESTful 風格的HTTP 方法有POST,GET ,PUT ,DELETE,PATCH 等等。那么我們在開發時應該如何寫出優雅的RESTful接口呢。本篇就為大家帶來一期RESTful API 實踐。

1. 前言

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

REST API 也稱RESTful API， 其遵循REST架構規范的應用編程接口， 支持與RESTful WEB服務進行交互。簡單來講就是：符合REST架構風格的 WEB API 或WEB 服務就是 REST API。

2. REST 的6大指導原則

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

• 統一接口(Uniform interface)

開發者一旦熟悉了你的其中一個API，那么他就可以遵循類似的結構去使用其他API.

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

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

• 無狀態(Stateless)

客戶端上下文狀態不應該存儲在服務端，而應該有客戶端去管理程序的狀態

• 可緩存(Cacheable)

優秀的緩存可以部分或者完全消除客戶端和服務端的交互，最終提高應用的伸縮性和性能。

• 分層系統(Layered System)

REST可以允許你使用分層架構，讓你在服務器A上部署API， 服務器B上存儲數據，服務器C上進行權限驗證，客戶端不知道它實際連接的是哪個服務器。

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

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

3. 最佳實踐

3.1 API名稱

API的名稱應該出現在URL中，API的標題也應該和名稱一致，所以起名子也是比較重要的一點，這決定了你的API是否容易讓人讀懂!

3.2 API的版本

API的版本應該遵循, MAJOR.MINOR.PATCH的結構，即主要.次要.補丁 。

如果有重大的改動，導致前后的版本不兼容應該升級主要版本， 比如從1.0 升級到2.0。

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

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

例如：

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

3.3提供準確的API文檔

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

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

3.4資源路徑命名

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

比如 POST : /cars 表示創建cars , GET: /cars 表示查詢cars 而不應該寫成/createCars ， /getCars 等等。

• 獲取集合資源與獲取特定資源,統一使用復數來表示資源。

#獲取資源集合時使用復數名詞 
例如 /schools


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


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

3.5資源操作

RESTful API 使用HTTP 方法來對資源進行操作，相對應的一些常用操作如下：

• 創建資源 POST

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

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

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

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

• 更新及修改資源 PUT/PATCH

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

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

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

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

例如：PATCH: /schools/{school-id}/teachers  調整某個學校的老師

舉個例子：

原有的資源如下：

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

當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請求參數

• 其余不是資源的參數應該出現在請求參數中。而且查詢參數應該出現在GET請求中，不應該出現在PUT，POST請求中。
• 請求參數應該使用駝峰命名法。

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

• 使用唯一查詢參數進行過濾。

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

• 分頁查詢

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

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

• 排序

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

例如：
    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狀態碼處理錯誤

總結

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