REST的6大指導原則

1. 前言

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

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

2. REST 的6大指導原則

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

• 統(tǒng)一接口（Uniform interface）
  開發(fā)者一旦熟悉了你的其中一個API，那么他就可以遵循類似的結構去使用其他API.
• 客戶端服務器（Client-server）
  只要不改變他們之間的接口，服務端和客戶端可以相互替換或獨立開發(fā)。
• 無狀態(tài)（Stateless）
  客戶端上下文狀態(tài)不應該存儲在服務端，而應該有客戶端去管理程序的狀態(tài)
• 可緩存（Cacheable）
  優(yōu)秀的緩存可以部分或者完全消除客戶端和服務端的交互，最終提高應用的伸縮性和性能。
• 分層系統(tǒng)（Layered System）
  REST可以允許你使用分層架構，讓你在服務器A上部署API， 服務器B上存儲數(shù)據，服務器C上進行權限驗證，客戶端不知道它實際連接的是哪個服務器。
• 按需編碼（Code on demand （optional））
  這些規(guī)則可以幫組你構建真正的RESTful API ，所以盡量遵循著些規(guī)則。如果因為某些原因違反這些規(guī)則，事實上你還是在構建RESTful API ，只是不算真正的RESTful。

3. 最佳實踐

3.1 API名稱

API的名稱應該出現(xiàn)在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文檔

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

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

3.4資源路徑命名

• 資源名稱使用名詞，而不要使用動詞。
  比如 POST : /cars 表示創(chuàng)建cars , GET: /cars 表示查詢cars 而不應該寫成/createCars ， /getCars 等等。
• 獲取集合資源與獲取特定資源,統(tǒng)一使用復數(shù)來表示資源。

  #獲取資源集合時使用復數(shù)名詞 
  例如 /schools
  
  
  #獲取特定資源
  例如 /schools/{school-id}  /schools/5
  
  
  #獲取特定資源的子資源 
  例如 /schools/{school-id}/grades  /schools/5/grades
  

3.5資源操作

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

• 創(chuàng)建資源 POST
  使用POST方法 創(chuàng)建資源，此處可以創(chuàng)建單個資源或者資源集合。創(chuàng)建成功應該立馬返回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請求參數(shù)

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

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

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

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

• 分頁查詢

  API 使用offset={resultOffset}&limit={resultsPerPage} 進行分頁查詢，
  并且以第0條數(shù)據為起始。
  
  另外也可以使用 page={pageNumber}&limit={resultPerPage} 此時起始頁為第1頁
  
  使用index={pageIndex}&limit={resultPerPage}, 每一頁可以返回上一頁或者下一頁的link
  
  可以看如下例子：
      GET /orders?page=1&limit=15 第一頁的15條數(shù)據
      GET /orders?offset=0&limit=15 第一頁的15條數(shù)據
      GET /orders?page=5&limit=10 第五頁的10條數(shù)據 第51-60條
      GET /orders?offset=50&limit=10 第51到60條數(shù)據
      GET /orders?index=xxxxxxx&limit=10  同樣也可以表示第51-60條數(shù)據，
    只不過對客戶端來說可能不知道第幾頁，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狀態(tài)碼處理錯誤

Http狀態(tài)碼有很多，這里列舉一些常見的。

總結

本篇介紹了一些REST API的一些食用方式，我們工作中可以根據一些各自的條件，作為參考。歡迎留言講講自己的一些實踐經驗！