Skip to content

api.md

Latest commit

 

History

History
176 lines (121 loc) · 7.11 KB

api.md

File metadata and controls

176 lines (121 loc) · 7.11 KB

Api 設計規範

RESTful API - Representational State Transfer( 表現層狀態轉移)

定義

  • RESTful API 是一種設計風格，
  • 是以資源為中心的架構，讓伺服器提供的功能（例如：新增、查詢、修改、刪除）成為一個或多個 RESTful 資源，並透過 HTTP 的方式進行通訊

三種組成方式

  1. Nouns 名詞：定義資源位置的 URL，每個資源在網路上都會有唯一的位置，就如每戶人家都有唯一的地址一樣。
  2. Verbs 動詞：對資源要做的動作。
  3. Content Types 資源呈現方式：API 資源可以以多種方式表現，最常用的是 JSON，較輕，也較好處理。

使用方式

  • GET：用於讀取資源，通常用於查詢、檢視等操作。
  • POST：用於新增資源，通常用於創建、提交等操作。
  • PUT：用於更新資源，通常用於修改、覆蓋等操作。
  • DELETE：用於刪除資源，通常用於刪除操作。.

主要特點

  1. 資源導向：每一個資源都有一個唯一的識別 URI，用來標識該資源。

  2. 無狀態：服務器不會保留客戶端的狀態。每次請求必須包含所有的必要資訊，以便伺服器能夠理解請求。

  3. 廣泛使用的 HTTP 方法：使用 HTTP 協議中的方法

    • 例如：GET、POST、PUT、DELETE

  4. 支援多種格式：RESTful API 可以支援多種請求和回應的格式，如 JSON、XML、HTML 等。

  5. 安全性：RESTful API 可以實現安全性機制，如 HTTPS、OAuth 等，以保護伺服器和客戶端之間的通訊安全

與一般 API 的差異

  • 一般

    獲得資料GET    /getData
新增資料POST   /createData
刪除資料DELETE /deleteData/1

  • RESTful API

    獲得資料GET     /data
新增資料POST    /data
刪除資料DELETE  /data/1

舉例

假設有一個資料庫儲存了某個電子商務網站的產品清單，需要透過 RESTful API 來提供使用者存取產品清單。

  1. GET /products

    • 描述：取得所有產品清單。
    • 方法：GET
    • 路徑：/products
    • 回傳：所有產品清單的 JSON 格式。

  2. GET /products/{id}

    • 描述：取得指定產品的詳細資料。
    • 方法：GET
    • 路徑：/products/{id}，其中 {id} 代表產品的唯一識 別- 碼。
    • 回傳：指定產品的詳細資料，以 JSON 格式回傳。

  3. POST /products

    • 描述：新增一筆產品。
    • 方法：POST
    • 路徑：/products
    • 輸入：欲新增的產品資料，以 JSON 格式傳送。
    • 回傳：新增成功的產品資料，以 JSON 格式回傳。

  4. PUT /products/{id}

    • 描述：更新指定產品的資料。
    • 方法：PUT
    • 路徑：/products/{id}，其中 {id} 代表欲更新產品的 唯- 一識別碼。
    • 輸入：欲更新的產品資料，以 JSON 格式傳送。
    • 回傳：更新成功的產品資料，以 JSON 格式回傳。

  5. DELETE /products/{id}

    • 描述：刪除指定產品。
    • 方法：DELETE
    • 路徑：/products/{id}，其中 {id} 代表欲刪除產品的 唯- 一識別碼。
    • 回傳：成功刪除訊息。

gRPC

什麼是 gRPC？

gRPC 是一個開源的遠程過程呼叫（RPC）框架，由 Google 開發。它基於 Protocol Buffers 和 HTTP/2 標準，用於不同語言之間的相互通信。

主要特點

  • 簡單的接口定義語言（IDL）：使用 Protocol Buffers 定義服務和消息類型，使得通信協議的定義更加清晰和簡潔。
  • 跨平台支援：gRPC 支援多種語言，如 C++、Java、Python、Go 等，這意味著您可以使用不同語言進行開發，並實現跨平台的相互通信。
  • 高效的序列化機制：使用 Protocol Buffers 作為序列化機制，可以將結構化的數據轉換為二進制格式，實現高效的數據傳輸。
  • HTTP/2 支援：gRPC 基於 HTTP/2 標準，能夠利用 HTTP/2 的多路徑請求、頭部壓縮和伺服器推送等特性，提供更高效和低延遲的通信。
  • 自動生成程式碼：根據接口定義文件，gRPC 可以自動生成客戶端和伺服器端的程式碼，從而減少開發人員的工作量和錯誤。

常見問題

Q.同步呼叫與非同步呼叫

同步呼叫

同步呼叫是一種阻塞式的通信模式，當發出呼叫時，呼叫方將一直等待直到接收到回應為止。在同步呼叫中，呼叫方會暫停執行直到呼叫的操作完成，然後才繼續執行後續的程式碼。同步呼叫通常是按照順序進行的，即呼叫方發出呼叫後，必須等待回應之後才能繼續執行下一個操作。

  • 特點：

    • 呼叫方會被阻塞，直到接收到回應。
    • 操作按照順序進行，一個接一個完成。
      • 較簡單直觀，易於理解和調試。

  • 使用場景：

    • 當操作之間有依賴關係，需要確保順序執行。
    • 當結果需要立即使用並且無法繼續執行其他操作時。

非同步呼叫

非同步呼叫是一種非阻塞式的通信模式，呼叫方發出呼叫後，不需要等待回應就可以繼續執行後續的程式碼。在非同步呼叫中，呼叫方通常會指定一個回調函數或事件處理程序，在操作完成後異步地接收結果或通知。

  • 特點：
    • 呼叫方不需要等待回應，可以繼續執行其他操作。
    • 操作以非順序的方式進行，可以並行處理。
    • 需要設計回調函數或事件處理程序來處理結果或通知。
  • 使用場景：
    • 當操作之間沒有依賴關係，可以並行處理。
    • 當結果可以在後續的時間點處理，而不需要立即使用。

比較

  • 執行方式：同步呼叫是阻塞式的，呼叫方必須等待回應；非同步呼叫是非阻塞式的，呼叫方可以繼續執行其他操作。
  • 執行順序：同步呼叫按照順序執行，一個接一個完成；非同步呼叫可以並行處理，不需要等待順序。
  • 處理方式：同步呼叫直接在呼叫方處理回應；非同步呼叫需要設計回調函數或事件處理程序來處理結果或通知。
  • 使用場景：同步呼叫適用於操作之間有依賴關係的情況，需要確保順序執行；非同步呼叫適用於操作之間沒有依賴關係，可以並行處理的情況。

Ref