Convenzioni comuni delle risposte

Le API seguono, nella maggior parte dei casi, una struttura di risposta uniforme. Conoscere questa convenzione ti aiuta a leggere più velocemente la documentazione tecnica e a scrivere integrazioni più semplici da mantenere.

La regola generale è questa: quasi tutti gli endpoint applicativi restituiscono una risposta JSON con quattro campi principali:

{
  "error": 0,
  "message": "",
  "data": {},
  "meta": {}
}

Questa struttura è molto utile perché rende prevedibile il modo in cui leggere il risultato di una chiamata, anche quando cambia il contenuto effettivo di data.

La struttura standard

error

Il campo error indica se la chiamata è andata a buon fine.

• 0 significa che la richiesta è stata gestita correttamente;
• un valore maggiore di 0 indica un errore.

In caso di errore, il codice HTTP della risposta resta comunque il primo riferimento da controllare, ma il campo error ti permette di leggere il risultato in modo coerente anche lato applicazione.

message

Il campo message contiene un messaggio testuale associato alla risposta.

Nei casi di successo è spesso una stringa vuota, mentre nei casi di errore contiene normalmente una descrizione del problema.

data

Il campo data contiene il risultato vero e proprio della chiamata.

A seconda dell'endpoint, può essere:

• un oggetto singolo;
• un array di elementi;
• un oggetto vuoto, se l'operazione non deve restituire dettagli;
• in alcuni casi particolari, un valore nullo.

meta

Il campo meta contiene informazioni aggiuntive sulla risposta.

Nella maggior parte degli endpoint non paginati è un oggetto vuoto. Negli endpoint paginati, invece, contiene i dati di paginazione.

Esempio di risposta di successo

Una tipica risposta di successo per un endpoint che restituisce un singolo oggetto può avere questa forma:

{
  "error": 0,
  "message": "",
  "data": {
    "id": 123,
    "status": "active"
  },
  "meta": {}
}

In questo caso:

• error vale 0, quindi la chiamata è andata a buon fine;
• message non contiene informazioni particolari;
• data contiene il risultato richiesto;
• meta è presente ma vuoto.

Quando data è un array

Molti endpoint di elenco restituiscono un array dentro data.

Per esempio:

{
  "error": 0,
  "message": "",
  "data": [
    {
      "id": 101,
      "name": "Elemento A"
    },
    {
      "id": 102,
      "name": "Elemento B"
    }
  ],
  "meta": {
    "total": 45,
    "count": 2,
    "pages": 23,
    "page": 1,
    "per_page": 2
  }
}

Qui il contenuto principale è l'array data, mentre meta descrive la paginazione.

Quando data è vuoto

Non tutte le operazioni devono restituire un contenuto dettagliato.

Per esempio, in alcune operazioni di cancellazione o applicazione di modifiche, puoi ricevere una risposta come questa:

{
  "error": 0,
  "message": "",
  "data": {},
  "meta": {}
}

Questo non significa che la chiamata sia incompleta: significa semplicemente che l'operazione è stata eseguita correttamente e non c'è un payload aggiuntivo da leggere.

Quando data contiene un task

In alcuni endpoint, soprattutto quando l'operazione può richiedere tempo o viene gestita in modo asincrono, data non contiene direttamente la risorsa finale ma un oggetto Task.

In questi casi la risposta va interpretata così:

• la richiesta è stata accettata;
• l'elaborazione è stata avviata;
• il risultato finale potrebbe non essere immediatamente disponibile.

Per chi integra le API, è importante non dare per scontato che ogni 200 OK significhi "operazione già completata": a volte significa invece "operazione presa in carico correttamente".

Il ruolo di meta

Il campo meta non va ignorato, anche quando non ti serve subito.

Può contenere:

• informazioni di paginazione standard, come total, count, pages, page e per_page;
• informazioni di navigazione limitata, come next, nei casi speciali in cui il totale non è noto;
• nessuna informazione aggiuntiva, quindi un oggetto vuoto.

Se stai sviluppando un client API, conviene sempre prevedere la lettura di meta, anche quando in un primo momento non lo utilizzi.

Come leggere correttamente una risposta

Un approccio pratico e affidabile è questo:

1. controlla il codice HTTP;
2. leggi error;
3. leggi message se presente;
4. interpreta data in base al tipo atteso;
5. usa meta se contiene informazioni utili, ad esempio per la paginazione.

Questo approccio evita errori comuni, come trattare data sempre come oggetto oppure ignorare meta negli endpoint che ne fanno uso.

Risposte di errore applicative

Quando una richiesta fallisce, la risposta segue normalmente questa struttura:

{
  "error": 400,
  "message": "Invalid request",
  "data": {},
  "meta": {}
}

In questo caso:

• error è maggiore di zero;
• message spiega il problema in forma testuale;
• data e meta sono presenti ma vuoti.

Dal punto di vista dell'integrazione, è utile mostrare o registrare il contenuto di message, ma conviene anche tenere traccia del codice HTTP ricevuto.

Le eccezioni più importanti

La struttura standard con error, message, data e meta è molto diffusa, ma non è universale. Ci sono alcune eccezioni importanti da conoscere.

Token OAuth2

L'endpoint /oauth/token non restituisce il wrapper standard applicativo.

La risposta contiene direttamente campi come:

• token_type;
• expires_in;
• access_token;
• refresh_token;
• scope;
• audience.

Questo comportamento è normale: segue il formato tipico delle risposte OAuth2.

Errori OAuth2

Anche gli errori dell'endpoint token seguono una struttura diversa, con campi come:

• error;
• error_description;
• error_uri.

In questo caso il campo error è una stringa, non un codice numerico come nelle risposte applicative standard.

Download di file

Gli endpoint che restituiscono file da scaricare non rispondono con il wrapper JSON standard in caso di successo.

Quando il download va a buon fine, la risposta contiene direttamente il file binario, ad esempio un PDF o un XML, insieme agli header HTTP del download.

Solo in caso di errore questi endpoint tornano normalmente a una risposta JSON di errore.

Endpoint particolari

Esistono anche alcuni casi particolari, come endpoint di servizio o diagnostica, in cui alcuni campi possono essere null oppure seguire una struttura leggermente diversa dal caso più comune.

Per questo motivo la documentazione tecnica dell'endpoint resta sempre il riferimento finale, soprattutto se stai gestendo un caso speciale.

Buone pratiche

• non assumere che data abbia sempre la stessa forma;
• non assumere che meta sia sempre vuoto;
• non leggere solo il codice HTTP ignorando il contenuto JSON;
• gestisci separatamente le eccezioni, come OAuth2 e download file;
• usa la documentazione tecnica del singolo endpoint per sapere cosa aspettarti in data.

In sintesi

La maggior parte delle API applicative restituisce risposte JSON con una convenzione semplice e uniforme:

• error indica l'esito;
• message fornisce un messaggio leggibile;
• data contiene il risultato;
• meta contiene informazioni accessorie, spesso legate alla paginazione.

Una volta compresa questa struttura, leggere le pagine tecniche e sviluppare un'integrazione diventa molto più immediato.