# 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)