Riferimento
Convenzioni ed errori
Le regole valide per ogni endpoint, così le impari una volta sola.
Paginazione
Gli endpoint di elenco accettano page (a partire da 1) e pageSize (1–100, default 30) come parametri query e racchiudono i risultati in un unico envelope:
{
"items": [ … ],
"pageNumber": 2,
"totalPages": 9,
"totalCount": 174,
"hasPreviousPage": true,
"hasNextPage": true
}Gli enum sono stringhe camelCase
I valori enum sono sempre stringhe in camelCase, mai interi: "pounds", "kilometers", "oneRepMax", "chest", "normal". Tratta i valori enum sconosciuti come forward-compatible: possono comparirne di nuovi senza un cambio di versione.
Unità
| Misura | Unità |
|---|---|
| Peso (serie, record) | Libbre |
| Distanza | Metri |
| Durata di serie / record | Secondi |
| Durata dell'allenamento | Minuti (durationMinutes) |
| Misurazioni corporee | Il sistema di unità nel weightUnit della voce (pollici con le libbre, centimetri con i chilogrammi) |
Le unità di visualizzazione preferite dall'utente sono su /api/v1/user: converti ai bordi della tua app, non nello storage.
Identificatori
- Dati utente (allenamenti, template, split, misurazioni): GUID stabili
- Dati di catalogo (esercizi, attrezzatura): id interi stabili condivisi con l'app Gravl
- L'utente: un id stringa opaco, stabile su tutti gli endpoint e i token
Date
Tutti i timestamp sono UTC, ISO 8601 (2026-07-12T17:03:00Z). I filtri per intervallo di date (startDate, endDate) sono inclusivi.
Rate limit
| Superficie | Limite | Chiave |
|---|---|---|
/api/v1/* | 100 richieste / 15 min | app + utente |
/oauth/* | 10 richieste / min | indirizzo IP |
Superare un limite restituisce 429 con un header Retry-After quando disponibile. Fai backoff esponenziale; non fare polling: la maggior parte dei dati personali cambia a velocità umana.
Errori
| Status | Quando | Corpo |
|---|---|---|
| 401 | Token mancante, malformato, scaduto o revocato; app sospesa | Vuoto (challenge WWW-Authenticate) |
| 403 | Token valido, scope mancante | Problem details con il nome dello scope mancante |
| 404 | La risorsa non esiste, oppure appartiene a un altro utente | Problem details |
| 429 | Rate limit superato | Vuoto; header Retry-After |
| 400 | Errore di validazione (page size errata, parametri malformati) | Problem details con gli errori per campo |
{
"status": 403,
"title": "Missing scope",
"detail": "This authorization is missing the 'measurements:read' scope."
}Nota la regola del 404 per i dati altrui: richiedere per id l'allenamento di un altro utente restituisce 404, non 403. L'API non conferma mai l'esistenza di dati che non puoi vedere.