Usare JSON nelle API REST: Buone Pratiche

2026-07-19· Tag: json, rest-api, api-design, json-best-practices, pagination, web-development

JSON nelle API REST

JSON e le API REST sono un matrimonio perfetto. La sintassi leggera di JSON, il supporto nativo degli array e il supporto universale dei linguaggi lo rendono il formato predefinito per le API web moderne. Ma usare semplicemente JSON nella tua API non è sufficiente -- seguire convenzioni e buone pratiche consolidate garantisce che la tua API sia coerente, intuitiva e facile da integrare.

Formato di richiesta e risposta

Struttura envelope coerente

Adotta un envelope JSON coerente per tutte le risposte API. Questo rende l'elaborazione lato client prevedibile e semplifica la gestione degli errori.

{
  "status": "success",
  "data": {
    "user": {
      "id": 123,
      "name": "Alice",
      "email": "alice@example.com"
    }
  },
  "meta": {
    "requestId": "req-a1b2c3d4",
    "timestamp": "2026-07-19T10:30:00Z"
  }
}

Snake Case vs Camel Case

Scegli una convenzione di denominazione e rispettala in tutta la tua API:

Camel Case (createdAt, firstName): Comune negli ecosistemi JavaScript/TypeScript
Snake Case (created_at, first_name): Comune negli ecosistemi Python, Ruby e PHP

Qualunque cosa tu scelga, documentala chiaramente e valuta l'uso di un livello di trasformazione se il linguaggio del tuo backend usa una convenzione diversa.

Codici di stato HTTP con JSON

I codici di stato HTTP corretti completano le tue risposte JSON. Usali in modo coerente:

| Codice di stato | Significato | Quando usarlo | |-------------|---------|-------------| | 200 OK | Successo | Successo di GET, PUT, PATCH | | 201 Created | Risorsa creata | Successo di POST | | 204 No Content | Successo dell'eliminazione | Successo di DELETE (nessun body JSON) | | 400 Bad Request | Sintassi JSON non valida | Body della richiesta malformato | | 401 Unauthorized | Autenticazione richiesta | Token mancante o non valido | | 403 Forbidden | Permessi insufficienti | Autenticazione valida ma non consentita | | 404 Not Found | La risorsa non esiste | ID o percorso non valido | | 422 Unprocessable Entity | Errore di validazione | Errori semantici in JSON valido | | 429 Too Many Requests | Limite di richieste raggiunto | Client che supera i limiti | | 500 Internal Server Error | Errore lato server | Errori imprevisti |

Formato di risposta di errore standard

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body contains invalid fields",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "code": "INVALID_FORMAT"
      },
      {
        "field": "age",
        "message": "Must be a positive integer",
        "code": "OUT_OF_RANGE"
      }
    ]
  }
}

Risorse annidate

Rappresentare le relazioni

Le API REST devono spesso rappresentare risorse correlate. Ecco i pattern comuni:

Embedded (caricamento eager):

{
  "order": {
    "id": 5001,
    "total": 29.99,
    "customer": {
      "id": 123,
      "name": "Alice",
      "email": "alice@example.com"
    },
    "items": [
      {
        "productId": 42,
        "name": "Widget",
        "quantity": 2,
        "price": 14.99
      }
    ]
  }
}

Referenziato (caricamento lazy) -- usa gli ID e fornisci endpoint separati:

{
  "order": {
    "id": 5001,
    "total": 29.99,
    "customerId": 123,
    "itemIds": [101, 102]
  }
}

Regola pratica: Incorpora i dati correlati che servono sempre insieme. Fai riferimento ai dati recuperati in modo condizionale o in un momento diverso.

Pattern di paginazione

Quando restituisci elenchi di risorse, la paginazione è essenziale. Usa un formato di paginazione coerente:

Paginazione basata su offset

{
  "status": "success",
  "data": [
    { "id": 1, "name": "User 1" },
    { "id": 2, "name": "User 2" }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "totalItems": 156,
    "totalPages": 8,
    "links": {
      "first": "/api/users?page=1&perPage=20",
      "prev": null,
      "next": "/api/users?page=2&perPage=20",
      "last": "/api/users?page=8&perPage=20"
    }
  }
}

Paginazione basata su cursore (consigliata per grandi set di dati)

{
  "status": "success",
  "data": [
    { "id": 100, "name": "User 100" },
    { "id": 101, "name": "User 101" }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6MTAxfQ==",
    "hasMore": true
  }
}

La paginazione basata su cursore è più affidabile per i dati in tempo reale in cui i nuovi record potrebbero spostare i confini delle pagine.

JSON nelle richieste API

Body delle richieste POST / PUT

Accetta JSON con l'header Content-Type: application/json:

{
  "title": "New Blog Post",
  "content": "This is the content...",
  "tags": ["json", "rest-api"],
  "published": false
}

Aggiornamenti parziali con PATCH

Usa PATCH per gli aggiornamenti parziali. Accetta solo i campi che dovrebbero cambiare:

// PATCH /api/users/123
{
  "email": "newemail@example.com"
}

Filtraggio, ordinamento e ricerca

Usa i parametri della query per la manipolazione dei dati, mantenendo pulito il body JSON:

GET /api/users?filter[role]=admin&sort=-createdAt&search=alice

{
  "status": "success",
  "data": [ /* filtered, sorted results */ ]
}

Limitazione della frequenza (rate limiting)

Includi le informazioni sul rate limit negli header della risposta e opzionalmente nel body JSON:

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later."
  },
  "meta": {
    "rateLimit": {
      "limit": 100,
      "remaining": 0,
      "resetAt": "2026-07-19T11:00:00Z"
    }
  }
}

Elenco di controllo delle buone pratiche JSON

[ ] Usa una denominazione delle chiavi coerente (camelCase o snake_case in tutto)
[ ] Restituisci codici di stato HTTP appropriati con ogni risposta
[ ] Includi un formato di errore coerente con codici di errore leggibili dalle macchine
[ ] Pagina gli endpoint degli elenchi con un oggetto di paginazione standardizzato
[ ] Usa JSON Schema per documentare e validare le strutture di richiesta/risposta
[ ] Imposta Content-Type: application/json su tutti gli endpoint JSON
[ ] Comprimi le risposte JSON con gzip o brotli in produzione
[ ] Imponi limiti massimi della dimensione del payload (ad es., 1MB predefinito)
[ ] Usa HTTPS per crittografare i dati JSON in transito
[ ] Struttura i dettagli degli errori per aiutare i client a eseguire il debug senza esporre le parti interne

Validare il JSON della tua API

Esegui le risposte della tua API attraverso un validatore JSON per individuare gli errori di formattazione prima che raggiungano i client. Risposte JSON coerenti e valide rendono la tua API affidabile e facile per gli sviluppatori. Usa il nostro strumento Formattatore & Validatore JSON per testare i tuoi payload durante lo sviluppo.