API 設計指南

在結束本章設計之前，讓我們總結並回顧一套 API 設計指南。擁有一致的設計指南對於團隊協作至關重要。當所有人遵循相同的規則時，API 不僅看起來像是由一個人編寫的（即使是由多人編寫），而且對使用者來說也更容易學習和預測。

以下是我們在設計 Pet Store User 模組時應用的關鍵指南，您應該將其應用於您未來的 API 專案。

1. 命名與路徑 (RESTful URL Design)

保持一致的命名慣例

路徑 (URLs): 使用 kebab-case (小寫，用連字號分隔)。

✅ /users

✅ /user-profiles

❌ /Users, /userProfiles, /user_profiles

欄位 (JSON Fields): 使用 camelCase (這是 JSON 的標準)。

✅ firstName, createdAt, userId

❌ first_name, Created_At, UserID

資源導向 (Resource-Oriented)

使用名詞，避免動詞。

✅ POST /users (Create)

❌ POST /createUser

使用複數名詞表示集合。

✅ /users/{id}

❌ /user/{id} (除非該資源在系統中真的是單例)

階層結構

使用路徑來表示關係。

✅ /users/{id}/orders (某個使用者的訂單)

✅ /users/{id}/preferences (某個使用者的偏好)

2. HTTP 方法的使用

正確使用 HTTP 動詞使 API 具有語義和預測性。

GET: 用於檢索。安全且冪等 (Idempotent)。不應有 Request Body。

POST: 用於建立新資源或執行非標準操作 (如 login, logout)。不冪等。

PUT: 用於完整替換資源。冪等。如果資源不存在，可能會建立它（取決於實作）。

PATCH: 用於部分更新資源。通常不是冪等的（取決於實作）。

DELETE: 用於移除資源。冪等。

3. 回應與狀態碼

不要只返回 200 OK。使用適當的狀態碼傳達結果。

成功

200 OK: 標準成功回應。

201 Created: 資源建立成功 (用於 POST)。通常返回新資源的位置 (Location header) 或內容。

204 No Content: 操作成功但無內容返回 (常用於 DELETE 或 PUT)。

客戶端錯誤

400 Bad Request: 通用客戶端錯誤，通常是用戶端發送了無效的 JSON 或參數。

401 Unauthorized: 未提供身分驗證憑證或憑證無效 (如無 token)。

403 Forbidden: 已驗證，但無權執行此操作 (如普通使用者想刪除管理員)。

404 Not Found: 資源不存在。

422 Unprocessable Entity: 語義錯誤，如驗證失敗 (email 格式錯誤、密碼太短)。

伺服器錯誤

500 Internal Server Error: 伺服器炸了。不應向用戶端透露堆疊追蹤 (Stack Trace)。

4. 資料模型與格式

遵循 JSON 標準

始終返回 JSON 物件，而不是純字串或頂層陣列（為擴展性保留頂層物件）。

✅ { "data": [ ... ] } 或 { "users": [ ... ] }

⚠️ [ ... ] (有些安全風險和擴展限制)

時間與日期

始終使用 ISO 8601 格式 (YYYY-MM-DDThh:mm:ssZ)。

✅ "2024-03-21T14:30:00Z"

❌ Unix timestamp (有時難以閱讀和除錯), "21/03/2024" (地區歧義)

分頁 (Pagination)

對於返回集合的端點，始終支援分頁。

使用 page/limit 或 offset/limit。

在回應中包含分頁元數據 (Metadata)。

{
  "data": [ ... ],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 20
  }
}

5. 安全性指南

HTTPS 隨處可見: 沒有例外。

不要在 URL 中傳遞敏感資訊: API Key 或 Token 應在 Header 中，不應在 Query String 中 (會被瀏覽器記錄和伺服器日誌捕捉)。

最小化資料暴露: 不要返回不必要的資料（如密碼 hash 或內部系統 ID）。

速率限制 (Rate Limiting): 保護您的 API 免受濫用。通過 Headers (X-RateLimit-Remaining) 傳達限制。

6. 版本控制 (Versioning)

API 會變。為了不破壞現有客戶端，制定版本策略。

URL 版本控制 (最常見):

/v1/users

/v2/users

主要版本 (Major Version): 當有破壞性變更 (Breaking Changes) 時升級 (v1 -> v2)。

非破壞性變更: (如新增欄位、新增端點) 通常不需要升級主要版號。

7. 文件 (Documentation)

Apidog 自動處理這部分，但您需要提供內容：

描述: 為每個端點、參數和 Schema 欄位編寫清晰的描述。

範例: 提供請求和回應的真實範例。

錯誤範例: 記錄可能發生的錯誤及其含義。

結語：Apidog 驅動的設計流程

回顧我們建立 Pet Store User API 的過程：

分析: 我們從需求和使用案例開始。

規劃: 我們識別了資源和從屬關係。

資料模型: 我們設計了 Schemas (User, Preferences)。

端點: 我們將操作映射到 HTTP 方法和路徑。

元件: 我們提取了可重用的部分 (參數, 錯誤, 安全方案)。

文件: 我們在設計過程中就已經（自動）編寫了文件。

這就是 API 設計優先 (API-Design-First) 的力量。您現在擁有一份完整的、可執行的規格，開發人員可以立即開始編碼，測試人員可以開始編寫測試用例，而無需等待後端完成。

恭喜！ 您已經完成了 API 設計 章節。您現在具備了從頭開始設計專業、可擴展且安全的 API 所需的知識和工具。

前往章節總結快速回顧我們所學的內容。

1. 命名與路徑 (RESTful URL Design)#

保持一致的命名慣例#

資源導向 (Resource-Oriented)#

階層結構#

2. HTTP 方法的使用#

3. 回應與狀態碼#

成功#

客戶端錯誤#

伺服器錯誤#

4. 資料模型與格式#

遵循 JSON 標準#

時間與日期#

分頁 (Pagination)#

5. 安全性指南#

6. 版本控制 (Versioning)#

7. 文件 (Documentation)#

結語：Apidog 驅動的設計流程#