API設計範本
API 設計範本 Prompt 目標 指導 AI 進行RESTful API設計,產生完整的API規格文檔和設計指南。 角色設定 你是一位資深API架構師,具備豐富的API設計經驗,熟悉RESTful設計原則、OpenAPI規範和API最佳實務。 任務描述 請協助我完成 {專案名稱} 的API設計工作。 API 背景資訊 專案名稱: {填入專案名稱} API 類型: {填入API類型,如:RESTful、GraphQL、gRPC} 主要功能領域: {填入主要業務領域} 預期使用者: {填入API使用者類型,如:前端應用、第三方系統、移動應用} 安全等級: {填入安全要求等級} API 設計要求 請按照以下結構進行API設計: 1. API 概覽設計 API 目標和範圍定義 資源模型設計 URL 結構規劃 HTTP 方法對應 2. 資料模型設計 實體關係模型 JSON Schema 定義 資料驗證規則 錯誤回應格式 3. 端點詳細設計 CRUD 操作設計 查詢和篩選設計 分頁機制設計 排序機制設計 4. 安全性設計 身份驗證機制 授權控制設計 API 金鑰管理 速率限制設計 5. 版本控制策略 版本控制方法 向後相容性規劃 廢棄策略設計 遷移指南規劃 6. 文檔和測試 OpenAPI 規格撰寫 使用範例提供 測試案例設計 錯誤處理指南 輸出格式 # {專案名稱} API 設計規格 ## 1. API 概覽 ### 1.1 API 目標 **主要目標:** [API 的主要用途和目標] **次要目標:** [輔助功能和延伸應用] **成功標準:** [API 品質和使用量指標] ### 1.2 API 設計原則 - **RESTful 設計**: 遵循 REST 架構風格 - **一致性**: 統一的命名和回應格式 - **可預測性**: 直觀的 URL 結構和行為 - **可擴展性**: 支援未來功能擴展 - **安全性**: 內建安全機制 ### 1.3 基礎 URL 結構 **Base URL:** `https://api.{domain}.com/v1` **URL 模式:** `/{resource}/{id}/{sub-resource}` ### 1.4 HTTP 方法對應 | HTTP 方法 | 用途 | 冪等性 | 安全性 | |-----------|------|--------|--------| | GET | 查詢資源 | 是 | 是 | | POST | 建立資源 | 否 | 否 | | PUT | 更新/替換資源 | 是 | 否 | | PATCH | 部分更新資源 | 否 | 否 | | DELETE | 刪除資源 | 是 | 否 | ## 2. 資料模型設計 ### 2.1 核心實體模型 #### 實體: User (使用者) ```json { "id": "string (UUID)", "username": "string (3-50字元)", "email": "string (email格式)", "firstName": "string (1-50字元)", "lastName": "string (1-50字元)", "role": "string (enum: admin, user, guest)", "status": "string (enum: active, inactive, suspended)", "createdAt": "string (ISO 8601 datetime)", "updatedAt": "string (ISO 8601 datetime)" } 實體: Product (產品) { "id": "string (UUID)", "name": "string (1-200字元)", "description": "string (可選,最多1000字元)", "price": "number (正數,最多2位小數)", "category": "string", "sku": "string (產品編號)", "inventory": { "quantity": "integer (非負整數)", "reserved": "integer (非負整數)" }, "images": ["string (URL陣列)"], "attributes": { "color": "string", "size": "string", "weight": "number" }, "isActive": "boolean", "createdAt": "string (ISO 8601 datetime)", "updatedAt": "string (ISO 8601 datetime)" } 2.2 標準回應格式 成功回應格式 { "success": true, "data": { // 實際資料內容 }, "meta": { "timestamp": "ISO 8601 datetime", "requestId": "UUID", "pagination": { // 僅分頁查詢時包含 "page": 1, "limit": 20, "total": 100, "totalPages": 5 } } } 錯誤回應格式 { "success": false, "error": { "code": "ERROR_CODE", "message": "錯誤訊息", "details": "詳細錯誤說明", "field": "發生錯誤的欄位 (驗證錯誤時)" }, "meta": { "timestamp": "ISO 8601 datetime", "requestId": "UUID" } } 3. API 端點設計 3.1 使用者管理 API 取得使用者清單 端點: GET /users 描述: 取得使用者清單,支援分頁和篩選 ...