ff

2026-10-26 00:25:18 +01:00
parent 1df884da84
commit 1bc033c329
46 changed files with 2958 additions and 0 deletions
@@ -0,0 +1,59 @@
+# API — Catalogo e convenzioni
+
+Ultimo aggiornamento: **{{DATA}}**
+
+Il contratto è [`openapi.yaml`](openapi.yaml), **fonte di verità**: in caso di differenza fra
+questo documento, il codice e il contratto, vale il contratto. Si scrive il contratto **prima**
+del codice (contract-first).
+
+---
+
+## 1. Convenzioni
+
+| Aspetto | Regola |
+|---|---|
+| Prefisso | `/api/v1` |
+| Formato | JSON, UTF-8, date ISO 8601 in UTC |
+| Nomi | <!-- DA COMPILARE: snake_case o camelCase, una sola scelta --> |
+| Autenticazione | <!-- DA COMPILARE --> |
+
+## 2. Errori
+
+Forma unica per tutti gli errori:
+
+```json
+{ "error": { "code": "stringa_stabile", "message": "testo leggibile", "details": {} } }
+```
+
+| Codice HTTP | Quando |
+|:-:|---|
+| 400 | Richiesta malformata |
+| 401 | Non autenticato |
+| 403 | Autenticato ma non autorizzato |
+| 404 | Risorsa inesistente **o di un altro tenant** (non si rivela l'esistenza) |
+| 409 | Conflitto (duplicato, stato non compatibile) |
+| 422 | Validazione fallita |
+
+## 3. Paginazione
+
+<!-- DA COMPILARE: parametri (page/size o cursore), limiti massimi, forma della risposta. -->
+
+## 4. Catalogo
+
+### <!-- Gruppo --> — `SPEC-…`
+
+| Metodo | Percorso | Ruolo minimo | Descrizione |
+|---|---|---|---|
+| <!-- DA COMPILARE --> | | | |
+
+## 5. API interne — non esposte
+
+<!-- DA COMPILARE o «nessuna». -->
+
+## 6. Idempotenza e concorrenza
+
+<!-- DA COMPILARE: chiavi di idempotenza, controllo delle versioni, comportamento in caso di doppio invio. -->
+
+## 7. Limiti
+
+<!-- DA COMPILARE: rate limit, dimensioni massime dei corpi e dei file. -->