Add REST API

2026-03-27 10:42:25 +00:00
parent fcb152c1c8
commit fd0481d014
1 changed files with 182 additions and 0 deletions
--- a/REST-API.md
+++ b/REST-API.md
@@ -0,0 +1,182 @@
+# REST API
+ 
+The server listens on port `8080`. All request bodies are JSON (`Content-Type: application/json`).
+ 
+---
+ 
+## Health
+ 
+### `GET /health`
+ 
+Returns server status, DB connection info, memory usage, and uptime.
+ 
+```bash
+curl http://localhost:8080/health
+```
+ 
+```json
+{
+  "status": "ok",
+  "uptime": "4m32s",
+  "database": {
+    "status": "ok",
+    "latency": "121µs",
+    "open_connections": 1,
+    "in_use": 0,
+    "idle": 1
+  },
+  "memory": {
+    "alloc_mb": 2.31,
+    "sys_mb": 9.44,
+    "num_gc": 3
+  },
+  "go_version": "go1.22.0",
+  "goroutines": 4
+}
+```
+ 
+Returns `503` with `"status": "degraded"` if the database is unreachable.
+ 
+---
+ 
+## Companies
+ 
+### `POST /company/add`
+ 
+```bash
+curl -X POST http://localhost:8080/company/add \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Novo Nordisk","shares_outstanding":4442064180,"price":251.00,"currency_id":1}'
+```
+ 
+### `GET /company/list`
+ 
+```bash
+curl http://localhost:8080/company/list
+```
+ 
+### `GET /company/revenue/categories`
+ 
+Returns all distinct revenue categories for a company.
+ 
+```bash
+curl "http://localhost:8080/company/revenue/categories?company_id=1"
+```
+ 
+---
+ 
+## Currencies
+ 
+### `POST /currency/add`
+ 
+```bash
+curl -X POST http://localhost:8080/currency/add \
+  -H "Content-Type: application/json" \
+  -d '{"code":"DKK","name":"Danish Krone"}'
+```
+ 
+### `GET /currency/list`
+ 
+```bash
+curl http://localhost:8080/currency/list
+```
+ 
+---
+ 
+## Trades
+ 
+### `POST /trade/add`
+ 
+Add a new trade. `product` is an integer enum and `type` is a boolean (see tables below).
+ 
+```bash
+curl -X POST http://localhost:8080/trade/add \
+  -H "Content-Type: application/json" \
+  -d '{
+    "symbol":        "NOVO",
+    "currency_code": "DKK",
+    "shares":        100,
+    "product":       0,
+    "type":          true,
+    "price":         251.00,
+    "date":          "2025-03-01T00:00:00Z"
+  }'
+```
+ 
+**`product` values:**
+ 
+| Value | Meaning |
+|-------|---------|
+| `0` | StockTrade |
+| `1` | OptionCallTrade |
+| `2` | OptionPutTrade |
+| `3` | CurrencyTrade |
+| `4` | BondTrade |
+ 
+**`type` values:**
+ 
+| Value | Meaning |
+|-------|---------|
+| `true` | Buy |
+| `false` | Sell |
+ 
+**Validation rules:**
+- `symbol` must not be empty
+- `shares` must be a positive integer
+- `product` must be 0–3
+- `price` must be a positive number
+- `currency_code` must not be empty
+- `date` must not be zero or in the future
+ 
+### `GET /trade/list`
+ 
+Returns all trades as a JSON array.
+ 
+```bash
+curl http://localhost:8080/trade/list
+```
+ 
+---
+ 
+## Positions
+ 
+### `GET /positions/list`
+ 
+Returns the current portfolio positions, computed by aggregating the trade history.
+ 
+```bash
+curl http://localhost:8080/positions/list
+```
+ 
+Each position includes `Symbol`, `CurrencyCode`, `CostBasis`, `Shares`, and `Weight`.
+ 
+---
+ 
+## Revenue
+ 
+### `POST /add/revenue/entry`
+ 
+Also available at `POST /api/v1/revenue/add`. Adds a single revenue line to a report. The period is created automatically if it doesn't exist.
+ 
+```bash
+curl -X POST http://localhost:8080/add/revenue/entry \
+  -H "Content-Type: application/json" \
+  -d '{
+    "company_id":  1,
+    "currency_id": 1,
+    "period_type": "Q",
+    "year":        2025,
+    "index":       1,
+    "category":    "product",
+    "label":       "iPhone",
+    "value":       69143
+  }'
+```
+ 
+`period_type` values:
+ 
+| Value | Meaning | `index` range |
+|-------|---------|---------------|
+| `Q` | Quarter | 1–4 |
+| `H` | Half-year | 1–2 |
+| `Y` | Full year | 1 |