From 43e8794998f3936f008064dd6ee7558ede54fc01 Mon Sep 17 00:00:00 2001 From: GnomeZworc Date: Sat, 13 Jun 2026 13:43:08 +0200 Subject: [PATCH] add doc api Signed-off-by: GnomeZworc --- docs/README.md | 1 + docs/api.md | 247 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 248 insertions(+) create mode 100644 docs/api.md diff --git a/docs/README.md b/docs/README.md index 725d233..eac1a58 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,6 +4,7 @@ - [how to dev](./dev.md) - [how to release](./release.md) +- [API reference](./api.md) ## Release list - [v0.1.0 Cachalot](./docs/release/v0.1.0_cachalot.md) diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..931899a --- /dev/null +++ b/docs/api.md @@ -0,0 +1,247 @@ +# API Reference + +Base URL : `http://localhost:8080` + +Toutes les réponses sont en `application/json`. Les erreurs retournent `{"error": "message"}`. + +--- + +## Health + +### `GET /health` + +Vérifie la disponibilité du serveur et de la base de données. + +**Réponse `200`** +```json +{ "status": "ok" } +``` + +**Réponse `503`** — base indisponible + +--- + +## Instruments + +Un instrument représente tout actif coté : devise (EUR), action, ETF, crypto. +Le prix EUR vaut toujours 1 et est inséré automatiquement au démarrage. + +### `GET /instruments` + +Liste tous les instruments. + +**Réponse `200`** +```json +[ + { "id": 1, "type": "devise", "code": "EUR", "name": "Euro", "devise_cotation": "EUR" }, + { "id": 2, "type": "etf", "code": "LU1681043599", "name": "Amundi MSCI World", "devise_cotation": "EUR" } +] +``` + +--- + +### `GET /instruments/{id}` + +**Réponse `200`** +```json +{ "id": 2, "type": "etf", "code": "LU1681043599", "name": "Amundi MSCI World", "devise_cotation": "EUR" } +``` + +**Réponse `404`** — instrument introuvable + +--- + +### `POST /instruments` + +**Corps** +| Champ | Type | Requis | Description | +|---|---|---|---| +| `type` | string | ✅ | `devise`, `action`, `etf`, `crypto` | +| `code` | string | ✅ | ISIN (actions/ETF), ticker (crypto), code devise | +| `name` | string | ✅ | Nom lisible | +| `devise_cotation` | string | | Devise de cotation (défaut : `EUR`) | + +**Réponse `201`** +```json +{ "id": 3, "type": "crypto", "code": "BTC", "name": "Bitcoin", "devise_cotation": "EUR" } +``` + +> **Pipeline de prix** : le ticker Yahoo Finance (actions/ETF) est résolu automatiquement via OpenFIGI au prochain cycle. L'ID CoinGecko (crypto) est résolu via l'API search CoinGecko. Les résolutions sont mises en cache dans `instrument_ticker_cache`. + +--- + +### `PUT /instruments/{id}` + +Même corps que `POST`. Retourne l'instrument mis à jour. + +--- + +### `DELETE /instruments/{id}` + +**Réponse `204`** — supprimé + +--- + +## Comptes + +Un compte est un conteneur de positions. Son solde est entièrement dérivé des transactions (aucun solde stocké). + +Les enveloppes sont des sous-comptes monétaires liés à un compte maître (voir section Enveloppes). +`GET /accounts/{id}` retourne toujours le compte avec sa liste d'enveloppes. + +### `GET /accounts` + +Liste les comptes maîtres (sans les enveloppes). + +**Réponse `200`** +```json +[ + { + "id": 1, + "nom": "Livret A", + "type": "livret", + "devise_reference": "EUR", + "plafond": 22950 + } +] +``` + +--- + +### `GET /accounts/{id}` + +Retourne le compte et ses enveloppes. + +**Réponse `200`** +```json +{ + "id": 1, + "nom": "Livret A", + "type": "livret", + "devise_reference": "EUR", + "plafond": 22950, + "envelopes": [ + { + "id": 3, + "nom": "Vacances", + "type": "livret", + "devise_reference": "EUR", + "master_account_id": 1, + "objectif": "Road trip USA" + } + ] +} +``` + +**Réponse `404`** — compte introuvable + +--- + +### `POST /accounts` + +Crée un compte maître. + +**Corps** +| Champ | Type | Requis | Description | +|---|---|---|---| +| `nom` | string | ✅ | Nom du compte | +| `type` | string | ✅ | `courant`, `livret`, `pea`, `cto`, `crypto`, ... | +| `devise_reference` | string | | Devise de référence (défaut : `EUR`) | +| `plafond` | number | | Plafond réglementaire (indicatif) | + +**Réponse `201`** +```json +{ "id": 1, "nom": "Livret A", "type": "livret", "devise_reference": "EUR", "plafond": 22950 } +``` + +--- + +### `PUT /accounts/{id}` + +Met à jour un compte maître. Même corps que `POST`. + +--- + +### `DELETE /accounts/{id}` + +Supprime le compte **et toutes ses enveloppes** (CASCADE). + +**Réponse `204`** + +--- + +## Enveloppes + +Une enveloppe est un sous-compte monétaire rattaché à un compte maître. Elle hérite automatiquement du `type` et de la `devise_reference` de son maître. Le solde est dérivé des transactions, comme pour tout compte. + +Règles : +- Un compte maître ne peut pas lui-même être une enveloppe (pas de chaînage) +- Supprimée automatiquement avec son compte maître + +### `GET /accounts/{id}/envelopes` + +Liste les enveloppes d'un compte. + +**Réponse `200`** +```json +[ + { + "id": 3, + "nom": "Vacances", + "type": "livret", + "devise_reference": "EUR", + "master_account_id": 1, + "objectif": "Road trip USA" + } +] +``` + +--- + +### `POST /accounts/{id}/envelopes` + +Crée une enveloppe sous le compte `{id}`. + +**Corps** +| Champ | Type | Requis | Description | +|---|---|---|---| +| `nom` | string | ✅ | Nom de l'enveloppe | +| `objectif` | string | | Description libre de l'objectif | + +**Réponse `201`** +```json +{ + "id": 3, + "nom": "Vacances", + "type": "livret", + "devise_reference": "EUR", + "master_account_id": 1, + "objectif": "Road trip USA" +} +``` + +**Réponse `400`** — le compte est lui-même une enveloppe (chaînage interdit) +**Réponse `404`** — compte introuvable + +--- + +### `PUT /envelopes/{id}` + +Met à jour le nom et/ou l'objectif d'une enveloppe. + +**Corps** +| Champ | Type | Requis | Description | +|---|---|---|---| +| `nom` | string | ✅ | Nouveau nom | +| `objectif` | string | | Nouvel objectif | + +**Réponse `200`** — enveloppe mise à jour +**Réponse `404`** — enveloppe introuvable + +--- + +### `DELETE /envelopes/{id}` + +Supprime l'enveloppe. + +**Réponse `204`**