前言

昨天我們認識了 API 的角色與常見類型，今天要更深入到目前最普及的 RESTful API。
REST 並不是一個框架或工具，而是一種「設計風格」。
如果你常用的 API 介面結構簡潔、容易理解，很有可能就是遵循了 RESTful 的設計原則。

什麼是 REST？

REST 全名 Representational State Transfer，是一種設計分散式系統的風格，由 Roy Fielding 在 2000 年提出。

它的核心精神是：

• 資源導向：所有東西都是一個資源（Resource）。
• 統一介面：透過 HTTP 的方法來操作資源。
• 無狀態（Stateless）：每一次請求都要帶齊資訊，伺服器不會記住客戶端狀態。
• 分層架構（Layered System）：客戶端不用知道伺服器的細節，可以透過 Proxy、快取等方式優化。

HTTP 方法（Methods）

在 RESTful API 中，最常用的 HTTP 方法對應到 CRUD 操作：

URI 設計原則

一個好的 RESTful API，URI（路徑）應該要：

1. 資源化（Noun-based）：URI 使用名詞，而不是動詞。

   • O: /books
   • X: /getBooks

2. 層級結構：用 / 代表資源的關係。

   • /books/1/authors → 取得 id=1 的書籍作者

3. 小寫與複數：保持一致性。

   • O: /users
   • X: /Users or /user

4. 避免冗長：簡潔易讀。

   • O: /orders/1
   • X: /getAllOrdersByUserId/1

RESTful API 範例：Todo 應用

假設我們要設計一個「待辦事項（Todo）」API，常見的設計如下：

這樣的設計簡單明瞭，光看路徑與方法就能知道在做什麼。

常見的反例

• 在 URI 裡放動詞

  • X: /createTodo
  • O: POST /todos

• 忽略 HTTP 狀態碼

  • X: 永遠回傳 200 OK
  • O: 建立成功回 201 Created，找不到回 404 Not Found

小結

• RESTful API 的核心是 資源導向 與 一致的介面設計。
• 好的 API 不只要能用，還要 易讀、可維護、具一致性。
• 今天我們學會了：
  • HTTP 方法如何對應 CRUD
  • URI 設計原則
  • Todo API 範例