在現代 Web 開發中，前端與後端的溝通幾乎都依賴 API，而 RESTful API 是目前最流行的 API 設計風格之一。無論你是開發前端、後端，還是全端應用，理解 RESTful API 都是必不可少的技能。
如果你曾經遇過以下問題：
- 「這個 API 該怎麼設計才符合標準？」
- 「為什麼 API 會有 GET、POST、PUT、DELETE？」
- 「如何讓 API 更易讀、可維護？」
那麼，這篇文章將帶你深入了解 RESTful API 的設計理念與最佳實踐。
什麼是 RESTful API？
REST（Representational State Transfer，表現層狀態轉換）是一種基於 HTTP 協議 的 API 設計風格，它強調統一的資源接口設計，使 API 更簡潔、可讀、可維護。
RESTful API 的核心理念：
✅ 資源導向（Resource-Oriented）— API 主要是對資源（Resource）進行操作
✅ 無狀態（Stateless）— 每次請求都是獨立的，不會記住用戶的狀態
✅ 統一接口（Uniform Interface）— 使用標準的 HTTP 方法（GET、POST、PUT、DELETE）
✅ 基於 URI 設計 — API 透過清晰的 URL 來表示資源
RESTful API 的 HTTP 方法
RESTful API 主要使用 HTTP 方法 來對資源進行操作：
| HTTP 方法 | 用途 | 範例 |
|---|---|---|
| GET | 取得資源 | GET /users （取得所有用戶） |
| POST | 新增資源 | POST /users （新增用戶） |
| PUT | 更新整個資源 | PUT /users/1 （更新用戶 ID=1） |
| PATCH | 部分更新資源 | PATCH /users/1 （修改部分欄位） |
| DELETE | 刪除資源 | DELETE /users/1 （刪除用戶 ID=1） |
RESTful API 設計範例
假設我們要設計一個 用戶管理系統，API 應該如何設計？
1. 取得所有用戶
GET /users
回應範例（JSON）：
[
{ "id": 1, "name": "Alice", "email": "alice@example.com" },
{ "id": 2, "name": "Bob", "email": "bob@example.com" }
]
2. 取得單一用戶
GET /users/1
回應範例（JSON）：
{ "id": 1, "name": "Alice", "email": "alice@example.com" }
3. 新增用戶
POST /users
請求 Body（JSON）：
{
"name": "Charlie",
"email": "charlie@example.com"
}
回應（成功建立）
201 Created
{
"id": 3,
"name": "Charlie",
"email": "charlie@example.com"
}
4. 更新用戶資訊
PUT /users/1
請求 Body（JSON）：
{
"name": "Alice Smith",
"email": "alice.smith@example.com"
}
回應（成功更新）
200 OK
{
"id": 1,
"name": "Alice Smith",
"email": "alice.smith@example.com"
}
5. 刪除用戶
DELETE /users/1
回應（成功刪除）
204 No Content
（無回應內容）
RESTful API 的設計原則
1️⃣ 使用名詞，而非動詞
✅
GET /users （取得用戶）❌
GET /getUsers（動詞不必要）
✅ POST /users （新增用戶）
❌ POST /createUser（動詞不必要）
2️⃣ 使用狀態碼來回應請求結果
200 OK：請求成功201 Created：成功建立新資源400 Bad Request：請求錯誤，如缺少必要欄位404 Not Found：找不到資源500 Internal Server Error：伺服器錯誤
3️⃣ 支援分頁與篩選
當 API 回傳大量資料時，應該支援分頁：
GET /users?page=1&limit=10
當 API 需要過濾特定資料時，可使用查詢參數：
GET /users?role=admin
4️⃣ 使用 JSON 作為回應格式
✅ JSON 是目前最廣泛使用的 API 格式，能與前端 JavaScript 直接解析
❌ 避免使用 XML，因為較為冗長且解析較慢
如何在後端建立 RESTful API（Node.js + Express）
使用 Express.js 快速建立一個 RESTful API
1. 安裝 Express
npm init -y
npm install express
2. 建立 server.js
const express = require("express");
const app = express();
app.use(express.json());
let users = [
{ id: 1, name: "Alice", email: "alice@example.com" },
{ id: 2, name: "Bob", email: "bob@example.com" }
];
// 取得所有用戶
app.get("/users", (req, res) => {
res.json(users);
});
// 取得單一用戶
app.get("/users/:id", (req, res) => {
const user = users.find(u => u.id == req.params.id);
user ? res.json(user) : res.status(404).json({ message: "User not found" });
});
// 新增用戶
app.post("/users", (req, res) => {
const newUser = { id: users.length + 1, ...req.body };
users.push(newUser);
res.status(201).json(newUser);
});
// 更新用戶
app.put("/users/:id", (req, res) => {
const user = users.find(u => u.id == req.params.id);
if (!user) return res.status(404).json({ message: "User not found" });
Object.assign(user, req.body);
res.json(user);
});
// 刪除用戶
app.delete("/users/:id", (req, res) => {
users = users.filter(u => u.id != req.params.id);
res.status(204).send();
});
// 啟動伺服器
app.listen(3000, () => console.log("Server running on port 3000"));
啟動伺服器：
node server.js
現在你已經有了一個完整的 RESTful API ?
結論
RESTful API 是全端工程師必須掌握的技術，它讓前後端能夠以清晰、標準化的方式進行數據交換。
重點回顧：
✅ RESTful API 使用標準 HTTP 方法（GET、POST、PUT、DELETE）
✅ API 設計應該以 資源導向，避免使用動詞
✅ 使用 JSON 格式 回應資料
✅ 使用 狀態碼 來指示請求結果
✅ 支援 分頁與查詢參數
你有使用 RESTful API 的經驗嗎？遇過什麼問題？歡迎留言討論！?
評論