Drama Ling API 規格文檔
📋 總覽
Drama Ling 應用的完整 RESTful API 規格文檔，採用模組化設計便於維護和擴展。
🏗️ API 架構
Base URL
Production: https://api.dramaling.com
Staging: https://staging-api.dramaling.com
Development: https://dev-api.dramaling.com
版本控制
所有 API 端點使用 /api/v1/ 前綴進行版本控制。
📚 模組文檔導航
🔐 核心認證與用戶
🎓 學習核心功能
🎮 遊戲化與競爭
💳 商業功能
🏆 進階功能
⚙️ 系統支援
🔧 API 設計原則
RESTful 標準
- ✅ 資源導向的URL設計
- ✅ 標準HTTP動詞 (GET, POST, PUT, DELETE, PATCH)
- ✅ 統一的HTTP狀態碼
- ✅ 無狀態設計
- ✅ 版本控制策略
安全原則
- ✅ JWT Token認證
- ✅ Role-based權限控制
- ✅ 嚴格資料驗證
- ✅ API速率限制
- ✅ 強制HTTPS傳輸
回應格式
所有API使用統一的JSON回應格式：
{
"success": boolean,
"data": object | array | null,
"message": string,
"error": {
"code": "ERROR_CODE",
"message": "錯誤描述",
"details": {}
},
"meta": {
"timestamp": "2024-09-07T12:00:00Z",
"request_id": "uuid-string",
"pagination": {}
}
}
📈 API 統計
整體規模
- 總端點數量: 78個API端點
- 功能模組: 10個主要模組
- 錯誤類別: 11種錯誤類型
- 文檔行數: ~2,400行 → 分拆為10個文件
開發狀態
- ✅ 已完成: 7個核心模組 (認證、用戶、對話、訂閱、任務、錯誤、共通) (70%)
- 🔄 進行中: 剩餘4個模組拆分 (遊戲化、語言程度、詞彙、學習內容) (25%)
- ⏳ 待優化: API詳細範例和整合測試 (5%)
🚀 快速開始
1. 認證流程
# 用戶註冊
POST /api/v1/auth/register
# 用戶登入取得Token
POST /api/v1/auth/login
# 使用Token存取API
GET /api/v1/user/profile
Authorization: Bearer <access_token>
2. 常用API範例
- 取得學習統計：
GET /api/v1/user/learning-stats
- 開始對話練習：
POST /api/v1/dialogues/start
- 獲取今日任務：
GET /api/v1/missions/today
- 檢查訂閱狀態：
GET /api/v1/subscriptions/status
📖 相關文檔
技術文檔
開發計劃
🤝 貢獻指南
文檔維護
- 每個模組文件維持在200-400行
- 所有API端點需要完整範例
- 錯誤情境需要詳細說明
- 定期同步更新相關文檔
版本更新
- API變更需要版本控制
- 向後相容性考量
- 廢棄API提前通知機制
文件版本: v2.0 (模組化重構)
最後更新: 2024年9月7日
維護負責: 技術團隊
下次審查: 每月第一週檢討更新