第八章

API 是什麼（房子怎麼接水接電）

你的程式要跟外界溝通，靠的就是 API。不需要會寫，但要知道它在幹嘛。

API 是什麼？

想像你走進一間餐廳。

你（前端）坐下來看菜單，選好要吃什麼。
服務生（API）把你的訂單送到廚房（後端）。
廚房做好菜之後，服務生再端回來給你。

你不需要知道廚房怎麼煮，也不用進去廚房。
你只需要知道：菜單上有什麼、怎麼點、點了之後會得到什麼。

API 的全名是 Application Programming Interface，翻成中文就是「程式之間的溝通介面」。

簡單說：

  • 前端（你看到的網頁）想要資料 → 跟 API 說「我要 XXX」
  • API 把請求送到後端 → 後端處理完 → 再透過 API 回傳結果
  • 前端收到結果 → 顯示在畫面上
為什麼要知道這個？
當你跟 Claude Code 說「幫我做一個客戶管理系統」，它會幫你建 API。你看到 GET /api/customers 這種東西時，就知道這是「去拿客戶列表」的意思，而不是一臉問號。

API 的角色定位

沒有 API 的世界
前端直接連資料庫
→ 安全漏洞大開
→ 每個頁面自己寫查詢邏輯
→ 改一個欄位，10 個頁面都要改
→ 手機 App 跟網頁各寫一套
有 API 的世界
前端只跟 API 溝通
→ API 統一管理權限和驗證
→ 邏輯集中在一個地方
→ 改一次，全部生效
→ 手機 / 網頁 / 第三方都用同一組 API

HTTP Methods（點菜的方式）

既然 API 是「服務生」，那你跟服務生講話時，有幾種不同的「動作」。這些動作在技術上叫做 HTTP Methods（HTTP 方法）。

方法 白話 餐廳比喻 實際例子
GET 「我要看」 看菜單 / 查目前的訂單 打開商品頁面、查訂單紀錄
POST 「我要新增」 下一筆新訂單 註冊帳號、送出表單、新增一筆資料
PUT 「我要整個換掉」 整張訂單重寫 更新個人資料（全部欄位都重新送）
PATCH 「我要改一部分」 只改訂單裡的一道菜 只改密碼、只改暱稱
DELETE 「我要刪掉」 取消訂單 刪除帳號、移除商品
PUT vs PATCH 差在哪？
PUT 像是把整張考卷擦掉重寫。就算你只改一題，也要把所有答案都重填一遍。
PATCH 像是用立可白只修一題。其他題目維持原樣。

實務上大部分系統用 PATCH 比較多，因為「只改一個欄位」的需求比「整個重送」常見得多。

狀態碼（服務生的回覆）

你跟 API 說「我要 XXX」之後，API 會回一個數字代碼告訴你結果。這就是 HTTP 狀態碼。

不用背，但看到的時候要知道什麼意思：

成功的回覆（2xx）

代碼 白話 餐廳比喻
200 成功，資料來了 「好的，菜來了」
201 建立成功 「訂單已成立，等候出餐」

你的問題（4xx）

代碼 白話 餐廳比喻
400 你的要求有問題 「菜單上沒這道菜」「你的格式不對」
401 沒有登入 「請先出示會員卡」
403 沒有權限 「VIP 專屬區域，你進不去」
404 找不到 「那道菜已經下架了」

伺服器的問題（5xx）

代碼 白話 餐廳比喻
500 伺服器壞了 「廚房失火了，我們也沒辦法」
記住這個規則
4xx = 你的問題（請求格式錯、沒登入、沒權限）
5xx = 伺服器的問題（後端程式炸了、資料庫掛了）

看到 4xx 先檢查自己；看到 5xx 去找後端工程師。

實際案例：一個「客戶管理」的完整流程

假設你請 Claude Code 幫你做一個客戶管理系統，它會建出以下這些 API。我們來走一遍完整流程：

1. 新增客戶（POST）

使用者在前端填好表單（姓名、電話、Email），按下「送出」。

POST /api/customers

