jettcheng1018
/
dramaling-app
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
dramaling-app/docs/04_technical/api/common.md

7.0 KiB
Raw Blame History

API 共通規範

📋 概述

所有 Drama Ling API 共用的設計原則、資料格式、安全規範等。

🏗️ RESTful 設計標準

✅ 已實施的設計標準

  • 資源導向: API端點基於資源設計而非動作
  • HTTP動詞: 正確使用GET、POST、PUT、DELETE、PATCH
  • 狀態碼: 使用標準HTTP狀態碼表示結果
  • 無狀態: API設計為無狀態，不依賴server端session
  • 版本控制: API版本控制策略 (使用 /api/v1/)

HTTP 動詞使用規範

動詞 用途 範例
GET 讀取資源 GET /api/v1/users/profile
POST 創建資源 POST /api/v1/auth/login
PUT 完整更新資源 PUT /api/v1/users/profile
PATCH 部分更新資源 PATCH /api/v1/users/preferences
DELETE 刪除資源 DELETE /api/v1/users/account

HTTP 狀態碼標準

狀態碼 含義 使用場景
200 OK 請求成功
201 Created 資源創建成功
204 No Content 成功但無回應內容
400 Bad Request 請求格式錯誤
401 Unauthorized 未認證或Token無效
403 Forbidden 無權限存取
404 Not Found 資源不存在
409 Conflict 資源衝突
422 Unprocessable Entity 資料驗證失敗
429 Too Many Requests 請求頻率超限
500 Internal Server Error 伺服器內部錯誤

📦 統一回應格式

成功回應格式

{
  "success": true,
  "data": {
    // 回應資料內容
  },
  "message": "操作成功描述",
  "meta": {
    "timestamp": "2024-09-07T12:00:00Z",
    "request_id": "req_550e8400-e29b-41d4-a716-446655440000",
    "api_version": "v1",
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_items": 89,
      "items_per_page": 20
    }
  }
}

錯誤回應格式

{
  "success": false,
  "data": null,
  "message": "操作失敗描述",
  "error": {
    "code": "SPECIFIC_ERROR_CODE",
    "message": "詳細錯誤訊息",
    "details": {
      "field": "username",
      "reason": "Username already exists",
      "suggestion": "Please choose a different username"
    }
  },
  "meta": {
    "timestamp": "2024-09-07T12:00:00Z",
    "request_id": "req_550e8400-e29b-41d4-a716-446655440000",
    "api_version": "v1"
  }
}

分頁回應格式

{
  "success": true,
  "data": {
    "items": [
      // 資料陣列
    ]
  },
  "meta": {
    "pagination": {
      "current_page": 2,
      "total_pages": 10,
      "total_items": 195,
      "items_per_page": 20,
      "has_next": true,
      "has_prev": true,
      "next_url": "/api/v1/resource?page=3&limit=20",
      "prev_url": "/api/v1/resource?page=1&limit=20"
    }
  }
}

🔒 API 安全原則

✅ 已實施的安全措施

  • 身份驗證: JWT Token認證機制
  • 授權控制: Role-based權限控制
  • 資料驗證: 嚴格的輸入資料驗證
  • 速率限制: 防止API濫用的速率控制
  • HTTPS強制: 所有API強制使用HTTPS

JWT Token 認證

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

API Key 認證 (內部服務)

X-API-Key: api_key_here
X-Client-ID: client_id_here

速率限制

用戶類型 限制 窗口
免費用戶 100 請求 每小時
訂閱用戶 500 請求 每小時
API 金鑰 1000 請求 每小時

📅 版本控制策略

URL 版本控制

  • 格式: /api/v1/, /api/v2/
  • 向後相容: 新版本保持向後相容性
  • 廢棄通知: 提前6個月通知API廢棄
  • 多版本支援: 同時支援2-3個版本
  • 版本文檔: 每個版本維護獨立文檔

版本生命週期

v1.0 (穩定版) ──── v1.1 (向下相容更新)
 │                  │
 └─ v2.0 (重大變更) ──── v2.1 (向下相容更新)

🌍 國際化支援

語言標頭

Accept-Language: zh-TW, en-US;q=0.8

時區處理

X-Timezone: Asia/Taipei

日期時間格式

  • 標準: ISO 8601 格式 (2024-09-07T12:00:00Z)
  • 時區: 統一使用UTC，客戶端負責本地化

📊 效能考量

✅ 已實施的效能優化

  • 回應時間: 95%的API請求在200ms內回應
  • 快取策略: 靜態內容使用CDN，動態內容使用Redis
  • 資料庫優化: 適當的索引和查詢優化
  • 負載平衡: 水平擴展API服務器
  • 監控告警: API效能和錯誤率監控

快取標頭

Cache-Control: max-age=300, must-revalidate
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Last-Modified: Wed, 07 Sep 2024 12:00:00 GMT

壓縮支援

Accept-Encoding: gzip, deflate, br
Content-Encoding: gzip

🔍 請求追蹤

請求識別

每個 API 請求都會分配唯一的請求 ID：

X-Request-ID: req_550e8400-e29b-41d4-a716-446655440000

除錯標頭

X-Debug-Mode: true
X-Correlation-ID: corr_12345

📋 資料驗證規則

通用驗證規則

  • Email: RFC 5322 標準
  • Password: 最少8位，包含大小寫字母和數字
  • Username: 3-20字元，僅允許字母數字和底線
  • URL: 有效的HTTP/HTTPS URL
  • UUID: 標準UUID格式

輸入清理

  • XSS 防護: 自動清理HTML標籤
  • SQL 注入防護: 參數化查詢
  • 檔案上傳: 類型和大小限制
  • JSON 深度: 最大巢狀層級限制

🚦 API 狀態監控

健康檢查端點

GET /health

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-09-07T12:00:00Z",
  "checks": {
    "database": "healthy",
    "redis": "healthy",
    "external_apis": "healthy"
  }
}

服務狀態

GET /api/v1/status
Authorization: Bearer <access_token>

{
  "api_status": "operational",
  "maintenance_mode": false,
  "rate_limit_remaining": 450,
  "rate_limit_reset": "2024-09-07T13:00:00Z"
}

📝 請求範例

標準 GET 請求

curl -X GET "https://api.dramaling.com/api/v1/users/profile" \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json" \
  -H "Accept-Language: zh-TW"

標準 POST 請求

curl -X POST "https://api.dramaling.com/api/v1/dialogues/start" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"scenario_id": "restaurant_order"}'

檔案上傳請求

curl -X POST "https://api.dramaling.com/api/v1/users/avatar" \
  -H "Authorization: Bearer <access_token>" \
  -F "avatar=@/path/to/image.jpg"

🔧 開發工具

Swagger/OpenAPI 文檔

Postman Collection

  • 檔案: dramaling-api.postman_collection.json
  • 環境變數: 開發/測試/生產環境設定
  • 自動化測試: API 回歸測試套件

負責人: 技術架構團隊
最後更新: 2024年9月7日
相關文檔: 錯誤處理, 認證API