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

195
REST-API.md

@@ -1,21 +1,12 @@
# 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
{
<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>
<hr>
<h2>Health</h2>
<h3><code>GET /health</code></h3>
<p>Returns server status, DB connection info, memory usage, and uptime.</p>
<pre><code class="language-bash">curl http://localhost:8080/health
</code></pre>
<pre><code class="language-json">{
"status": "ok",
"uptime": "4m32s",
"database": {
@@ -33,64 +24,37 @@ curl http://localhost:8080/health
"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 \
</code></pre>
<p>Returns <code>503</code> with <code>"status": "degraded"</code> if the database is unreachable.</p>
<hr>
<h2>Companies</h2>
<h3><code>POST /company/add</code></h3>
<pre><code class="language-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 \
</code></pre>
<h3><code>GET /company/list</code></h3>
<pre><code class="language-bash">curl http://localhost:8080/company/list
</code></pre>
<h3><code>GET /company/revenue/categories</code></h3>
<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>
<hr>
<h2>Currencies</h2>
<h3><code>POST /currency/add</code></h3>
<pre><code class="language-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 \
</code></pre>
<h3><code>GET /currency/list</code></h3>
<pre><code class="language-bash">curl http://localhost:8080/currency/list
</code></pre>
<hr>
<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 \
-H "Content-Type: application/json" \
-d '{
"symbol": "NOVO",
@@ -101,82 +65,13 @@ curl -X POST http://localhost:8080/trade/add \
"price": 251.00,
"date": "2025-03-01T00:00:00Z"
}'
```
</code></pre>
<p><strong><code>product</code> values:</strong></p>
**`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 |
Value | Meaning
-- | --
0 | StockTrade
1 | OptionCallTrade
2 | OptionPutTrade
3 | CurrencyTrade
4 | BondTrade