chore: add docs sync guardrails and spec documents
This commit is contained in:
@@ -0,0 +1,287 @@
|
||||
# PortfolioHub API Examples
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document contains example requests and responses for PortfolioHub HTTP APIs.
|
||||
|
||||
- Sync rule: when files under `app/api/` or `app/schemas/` change, this document must be updated in the same commit/PR.
|
||||
- Companion spec: `docs/portfoliohub-spec.md`
|
||||
|
||||
## 2. Conventions
|
||||
|
||||
- Base URL example: `http://localhost:8000`
|
||||
- Auth header format: `Authorization: Bearer <TOKEN>`
|
||||
- JSON examples are representative and may omit some optional fields.
|
||||
|
||||
## 3. Health
|
||||
|
||||
### 3.1 GET /health
|
||||
|
||||
Request:
|
||||
|
||||
```bash
|
||||
curl -X GET "http://localhost:8000/health"
|
||||
```
|
||||
|
||||
Response 200:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok"
|
||||
}
|
||||
```
|
||||
|
||||
## 4. Portfolios
|
||||
|
||||
### 4.1 GET /portfolios
|
||||
|
||||
Request:
|
||||
|
||||
```bash
|
||||
curl -X GET "http://localhost:8000/portfolios?broker=upbit&status_filter=enabled" \
|
||||
-H "Authorization: Bearer <READ_TOKEN>"
|
||||
```
|
||||
|
||||
Response 200:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"portfolio_id": "krw-btc",
|
||||
"broker": "upbit",
|
||||
"status": "enabled",
|
||||
"symbol": "KRW-BTC",
|
||||
"strategy_name": "target_value",
|
||||
"strategy_params": {},
|
||||
"cash_balance": 1000000.0,
|
||||
"asset_quantity": 0.1,
|
||||
"price": 100000000.0,
|
||||
"profit_buffer": 0.0,
|
||||
"current_strategy_set_id": "stv-001",
|
||||
"created_at": "2026-04-03T00:00:00Z",
|
||||
"updated_at": "2026-04-03T00:00:00Z",
|
||||
"last_trade_at": "2026-04-03T00:00:00Z",
|
||||
"total_value": 11000000.0
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### 4.2 GET /portfolios/{portfolio_id}
|
||||
|
||||
Request:
|
||||
|
||||
```bash
|
||||
curl -X GET "http://localhost:8000/portfolios/krw-btc?recent_trades=5" \
|
||||
-H "Authorization: Bearer <READ_TOKEN>"
|
||||
```
|
||||
|
||||
Response 200:
|
||||
|
||||
```json
|
||||
{
|
||||
"portfolio": {
|
||||
"portfolio_id": "krw-btc",
|
||||
"broker": "upbit",
|
||||
"status": "enabled",
|
||||
"symbol": "KRW-BTC",
|
||||
"strategy_name": "target_value",
|
||||
"strategy_params": {},
|
||||
"cash_balance": 1000000.0,
|
||||
"asset_quantity": 0.1,
|
||||
"price": 100000000.0,
|
||||
"profit_buffer": 0.0,
|
||||
"current_strategy_set_id": "stv-001",
|
||||
"created_at": "2026-04-03T00:00:00Z",
|
||||
"updated_at": "2026-04-03T00:00:00Z",
|
||||
"last_trade_at": "2026-04-03T00:00:00Z"
|
||||
},
|
||||
"recent_entries": [
|
||||
{
|
||||
"portfolio_id": "krw-btc",
|
||||
"recorded_at": "2026-04-03T00:00:00Z",
|
||||
"action": "buy",
|
||||
"price": 100000000.0,
|
||||
"quantity": 0.1,
|
||||
"fee_amount": 0.0,
|
||||
"tax_amount": 0.0,
|
||||
"cash_balance_after": 1000000.0,
|
||||
"asset_quantity_after": 0.1,
|
||||
"total_value_after": 11000000.0,
|
||||
"profit_buffer_after": 0.0,
|
||||
"strategy_set_id": "stv-001",
|
||||
"note": ""
|
||||
}
|
||||
],
|
||||
"strategy_set": {
|
||||
"id": "stv-001",
|
||||
"strategy_name": "target_value",
|
||||
"strategy_config": "{}",
|
||||
"created_at": "2026-04-03T00:00:00Z"
|
||||
},
|
||||
"live_quantity": null
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 POST /portfolios
|
||||
|
||||
Request:
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:8000/portfolios" \
|
||||
-H "Authorization: Bearer <TRADE_WRITE_TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"portfolio_id": "krw-btc",
|
||||
"broker": "upbit",
|
||||
"status": "enabled",
|
||||
"symbol": "KRW-BTC",
|
||||
"strategy_name": "target_value",
|
||||
"strategy_params": {},
|
||||
"cash_balance": 1000000,
|
||||
"asset_quantity": 0,
|
||||
"asset_price": 0,
|
||||
"profit_buffer": 0
|
||||
}'
|
||||
```
|
||||
|
||||
Response 201:
|
||||
|
||||
- Response body shape is `PortfolioDetailResponse` (same as 4.2).
|
||||
|
||||
### 4.4 PATCH /portfolios/{portfolio_id}
|
||||
|
||||
Request:
|
||||
|
||||
```bash
|
||||
curl -X PATCH "http://localhost:8000/portfolios/krw-btc" \
|
||||
-H "Authorization: Bearer <TRADE_WRITE_TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"broker": "upbit",
|
||||
"symbol": "KRW-BTC"
|
||||
}'
|
||||
```
|
||||
|
||||
Response 200:
|
||||
|
||||
- Response body shape is `PortfolioDetailResponse`.
|
||||
|
||||
### 4.5 POST /portfolios/{portfolio_id}/buy
|
||||
|
||||
Request:
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:8000/portfolios/krw-btc/buy" \
|
||||
-H "Authorization: Bearer <TRADE_WRITE_TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"quantity": 0.01, "price": 100000000, "fee": 0, "tax": 0, "note": ""}'
|
||||
```
|
||||
|
||||
Response 200:
|
||||
|
||||
- Response body shape is `PortfolioDetailResponse`.
|
||||
|
||||
### 4.6 POST /portfolios/{portfolio_id}/sell
|
||||
|
||||
Request:
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:8000/portfolios/krw-btc/sell" \
|
||||
-H "Authorization: Bearer <TRADE_WRITE_TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"quantity": 0.01, "price": 100000000, "fee": 0, "tax": 0, "note": ""}'
|
||||
```
|
||||
|
||||
Response 200:
|
||||
|
||||
- Response body shape is `PortfolioDetailResponse`.
|
||||
|
||||
### 4.7 POST /portfolios/{portfolio_id}/invest
|
||||
|
||||
Request:
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:8000/portfolios/krw-btc/invest" \
|
||||
-H "Authorization: Bearer <TRADE_WRITE_TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"movement_type": "deposit", "amount": 50000, "note": ""}'
|
||||
```
|
||||
|
||||
Response 200:
|
||||
|
||||
- Response body shape is `PortfolioDetailResponse`.
|
||||
|
||||
### 4.8 POST /portfolios/{portfolio_id}/transfer
|
||||
|
||||
Request:
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:8000/portfolios/krw-btc/transfer" \
|
||||
-H "Authorization: Bearer <TRADE_WRITE_TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"direction": "to-buffer", "amount": 10000, "note": ""}'
|
||||
```
|
||||
|
||||
Response 200:
|
||||
|
||||
- Response body shape is `PortfolioDetailResponse`.
|
||||
|
||||
### 4.9 POST /portfolios/{portfolio_id}/reset
|
||||
|
||||
Request:
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:8000/portfolios/krw-btc/reset" \
|
||||
-H "Authorization: Bearer <TRADE_WRITE_TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"infer_symbol": "KRW-BTC"}'
|
||||
```
|
||||
|
||||
Response 200:
|
||||
|
||||
- Response body shape is `PortfolioDetailResponse`.
|
||||
|
||||
### 4.10 DELETE /portfolios/{portfolio_id}
|
||||
|
||||
Request:
|
||||
|
||||
```bash
|
||||
curl -X DELETE "http://localhost:8000/portfolios/krw-btc?keep_ledger=false" \
|
||||
-H "Authorization: Bearer <ADMIN_TOKEN>"
|
||||
```
|
||||
|
||||
Response 204:
|
||||
|
||||
- No content.
|
||||
|
||||
## 5. Common Error Examples
|
||||
|
||||
### 5.1 Missing token
|
||||
|
||||
Response 401:
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "Missing bearer token"
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 Invalid token
|
||||
|
||||
Response 401:
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "Invalid token"
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 Insufficient permission
|
||||
|
||||
Response 403:
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "Insufficient permission"
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user