Formati di Risposta API: Best Practice per API Coerenti
Le risposte API incoerenti sono una delle principali lamentele degli sviluppatori frontend. Quando ogni endpoint restituisce dati in una forma diversa, il codice client diventa pieno di casi speciali. Un formato di risposta coerente migliora l'esperienza dello sviluppatore, riduce i bug e rende la tua API auto-documentante.
L'Envelope di Risposta
Avvolgi ogni risposta in una struttura coerente:
Successo (Risorsa Singola)
{
"data": {
"id": "user_123",
"name": "Alice",
"email": "[email protected]",
"createdAt": "2024-01-15T10:30:00Z"
},
"meta": {
"requestId": "req_abc123"
}
}
Successo (Collezione)
{
"data": [
{ "id": "user_123", "name": "Alice" },
{ "id": "user_456", "name": "Bob" }
],
"meta": {
"total": 142,
"page": 1,
"perPage": 20,
"requestId": "req_def456"
}
}
Errore
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": [
{ "field": "email", "message": "Invalid email format" }
]
},
"meta": {
"requestId": "req_ghi789"
}
}
Il principio chiave: i client controllano sempre data o error al livello superiore. Non mescolare mai dati di successo e informazioni di errore nella stessa risposta.
Valida il formato della tua risposta con il nostro Validatore JSON.
Codici di Stato HTTP
Usa i codici di stato correttamente — sono la prima cosa che i client controllano:
Codici di Successo
| Codice | Quando |
|---|---|
| 200 OK | GET riuscito, PUT/PATCH riuscito |
| 201 Created | POST che ha creato una risorsa |
| 204 No Content | DELETE riuscito (nessun body) |
Codici di Errore Client
| Codice | Quando |
|---|---|
| 400 Bad Request | Sintassi della richiesta malformata |
| 401 Unauthorized | Autenticazione mancante o non valida |
| 403 Forbidden | Autenticato ma non autorizzato |
| 404 Not Found | La risorsa non esiste |
| 409 Conflict | Conflitto di stato della risorsa (duplicato) |
| 422 Unprocessable | Sintassi valida ma errori semantici |
| 429 Too Many Requests | Limite di frequenza superato |
Codici di Errore Server
| Codice | Quando |
|---|---|
| 500 Internal Server Error | Errore server inatteso |
| 502 Bad Gateway | Errore servizio upstream |
| 503 Service Unavailable | Sovraccarico temporaneo o manutenzione |
Design della Risposta di Errore
Buone risposte di errore aiutano gli sviluppatori a fare debug rapidamente:
{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "User with ID 'user_999' not found",
"details": [],
"documentationUrl": "https://api.example.com/docs/errors#RESOURCE_NOT_FOUND"
},
"meta": {
"requestId": "req_xyz789",
"timestamp": "2024-01-15T10:30:00Z"
}
}
Regole:
codeè leggibile dalla macchina (stringa costante, non stato HTTP)messageè leggibile dall'uomo (può cambiare senza rompere i client)detailsfornisce errori a livello di campo per i fallimenti di validazionerequestIdpermette al team di supporto di tracciare la richiesta nei log
Pattern di Paginazione
Basata su Offset
Semplice e supporta il salto a pagine arbitrarie:
{
"data": ["..."],
"meta": {
"page": 2,
"perPage": 20,
"total": 142,
"totalPages": 8
},
"links": {
"first": "/api/users?page=1&per_page=20",
"prev": "/api/users?page=1&per_page=20",
"next": "/api/users?page=3&per_page=20",
"last": "/api/users?page=8&per_page=20"
}
}
Basata su Cursore
Migliore per dati in tempo reale e grandi dataset:
{
"data": ["..."],
"meta": {
"hasNext": true,
"hasPrev": true
},
"links": {
"next": "/api/users?cursor=eyJpZCI6MTQzfQ&limit=20",
"prev": "/api/users?cursor=eyJpZCI6MTIzfQ&limit=20&direction=prev"
}
}
Data e Ora
Usa sempre ISO 8601 con informazione sul fuso orario:
{
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T14:22:33+00:00",
"expiresAt": "2024-12-31T23:59:59Z"
}
Non usare mai:
- Timestamp Unix (ambigui: secondi o millisecondi?)
- Date locali senza fuso orario
- Formati personalizzati come MM/GG/AAAA
Per approfondire la gestione dei timestamp, consulta la nostra guida ai Timestamp Unix.
Null vs Campi Assenti
Due approcci comuni:
Includi con null (esplicito):
{ "name": "Alice", "avatar": null, "bio": null }
Ometti i campi assenti (sparso):
{ "name": "Alice" }
Raccomandazione: Sii coerente all'interno della tua API. I null espliciti sono migliori per i linguaggi tipizzati (i client sanno che il campo esiste). Lo stile sparso è migliore per ambienti con larghezza di banda limitata.
Versionamento delle Risposte
Quando il formato della risposta cambia, versiona la tua API:
GET /api/v2/users/123
Modifiche che richiedono versionamento:
- Rimuovere un campo
- Cambiare il tipo di un campo
- Rinominare un campo
- Cambiare la struttura dell'envelope di risposta
Modifiche non distruttive (sicure senza versionamento):
- Aggiungere nuovi campi
- Aggiungere nuovi endpoint
- Aggiungere nuovi valori enum
FAQ
Dovrei avvolgere le risposte di successo in una chiave data o restituire la risorsa direttamente?
Usare un wrapper data fornisce una struttura coerente per tutte le risposte e lascia spazio per metadati, paginazione e link insieme ai dati. Restituire la risorsa direttamente è più semplice per endpoint a risorsa singola. La maggior parte delle API moderne usa l'approccio wrapper per coerenza.
Come dovrei gestire i fallimenti parziali nelle operazioni batch?
Restituisci 200 con una risposta che include sia successi che fallimenti nell'oggetto data. Usare 207 Multi-Status (WebDAV) è un'altra opzione ma meno comunemente usata nelle API REST.
Denominazione delle Risorse
Le risorse sono sostantivi, non verbi. Usa sostantivi plurali per le collezioni e risorse singole tramite ID:
GET /api/users # Lista utenti
POST /api/users # Crea un utente
GET /api/users/123 # Ottieni utente 123
PUT /api/users/123 # Aggiorna utente 123
DELETE /api/users/123 # Elimina utente 123
Convenzioni di denominazione:
- Usa minuscole con trattini:
/api/blog-posts(nonblogPostsoblog_posts) - Annida risorse correlate:
/api/users/123/orders - Limita l'annidamento a 2 livelli:
/api/users/123/orders/456(non più in profondità) - Evita verbi negli URL:
/api/users/123/activateè accettabile per azioni che non mappano a CRUD
Filtraggio e Ordinamento
Filtraggio
GET /api/users?status=active&role=admin
GET /api/users?created_after=2024-01-01
GET /api/users?search=alice
Per filtri complessi, considera un parametro di query dedicato:
GET /api/users?filter[status]=active&filter[role]=admin
Ordinamento
GET /api/users?sort=name # Ascendente
GET /api/users?sort=-created_at # Discendente (prefisso con -)
GET /api/users?sort=-created_at,name # Campi multipli
Rate Limiting
Comunica i limiti di frequenza negli header di risposta:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 67
X-RateLimit-Reset: 1705312800
Retry-After: 30
Restituisci 429 Too Many Requests quando il limite viene superato, con un messaggio di errore chiaro e header Retry-After.
HATEOAS (Opzionale ma Potente)
Includi link a risorse e azioni correlate:
{
"data": {
"id": "123",
"name": "Alice",
"links": {
"self": "/api/users/123",
"orders": "/api/users/123/orders",
"avatar": "/api/users/123/avatar"
}
}
}
Questo rende la tua API auto-documentante e riduce la costruzione di URL lato client.
FAQ
Come dovrei gestire gli aggiornamenti parziali (PATCH vs PUT)?
Usa PUT per la sostituzione completa della risorsa (il client invia tutti i campi). Usa PATCH per aggiornamenti parziali (il client invia solo i campi modificati). PATCH con JSON Merge Patch (RFC 7396) è l'approccio più semplice: invia un oggetto JSON con solo i campi da aggiornare, e null per rimuovere un campo.
Basata su Keyset
GET /api/users?after_id=123&limit=20
Usa l'ID dell'ultimo elemento (o altro campo ordinato) per ottenere la pagina successiva. Simile alla paginazione basata su cursore ma con parametri trasparenti.
Raccomandazione: Usa basata su cursore per feed in tempo reale e grandi dataset. Usa basata su offset per dashboard admin dove il salto di pagina è importante.
Basato su Header
GET /api/users
Accept: application/vnd.myapi.v2+json
Pro: URL puliti. Contro: Più difficile da testare, meno scopribile.
Parametro Query
GET /api/users?version=2
Pro: Facile da testare. Contro: Semantica dei parametri opzionali.
Raccomandazione: Il versionamento nel percorso URL è la scelta più pratica. È esplicito, cacheable e funziona con ogni strumento HTTP.
Dovrei usare la specifica JSON:API o progettare il mio formato?
La specifica JSON:API (jsonapi.org) fornisce uno standard completo, ma può essere verbosa per API semplici. Per la maggior parte dei progetti, progettare un formato personalizzato più semplice seguendo i pattern in questa guida è più pratico. Usa JSON:API se hai bisogno di librerie client automatiche e uno standard rigoroso.
Risorse Correlate
- Formattatore JSON — Formatta le risposte API
- Pattern di Design per API JSON — Guida completa al design delle API
- Validazione JSON Schema — Valida le strutture delle risposte
🛠️ Provalo ora: JSON Formatter | JSON Validator — 100% gratuito, tutto viene elaborato nel tuo browser. Nessun dato caricato.