Convenzioni ed errori

URL di base e formato

Tutti gli endpoint si trovano sotto https://app.todomino.eu/api. Richieste e risposte sono in JSON (Content-Type: application/json) salvo indicazione contraria. Autenticati con un token di accesso personale.

Identificatori e timestamp

Gli ID sono UUID, generati dal server.
I timestamp sono istanti ISO-8601 in UTC, ad es. 2026-07-18T09:30:00Z.
Anche le date di scadenza sono istanti; il client web le memorizza come mezzanotte UTC del giorno scelto (2026-08-01T00:00:00Z).

Enum

Campo	Valori
`status` di attività/sottoattività	`PENDING`, `DONE`
`priority` dell’attività	`LOW`, `NORMAL`, `HIGH`, `CRITICAL`, oppure `null`
`role` del membro	`OWNER`, `ADMIN`, `MEMBER`

Locking ottimistico

Le attività hanno un numero di version. Gli aggiornamenti completi (PUT) devono rimandare la versione che hai letto per ultima; se qualcun altro ha modificato l’attività nel frattempo, l’API risponde 409 Conflict — rileggi l’attività e riapplica la tua modifica.

Operazioni offline

Gli endpoint di mutazione per attività, sottoattività e liste accettano un header opzionale X-Op-Id con un UUID generato dal client. Lo stesso op id viene eseguito esattamente una volta: le ripetizioni (ad es. un nuovo tentativo dopo una risposta persa) vengono confermate con lo stesso stato senza essere rieseguite, così i client offline possono inviare in sicurezza le operazioni in coda. Le creazioni inviate con un op id devono inoltre portare un id generato dal client nel corpo — il client conosce così già ogni id di cui una ripetizione avrebbe bisogno. Le eliminazioni sono idempotenti per natura e non hanno bisogno di alcun op id.

Errori

Stato	Significato
`400`	Richiesta malformata (campo mancante, valore non valido)
`401`	Token mancante o non valido / accesso non effettuato
`403`	Autenticato, ma il tuo ruolo non consente questa azione
`404`	Non trovato — restituito anche per gli spazi di lavoro di cui non sei membro
`409`	Conflitto: nome duplicato, versione non corrispondente o allegato duplicato
`413`	Limite di archiviazione dello spazio di lavoro raggiunto

Le risposte di errore sono problem details di Spring; lo stato HTTP è il contratto, il testo del corpo è informativo e può cambiare.