什麼是 REST API?

REST API (具象狀態傳輸應用程式設計介面) 是一種架構樣式,通常視為設計及建構網路應用程式的標準,而這些應用程式正是網路的基礎。只要遵守這套架構底下的規則和限制,您將能打造簡單、可擴充且易於整合的 Web 服務。

REST API 定義

REST API 是符合 REST 架構設計樣式的 API。REST 的核心概念是「資源」,而資源可以是任何資訊,例如使用者、產品、文件或項目集合。

REST API 提供一組預先定義的無狀態作業,讓用戶端應用程式能存取及操作資源。

REST API 的運作方式

1. 用戶端傳送要求

用戶端應用程式 (例如行動應用程式、網路瀏覽器或其他伺服器) 會向 API 發出請求,要求執行動作。該要求會傳送至特定網址,當中包含 HTTP 方法、帶有中繼資料的標頭,有時也會包含帶有資料的要求主體。

2. 伺服器處理要求

伺服器會接收並驗證要求,確認用戶端已通過驗證,有權執行要求的操作。接著,伺服器會處理要求,例如從資料庫擷取資料、建立新資源或更新現有資源。

3. 伺服器傳送回應

處理要求後,伺服器會將回應傳回給用戶端。這個回應包含用來表示結果的 HTTP 狀態碼 (例如「200 OK」代表成功、「404 Not Found」代表資源不存在、「401 Unauthorized」代表安全性問題),以及回應主體中的要求資料。

4. 資料移轉

用戶端與伺服器之間傳輸的資料,是資源狀態的「表示法」。JSON (JavaScript Object Notation) 是最常見的資料格式,因為它精簡、人類可讀,且便於程式設計語言剖析。

REST API 架構與元件

REST 的強大功效和擴充性源自一組架構限制,這些限制規範了 REST 的設計樣式,符合這些限制的系統即稱為「符合 REST 樣式」(RESTful)。

REST API 模型示意圖

資源

資源是 REST 的基礎概念,這種物件具有類型、相關資料、與其他資源的關係,以及一組可操作資源的方法。舉例來說,在電子商務 API 中,「產品」或「顧客」就是資源的一種。

URI (統一資源識別碼)

每個資源都有專屬 URI,設計良好的 API 通常採用簡潔、描述性強且一致的 URI 來識別資源。舉例來說,/users 可能用來識別使用者集合,而 /users/123 則用來識別 ID 為 123 的特定使用者。

聲明

用戶端不會直接與資源互動,而是與資源的表示法互動。最常見的表示格式是 JSON,但也可以使用 XML 或 HTML 等其他格式,這有助於彈性表示資源狀態。

無狀態

用戶端傳送給伺服器的每個要求,都必須包含伺服器理解及處理要求所需的所有資訊。伺服器不會在每個要求之間,儲存任何用戶端結構定義或工作階段狀態。這項限制讓 REST API 具備高度擴充性,因為任何伺服器都能處理任何要求。

用戶端伺服器架構

用戶端與伺服器分開,API 做為兩者之間的介面。藉由分離關注點,獨立發展用戶端應用程式和伺服器端應用程式。

統一介面

REST 的用戶端與伺服器之間須有統一介面。實務上會使用標準 HTTP 方法和超媒體即應用程式狀態引擎 (HATEOAS),並以 URI 識別資源來做到這點。

可快取性

應將伺服器回應定義為可快取或不可快取。如果回應可快取,用戶端或中介服務就能將該回應重複用於後續的相同要求,大幅提升效能並減輕伺服器負載。

分層系統

用戶端與 REST API 連線時,通常無法判斷自己是直接連線至終端伺服器,還是途中的中介伺服器。在架構中導入 API 閘道、負載平衡器等中介伺服器,可提升擴充性、安全性和效能。

REST API 最佳做法

URI 代表資源,因此應使用名詞 (如為集合則使用複數,如為特定項目則使用單數或 ID),而非動詞。例如,應以 /users 代表所有使用者,而非 /getAllUsers。

使用標準 HTTP 動詞來表示動作:GET 為擷取,POST 為建立,PUT 為更新,DELETE 則為移除。這樣就能建立可預測且一致的介面。

REST 的重要原則,是回應必須包含其他相關動作或資源的連結。這樣用戶端才能動態瀏覽 API,不必透過硬式編碼來設定 URI 模式。

