--- title: Reference API description: Liste des endpoints de l'API Glibredecision --- # Reference API Tous les endpoints sont prefixes par `/api/v1`. L'API est auto-documentee via OpenAPI/Swagger a l'adresse `/docs` en mode debug. ## Authentification (`/api/v1/auth`) | Methode | Endpoint | Description | Auth | | ------- | ------------- | ----------------------------------------------------- | ---- | | POST | `/challenge` | Generer un challenge Ed25519 pour une adresse Duniter | Non | | POST | `/verify` | Verifier la signature du challenge et obtenir un token | Non | | GET | `/me` | Retourner l'identite authentifiee courante | Oui | | POST | `/logout` | Invalider la session courante | Oui | ## Documents (`/api/v1/documents`) | Methode | Endpoint | Description | Auth | | ------- | -------------------------------------- | ---------------------------------------- | ---- | | GET | `/` | Lister les documents (filtres: doc_type, status) | Non | | POST | `/` | Creer un nouveau document | Oui | | GET | `/{slug}` | Obtenir un document par son slug | Non | | PUT | `/{slug}` | Mettre a jour un document | Oui | | POST | `/{slug}/items` | Ajouter un item au document | Oui | | GET | `/{slug}/items` | Lister les items d'un document | Non | | GET | `/{slug}/items/{item_id}` | Obtenir un item avec son historique | Non | | PUT | `/{slug}/items/{item_id}` | Mettre a jour un item (titre, texte, position, type) | Oui | | DELETE | `/{slug}/items/{item_id}` | Supprimer un item du document | Oui | | POST | `/{slug}/items/{item_id}/versions` | Proposer une nouvelle version d'un item | Oui | | GET | `/{slug}/items/{item_id}/versions` | Lister les versions d'un item | Non | | PUT | `/{slug}/items/{item_id}/versions/{version_id}/accept` | Accepter une version proposee (applique le texte a l'item) | Oui | | PUT | `/{slug}/items/{item_id}/versions/{version_id}/reject` | Rejeter une version proposee | Oui | | PUT | `/{slug}/items/reorder` | Reordonner les items d'un document | Oui | | POST | `/{slug}/archive` | Archiver le document dans le sanctuaire (hash SHA-256 + IPFS + on-chain) | Oui | ## Decisions (`/api/v1/decisions`) | Methode | Endpoint | Description | Auth | | ------- | ---------------- | ------------------------------------------------ | ---- | | GET | `/` | Lister les decisions (filtres: decision_type, status) | Non | | POST | `/` | Creer une nouvelle decision | Oui | | GET | `/{id}` | Obtenir une decision avec ses etapes | Non | | PUT | `/{id}` | Mettre a jour une decision | Oui | | POST | `/{id}/steps` | Ajouter une etape a une decision | Oui | ## Votes (`/api/v1/votes`) | Methode | Endpoint | Description | Auth | | ------- | --------------------------- | -------------------------------------------- | ---- | | POST | `/sessions` | Creer une session de vote | Oui | | GET | `/sessions/{id}` | Obtenir une session de vote | Non | | POST | `/sessions/{id}/vote` | Soumettre un vote (signe) | Oui | | GET | `/sessions/{id}/votes` | Lister les votes d'une session | Non | | GET | `/sessions/{id}/result` | Calculer et retourner le resultat courant | Non | ## Mandats (`/api/v1/mandates`) | Methode | Endpoint | Description | Auth | | ------- | ----------------- | ---------------------------------------------- | ---- | | GET | `/` | Lister les mandats (filtres: mandate_type, status) | Non | | POST | `/` | Creer un nouveau mandat | Oui | | GET | `/{id}` | Obtenir un mandat avec ses etapes | Non | | PUT | `/{id}` | Mettre a jour un mandat | Oui | | DELETE | `/{id}` | Supprimer un mandat (brouillon uniquement) | Oui | | POST | `/{id}/steps` | Ajouter une etape a un mandat | Oui | | GET | `/{id}/steps` | Lister les etapes d'un mandat | Non | ## Protocoles (`/api/v1/protocols`) | Methode | Endpoint | Description | Auth | | ------- | --------------- | -------------------------------------------------- | ---- | | GET | `/` | Lister les protocoles de vote | Non | | POST | `/` | Creer un protocole de vote | Oui | | GET | `/{id}` | Obtenir un protocole avec sa configuration formule | Non | | GET | `/formulas` | Lister les configurations de formules | Non | | POST | `/formulas` | Creer une configuration de formule | Oui | ## Sanctuaire (`/api/v1/sanctuary`) | Methode | Endpoint | Description | Auth | | ------- | --------------------------------- | ---------------------------------------------------------- | ---- | | GET | `/` | Lister les entrees du sanctuaire (filtre: entry_type) | Non | | GET | `/{id}` | Obtenir une entree du sanctuaire | Non | | POST | `/` | Creer une entree (hash SHA-256, CID IPFS, TX on-chain) | Oui | | GET | `/{id}/verify` | Verifier l'integrite d'une entree (recalcul SHA-256, verification IPFS et on-chain) | Non | | GET | `/by-reference/{reference_id}` | Obtenir les entrees liees a une entite source par son UUID | Non | ## WebSocket (`/api/v1/ws`) | Endpoint | Description | | --------- | -------------------------------------------------------- | | `/ws` | Connexion WebSocket pour notifications temps reel (votes, decisions) | ## Sante | Methode | Endpoint | Description | | ------- | -------------- | -------------------------- | | GET | `/api/health` | Verification de sante (hors versionning) | ## Details des endpoints Sprint 2 ### `PUT /api/v1/documents/{slug}/items/{item_id}` -- Mettre a jour un item Met a jour les champs d'un item existant (titre, texte courant, position, type). Seuls les champs fournis sont mis a jour (mise a jour partielle). **Corps de la requete** (tous les champs sont optionnels) : ```json { "title": "Nouveau titre", "current_text": "Texte mis a jour...", "position": "2.1", "item_type": "rule" } ``` **Reponse** : `200 OK` avec l'item mis a jour (`DocumentItemOut`). --- ### `DELETE /api/v1/documents/{slug}/items/{item_id}` -- Supprimer un item Supprime un item d'un document. La suppression est en cascade : toutes les versions associees sont egalement supprimees. **Reponse** : `204 No Content`. --- ### `GET /api/v1/documents/{slug}/items/{item_id}/versions` -- Lister les versions d'un item Retourne l'historique complet des versions proposees pour un item, ordonne par date de creation decroissante. **Parametres de requete** : `skip`, `limit` (pagination standard). **Reponse** : `200 OK` avec une liste de `ItemVersionOut`. --- ### `PUT /api/v1/documents/{slug}/items/{item_id}/versions/{version_id}/accept` -- Accepter une version Accepte une version proposee. Le texte propose remplace le texte courant de l'item. Toutes les autres versions en statut `proposed` ou `voting` pour cet item sont automatiquement rejetees. **Reponse** : `200 OK` avec la version mise a jour (`ItemVersionOut`, statut `accepted`). --- ### `PUT /api/v1/documents/{slug}/items/{item_id}/versions/{version_id}/reject` -- Rejeter une version Rejette une version proposee. Le texte courant de l'item reste inchange. **Reponse** : `200 OK` avec la version mise a jour (`ItemVersionOut`, statut `rejected`). --- ### `PUT /api/v1/documents/{slug}/items/reorder` -- Reordonner les items Modifie l'ordre d'affichage des items dans un document en mettant a jour le champ `sort_order` de chaque item. **Corps de la requete** : ```json { "items": [ { "item_id": "uuid-1", "sort_order": 0 }, { "item_id": "uuid-2", "sort_order": 1 }, { "item_id": "uuid-3", "sort_order": 2 } ] } ``` **Reponse** : `200 OK` avec la liste des items reordonnes. --- ### `POST /api/v1/documents/{slug}/archive` -- Archiver un document Archive le document complet dans le sanctuaire. Le processus : 1. Le contenu integral du document (metadonnees + items) est serialise. 2. Un hash SHA-256 est calcule sur le contenu. 3. Le contenu est envoye sur IPFS (CID retourne). 4. Le hash est ancre on-chain via `system.remark` sur Duniter V2. 5. Une entree `sanctuary_entries` est creee avec les references. 6. Le statut du document passe a `archived` et les champs `ipfs_cid` et `chain_anchor` sont mis a jour. **Reponse** : `200 OK` avec le document mis a jour incluant `ipfs_cid` et `chain_anchor`. --- ### `GET /api/v1/sanctuary/{id}/verify` -- Verifier l'integrite d'une entree Verifie l'integrite d'une entree du sanctuaire en effectuant trois controles : 1. **Hash SHA-256** : recalcul du hash a partir du contenu source et comparaison avec `content_hash`. 2. **IPFS** : verification que le CID IPFS pointe vers un contenu valide (si disponible). 3. **On-chain** : verification que le hash est present dans le `system.remark` du bloc reference (si disponible). **Reponse** : ```json { "entry_id": "uuid", "hash_valid": true, "ipfs_valid": true, "chain_valid": true, "verified_at": "2026-02-28T12:00:00Z", "details": "Tous les controles sont valides." } ``` --- ### `GET /api/v1/sanctuary/by-reference/{reference_id}` -- Entrees par reference Retourne toutes les entrees du sanctuaire liees a une entite source (document, decision ou session de vote) identifiee par son UUID. **Parametres de requete** : `skip`, `limit` (pagination standard). **Reponse** : `200 OK` avec une liste de `SanctuaryEntryOut`. ## Pagination Les endpoints de liste acceptent les parametres `skip` (offset, defaut 0) et `limit` (max 200, defaut 50). ## Authentification Les endpoints marques "Oui" dans la colonne Auth requierent un header : ``` Authorization: Bearer ``` Le token est obtenu via le flux challenge-response (`/auth/challenge` puis `/auth/verify`).