23 KiB
23 KiB
API 規格文檔
概述
定義 Drama Ling 應用的完整 RESTful API 規格,基於 system_structure_design.json 中定義的14個功能特性和9個數據源設計。
API 設計原則
RESTful 設計標準
- 資源導向: API端點基於資源設計而非動作
- HTTP動詞: 正確使用GET、POST、PUT、DELETE、PATCH
- 狀態碼: 使用標準HTTP狀態碼表示結果
- 無狀態: API設計為無狀態,不依賴server端session
- 版本控制: API版本控制策略 (如
/api/v1/)
API 安全原則
- 身份驗證: JWT Token認證機制
- 授權控制: Role-based權限控制
- 資料驗證: 嚴格的輸入資料驗證
- 速率限制: 防止API濫用的速率控制
- HTTPS強制: 所有API強制使用HTTPS
回應格式標準
{
"success": boolean,
"data": object | array | null,
"message": string,
"error": {
"code": string,
"message": string,
"details": object
},
"meta": {
"timestamp": "ISO8601",
"request_id": "string",
"pagination": object
}
}
認證與授權 API
用戶認證
POST /api/v1/auth/register
Content-Type: application/json
{
"email": "user@example.com",
"password": "securePassword123",
"username": "dramatic_learner",
"preferredLanguage": "en",
"nativeLanguage": "zh-TW"
}
Response 201 Created
{
"success": true,
"data": {
"userId": "550e8400-e29b-41d4-a716-446655440000",
"username": "dramatic_learner",
"email": "user@example.com",
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "550e8400-e29b-41d4-a716-446655440001",
"expiresIn": 3600
},
"message": "User registered successfully",
"meta": {
"timestamp": "2024-09-05T15:30:00Z",
"requestId": "550e8400-e29b-41d4-a716-446655440002"
}
}
登入驗證
POST /api/v1/auth/login
{
"email": "user@example.com",
"password": "securePassword123"
}
Token 更新
POST /api/v1/auth/refresh
Authorization: Bearer <refresh_token>
登出
POST /api/v1/auth/logout
Authorization: Bearer <access_token>
用戶資料管理 API
用戶資料 (UserProfile)
獲取用戶資料
GET /api/v1/users/profile
Authorization: Bearer <access_token>
Response 200 OK
{
"success": true,
"data": {
"user_id": "USR_12345",
"username": "dramatic_learner",
"email": "user@example.com",
"avatar_url": "https://cdn.example.com/avatars/12345.jpg",
"level": "B1",
"total_score": 15680,
"streak_days": 15,
"joined_date": "2024-01-15T08:00:00Z",
"last_active": "2024-09-05T14:30:00Z",
"preferences": {
"target_language": "en",
"native_language": "zh-TW",
"difficulty_preference": "adaptive",
"daily_goal_minutes": 30,
"notifications_enabled": true,
"theme": "light"
},
"subscription": {
"plan": "premium",
"status": "active",
"expires_at": "2025-01-15T08:00:00Z"
}
}
}
更新用戶資料
PUT /api/v1/users/profile
Authorization: Bearer <access_token>
{
"username": "new_username",
"avatar_url": "https://cdn.example.com/avatars/new_avatar.jpg",
"preferences": {
"daily_goal_minutes": 45,
"notifications_enabled": false
}
}
用戶學習統計
GET /api/v1/users/stats
Authorization: Bearer <access_token>
Response 200 OK
{
"success": true,
"data": {
"total_dialogues": 245,
"total_study_time": 1280, // minutes
"vocabulary_learned": 890,
"vocabulary_mastered": 650,
"scenarios_completed": 35,
"achievements_unlocked": 18,
"current_streak": 15,
"longest_streak": 28,
"weekly_progress": {
"dialogues_this_week": 12,
"minutes_this_week": 180,
"goal_completion_rate": 0.85
}
}
}
學習內容 API
課程與場景 (Lesson)
獲取場景列表
GET /api/v1/lessons/scenarios
Authorization: Bearer <access_token>
Query Parameters:
- category: string (daily_life, social, emergency, professional)
- difficulty: string (A1, A2, B1, B2, C1, C2)
- limit: integer (default: 20)
- offset: integer (default: 0)
Response 200 OK
{
"success": true,
"data": {
"scenarios": [
{
"scenario_id": "SC_Restaurant_01",
"title": "餐廳訂位",
"description": "學習如何在餐廳預約座位和點餐",
"category": "daily_life",
"difficulty": "A2",
"estimated_duration": 8, // minutes
"thumbnail_url": "https://cdn.example.com/scenarios/restaurant.jpg",
"vocabulary_count": 25,
"completion_rate": 0.75,
"user_completed": true,
"user_score": 85,
"unlock_condition": null,
"is_premium": false
}
],
"pagination": {
"total": 65,
"page": 1,
"per_page": 20,
"total_pages": 4
}
}
}
獲取場景詳情
GET /api/v1/lessons/scenarios/{scenario_id}
Authorization: Bearer <access_token>
Response 200 OK
{
"success": true,
"data": {
"scenario_id": "SC_Restaurant_01",
"title": "餐廳訂位",
"description": "學習如何在餐廳預約座位和點餐",
"category": "daily_life",
"difficulty": "A2",
"learning_objectives": [
"學會預約餐廳座位",
"掌握點餐相關詞彙",
"練習詢問食材和偏好"
],
"target_vocabulary": [
{
"word": "reservation",
"phonetic": "/ˌrezəˈveɪʃən/",
"translation": "預約",
"definition": "an arrangement to have something kept for you"
}
],
"cultural_notes": "西式餐廳通常需要事先預約,特別是在熱門時段...",
"estimated_duration": 8,
"prerequisite_scenarios": ["SC_Greeting_01"],
"user_progress": {
"completed": true,
"best_score": 85,
"completion_count": 3,
"last_completed": "2024-09-03T19:20:00Z"
}
}
}
詞彙管理 API
獲取詞彙列表
GET /api/v1/vocabulary
Authorization: Bearer <access_token>
Query Parameters:
- category: string (life, academic, business, etc.)
- difficulty: string (A1-C2)
- mastery_level: string (learning, practicing, mastered)
- limit: integer (default: 50)
Response 200 OK
{
"success": true,
"data": {
"vocabulary": [
{
"vocab_id": "VOC_0001",
"word": "restaurant",
"phonetic": "/ˈrestərɑːnt/",
"part_of_speech": "noun",
"definition": "A place where people pay to sit and eat meals",
"translation": "餐廳",
"difficulty": "A2",
"frequency_rank": 1250,
"user_mastery": {
"level": "practicing", // learning, practicing, mastered
"score": 75,
"review_count": 5,
"last_reviewed": "2024-09-03T10:15:00Z",
"next_review": "2024-09-07T10:15:00Z"
},
"example_sentences": [
{
"english": "We made a reservation at the new restaurant.",
"chinese": "我們在新餐廳訂了位。"
}
]
}
]
}
}
詞彙複習API
GET /api/v1/vocabulary/review/daily
Authorization: Bearer <access_token>
Response 200 OK
{
"success": true,
"data": {
"review_session_id": "REV_20240905_USR12345",
"total_words": 15,
"estimated_time": 5, // minutes
"words": [
{
"vocab_id": "VOC_0001",
"word": "restaurant",
"review_type": "recognition", // recognition, recall, spelling
"options": ["餐廳", "旅館", "商店", "學校"] // for recognition type
}
]
}
}
提交複習結果
POST /api/v1/vocabulary/review/submit
Authorization: Bearer <access_token>
{
"review_session_id": "REV_20240905_USR12345",
"results": [
{
"vocab_id": "VOC_0001",
"user_answer": "餐廳",
"is_correct": true,
"response_time": 2.5, // seconds
"confidence": 4 // 1-5 scale
}
]
}
對話練習 API
對話系統 (Dialogue)
開始對話練習
POST /api/v1/dialogues/start
Authorization: Bearer <access_token>
{
"scenario_id": "SC_Restaurant_01",
"difficulty_override": "A2", // optional
"target_vocabulary": ["reservation", "menu", "order"] // optional
}
Response 201 Created
{
"success": true,
"data": {
"dialogue_id": "DLG_20240905_001",
"scenario_id": "SC_Restaurant_01",
"session_token": "session_token_here",
"initial_context": {
"setting": "高級餐廳內部,晚上8點",
"your_role": "客人",
"ai_role": "餐廳服務員",
"objective": "成功預約並點餐"
},
"ai_message": {
"message": "Good evening! Welcome to Milano Restaurant. Do you have a reservation?",
"audio_url": "https://cdn.example.com/audio/dlg001_001.mp3",
"suggestions": [
"Yes, I have a reservation under Smith.",
"No, but could we get a table for two?",
"I'd like to make a reservation for tonight."
]
}
}
}
發送對話訊息
POST /api/v1/dialogues/{dialogue_id}/message
Authorization: Bearer <access_token>
{
"message": "Yes, I have a reservation under Chen for 8 PM.",
"message_type": "text", // text, audio
"audio_url": "https://cdn.example.com/user_audio/msg001.mp3" // if audio
}
Response 200 OK
{
"success": true,
"data": {
"ai_response": {
"message": "Perfect! Mr. Chen, your table for two is ready. Right this way please.",
"audio_url": "https://cdn.example.com/audio/dlg001_002.mp3",
"analysis": {
"grammar_score": 90,
"semantic_score": 95,
"fluency_score": 85,
"overall_score": 90,
"feedback": "Excellent use of formal language for restaurant context!"
},
"suggestions": [
"Thank you. Could we see the menu please?",
"Great! What do you recommend today?",
"Thank you. We'd like to start with drinks."
]
},
"dialogue_progress": {
"turns_completed": 2,
"estimated_turns_remaining": 6,
"objectives_completed": ["greeting", "reservation_confirmation"],
"objectives_remaining": ["ordering", "payment"]
}
}
}
獲取AI分析詳情
GET /api/v1/dialogues/{dialogue_id}/analysis
Authorization: Bearer <access_token>
Response 200 OK
{
"success": true,
"data": {
"dialogue_id": "DLG_20240905_001",
"overall_analysis": {
"grammar_score": 88,
"semantic_score": 92,
"fluency_score": 85,
"total_score": 88,
"completion_percentage": 100
},
"detailed_feedback": [
{
"turn_number": 1,
"user_message": "Yes, I have a reservation under Chen for 8 PM.",
"analysis": {
"grammar_issues": [],
"semantic_appropriateness": "Excellent - appropriate formality level",
"fluency_notes": "Natural and confident delivery",
"suggestions": [],
"vocabulary_used": [
{
"word": "reservation",
"usage_correctness": "perfect",
"context_appropriateness": "excellent"
}
]
}
}
],
"improvement_suggestions": [
"Consider using more varied vocabulary for ordering",
"Practice pronunciation of 'th' sounds"
],
"vocabulary_progress": {
"words_practiced": 8,
"words_used_correctly": 7,
"new_words_encountered": 3
}
}
}
結束對話
POST /api/v1/dialogues/{dialogue_id}/complete
Authorization: Bearer <access_token>
Response 200 OK
{
"success": true,
"data": {
"dialogue_summary": {
"dialogue_id": "DLG_20240905_001",
"duration": 420, // seconds
"turns_completed": 8,
"final_score": 88,
"objectives_achieved": 4,
"objectives_total": 4,
"vocabulary_practiced": 12,
"experience_gained": 150,
"score_gained": 75
},
"rewards": {
"experience_points": 150,
"score_points": 75,
"achievements_unlocked": ["First Perfect Dialogue"],
"vocabulary_progress": {
"words_advanced": 3,
"words_mastered": 1
}
}
}
}
任務系統 API
任務管理 (Task & TaskReward)
獲取可用任務
GET /api/v1/tasks
Authorization: Bearer <access_token>
Query Parameters:
- type: string (daily, weekly, achievement, challenge)
- status: string (available, in_progress, completed)
Response 200 OK
{
"success": true,
"data": {
"tasks": [
{
"task_id": "TASK_DAILY_001",
"type": "daily",
"title": "完成3次對話練習",
"description": "今天完成任意3次對話練習以獲得獎勵",
"objectives": [
{
"objective_id": "OBJ_001",
"description": "完成對話練習",
"target_value": 3,
"current_value": 1,
"unit": "次"
}
],
"rewards": {
"experience": 100,
"score": 50,
"special_items": ["daily_streak_bonus"]
},
"deadline": "2024-09-05T23:59:59Z",
"status": "in_progress",
"created_at": "2024-09-05T00:00:00Z"
}
]
}
}
獲取任務詳情
GET /api/v1/tasks/{task_id}
Authorization: Bearer <access_token>
Response 200 OK
{
"success": true,
"data": {
"task_id": "TASK_WEEKLY_001",
"type": "weekly",
"title": "週練習大師",
"description": "本週完成20次對話練習並達到平均85分",
"long_description": "挑戰自己在本週內完成20次高品質的對話練習...",
"objectives": [
{
"objective_id": "OBJ_001",
"description": "完成對話練習",
"target_value": 20,
"current_value": 8,
"unit": "次"
},
{
"objective_id": "OBJ_002",
"description": "平均分數達標",
"target_value": 85,
"current_value": 87.5,
"unit": "分"
}
],
"rewards": {
"experience": 500,
"score": 300,
"special_items": ["premium_scenario_unlock"],
"achievements": ["weekly_master"]
},
"progress_percentage": 40,
"deadline": "2024-09-08T23:59:59Z",
"difficulty": "medium"
}
}
領取任務獎勵
POST /api/v1/tasks/{task_id}/claim_reward
Authorization: Bearer <access_token>
Response 200 OK
{
"success": true,
"data": {
"rewards_claimed": {
"experience": 500,
"score": 300,
"special_items": ["premium_scenario_unlock"],
"achievements": ["weekly_master"]
},
"updated_user_stats": {
"total_experience": 15680,
"total_score": 8950,
"level": "B1+",
"achievements_count": 19
}
}
}
排行榜與競爭 API
排行榜系統 (Leaderboard)
獲取排行榜
GET /api/v1/leaderboard
Authorization: Bearer <access_token>
Query Parameters:
- type: string (global, weekly, friends, regional)
- category: string (overall, dialogue_count, vocabulary_mastered)
- limit: integer (default: 50)
Response 200 OK
{
"success": true,
"data": {
"leaderboard_type": "global",
"category": "overall",
"period": "all_time",
"updated_at": "2024-09-05T15:30:00Z",
"user_rank": {
"rank": 1247,
"score": 15680,
"percentile": 78.5
},
"top_users": [
{
"rank": 1,
"user_id": "USR_VIP_001",
"username": "LanguageMaster",
"avatar_url": "https://cdn.example.com/avatars/vip001.jpg",
"score": 45680,
"level": "C2",
"country": "TW",
"streak_days": 365,
"badges": ["yearly_champion", "perfectionist"]
}
],
"nearby_users": [
// Users around current user's rank
]
}
}
好友排行榜
GET /api/v1/leaderboard/friends
Authorization: Bearer <access_token>
Response 200 OK
{
"success": true,
"data": {
"friends_ranking": [
{
"rank": 1,
"user_id": "USR_12346",
"username": "StudyBuddy",
"avatar_url": "https://cdn.example.com/avatars/12346.jpg",
"score": 18950,
"level": "B2",
"status": "online",
"recent_activity": "完成了商務會議場景 - 2小時前"
}
],
"current_user": {
"rank": 3,
"score": 15680,
"score_difference": -3270, // difference from rank 1
"rank_change": 1 // compared to last week
}
}
}
訂閱與購買 API
訂閱管理 (Subscription)
獲取訂閱方案
GET /api/v1/subscriptions/plans
Authorization: Bearer <access_token>
Response 200 OK
{
"success": true,
"data": {
"plans": [
{
"plan_id": "PLAN_BASIC",
"name": "基礎版",
"description": "解鎖基礎功能,享受無廣告體驗",
"price": {
"monthly": {
"amount": 199,
"currency": "TWD",
"original_price": 199
},
"yearly": {
"amount": 1980,
"currency": "TWD",
"original_price": 2388,
"discount_percentage": 17
}
},
"features": [
"無限對話練習",
"無廣告體驗",
"基礎AI分析",
"雲端同步"
],
"limitations": [
"僅基礎和社交場景",
"不含語音識別"
]
}
],
"current_subscription": {
"plan_id": "PLAN_PREMIUM",
"status": "active",
"expires_at": "2025-01-15T08:00:00Z",
"auto_renewal": true,
"payment_method": "credit_card"
}
}
}
訂閱方案
POST /api/v1/subscriptions/subscribe
Authorization: Bearer <access_token>
{
"plan_id": "PLAN_PREMIUM",
"billing_cycle": "yearly", // monthly, yearly
"payment_method_id": "pm_1234567890",
"auto_renewal": true
}
Response 201 Created
{
"success": true,
"data": {
"subscription_id": "SUB_20240905_001",
"plan_id": "PLAN_PREMIUM",
"status": "active",
"started_at": "2024-09-05T15:30:00Z",
"expires_at": "2025-09-05T15:30:00Z",
"next_billing_date": "2025-09-05T15:30:00Z",
"amount_paid": 3999,
"currency": "TWD"
}
}
內購系統 (Purchase)
獲取付費內容
GET /api/v1/store/content
Authorization: Bearer <access_token>
Query Parameters:
- category: string (scenario_pack, expert_course, premium_content)
- price_range: string (0-100, 100-500, 500+)
Response 200 OK
{
"success": true,
"data": {
"content_packs": [
{
"content_id": "PACK_TRAVEL_001",
"type": "scenario_pack",
"title": "旅遊場景包",
"description": "包含機場、飯店、觀光等15個實用旅遊場景",
"price": {
"amount": 149,
"currency": "TWD",
"original_price": 199,
"discount_percentage": 25
},
"content_preview": {
"scenarios_count": 15,
"estimated_hours": 8,
"difficulty_range": "A2-B2",
"preview_scenario": "SC_AIRPORT_001"
},
"thumbnail_url": "https://cdn.example.com/packs/travel.jpg",
"user_owned": false,
"special_offer": {
"expires_at": "2024-09-10T23:59:59Z",
"offer_text": "限時75折優惠!"
}
}
]
}
}
購買內容
POST /api/v1/store/purchase
Authorization: Bearer <access_token>
{
"content_id": "PACK_TRAVEL_001",
"payment_method_id": "pm_1234567890"
}
Response 201 Created
{
"success": true,
"data": {
"purchase_id": "PUR_20240905_001",
"content_id": "PACK_TRAVEL_001",
"amount_paid": 149,
"currency": "TWD",
"purchased_at": "2024-09-05T15:45:00Z",
"content_unlocked": {
"scenarios": ["SC_AIRPORT_001", "SC_HOTEL_001", "..."],
"access_expires": null // permanent access
}
}
}
廣告系統 (AdImpression)
獲取廣告獎勵機會
GET /api/v1/ads/opportunities
Authorization: Bearer <access_token>
Response 200 OK
{
"success": true,
"data": {
"available_ads": [
{
"ad_id": "AD_REWARD_001",
"type": "video",
"duration": 30, // seconds
"reward": {
"type": "extra_dialogue",
"quantity": 2,
"description": "額外2次對話練習機會"
},
"cooldown_remaining": 0, // seconds until next ad
"daily_limit_remaining": 3
}
]
}
}
觀看廣告獲得獎勵
POST /api/v1/ads/watch
Authorization: Bearer <access_token>
{
"ad_id": "AD_REWARD_001",
"watch_duration": 30, // seconds actually watched
"completion_status": "completed" // completed, skipped, error
}
Response 200 OK
{
"success": true,
"data": {
"reward_granted": {
"type": "extra_dialogue",
"quantity": 2,
"expires_at": "2024-09-06T15:45:00Z"
},
"next_ad_available_at": "2024-09-05T16:15:00Z"
}
}
錯誤處理
標準錯誤碼
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "輸入資料驗證失敗",
"details": {
"field": "email",
"reason": "invalid_format"
}
}
}
常見錯誤碼
UNAUTHORIZED(401): 未授權存取FORBIDDEN(403): 權限不足NOT_FOUND(404): 資源不存在VALIDATION_ERROR(400): 資料驗證失敗RATE_LIMIT_EXCEEDED(429): 超過速率限制INTERNAL_SERVER_ERROR(500): 伺服器內部錯誤SERVICE_UNAVAILABLE(503): 服務暫時不可用
訂閱相關錯誤
SUBSCRIPTION_REQUIRED: 需要訂閱才能存取SUBSCRIPTION_EXPIRED: 訂閱已過期PAYMENT_FAILED: 付款處理失敗CONTENT_NOT_PURCHASED: 內容未購買
API 版本控制與部署
版本控制策略
- URL版本控制:
/api/v1/,/api/v2/ - 向後相容: 新版本保持向後相容性
- 廢棄通知: 提前6個月通知API廢棄
- 多版本支援: 同時支援2-3個版本
- 版本文檔: 每個版本維護獨立文檔
環境配置
# 開發環境
API_BASE_URL=https://dev-api.dramaling.com
API_VERSION=v1
# 測試環境
API_BASE_URL=https://staging-api.dramaling.com
API_VERSION=v1
# 生產環境
API_BASE_URL=https://api.dramaling.com
API_VERSION=v1
效能考量
- 回應時間: 95%的API請求在200ms內回應
- 快取策略: 靜態內容使用CDN,動態內容使用Redis
- 資料庫優化: 適當的索引和查詢優化
- 負載平衡: 水平擴展API服務器
- 監控告警: API效能和錯誤率監控
待完成任務
高優先級
- 完善所有API端點的詳細規格和範例
- 設計API的認證和授權機制
- 建立API文檔的自動生成和維護流程
- 實現API的錯誤處理和驗證邏輯
中優先級
- 設計API的快取和效能優化策略
- 建立API的測試套件和自動化測試
- 規劃API的版本控制和遷移策略
- 設計API的監控和分析系統
低優先級
- 研究GraphQL作為REST API的補充
- 探索Real-time API (WebSocket) 的應用場景
- 建立API的開發者工具和SDK
- 設計第三方整合的API授權機制
最後更新: 2024年9月5日
負責人: 待分配
審查週期: 每兩週檢討一次