API 設計介紹
1. 什麼是 API 設計？
2. RESTful API 設計原則
基於資源的設計 (Resource-Based Design)
users, orders, pets），而不是動詞。/users — 使用者的集合/users/{id} — 特定使用者/orders — 訂單的集合/getUsers — 使用動詞/createUser — 使用動詞/userData — 命名不清使用 HTTP 方法表達操作
| HTTP 方法 | 含義 | 範例 |
|---|---|---|
| GET | 檢索資料 | GET /users/{id} — 獲取一個使用者 |
| POST | 建立資料 | POST /users — 建立一個使用者 |
| PUT | 取代資料 | PUT /users/{id} — 更新整個使用者 |
| PATCH | 部分更新 | PATCH /users/{id} — 更新部分欄位 |
| DELETE | 移除資料 | DELETE /users/{id} — 刪除一個使用者 |
/users/{id}) 如何與不同的方法一起使用以執行不同的操作。這是一個關鍵的 REST 原則。無狀態 (Stateless)
統一介面 (Uniform Interface)
/resource/{id})3. API 設計最佳實踐
命名慣例
/users, /orders/user-preferences 或 /user_preferences/users 比 /u 或 /user_accounts_management 更好✅ Good: POST /users
✅ Good: GET /users/{id}
❌ Bad: POST /createUser
❌ Bad: GET /getUserById/{id}URL 結構
/users/{id} — 獲取特定使用者/users/{id}/orders — 獲取使用者的訂單/users/{id}/preferences — 獲取使用者偏好✅ Good: /users/{id}/orders/{orderId}
❌ Bad: /users/{id}/orders/{orderId}/items/{itemId}/details/{detailId}版本控制
/v1/users, /v2/users/users?version=1錯誤處理
| 狀態碼 | 含義 | 範例 |
|---|---|---|
| 200 | 成功 | 請求成功完成 |
| 201 | 已建立 | 資源已成功建立 |
| 400 | 錯誤的請求 | 無效的輸入資料 |
| 401 | 未經授權 | 需要身分驗證 |
| 403 | 禁止 | 權限不足 |
| 404 | 未找到 | 資源不存在 |
| 422 | 無法處理的實體 | 驗證錯誤 |
| 500 | 內部伺服器錯誤 | 伺服器錯誤 |
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Email address is required",
"field": "email"
}
}4. API 優先 (API-First) vs 程式碼優先 (Code-First)
程式碼優先方法
1.
2.
3.
API 優先方法（推薦）
1.
2.
3.
4.
5.
5. 完整的 API 設計流程
1.
2.
3.
4.
5.
6.
7.
8.
9.
6. 關鍵收穫
1.
2.
3.
4.
5.
Modified at 2025-12-29 09:35:19