API Endpoints & Schemas

API 엔드포인트 & 스키마 (API Endpoints & Schemas)

설계 원칙

• Additive-only Contract — 기존 필드 삭제/이름 변경 금지. 새 필드 추가 시 기본값 필수.
• run_id 기반 상태 추적 — 모든 실행에 UUID4 부여, 전 구간 추적 가능.
• 오류 타입 분리 — user_error (400) vs system_error (500).

설계 원칙 상세 → Design Principles

---

1. Endpoints

Core Endpoints

Method	Path	Description	Status
GET	/	Dashboard UI	Implemented
POST	/run_backtest	Submit backtest (async)	Implemented
GET	/status/<run_id>	Poll run status/result	Implemented (Phase 3)
GET	/health	Health check	Implemented

Strategy Management Endpoints

Method	Path	Description	Status
GET	/api/strategies	List presets	Implemented
POST	/api/strategies	Create preset	Implemented
DELETE	/api/strategies/<id>	Delete preset	Implemented

---

2. Run Backtest

Request — Core Minimal Contract (Phase 3)

POST /run_backtest

{
  "ticker": "AAPL.csv",
  "rule_type": "RSI",
  "params": { "period": 14, "oversold": 30, "overbought": 70 },
  "start_date": "2020-01-01",
  "end_date": "2024-01-01"
}

Request — Extended UI Contract (Day 3.9, Additive)

Core 필드에 추가되는 선택 필드. 모두 기본값이 있으므로 하위 호환성 유지.

Field	Type	Default	Description
rule_id	string	(auto-derived)	추적/로깅용 헬퍼 slug
initial_capital	number	100000	초기 자본금
fee_rate	number	0.001	수수료율 (0.1%)
slippage_bps	number	0	슬리피지 (미구현, Day 3.9)
position_size	number	10000	포지션 크기
size_type	string	"value"	"value" 또는 "percent"
direction	string	"longonly"	"longonly" 또는 "longshort"
timeframe	string	"1d"	"1d" (5m/1h는 Phase 2+)

Immediate Response

{
  "run_id": "a1b2c3d4-...",
  "status": "PENDING"
}

---

3. Status Response

GET /status/<run_id>

Pending / Running

{
  "run_id": "a1b2c3d4-...",
  "status": "RUNNING"
}

Succeeded

{
  "run_id": "a1b2c3d4-...",
  "status": "SUCCEEDED",
  "data_hash": "sha256:abc123...",
  "image_tag": "3f8a1c2",
  "start_date": "2020-01-01",
  "end_date": "2024-01-01",
  "metrics": {
    "total_return_pct": 12.34,
    "sharpe_ratio": 1.45,
    "max_drawdown_pct": 8.21,
    "num_trades": 42,
    "cagr": 10.5,
    "volatility": 18.2,
    "win_rate": 65.5,
    "avg_trade_return": 2.1,
    "exposure_pct": 82.3,
    "profit_factor": 1.85
  },
  "equity_curve": [
    { "date": "2020-01-01", "equity": 100000 }
  ],
  "trades": [
    {
      "trade_no": 0,
      "side": "BUY",
      "size": 100,
      "entry_timestamp": "2020-01-15T21:00:00+00:00",
      "entry_price": 153.17,
      "entry_fees": 15.32,
      "exit_timestamp": "2020-05-06T21:00:00+00:00",
      "exit_price": 166.84,
      "exit_fees": 16.68,
      "pnl_abs": 1337.0,
      "pnl_pct": 8.7,
      "holding_period": 112.0
    }
  ],
  "charts": {
    "drawdown_curve_base64": "data:image/png;base64,...",
    "portfolio_orders_base64": "data:image/png;base64,...",
    "trade_pnl_base64": "data:image/png;base64,...",
    "cumulative_return_base64": "data:image/png;base64,..."
  },
  "chart_base64": "data:image/png;base64,..."
}

Notes:

• metrics 내 Phase 2 필드(cagr, volatility 등)는 optional (Adapter에서 계산)
• charts 객체의 모든 차트는 Adapter에서 on-demand 렌더링
• chart_base64는 레거시 호환 필드 (primary equity curve chart)
• drawdown_curve, portfolio_curve는 응답에 포함 가능하나 DB에는 저장하지 않음 (파생 데이터)

저장 vs 파생 경계 → Reproducibility

---

4. Error Schema

user_error (HTTP 400)

입력 검증 실패. Job을 생성하지 않는다.

{
  "error_type": "user_error",
  "message": "Invalid date range: start_date must be before end_date",
  "run_id": "a1b2c3d4-..."
}

system_error (HTTP 500)

런타임 장애. Job 생성 실패 또는 Worker 실행 중 오류.

{
  "error_type": "system_error",
  "message": "Internal server error",
  "run_id": "a1b2c3d4-..."
}

오류 분류 기준 및 상태 전이 규칙 → Execution Lifecycle

---

5. Status Lifecycle

PENDING → RUNNING → SUCCEEDED
   │                └→ FAILED
   └──────────────────→ FAILED

• Forward-only transition (역방향 전이 금지)
• 모든 상태 변경은 UTC timestamp과 함께 MySQL에 기록
• FAILED 상태에서는 반드시 error_message 포함

상태 머신 상세 → Execution Lifecycle

---

See Also

• Execution Lifecycle — 상태 머신, Failure 분류
• Reproducibility — 저장 vs 파생 경계
• ERD-Data Model — DB 컬럼 스키마
• Glossary — rule_type, rule_id, params_json 등 용어 정의