RESTful開發規範詳解

什麼是Restful

興起于Rails。是一種優雅的URI表述方式，可以表示資源的狀态和狀态轉移。

Fielding将他對網際網路軟體的架構原則，定名為REST，即 Resource Representational State Transfer的縮寫。

如果一個架構符合REST原則，就稱它為RESTful架構。

RESTful資源-Resource

• 文本
• 圖檔
• 服務
• 音頻
• …

RESTful表現層-Representational

• 文本：txt、html、xml、json、二進制
• 圖檔：jpg、png
• http協定的content-type和accept(通過這個協定頭指定表現形式)

RESTful狀态轉化-State Transfer

• 幂等性：每次HTTP請求相同的參數，相同的URI，産生的結果是相同的
• GET-擷取資源
• POST-建立資源，不具有幂等性
• PUT-建立(更新)資源
• DELETE-删除資源

設計概念和準則

• 網絡上的所有事物都可以被抽象為資源。
• 每一個資源有唯一的資源辨別，對資源的操作不會改變這些辨別。
• 所有的操作都是無狀态的。

RESTful架構與其他架構的差別

SOAP WebService

WebService 是一種跨程式設計語言跨作業系統平台的遠端調用技術。

WebService 通過HTTP協定發送請求和接收結果時XML格式封裝，并增加了一些特定的HTTP消息頭，這些特定的HTTP消息頭和XML内容格式就是SOAP協定。

• 效率和易用性

SOAP由于各種需求不斷擴充其本身内容，導緻在SOAP處理方面的性能有所下降。同時在易用性方面以及學習成本上也有所增加。

• 安全性

RESTful對于資源型服務接口來說很适合，同時特别适合對于效率要求很高，但是對于安全性要求不高的場景。

SOAP的成熟性可以給需要提供給多開發語言的，對于安全性要求較高的接口設計帶來便利。是以，什麼設計模式将會占據主導地位，關鍵是看應用場景。

RESTful設計要素

1. 如何設計RESTful API
   • 資源路徑(URI)

   在RESTful架構中，每個網址代表一種資源，是以網址中不能有動詞，隻能有名詞。一般來說API中的名詞應該複數。

   例如：一個API提供動物園(zoo)的資訊，還包括各種動物和雇員的資訊，則路徑應該設計成如下所示：

https://api.example.com/v1/zoos  // 動物園資源

https://api.example.com/v1/animals  // 動物資源

https://api.example.com/v1/employees  // 雇員資源
           

• HTTP動詞

  對于資源的操作(CURD)，由HTTP動詞(謂詞)表示。

  1. GET:從伺服器取出資源(一項或多項)。
  2. POST: 在伺服器建立一個資源。
  3. PUT: 在伺服器更新資源(用戶端提供改變後的完整資源)。
  4. PATCH: 在伺服器更新資源(用戶端提供改變的屬性)。
  5. DELETE: 從伺服器删除資源。
  例如：
  1. POST /zoos: 建立一個動物園
  2. GET /zoos/ID: 擷取某個指定動物園的資訊
  3. PUT /zoos/ID: 更新某個指定動物園的資訊
  4. DELETE /zoos/ID: 删除某個動物園

• 過濾資訊

  如果記錄數量很多，伺服器不可能都将它們傳回給使用者。

  API應該提供參數，過濾傳回結果。

  例如：

  1. ?offset=10: 指定傳回記錄的開始位置
  2. ?page=2&per_page=100: 指定第幾頁，以及每頁的記錄數。
  3. ?sortby=name&order=asc: 指定傳回結果排序，以及排序順序。
  4. ?animal_type_id=1: 指定篩選條件。

• 狀态碼

  伺服器向使用者傳回的狀态碼和提示資訊，使用标準HTTP狀态碼。

  1. 200 OK 伺服器成功傳回使用者請求的資料，該操作是幂等的。
  2. 201 CREATED 建立或修改資料成功。
  3. 204 NO CONTENT 删除資料成功。
  4. 400 BAD REQUEST 使用者發出的請求有錯誤，該操作是幂等的。
  5. 401 Unauthorized 表示使用者未認證，無法進行目前操作。
  6. 403 Frobidden 表示使用者通路是被禁止的。
  7. 422 Unprocesable Entity 當建立一個對象時，發生一個驗證碼錯誤。
  8. 500 INTERNAL SERVER ERROR 伺服器發生錯誤，使用者将無法判斷發出的請求是否成功。

• 錯誤處理

  如果狀态碼是4xx或5xx，就應該向使用者傳回出錯資訊。一般來說，傳回的資訊中将error作為鍵名，出錯資訊作為鍵值即可：

  {

  “error”: “參數錯誤”

  }

• 傳回結果

  針對不同操作，伺服器向使用者傳回的結果應該符合以下規範：

  1. GET /collections: 傳回對象的清單(數組)
  2. GET /collections/identity: 傳回單個資源對象
  3. POST /collections: 傳回新生成的資源對象
  4. PUT /collections/identity: 傳回完整的資源對象
  5. PATCH /collections/identity: 傳回被修改的屬性
  6. DELETE /collections/identity: 傳回一個空文檔
• URL設計

/子產品/資源/{辨別}/集合1/…

例如：

/user/{uid}/friends -->好友清單
/user/{uid}/followers --> 關注者清單