samantha/Portfolio-Engine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update REST API

samantha
2026-03-27 10:45:36 +00:00
parent 346dd293da
commit 0bed518af3
1 changed files with 46 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files

197
REST-API.md

@@ -1,21 +1,12 @@
# REST API <h1>REST API</h1>
<p>The server listens on port <code>8080</code>. All request bodies are JSON (<code>Content-Type: application/json</code>).</p>
The server listens on port `8080`. All request bodies are JSON (`Content-Type: application/json`). <hr>
<h2>Health</h2>
--- <h3><code>GET /health</code></h3>
<p>Returns server status, DB connection info, memory usage, and uptime.</p>
## Health <pre><code class="language-bash">curl http://localhost:8080/health
</code></pre>
### `GET /health` <pre><code class="language-json">{
Returns server status, DB connection info, memory usage, and uptime.
```bash
curl http://localhost:8080/health
```
```json
{
"status": "ok", "status": "ok",
"uptime": "4m32s", "uptime": "4m32s",
"database": { "database": {
@@ -33,64 +24,37 @@ curl http://localhost:8080/health
"go_version": "go1.22.0", "go_version": "go1.22.0",
"goroutines": 4 "goroutines": 4
} }
``` </code></pre>
<p>Returns <code>503</code> with <code>"status": "degraded"</code> if the database is unreachable.</p>
Returns `503` with `"status": "degraded"` if the database is unreachable. <hr>
<h2>Companies</h2>
--- <h3><code>POST /company/add</code></h3>
<pre><code class="language-bash">curl -X POST http://localhost:8080/company/add \
## Companies
### `POST /company/add`
```bash
curl -X POST http://localhost:8080/company/add \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{"name":"Novo Nordisk","shares_outstanding":4442064180,"price":251.00,"currency_id":1}' -d '{"name":"Novo Nordisk","shares_outstanding":4442064180,"price":251.00,"currency_id":1}'
``` </code></pre>
<h3><code>GET /company/list</code></h3>
### `GET /company/list` <pre><code class="language-bash">curl http://localhost:8080/company/list
</code></pre>
```bash <h3><code>GET /company/revenue/categories</code></h3>
curl http://localhost:8080/company/list <p>Returns all distinct revenue categories for a company.</p>
``` <pre><code class="language-bash">curl "http://localhost:8080/company/revenue/categories?company_id=1"
</code></pre>
### `GET /company/revenue/categories` <hr>
<h2>Currencies</h2>
Returns all distinct revenue categories for a company. <h3><code>POST /currency/add</code></h3>
<pre><code class="language-bash">curl -X POST http://localhost:8080/currency/add \
```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" \ -H "Content-Type: application/json" \
-d '{"code":"DKK","name":"Danish Krone"}' -d '{"code":"DKK","name":"Danish Krone"}'
``` </code></pre>
<h3><code>GET /currency/list</code></h3>
### `GET /currency/list` <pre><code class="language-bash">curl http://localhost:8080/currency/list
</code></pre>
```bash <hr>
curl http://localhost:8080/currency/list <h2>Trades</h2>
``` <h3><code>POST /trade/add</code></h3>
<p>Add a new trade. <code>product</code> is an integer enum and <code>type</code> is a boolean (see tables below).</p>
--- <pre><code class="language-bash">curl -X POST http://localhost:8080/trade/add \
## 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" \ -H "Content-Type: application/json" \
-d '{ -d '{
"symbol": "NOVO", "symbol": "NOVO",
@@ -101,82 +65,13 @@ curl -X POST http://localhost:8080/trade/add \
"price": 251.00, "price": 251.00,
"date": "2025-03-01T00:00:00Z" "date": "2025-03-01T00:00:00Z"
}' }'
``` </code></pre>
<p><strong><code>product</code> values:</strong></p>
**`product` values:**
Value | Meaning
| Value | Meaning | -- | --
|-------|---------| 0 | StockTrade
| `0` | StockTrade | 1 | OptionCallTrade
| `1` | OptionCallTrade | 2 | OptionPutTrade
| `2` | OptionPutTrade | 3 | CurrencyTrade
| `3` | CurrencyTrade | 4 | BondTrade
| `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 |