RESTful API 設計原則

設計良好的 API 是現代應用程式的基礎。這篇文章分享 RESTful API 設計的最佳實踐。

REST 原則

REST（Representational State Transfer）是一種架構風格，基於以下原則：

• 資源導向：使用名詞而非動詞
• HTTP 方法：GET、POST、PUT、DELETE
• 無狀態：每個請求都包含所有必要資訊
• 統一介面：一致的 API 設計

URL 設計

良好的 URL 設計應該：

GET    /api/users          # 取得所有使用者
GET    /api/users/123      # 取得特定使用者
POST   /api/users          # 建立新使用者
PUT    /api/users/123      # 更新使用者
DELETE /api/users/123      # 刪除使用者

HTTP 狀態碼

正確使用 HTTP 狀態碼：

• 200 OK：成功
• 201 Created：資源已建立
• 400 Bad Request：請求錯誤
• 404 Not Found：資源不存在
• 500 Internal Server Error：伺服器錯誤

版本控制

API 版本控制很重要：

/api/v1/users
/api/v2/users

分頁和過濾

提供分頁和過濾功能：

GET /api/users?page=1&limit=10&sort=name&filter=active

錯誤處理

統一的錯誤回應格式：

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "User with ID 123 does not exist"
  }
}

安全性

• 使用 HTTPS
• 實作身份驗證和授權
• 驗證輸入資料
• 防止 SQL 注入和 XSS

遵循這些原則，設計出易用、安全且可維護的 API。