RESTful API 規格參考指南

什麼是 RESTful API？

REST（Representational State Transfer）是一種軟體架構風格，用於設計網路服務。RESTful API 遵循 REST 原則，提供一致且直觀的方式來操作資源。

核心原則核心原則

統一介面（Uniform Interface）
所有資源都通過統一的介面進行操作，使用標準的 HTTP 方法。

無狀態（Stateless）
每個請求都包含處理該請求所需的所有資訊，伺服器不保存客戶端狀態。

可快取（Cacheable）
回應應該明確標示是否可以快取，以提高效能。

分層系統（Layered System）
客戶端無法判斷是直接連接到終端伺服器，還是連接到中間層。

HTTP 方法對應

HTTP 方法	用途	範例 URL	說明
GET	讀取資源	GET /users	獲取所有用戶
GET	讀取單一資源	GET /users/123	獲取 ID 為 123 的用戶
POST	創建資源	POST /users	創建新用戶
PUT	完整更新資源	PUT /users/123	完整更新用戶 123
PATCH	部分更新資源	PATCH /users/123	部分更新用戶 123
DELETE	刪除資源	DELETE /users/123	刪除用戶 123

URL 設計規範

使用名詞，不用動詞

✅ 正確：GET /users
❌ 錯誤：GET /getUsers

使用複數形式

✅ 正確：/users, /products, /orders
❌ 錯誤：/user, /product, /order

階層關係表示

GET /users/123/orders # 獲取用戶 123 的所有訂單
GET /users/123/orders/456 # 獲取用戶 123 的訂單 456

查詢參數用於篩選和分頁

GET /users?page=2&limit=10&status=active
GET /products?category=electronics&sort=price&order=desc

HTTP 狀態碼

成功回應 (2xx)

• 200 OK – 請求成功
• 201 Created – 資源創建成功
• 204 No Content – 請求成功但無回應內容（通常用於 DELETE）

客戶端錯誤 (4xx)

• 400 Bad Request – 請求語法錯誤
• 401 Unauthorized – 需要驗證
• 403 Forbidden – 禁止訪問
• 404 Not Found – 資源不存在
• 405 Method Not Allowed – HTTP 方法不被允許
• 422 Unprocessable Entity – 請求格式正確但語義錯誤

伺服器錯誤 (5xx)

• 500 Internal Server Error – 伺服器內部錯誤
• 502 Bad Gateway – 網關錯誤
• 503 Service Unavailable – 服務暫時無法使用

回應格式規範

成功回應範例

{
    "success": true,
    "data": {
        "id": 123,
        "name": "John Doe",
        "email": "john@example.com"
    },
    "message": "User retrieved successfully"
}

錯誤回應範例

{
    "success": false,
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Email is required",
        "details": {
            "field": "email",
            "value": null
        }
    }
}

列表回應範例

{
    "success": true,
    "data": [
        {"id": 1, "name": "User 1"},
        {"id": 2, "name": "User 2"}
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 10,
        "total": 100,
        "total_pages": 10
    }
}

版本控制

URL 路徑版本控制

GET /v1/users
GET /v2/users

Header 版本控制

GET /users
Accept: application/vnd.api+json;version=1

認證與授權

Bearer Token

Authorization: Bearer your_access_token_here

API Key

X-API-Key: your_api_key_here

最佳實踐

使用 HTTPS
所有 API 端點都應該使用 HTTPS 來確保資料傳輸安全。

提供清楚的錯誤訊息
錯誤回應應該包含足夠的資訊讓開發者理解問題所在。

實作速率限制

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

使用適當的 Content-Type

Content-Type: application/json
Content-Type: application/xml

支援 CORS

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization

常見 API 端點範例

# 用戶管理
GET    /users           # 獲取用戶列表
POST   /users           # 創建新用戶
GET    /users/{id}      # 獲取特定用戶
PUT    /users/{id}      # 更新用戶
DELETE /users/{id}      # 刪除用戶

# 文章管理
GET    /posts           # 獲取文章列表
POST   /posts           # 創建新文章
GET    /posts/{id}      # 獲取特定文章
PUT    /posts/{id}      # 更新文章
DELETE /posts/{id}      # 刪除文章

# 巢狀資源
GET    /users/{id}/posts        # 獲取用戶的文章
POST   /users/{id}/posts        # 為用戶創建文章
GET    /posts/{id}/comments     # 獲取文章的評論