送出的資料（Request Body）：
{
  "name": "王小明",
  "phone": "0912-345-678",
  "email": "ming@example.com"
}

後端收到 → 存進資料庫 → 回傳：

狀態碼：201 Created

回傳的資料（Response）：
{
  "id": 123,
  "name": "王小明",
  "phone": "0912-345-678",
  "email": "ming@example.com",
  "created_at": "2026-03-28T10:30:00Z"
}

前端收到 201 → 顯示「新增成功！」

2. 列出所有客戶（GET）

GET /api/customers

狀態碼：200 OK

回傳：
[
  { "id": 123, "name": "王小明", "phone": "0912-345-678" },
  { "id": 124, "name": "李大華", "phone": "0933-456-789" },
  { "id": 125, "name": "張美玲", "phone": "0955-567-890" }
]

前端收到資料 → 渲染成表格顯示在頁面上。

3. 查看單一客戶（GET + ID）

GET /api/customers/123

狀態碼：200 OK

回傳：王小明的完整資料

4. 修改客戶資料（PATCH）

王小明換了電話號碼，只要改這個欄位：

PATCH /api/customers/123

送出的資料：
{
  "phone": "0987-654-321"
}

狀態碼：200 OK
→ 只有電話被改掉，其他欄位不動

5. 刪除客戶（DELETE）

DELETE /api/customers/123

狀態碼：200 OK
→ 王小明的資料被刪除了
整理一下
看出規律了嗎？同一個路徑 /api/customers，搭配不同的 HTTP Method，就能做不同的事：
  • GET /api/customers → 看全部
  • GET /api/customers/123 → 看一個
  • POST /api/customers → 新增
  • PATCH /api/customers/123 → 改一個
  • DELETE /api/customers/123 → 刪一個
這就是 API 設計的核心概念。

API 組合排列的概念（RESTful）

上面那種「用 HTTP Method + 路徑」來操作資源的設計方式，有一個正式的名字叫做 RESTful API。

RESTful 命名慣例

好的 API 設計有一些約定俗成的規則：

規則 好的例子 不好的例子
用名詞，不用動詞 /api/customers /api/getCustomers
用複數 /api/orders /api/order
巢狀表示關聯 /api/customers/123/orders /api/getOrdersByCustomer?id=123
版本號放前面 /api/v1/customers /api/customers?version=1

Endpoint 怎麼看

當你看到一個 API 路徑，可以像看地址一樣來拆解：

/api/v1/users/123/orders

拆解：
├── /api → 表示這是 API（不是一般網頁）
├── /v1 → 版本 1
├── /users → 資源類型：使用者
├── /123 → 特定使用者（ID = 123）
└── /orders → 這個使用者的訂單

白話翻譯：「API 版本 1，去找 ID 為 123 的使用者，然後拿他的訂單」

再多幾個例子：

GET /api/v1/products → 拿所有商品列表
POST /api/v1/products → 新增一個商品
GET /api/v1/products/456/reviews → 看商品 456 的所有評價
DELETE /api/v1/users/123/orders/789 → 刪掉使用者 123 的訂單 789

跟 Claude Code 的關係

當你對 Claude Code 說：

不知道 API 概念
「幫我做一個可以新增客戶
的功能，然後還要能查詢
跟刪除」
知道 API 概念
「幫我建 RESTful API：
POST/GET/PATCH/DELETE
/api/v1/customers
回傳 JSON，需要驗證」

右邊的指令更精準，Claude Code 產出的結果也會更符合你的期待。不需要你會寫程式碼，但知道這些「菜名」就能點對菜。

本章重點回顧
  • API = 程式之間溝通的介面（服務生）
  • HTTP Methods = 你要做什麼動作（GET 看 / POST 新增 / PATCH 改 / DELETE 刪）
  • 狀態碼 = 服務生的回覆（200 成功 / 4xx 你的問題 / 5xx 伺服器的問題）
  • RESTful = API 的命名規則（用名詞、用複數、巢狀表示關聯）
  • Endpoint = API 的地址，像 /api/v1/users/123/orders