La maggior parte delle app Web moderne comunica continuamente con un server. L’API JavaScript Fetch è il modo standard per farlo ed è integrata nei browser e in Node.js 18 e versioni successive, quindi non c’è nulla da installare.

L’utilizzo di base richiede due righe, ma molti tutorial si fermano qui e tralasciano la parte che causa veri bug: la gestione degli errori. Abbiamo testato gli esempi in questa guida su un piccolo server locale su Node.js 24 e l’output mostrato proviene da quell’esecuzione. example.com nel codice indica la tua API. Se le promesse sono nuove per te, inizia con Spiegazione delle promesse JavaScript.

Cos’è l’API di recupero?

Fetch è un’interfaccia basata su promesse per effettuare richieste HTTP. Ha sostituito il vecchio, basato sul callback XMLHttpRequest, e molti progetti ora lo utilizzano invece di aggiungere una libreria per semplici chiamate.

Una richiesta GET

Fetch effettua una richiesta GET per impostazione predefinita. Ci sono due passaggi e ognuno richiede await: prima arrivano le intestazioni della risposta e poi si legge il corpo.

const response = await fetch("https://example.com/users/1");
const user = await response.json();

console.log(user);

// { id: 1, name: 'Asha' }

I due passaggi esistono perché il corpo può essere grande e arrivare dopo le intestazioni. In uno script del browser, il livello superiore await necessita di un modulo, quindi di solito lo inserirai all’interno di una funzione async. Consulta la nostra guida JavaScript async/await.

L’oggetto Risposta

Prima di leggere il corpo, puoi esaminare la risposta:

console.log(response.status, response.ok, response.headers.get("content-type"));

// 200 true application/json

Un corpo può essere letto una sola volta. Chiamare json() una seconda volta non è riuscito nel nostro test:

await res.json();
await res.json();

// TypeError: Body is unusable: Body has already been read

Se hai bisogno di leggerlo due volte, chiama prima response.clone().

La grande sorpresa: un 404 non lancia

Questa è la cosa più importante in questo articolo. Abbiamo richiesto un utente che non esiste:

const res = await fetch("https://example.com/users/999");
console.log(res.status, res.ok);

// 404 false

Non è stata lanciata alcuna eccezione. Per quanto riguarda il fetch la richiesta ha funzionato: il server è stato raggiunto e ha risposto. La promessa viene rifiutata solo quando non arriva alcuna risposta utilizzabile, come nel caso di un guasto della rete. Quindi un codice come questo ha un bug nascosto:

try {
  const res = await fetch(url);
  const data = await res.json();   // may be an error payload
  showUser(data);                  // runs anyway for 404 and 500
} catch (error) {
  showError();                     // does not run for 404 or 500
}

Controlla il nostro trucco sui codici di stato HTTP per vedere il significato di ciascun codice.

Un aiuto riutilizzabile

Non ripetere il controllo ovunque. Avvolgilo una volta:

async function getJson(url, options) {
  const response = await fetch(url, options);
  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }
  return response.json();
}

try {
  await getJson("https://example.com/users/999");
} catch (error) {
  console.log("caught:", error.message);
}

// caught: Request failed with status 404

Ora gli errori HTTP e gli errori di rete finiscono entrambi nello stesso catch. Vale la pena avere questa piccola funzione in ogni progetto. Una versione reale potrebbe anche leggere un messaggio di errore dal corpo della risposta e gestire una risposta 204 No Content, che non ha JSON da analizzare.

POSTARE dati JSON

Passa un oggetto opzioni come secondo argomento. Per JSON, devi fare due cose tu stesso: convertire i dati in una stringa e impostare l’intestazione.

const created = await getJson("https://example.com/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Ben" }),
});

console.log(created);

// { id: 2, name: 'Ben', type: 'application/json' }

Il nostro server di test ha risposto al tipo di contenuto ricevuto, confermando l’arrivo dell’intestazione. Dimenticare quell’intestazione è una causa comune di errori del server confusi, perché molti framework analizzano JSON solo quando viene dichiarato. Per caricare un modulo o file, passa un oggetto FormData come corpo e non imposta Content-Type, poiché il browser stesso deve aggiungere un valore limite.

