Development

RESTful API設計

RESTful API 設計之學習記錄

REST要點(REST是”設計風格”而不是標準。REST通常基於HTTP、URI、XML以及HTML這些現有的廣泛流行的協定和標準。)

  • 資源是由URI來指定。
  • 對資源的操作包括取得、建立、修改和刪除，這些操作正好對應HTTP協定提供的GET、POST、PUT和DELETE方法。
  • 通過操作資源的表現形式來操作資源。
  • 資源的表現形式則是XML或者HTML，取決於讀者是機器還是人、是消費Web服務的客戶軟體還是Web瀏覽器。當然也可以是任何其他的格式，例如JSON。

特徵

  • 統一介面(Uniform Interface)
    • Identification of resources - 唯一的資源識別
    • Manipulation of resources - 特定的操作方法
    • Self-descriptive messages - 訊息自我描述
    • Hypermedia as the engine of application state (HATEOAS)
      • Level 0 : 使用一個 URI 與一個 HTTP 方法，基本上就是單純使用 HTTP 作為傳輸協定，服務使用的 URI 只是個接收請求進行回應的端點，HTTP 方法只是用來發起請求，至於請求的相關細節，例如想進行的動作、必須提供的資料等，全部包含在發送過去的文件之中，像是 XML、JSON 等其他（自訂）格式，回應使用某個文件格式傳回，當中包含了請求操作後的結果。
      • Level 1 : 使用多個 URI 與一個 HTTP 方法，URI 代表了資源，像是 /show_message、/create_message、/update_message、/delete_message 都是資源，HTTP 方法只是用來發起請求，至於請求的細節由請求本體來提供，例如，在請求 /show_message 這項資源時，若包含 all 請求參數，表示顯示全部的訊息，若是 “id=1” 這類請求參數，表示顯示指定的訊息。
      • Level 2 :使用多個 URI、多個 HTTP 方法，並善用 HTTP 回應狀態碼，URI 用來代表資源，像是 /messages、/messages/1，HTTP 方法用來表示想進行的操作，例如 GET /messages 表示取得全部訊息，GET /messages/1 表示取得指定訊息，POST /messages 表示新增訊息、DELETE /messages/1 表示刪除指定訊息等
      • Level 3 : 更進一步地，支援 HATEOAS（Hypermedia As The Engine Of Application State）的概念，就類似 HTML 頁面鏈結，你可以從這個頁面得知可通往哪些頁面，在 REST 的 Level 3 模型中，客戶端可以從某個資源，知道還有哪些其他相關的資源，以及如何對它進行操作
  • Stateless(無狀態)
1
2
3
4
5
#How to understand “RESTful API is stateless”?(stackoverflow) (部分內容擷取)
[...] 
 each request from client to server must contain all of the information necessary to understand the request,
 and cannot take advantage of any stored context on the server. 
 Session state is therefore kept entirely on the client. [...]
  • Cacheable(可快取)
  • Client-Server(客戶伺服器分離模式，任何一個客戶端與伺服器都是可替換的)
  • Layered System (分層的系統，客戶端不知道他請求的是不是最終伺服器)
  • Code on Demand (optional)
    • 允許客戶端提高其靈活性(視情況決定要不要遵守，Server端 可以傳送可執行的程式碼給 Client端)

REST設計

符合REST設計風格的Web API稱為RESTful API。它從以下三個方面資源進行定義：

  • 直觀簡短的資源位址，比如: http://example.com/resources。
  • 傳輸的資源：Web服務接受與返回的網際網路媒體類型，比如：JSON，XML，YAML等。
  • 對資源的操作：Web服務在該資源上所支援的一系列請求方法（比如：POST，GET，PUT或DELETE）。

RESTful API設計要點

HTTP動詞

  • GET（SELECT）：請求指定資源，只應用於取得資料。(Filtering， query string)
  • POST（CREATE）：在服務器新建一個資源。
  • PUT（UPDATE）：會取代指定資源所酬載請求（request payload）的所有表現。
  • PATCH（UPDATE）：指定資源的部份修改。
  • DELETE（DELETE）：從服務器刪除指定資源。
  • HEAD：請求與 GET方法相同的回應，但它沒有回應主體（response body）。(應用於HTTP標頭，判別資源是否存在)
  • OPTIONS：描述指定資源的溝通方法（communication option）。
  • CONNECT: 指定資源標明的伺服器之間，建立隧道（tunnel）。
  • TRACE: 指定資源標明的伺服器之間，執行迴路返回測試（loop-back test）。

資源命名與設計:

參考:

REST 成熟度模型
成熟度模型-REST的实现步骤
HyperText Transfer Protocol，HTTP (wiki)
How to understand “RESTful API is stateless”?(stackoverflow)
REST Wiki
RESTful API 设计指南 - 阮一峰的网络日志
Hypermedia As The Engine Of Application State(HATEOAS) Spring HATEOAS
Backend社團-紫色石虎-RESTful API淺談
Backend社團-紫色石虎-RESTful淺談 - demo
HTTP (MDN)