Skip to main content

如何打造一個漂亮乾淨俐落的 RESTful API

1. 路由設計（Endpoints）​

  • 使用名詞，不用動詞
    ✅ /users、/orders/123
    ❌ /getUsers、/createOrder

  • 用複數表示資源

    • /users → 所有使用者

    • /users/123 → 指定使用者

  • 巢狀結構反映資源關係

    • /users/123/orders → 指定使用者的訂單

2. HTTP 方法（Verbs）​

  • GET → 讀取

  • POST → 新增

  • PUT → 完整更新

  • PATCH → 部分更新

  • DELETE → 刪除

範例：

  • GET /users → 取得所有使用者

  • POST /users → 建立新使用者

  • GET /users/123 → 查詢 ID=123 的使用者

  • PUT /users/123 → 覆蓋使用者資料

  • PATCH /users/123 → 更新使用者部分資料

  • DELETE /users/123 → 刪除使用者

3. 資料格式（Representation）​

  • 一致回傳 JSON（除非另有需求）。

  • 欄位命名：小寫 + 下底線/駝峰一致性

    • 建議駝峰：createdAt, userName

回應範例：

{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com",
  "createdAt": "2025-09-13T10:30:00Z"
}

4. 錯誤處理（Error Handling）​

  • 使用標準 HTTP 狀態碼：

    • 200 OK → 成功

    • 201 Created → 成功建立

    • 400 Bad Request → 客戶端錯誤

    • 401 Unauthorized → 未登入

    • 403 Forbidden → 沒權限

    • 404 Not Found → 找不到

    • 500 Internal Server Error → 伺服器錯誤

  • 回傳清楚的錯誤訊息：

{
  "error": "ValidationError",
  "message": "Email format is invalid",
  "field": "email"
}

5. 分頁與查詢（Filtering & Pagination）​

  • Query Parameters

    • /users?role=admin&status=active

  • 分頁標準做法

    • /users?page=2&limit=20

  • 回傳分頁資訊：

{
  "data": [...],
  "meta": {
    "page": 2,
    "limit": 20,
    "total": 145
  }
}

6. 版本控制（Versioning）​

  • 在 URL 或 Header 指定版本：

    • /api/v1/users

    • Header: Accept: application/vnd.myapp.v1+json

7. 文件與一致性​

  • 自動文件化（例如 Swagger / OpenAPI）。

  • 一致的結構與風格 → 讓團隊協作更順暢。

✅ 總結：
一個漂亮乾淨的 RESTful API =
👉 直覺的 URL 結構（名詞化、分層清楚）
👉 語意正確的 HTTP 方法
👉 一致的資料格式與錯誤回應
👉 支援分頁、查詢、版本化
👉 有清楚的文件與風格指南