mkt.ose.tw/docs/backend/API_CONTRACT_MASTER.md

API Contract Master

目標

固定 v1 對外契約，避免前後端與 SDK 在開發中漂移。

參數必填/可選與路由實際狀態，請優先看： PYTHON_API_PARAMETER_GUIDE.md

這輪契約調整（2026-03-22）

• experiment_key 改為系統生成（EX+timestamp），不接受使用者輸入。
• variant_key 改為系統生成（VA+timestamp），不接受使用者輸入。
• Variant 不再暴露 status、is_control 作為使用者可編輯欄位。
• variant_changes 移除 enabled 欄位（每筆 change 預設啟用）。
• 建立 Experiment API 成功時，需同步建立一個原始版本 Variant（系統管理）。
• Runtime 實驗匹配需基於 URL 規則與裝置限制。
• Release rollback 僅允許針對 published 版本，且操作後需維持「每個 experiment 僅一個 published」。

分區

• Admin API
• Editor API
• Runtime API

Admin API（v1）

Sites

• GET /api/admin/sites
• GET /api/admin/sites/{site_id}

Experiments

• GET /api/admin/experiments
• GET /api/admin/experiments/{experiment_id}
• POST /api/admin/experiments
• PATCH /api/admin/experiments/{experiment_id}
• GET /api/admin/experiments/{experiment_id}/activity

POST/PATCH /api/admin/experiments 使用者輸入重點：

• name
• module_type
• status
• targeting_config.url_rules
• targeting_config.device_targets

使用者不輸入：

• experiment_key（系統生成）

Variants

• GET /api/admin/variants/{variant_id}
• GET /api/admin/variants?experiment_id=...
• POST /api/admin/variants
• PATCH /api/admin/variants/{variant_id}

POST/PATCH /api/admin/variants 使用者輸入重點：

• name
• traffic_weight

使用者不輸入：

• variant_key（系統生成）
• status
• is_control

Releases

• GET /api/admin/releases?experiment_id=...
• GET /api/admin/releases/{release_id}
• POST /api/admin/releases/build
• POST /api/admin/releases/{release_id}/publish
• POST /api/admin/releases/{release_id}/rollback
• POST /api/admin/releases/{release_id}/archive

Goals / SDK Config

• GET /api/admin/goals
• GET /api/admin/goals/{goal_id}
• GET /api/admin/sdk-configs
• GET /api/admin/sdk-configs/{sdk_config_id}

Editor API（v1）

• POST /api/editor/sessions
• GET /api/editor/sessions/{session_id}
• PATCH /api/editor/sessions/{session_id}
• DELETE /api/editor/sessions/{session_id}
• GET /api/editor/variants/{variant_id}/changes
• PUT /api/editor/variants/{variant_id}/changes
• POST /api/editor/previews/build

PUT /api/editor/variants/{variant_id}/changes：

• change 欄位不含 enabled
• change 是否生效由是否存在於 change set 決定

Runtime API（v1）

• POST /api/runtime/bootstrap
• POST /api/runtime/assign
• POST /api/runtime/payload
• POST /api/runtime/events/impression
• POST /api/runtime/events/conversion

契約原則

• 所有 API 回傳統一 DTO，不回傳 Directus raw item
• editor 專用 DTO 與 runtime 專用 DTO 分離
• breaking change 需升 API 版本
• 對外 C/U/D 一律經 FastAPI，禁止 frontend 直接對 Directus 做新業務寫入