在今日高度互聯的數位世界中，應用程式之間的溝通與資料交換是所有服務的基石。從手機應用程式更新動態、網站載入天氣資訊，到企業內部系統的資料同步，這一切都仰賴著一種無形的橋樑——API (Application Programming Interface)。然而，API 的設計良莠不齊，一個缺乏清晰結構的 API 會導致前後端開發者之間溝通成本劇增，整合困難且難以維護。
為了解決這個問題，一套名為 REST (Representational State Transfer) 的架構風格應運而生，並迅速成為設計網路 API 的主流通訊標準與典範。遵循 REST 原則設計的 API，我們稱之為「RESTful API」。它不僅僅是一種技術，更是一種設計哲學，旨在建立可擴展、具彈性且易於理解的網路服務。
本文章將作為一份完整的教學指南，帶您深入剖析 RESTful API 的世界。我們將從 API 的基本概念出發，探討 REST 的核心原則，並結合業界最佳實踐，提供一份涵蓋 URI 設計、HTTP 方法運用、安全性考量及版本管理的詳細實戰手冊。無論您是後端開發者、前端工程師，還是對系統架構感興趣的技術人員，都能從中獲得深刻的理解與實用的知識。
什麼是 API？一切溝通的起點
在深入 RESTful 之前，我們必須先理解什麼是 API。API，其全名「應用程式介面」(Application Programming Interface)，它定義了不同軟體系統之間進行通訊和互動時必須遵循的規則與協定。
您可以將 API 想像成一位餐廳裡的服務生。當您（用戶端）想要點餐時，您不會直接衝進廚房（伺服器端），而是透過服務生（API）來傳達您的需求。您按照菜單（API 文件）上的品項點菜（發出請求），服務生將您的請求傳達給廚房，廚房準備好餐點後，再由服務生將餐點（回應）送到您的桌上。
在這個過程中，服務生扮演了關鍵的溝通角色，您不需要了解廚房內部的運作細節，只需要遵循與服務生溝通的規則即可。同樣地，API 讓應用程式之間可以有效協作，而無需暴露其內部複雜的實作邏輯。
雖然 API 的概念廣泛存在於各種軟體中（例如作業系統的 API），但本文的焦點是 Web API。Web API 是基於網際網路標準的 http協議來運作的 API，它使得位於世界各地的不同伺服器與用戶端能夠可靠地交換資訊。
REST 的誕生：為何需要一種架構風格？
在 REST 出現之前，Web API 的設計五花八門。開發者可能這樣設計 rest api：
- POST /createUser
- GET /getAllUsers
- GET /queryUserById?id=123
這種隨性的命名方式導致每個 API 都像一個獨立的方言，前端工程師或任何需要使用這個 API 的人，都必須花費大量時間閱讀文件，才能理解每個端點（Endpoint）的功能。這種混亂的局面大大增加了開發與維護的複雜性。
2000 年，HTTP 協定的主要設計者之一 Roy Fielding 在其博士論文中提出了 REST，即「具象狀態傳輸」(Representational State Transfer)。REST 並非一個嚴格的標準或協定，而是一組用於設計網路應用程式的架構約束與指導原則。當一個 API 的設計遵循了這些 restful風格的原則，我們就可以稱之為 RESTful API。
「具象狀態傳輸」這個名字聽起來很學術，但我們可以將其拆解來理解：
- 資源 (Resource)：REST 的核心概念。網路上任何可被命名的資訊或實體都是資源，例如一個使用者、一張訂單、一張圖片或一段影片。每個資源都有一個唯一的識別符。
- 具象 (Representation)：資源在特定時間點的狀態的表現形式。它不是資源本身（資源存放在伺服器端），而是資源的一種快照，通常以 JSON 或 XML 格式呈現。例如，一個使用者的 JSON 物件就是該使用者資源的「具象」。
- 狀態傳輸 (State Transfer)：用戶端與伺服器端之間的互動，本質上就是資源「狀態」的「傳輸」。用戶端透過操作資源的「具象」來改變伺服器端上資源的狀態。例如，用戶端修改了本地的用戶 JSON 物件，然後將其發送到伺ervidor端，從而更新了伺服器端上的用戶資料，這就是一次狀態傳輸。
揭密 RESTful API 的六大指導原則
REST 的精髓在於其六大指導原則。這些原則共同作用，構建出一個鬆散耦合、高效率且易於演進的系統。
統一介面 (Uniform Interface)
這是 REST 最核心且最基本的原則，它簡化並解耦了架構，讓各個部分可以獨立演進。統一介面包含四個子約束：
- 資源的識別 (Identification of resources)：所有資源都必須能透過一個唯一的識別符（URI, Uniform Resource Identifier）來定位。例如，/customers/123 就是一個明確的 URI，指向 ID 為 123 的客戶。
- 透過表現層操作資源 (Manipulation of resources through representations)：用戶端持有的資源表現層（如 JSON 物件）應包含足夠的資訊，以便能修改或刪除伺服器端上的資源。
- 自描述訊息 (Self-descriptive messages)：每個請求和回應都應包含足夠的資訊，讓接收方能夠理解。例如，透過 Content-Type: application/json 標頭，伺服器端知道請求的內容是 JSON 格式；用戶端則知道回應是 JSON。
- 超媒體作為應用程式狀態的引擎 (Hypermedia as the Engine of Application State, HATEOAS)：這是最常被忽略但卻十分強大的一點。回應中應包含超媒體連結，指引用戶端可以進行的下一步操作或相關資源的位置。這使得用戶端應用程式可以動態地探索和導航 API，而無需硬編碼 URI 路徑或查閱大量文件。
json { “orderId”: 123, “status”: “shipped”, “total”: 99.99, “_links”: { “self”: { “href”: “/orders/123” }, “customer”: { “href”: “/customers/56” }, “tracking”: { “href”: “/tracking/xyz-789” } } }
無狀態 (Stateless)
從用戶端到伺服器端的每個請求都必須包含所有必要的資訊，以便伺服器端能夠理解和處理該請求。伺服器端不會在兩次請求之間儲存任何關於用戶端的狀態資訊（例如 Session 或 cookie 資訊）。所有狀態要麼由用戶端自己維護，要麼在每次請求中提供。
- 優點：極大地提高了系統的可擴展性和可靠性。由於伺服器端無需維護用戶端狀態，任何一台伺服器都可以處理任何請求，便於進行負載平衡。
可快取性 (Cacheability)
回應必須明確或隱含地標示其自身是否可被快取。如果一個回應是可快取的，那麼用戶端或中間代理（如 CDN）就可以重用該回應來處理後續相同的請求，從而減少網路延遲，提升效能。
分層系統 (Layered System)
用戶端通常不知道自己是直接連接到終端伺服器，還是連接到中間的某個代理伺服器（如負載平衡器、安全閘道）。這種分層架構可以將複雜的系統拆分為多個層次，每個層次只關注特定的功能，從而提高系統的可管理性和安全性。
客戶端-伺服器分離 (Client-Server)
client端（通常是使用者介面）和伺服器端（通常是資料儲存）的關注點應該完全分離。伺服器端負責提供資料和服務，而client端負責呈現資料和使用者互動。這種分離使得兩者可以獨立開發、部署和演進。
隨需編碼 (Code on Demand) – (選用)
這是 REST 中唯一一個非必要的原則。它允許伺服器端透過傳輸可執行的程式碼（例如 JavaScript）來臨時擴展或自訂用戶端的功能。
設計優雅的 RESTful API：實戰指南
理論是基礎，但實踐才是關鍵。一個好的 restful web api 應該像一本寫得很好的書，在 api設計上，直觀、一致且易於閱讀。
URI 設計：資源的地址
URI 是 API 的門面，清晰的 URI 設計至關重要。
使用名詞而非動詞：URI 代表資源，而操作資源的行為應該由 HTTP 方法來體現。
- 優良: GET /orders (獲取所有訂單)
- 避免: GET /getAllOrders
使用複數名詞表示集合：使用複數名詞來命名代表資源集合的端點，這是一種普遍的慣例，使 API 更具可讀性。
- 集合: /customers，例如 GET /users (獲取所有使用者)
- 單一資源: /customers/123
保持 URI 結構簡潔與階層化：使用斜線 / 來表示資源之間的階層關係。但應避免過於深層的巢狀結構，這會讓 URI 變得脆弱且難以維護。
- 良好: GET /customers/123/orders (獲取 123 號客戶的所有訂單)
- 避免: GET /customers/123/orders/456/products (過於複雜)
- 更好的方式是透過 HATEOAS 在 /orders/456 的回應中提供指向其產品的連結。
HTTP 方法：資源的操作
http method 是 RESTful API 中的「動詞」，它定義了要對資源執行的操作。這些方法與資料庫的 CRUD（Create, Read, Update, Delete）操作有著清晰的對應關係。
| HTTP 方法 | 特性 | CRUD 操作 | 描述與應用 |
|---|---|---|---|
| GET | 安全(Safe)、冪等(Idempotent) | Read (讀取) | 從伺服器檢索資源，不應對伺服器狀態產生任何副作用。 |
| POST | 非冪等(Non-idempotent) | Create (新增) | 在指定的資源集合下建立一個新的資源，即新增資料。多次發送相同的 POST 請求會建立多個資源。 |
| PUT | 冪等(Idempotent) | Update (更新/替換) | 用請求中的內容完整替換指定 URI 的現有資源。如果資源不存在，可以選擇建立它。多次發送相同的 PUT 請求，結果都一樣。 |
| PATCH | 非冪等(Non-idempotent) | Update (更新/修改) | 對指定 URI 的資源進行部分修改。它只包含需要變更的欄位，比 PUT 更有效率。 |
| DELETE | 冪等(Idempotent) | Delete (刪除) | 刪除指定 URI 的資源。多次刪除同一個資源，結果都是該資源不存在。 |
深入辨析 PUT vs. PATCH vs. POST
在 GET, POST, PUT 等方法中，後三者是常見的混淆點：
- POST 用於創建：POST /users (請求 body 包含新使用者的資料)。伺服器端決定新資源的 URI (如 /users/456)。
- PUT 用於替換：PUT /users/123 (請求 body 包含 ID 123 使用者的全部新資料)。如果原本只有姓名和信箱，而請求 body 只有姓名，那麼信箱欄位將會被清除。
- PATCH 用於修改：PATCH /users/123 (請求 body 只包含要修改的欄位，如 {“email”: “[email protected]”} )。其他欄位保持不變。
請求與回應 (Request & Response)
一個完整的 restful api http 互動由請求和回應構成。
請求 (Request)
- 標頭 (Headers): 包含元數據，如 Content-Type (發送的資料格式), Accept (期望接收的資料格式), Authorization (認證憑證)。
- 主體 (Body): 請求的實際內容，通常用於 POST, PUT, PATCH 方法。
- 參數 (Parameters):
- 路徑參數 (Path Parameters): 嵌入在 URI 路徑中，用於識別特定資源，如 /users/{userId}。
- 查詢參數 (Query Parameters): 附加在 URI 後面，用於篩選、排序或分頁，如 /users?role=admin&sort=name。
回應 (Response)
- HTTP 狀態碼 (Status Codes): 用於表示請求處理結果的標準三位數代碼。正確使用狀態碼至關重要。
- 2xx (成功): 200 OK, 201 Created (資源創建成功), 204 No Content (成功但無內容返回，如 DELETE)。
- 3xx (重定向): 301 Moved Permanently。
- 4xx (客戶端錯誤): 400 Bad Request (請求語法錯誤), 401 Unauthorized (未認證), 403 Forbidden (已認證但無權限), 404 Not Found (資源不存在)。
- 5xx (伺服器錯誤): 500 Internal Server Error (伺服器端內部發生未知錯誤)。
- 標頭 (Headers): Content-Type (回應內容的格式), Location (與 201 Created 一同使用，指向新資源的 URI)。
- 主體 (Body): 回應的內容，即資源的「具象」(通常是 JSON)。
資料處理：分頁、篩選與版本管理
- 分頁 (Pagination)：當資源集合非常大時，必須進行分頁。常見的方式是使用查詢參數，如 GET /orders?page=2&limit=20。
- 篩選與排序 (Filtering and Sorting)：提供彈性的查詢參數讓用戶端可以精準獲取所需資料的特定部分，如 GET /products?category=electronics&min_price=100&sort=-rating。
- 版本管理 (Versioning)：API 總會演進，版本管理是確保向後相容的關鍵。
| 版本管理策略 | 範例 | 優點 | 缺點 |
|---|---|---|---|
| URI 版本控制 | /api/v1/customers | 直觀，易於瀏覽器和快取理解。 | 污染了 URI，違反了「URI 應指向唯一資源」的理念。 |
| 查詢字串版本控制 | /api/customers?version=1 | 不會污染 URI 結構。 | 某些快取代理可能不會快取帶有查詢字串的請求。 |
| 標頭版本控制 | Custom-Header: api-version=1 | URI 保持乾淨，語意清晰。 | 需要用戶端記得添加自訂標頭，不易於在瀏覽器中直接測試。 |
| 媒體類型版本控制 | Accept: application/vnd.myapi.v1+json | 最符合 REST 理念 (HATEOAS)。 | 實作和使用上最為複雜。 |
安全性考量：保護你的 API
公開的 web服務與 API 必須有嚴格的安全機制。
- 認證 (Authentication)：驗證「你是誰」。
- API 金鑰 (API Keys)：簡單，但金鑰若洩漏則安全性堪憂。
- HTTP 基本/承載者驗證 (Basic/Bearer Authentication)：基本驗證將使用者名稱密碼編碼後傳輸，不安全；承載者驗證（通常是 JWT）是目前主流。
- OAuth 2.0: 一個強大的授權框架，用於第三方應用程式的授權。它允許使用者授予應用程式訪問其資源的權限，而無需透露密碼。
- 授權 (Authorization)：驗證「你能做什麼」。即使認證通過，使用者也可能沒有權限執行特定操作（如非管理員使用者試圖刪除其他用戶）。
- 傳輸安全: 始終使用 HTTPS (HTTP over TLS/SSL) 來加密所有通訊，防止資料在傳輸過程中被竊聽或篡改。
- 避免在 URI 中傳遞敏感資訊：例如，使用者的身分證號碼不應出現在 URI 中。應改用 POST 請求，並將敏感資訊放在請求主體中傳遞。
常見問題 (FAQ)
Q1: RESTful API 和一般的 Web API 有什麼根本上的不同？
A: 主要區別在於 RESTful API 遵循一組特定的架構原則（如統一介面、無狀態等），而一般的 Web API 則沒有固定的設計風格，可能導致結構混亂、難以理解。RESTful 提供了一套共同的詞彙和設計模式，大大簡化了開發者之間的溝通。
Q2: 所有的 API 都必須是 RESTful 的嗎？
A: 不。RESTful 非常適合以「資源」為中心的 CRUD 操作，但在某些場景下，其他技術可能是更好的選擇。例如，GraphQL 允許用戶端精確請求所需數據，避免了過度或不足的資料獲取問題，適合需要高度彈性查詢的前端應用。gRPC 則適用於需要高效能、低延遲的微服務內部通訊。
Q3: PUT 和 PATCH 到底該用哪一個？
A: 這取決於您的意圖。如果您想用新的資料完整替換一個現有資源，請使用 PUT。如果您只想修改資源的部分欄位，而保持其他欄位不變，請使用 PATCH，因為它更有效率，只傳輸需要變更的資料。
Q4: 為什麼「無狀態 (Stateless)」這麼重要？
A: 「無狀態」是 REST 可擴展性的關鍵。因為伺服器端不需要儲存用戶端的會話資訊，任何一台伺服器都可以處理來自任何用戶端的請求。這使得系統可以輕鬆地透過增加更多伺服器來水平擴展，以應對不斷增長的流量，同時也提高了系統的可靠性。
Q5: 如何決定 API 的版本號要放在哪裡 (URI、標頭還是查詢參數)？
A: 這是一個權衡的選擇，沒有絕對的答案。URI 版本控制 (/api/v1/) 最直觀，對開發者和快取最友好，是許多大型企業的首選。標頭版本控制在語意上更「純粹」，但使用起來較不方便。查詢字串是一個折衷方案。團隊應根據專案需求、開發者便利性和架構理念來選擇最適合的策略並保持一致。
總結
RESTful API 不僅僅是一套技術規範，它更是一種提升軟體架構清晰度、可擴展性和可維護性的設計哲學。透過圍繞「資源」進行設計，利用統一的介面和無狀態的通訊，我們能夠構建出強大而優雅的網路服務。
本篇文從 API 的基礎概念，深入到 REST 的六大核心原則，再到涵蓋 URI 設計、HTTP 方法、狀態碼、資料處理、版本控制和安全性的詳細實戰指南，旨在為您提供一個全方位的視角。
請記住，這些原則和最佳實踐是指導方針，而非僵化的教條。在真實世界的專案中，我們需要根據具體場景做出明智的權衡。最終的目標，是打造出一個不僅功能強大，而且能讓其他開發者愉快地使用的 API。掌握 RESTful 的精髓，將是您在現代軟體開發領域中一項不可或缺的核心技能。