Altri metodi e opzioni

Scegliere tra REST e altri stili API? Il nostro confronto tra REST e GraphQL mostra come il recupero si adatta a ciascuno.

Stringhe di query

Non creare stringhe di query unendo il testo, perché i caratteri speciali le interromperebbero. URLSearchParams gestisce la codifica per te:

const params = new URLSearchParams({ q: "red shoes", page: 2 });
console.log(params.toString());

// q=red+shoes&page=2

await getJson(`https://example.com/search?${params}`);

// { q: 'red shoes', page: '2' }

Il server ha ricevuto red shoes correttamente, con lo spazio ripristinato.

Timeout e annullamento

Fetch attenderà a lungo su un server lento a meno che tu non dica diversamente. AbortSignal.timeout() stabilisce un limite. Il nostro endpoint di test ha impiegato due secondi, contro un limite di 200 millisecondi:

try {
  await fetch("https://example.com/slow", { signal: AbortSignal.timeout(200) });
} catch (error) {
  console.log(error.name);
}

// TimeoutError

Per annullare manualmente, ad esempio quando un utente lascia una pagina o digita un nuovo termine di ricerca, utilizza un AbortController:

const controller = new AbortController();
const pending = fetch("https://example.com/slow", { signal: controller.signal });

controller.abort();

try {
  await pending;
} catch (error) {
  console.log(error.name);
}

// AbortError

Per eseguire più richieste contemporaneamente, utilizzare Promise.all, che è molto più veloce che attenderle una alla volta:

const [user, search] = await Promise.all([
  getJson("https://example.com/users/1"),
  getJson("https://example.com/search?q=a&page=1"),
]);

Ogni tipo di fallimento

Ecco come appariva ogni fallimento nella nostra corsa, insieme a come distinguerli:

Quest’ultima riga è comune nella produzione. Un proxy che restituisce un 502 invia spesso una pagina di errore HTML. Lo abbiamo riprodotto e res.json() ha lanciato un SyntaxError. Controllare response.ok prima dell’analisi significa segnalare il problema reale piuttosto che un errore di analisi confuso.

CORS e credenziali

In un browser, una richiesta da un’origine a un’altra è soggetta a CORS, le regole di condivisione delle risorse tra origini. Se vedi un errore che menziona Access-Control-Allow-Origin, la correzione appartiene al server, che deve consentire il tuo sito. Nel tuo JavaScript, l’errore viene visualizzato solo come generico TypeError, quindi cerca il motivo effettivo nella console del browser. Node.js non applica CORS, quindi una richiesta che funziona in uno script può comunque fallire nel browser.

Per impostazione predefinita, i browser non inviano cookie su richieste multiorigine. Imposta credentials: "include" se ne hai bisogno e assicurati che il server lo consenta. Non inserire mai chiavi API segrete nel JavaScript del browser, poiché chiunque può leggerle. Tienili sul tuo server.

Errori comuni

• Non controllare response.ok. Le risposte agli errori vengono trattate come riuscite.
• Dimenticare il secondo await. response.json() restituisce anche una promessa.
• Dimenticare JSON.stringify. Passare un oggetto mentre il corpo invia [object Object].
• Impostazione Content-Type con FormData. Questo rompe il confine, quindi lascialo fuori.
• Non esiste timeout. Una richiesta sospesa può lasciare lo spinner di una pagina in esecuzione per un tempo indefinito.
• Analisi JSON per una risposta vuota. Un 204 non ha corpo e json() genererà un’eccezione.

Considerazioni finali

Il recupero è semplice una volta ricordata la sua regola principale: una risposta non è la stessa cosa di un successo. Copia il piccolo helper nel tuo progetto, aggiungi un timeout e testa i tuoi percorsi di errore. Come passaggio successivo, crea una piccola pagina che carichi i dati da un’API, mostri un messaggio di errore chiaro e consenta all’utente di annullare una ricerca lenta.

Domande frequenti

Continua a imparare