如要對 API 做出破壞性變更,建議推出新版本。最常見的做法是在 URI 加入版本號碼,例如 /api/v2/users。這樣一來,現有用戶端可繼續使用舊版本,新用戶端則可採用新版本。

如果要求失敗,請在回應主體資訊加入明確有用的錯誤訊息,並附上適當的 HTTP 狀態碼 (例如 400 Bad Request、500 Internal Server Error)。這樣用戶端開發人員就能瞭解問題原因。

導入完善的驗證機制 (例如 OAuth 2.0、API 金鑰) 來檢查用戶端身分和授權,確保用戶端只會看到有權存取的資源,藉此保護 API。此外,一律使用 TLS/SSL 來加密流量。

如果端點會傳回大量項目,導入分頁功能即可將資料彙整成容易管理的分塊,再傳回資料。此外,提供查詢參數可讓用戶端篩選結果並排序,進而縮減資料傳輸量。

使用 REST API 的優點

簡單可讀

REST API 採用標準 HTTP 方法和人類可讀的 URI,因此開發人員相當容易學習、使用這類介面並偵錯。此外,REST API 屬於自我描述性介面,可簡化整合作業。

擴充性

REST 屬於無狀態架構,這點是 REST 具備高擴充性的一大關鍵。由於伺服器不必保留用戶端工作階段,系統很容易就能將要求分散到多個伺服器,還能加入新伺服器來處理增加的負載,完全不需要複雜程序。

工作彈性

REST 適用於多種資料格式,最常與輕量且支援範圍廣泛的 JSON 搭配運作,提供極高彈性。因此,REST API 可用於眾多用戶端應用程式,包括網路瀏覽器、行動裝置和 IoT 感應器。

用戶端與伺服器分離

REST 會強制落實用戶端-伺服器架構,明確分離關注點,讓開發人員能分別處理用戶端前端和伺服器端後端作業,進而加快開發週期。

各種語言都適用

REST 是以標準 HTTP 為基礎的架構類型,因此能以各種程式設計語言實作,且適用於任何可發出 HTTP 要求的用戶端,在不同技術堆疊之間提供最大互通性。

REST API 範例

公用 API 範例

REST API 常用於行動裝置的天氣應用程式。這類應用程式會從公開天氣 API 擷取特定地點的目前天氣資訊。

具體來看,用戶端應用程式會向 API 端點發出 HTTP GET 要求,其中包含位置和用於驗證的 API 金鑰。

curl

"https://api.weather-service.com/v1/current?location=94043&key=YOUR_API_KEY"

curl

"https://api.weather-service.com/v1/current?location=94043&key=YOUR_API_KEY"

伺服器會處理要求、擷取指定地點的天氣資料,並傳回 JSON 回應。

{

 "temperature": 20,

 "unit": "celsius",

 "condition": "Clear",

 "humidity": 55

}

{

 "temperature": 20,

 "unit": "celsius",

 "condition": "Clear",

 "humidity": 55

}

內部 API 範例

微服務架構中,「產品」服務必須先從「庫存」服務取得最新價格,才能在電子商務網站上顯示。

因此,產品服務會向庫存服務的 API 端點發出內部 HTTP GET 要求,以取得特定產品 ID。

curl

"http://inventory-service.internal/api/products/PN-5821/price"

curl

"http://inventory-service.internal/api/products/PN-5821/price"

庫存服務會查詢目前的價格,並傳回簡單的 JSON 回應。

{

"productId": "PN-5821",

"price": 1299.99,

"currency": "USD"

}

```

{

"productId": "PN-5821",

"price": 1299.99,

"currency": "USD"

}

```

透過 Google Cloud 解決業務難題

新客戶可以獲得價值 $300 美元的免費抵免額,盡情試用各項 Google Cloud 功能。

額外資源

  • 使用 Google APIs Explorer 互動式工具,直接從瀏覽器探索及測試各種 Google REST API
  • 參閱這篇網誌文章提供的最佳做法指南,詳細瞭解如何設計及開發符合 REST 樣式的網路 API
  • 透過 Google Cloud Skills Boost 的 Cloud Hero 學習路徑實作實驗室,實際管理 API

展開下一步行動

運用價值 $300 美元的免費抵免額和超過 20 項一律免費的產品,開始在 Google Cloud 中建構產品與服務。