REST API (具象狀態傳輸應用程式設計介面) 是一種架構樣式,通常視為設計及建構網路應用程式的標準,而這些應用程式正是網路的基礎。只要遵守這套架構底下的規則和限制,您將能打造簡單、可擴充且易於整合的 Web 服務。
REST API 是符合 REST 架構設計樣式的 API。REST 的核心概念是「資源」,而資源可以是任何資訊,例如使用者、產品、文件或項目集合。
REST API 提供一組預先定義的無狀態作業,讓用戶端應用程式能存取及操作資源。
用戶端應用程式 (例如行動應用程式、網路瀏覽器或其他伺服器) 會向 API 發出請求,要求執行動作。該要求會傳送至特定網址,當中包含 HTTP 方法、帶有中繼資料的標頭,有時也會包含帶有資料的要求主體。
伺服器會接收並驗證要求,確認用戶端已通過驗證,有權執行要求的操作。接著,伺服器會處理要求,例如從資料庫擷取資料、建立新資源或更新現有資源。
處理要求後,伺服器會將回應傳回給用戶端。這個回應包含用來表示結果的 HTTP 狀態碼 (例如「200 OK」代表成功、「404 Not Found」代表資源不存在、「401 Unauthorized」代表安全性問題),以及回應主體中的要求資料。
用戶端與伺服器之間傳輸的資料,是資源狀態的「表示法」。JSON (JavaScript Object Notation) 是最常見的資料格式,因為它精簡、人類可讀,且便於程式設計語言剖析。
REST 的強大功效和擴充性源自一組架構限制,這些限制規範了 REST 的設計樣式,符合這些限制的系統即稱為「符合 REST 樣式」(RESTful)。
資源是 REST 的基礎概念,這種物件具有類型、相關資料、與其他資源的關係,以及一組可操作資源的方法。舉例來說,在電子商務 API 中,「產品」或「顧客」就是資源的一種。
每個資源都有專屬 URI,設計良好的 API 通常採用簡潔、描述性強且一致的 URI 來識別資源。舉例來說,/users 可能用來識別使用者集合,而 /users/123 則用來識別 ID 為 123 的特定使用者。
用戶端不會直接與資源互動,而是與資源的表示法互動。最常見的表示格式是 JSON,但也可以使用 XML 或 HTML 等其他格式,這有助於彈性表示資源狀態。
用戶端傳送給伺服器的每個要求,都必須包含伺服器理解及處理要求所需的所有資訊。伺服器不會在每個要求之間,儲存任何用戶端結構定義或工作階段狀態。這項限制讓 REST API 具備高度擴充性,因為任何伺服器都能處理任何要求。
用戶端與伺服器分開,API 做為兩者之間的介面。藉由分離關注點,獨立發展用戶端應用程式和伺服器端應用程式。
REST 的用戶端與伺服器之間須有統一介面。實務上會使用標準 HTTP 方法和超媒體即應用程式狀態引擎 (HATEOAS),並以 URI 識別資源來做到這點。
應將伺服器回應定義為可快取或不可快取。如果回應可快取,用戶端或中介服務就能將該回應重複用於後續的相同要求,大幅提升效能並減輕伺服器負載。
用戶端與 REST API 連線時,通常無法判斷自己是直接連線至終端伺服器,還是途中的中介伺服器。在架構中導入 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 採用標準 HTTP 方法和人類可讀的 URI,因此開發人員相當容易學習、使用這類介面並偵錯。此外,REST API 屬於自我描述性介面,可簡化整合作業。
擴充性
REST 屬於無狀態架構,這點是 REST 具備高擴充性的一大關鍵。由於伺服器不必保留用戶端工作階段,系統很容易就能將要求分散到多個伺服器,還能加入新伺服器來處理增加的負載,完全不需要複雜程序。
工作彈性
REST 適用於多種資料格式,最常與輕量且支援範圍廣泛的 JSON 搭配運作,提供極高彈性。因此,REST API 可用於眾多用戶端應用程式,包括網路瀏覽器、行動裝置和 IoT 感應器。
用戶端與伺服器分離
REST 會強制落實用戶端-伺服器架構,明確分離關注點,讓開發人員能分別處理用戶端前端和伺服器端後端作業,進而加快開發週期。
各種語言都適用
REST 是以標準 HTTP 為基礎的架構類型,因此能以各種程式設計語言實作,且適用於任何可發出 HTTP 要求的用戶端,在不同技術堆疊之間提供最大互通性。
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 端點發出內部 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"
}
```