297 lines
7.0 KiB
Markdown
297 lines
7.0 KiB
Markdown
# 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 | 伺服器內部錯誤 |
|
||
|
||
## 📦 統一回應格式
|
||
|
||
### 成功回應格式
|
||
```json
|
||
{
|
||
"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
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 錯誤回應格式
|
||
```json
|
||
{
|
||
"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"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 分頁回應格式
|
||
```json
|
||
{
|
||
"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 認證
|
||
```http
|
||
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||
```
|
||
|
||
### API Key 認證 (內部服務)
|
||
```http
|
||
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 (向下相容更新)
|
||
```
|
||
|
||
## 🌍 國際化支援
|
||
|
||
### 語言標頭
|
||
```http
|
||
Accept-Language: zh-TW, en-US;q=0.8
|
||
```
|
||
|
||
### 時區處理
|
||
```http
|
||
X-Timezone: Asia/Taipei
|
||
```
|
||
|
||
### 日期時間格式
|
||
- **標準**: ISO 8601 格式 (`2024-09-07T12:00:00Z`)
|
||
- **時區**: 統一使用UTC，客戶端負責本地化
|
||
|
||
## 📊 效能考量
|
||
|
||
### ✅ 已實施的效能優化
|
||
- **回應時間**: 95%的API請求在200ms內回應
|
||
- **快取策略**: 靜態內容使用CDN，動態內容使用Redis
|
||
- **資料庫優化**: 適當的索引和查詢優化
|
||
- **負載平衡**: 水平擴展API服務器
|
||
- **監控告警**: API效能和錯誤率監控
|
||
|
||
### 快取標頭
|
||
```http
|
||
Cache-Control: max-age=300, must-revalidate
|
||
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
|
||
Last-Modified: Wed, 07 Sep 2024 12:00:00 GMT
|
||
```
|
||
|
||
### 壓縮支援
|
||
```http
|
||
Accept-Encoding: gzip, deflate, br
|
||
Content-Encoding: gzip
|
||
```
|
||
|
||
## 🔍 請求追蹤
|
||
|
||
### 請求識別
|
||
每個 API 請求都會分配唯一的請求 ID：
|
||
```http
|
||
X-Request-ID: req_550e8400-e29b-41d4-a716-446655440000
|
||
```
|
||
|
||
### 除錯標頭
|
||
```http
|
||
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 狀態監控
|
||
|
||
### 健康檢查端點
|
||
```http
|
||
GET /health
|
||
```
|
||
|
||
```json
|
||
{
|
||
"status": "healthy",
|
||
"version": "1.0.0",
|
||
"timestamp": "2024-09-07T12:00:00Z",
|
||
"checks": {
|
||
"database": "healthy",
|
||
"redis": "healthy",
|
||
"external_apis": "healthy"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 服務狀態
|
||
```http
|
||
GET /api/v1/status
|
||
Authorization: Bearer <access_token>
|
||
```
|
||
|
||
```json
|
||
{
|
||
"api_status": "operational",
|
||
"maintenance_mode": false,
|
||
"rate_limit_remaining": 450,
|
||
"rate_limit_reset": "2024-09-07T13:00:00Z"
|
||
}
|
||
```
|
||
|
||
## 📝 請求範例
|
||
|
||
### 標準 GET 請求
|
||
```bash
|
||
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 請求
|
||
```bash
|
||
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"}'
|
||
```
|
||
|
||
### 檔案上傳請求
|
||
```bash
|
||
curl -X POST "https://api.dramaling.com/api/v1/users/avatar" \
|
||
-H "Authorization: Bearer <access_token>" \
|
||
-F "avatar=@/path/to/image.jpg"
|
||
```
|
||
|
||
## 🔧 開發工具
|
||
|
||
### Swagger/OpenAPI 文檔
|
||
- **URL**: https://api.dramaling.com/docs
|
||
- **互動測試**: 支援直接在文檔中測試API
|
||
- **Schema 驗證**: 自動驗證請求和回應格式
|
||
|
||
### Postman Collection
|
||
- **檔案**: `dramaling-api.postman_collection.json`
|
||
- **環境變數**: 開發/測試/生產環境設定
|
||
- **自動化測試**: API 回歸測試套件
|
||
|
||
---
|
||
|
||
**負責人**: 技術架構團隊
|
||
**最後更新**: 2024年9月7日
|
||
**相關文檔**: [錯誤處理](./errors.md), [認證API](./authentication.md) |