前幾天我們學會了呼叫 API、解析 JSON，也練習了錯誤處理。

如果換成自己要設計一個 API，又該從哪裡開始呢？

今天的目標是認識 RESTful API 的基礎，理解 endpoint 和 parameters，並透過書店的例子，學習 API 是如何一步步設計出來的。

什麼是 RESTful API？

REST 是什麼？

REST（Representational State Transfer），它不是一個程式語言或工具，而是一種設計風格或規範，用來讓網路上的不同系統溝通。

RESTful API 的核心概念：

1. 用 HTTP 方法來表示動作

像是常見的 HTTP 方法：

• GET：拿取資料
• POST：新增資料
• PUT 或 PATCH：修改資料
• DELETE：刪除資料

2. 用 URL 表示資源

URL 不再是「動詞+動作」，而是用名詞表示「資源」。

例如：

• /books 表示書籍
• /orders 表示訂單

3. Stateless（無狀態）

每一次跟伺服器的請求都是獨立的，也就是說伺服器不會記住上一次做了什麼。

這樣可以讓系統更穩定，也容易維護。

RESTful API 有什麼優點？

• 易讀易懂：規則清楚，網路上大多數 API 都用這種方式。

• 方便溝通：前端和後端都容易知道怎麼用，合作更順利。

• 標準化：跟著 HTTP 規則走，讓網路應用更一致。

簡單舉例：

如果要查某本書的資料，API 會長這樣：

GET /books/123

這代表「用 GET 方法，拿 ID 是 123 的書籍資訊」。

如果新增一本書，就用：

POST /books

後面搭配書的資料。

API 的結構長怎樣？

一個 API 主要由三部分組成：

1. Endpoint（端點）

API 的「地址」或「門牌號碼」，告訴你去哪裡拿資料和做事情。

例如：

• GET /books → 拿所有書的列表

• GET /books/123 → 拿書籍ID是123的詳細資料

2. Parameters（參數）

給 API 的額外條件，可以讓它做更精準的工作。

常見的4種參數：

• Path 參數：在網址路徑裡的，像 /books/{book_id}，book_id就是變數。

• Query 參數：在網址問號後面加的條件，像 /books?page=2&author_id=99，意思是要第2頁作者是99的書。

• Header 參數：放在 HTTP 請求的標頭裡，常用來放認證資料，例如 Authorization: Bearer ...。

• Body 參數：通常用在 POST 或 PUT，會放在請求主體裡，通常是 JSON 格式，像附帶資料寫入伺服器。

3. Response（回應）

API 回傳的資料，通常是 JSON 格式，裡面會有我們要的內容，還有狀態碼表示成功或失敗。
遇錯時，回應會告訴我們錯誤訊息。

實際例子：書店API

需求變資源

在設計 RESTful API 時，會把功能需求用「資源」的形式名詞化，變成 API 的操作對象。

舉例：書店裡會有哪些資源？

• 我想查書 → books

• 我想看某本書的作者 → authors

• 我想下單 → orders

• 我想看某訂單的品項 → order_items

為什麼用名詞？

在 RESTful API 中，資源一定用名詞表示，因為 API 就像在操作東西或物件，而不是直接叫「做什麼」的動詞動作。
像是 books 就是「書」的集合，orders 是「訂單」的集合。

多數資源名稱使用複數形

例如：

• books 代表所有書的集合

• authors 代表所有作者的集合

這樣符合 RESTful API 的習慣，也讓 API 路徑更清楚。

設計資源路徑的基本規則

1. 路徑用全小寫且用複數名詞

例如：/books、/authors，代表資源集合。

2. 表示巢狀關係（層級結構）

用階層方式表示子資源，例如：

/orders/{order_id}/items

意思是「在訂單（orders）裡的品項（items）」

3. 避免在路徑中出現動詞

不要寫 /createBook，而是用 HTTP 方法來表示操作：

• POST /books → 新增一本書

• GET /books → 取得書籍列表

• DELETE /books/{book_id} → 刪除某本書

書店範例的資源路徑

巢狀資源 vs 查詢參數

• 巢狀路徑：

如果子資源跟主要資源有強烈關聯，而且只有在該主要資源的上下文合理，選擇用階層巢狀路徑，例如：

/orders/{id}/items

這表示查看特定訂單的品項。

• 查詢參數：

如果需要跨資源篩選資料，使用查詢參數。例如：

/books?author_id=123

找作者為 123 的書。

參數怎麼用？

Query 參數（查詢參數）

用來篩選、分頁、排序資料。

這些參數會放在網址的問號後面。

例如：

GET /books?page=1&page_size=20&sort=-published_at

這裡表示：

• page=1：第 1 頁
• page_size=20：每頁 20 筆資料
• sort=-published_at：依發行日期由新到舊排序

Body 參數（請求內容）

當要新增或修改資料時，會把資料放在 HTTP 請求的內容裡。

常用 JSON 格式，例如：

要新增一本書，Body 內容會是：

{
  "title": "Clean Architecture",
  "author_id": 42,
  "price": 650
}

Header 參數（標頭）

放在 HTTP 請求的「標頭」，用來帶一些額外資訊。

常見的用途是帶認證和告訴伺服器我們要的資料格式。

例如：

Authorization: Bearer <token>
Accept: application/json

• Authorization 用來帶 token 認證，讓伺服器知道你是誰、有沒有權限。
• Accept 告訴伺服器，想用 JSON 格式收到資料。

回應與錯誤格式

成功回應（狀態碼 200）

當用 API 請求資料成功時，伺服器會回傳「狀態碼 200」和一份資料（通常是 JSON 格式）。

這份資料會包含請求的內容。

範例：查一本書，伺服器回來的資料可能長這樣：

{
  "id": 123,
  "title": "Clean Architecture",
  "author_id": 42,
  "price": 650
}

意思是這本書的編號是 123，書名是「Clean Architecture」，作者編號是 42，價格 650。

錯誤回應（狀態碼 404 Not Found）

如果請求的資源不存在或找不到，伺服器會回傳錯誤狀態碼（例如 404）。

同時也會回一段錯誤訊息，用來告訴我們發生了什麼問題。

範例：找不到書的錯誤回應：

{
  "code": "BOOK_NOT_FOUND",
  "message": "Book not found"
}

這是伺服器告訴我們「書不存在」，而且用 code 和 message 讓我們可以程式化地判斷錯誤。

設計 API 的小技巧

1. URL 用名詞，不用動詞

• 用清楚的「名詞」表示資源，例如：/books

• 不要用動詞，例如：/getBooks

2. 統一命名風格

參數和欄位名稱要保持風格一致，常見的是全用蛇底線（snake_case）或駝峰式（camelCase），二選一。

例如：author_id 或 authorId，選一種就好。

3. 資源名稱都用複數形式

表示一群該類型的物件，像是：/books
而非用單數 /book。

4. 時間格式用標準 ISO 8601

時間欄位用統一格式，方便跨系統使用，例如：

2025-09-21T01:23:45Z

5. 大量資料回傳時加分頁資訊

如果會回傳很多筆資料，建議加上分頁功能，避免一次回傳太多導致效能問題。

今日總結

• 了解 RESTful API 的概念：用 HTTP 方法操作資源。

• 認識 Endpoint 與 Parameters 的結構。

• 用書店 API 當例子，學會 API 是如何設計。