JavaScript Fetch API

La Fetch API è una funzionalità fondamentale di JavaScript che consente di effettuare richieste di rete (scaricare dati, inviare form, comunicare con le API) e restituisce una Promise. È il moderno sostituto del vecchio XMLHttpRequest e si abbina naturalmente con async/await. Questa guida tratta i pattern più comuni: richieste GET e POST, ispezione della risposta, lettura di JSON e testo, invio di header e gestione degli errori — con esempi eseguibili che utilizzano la API gratuita JSONPlaceholder.

Comprendere la Fetch API

La Fetch API è progettata per la comunicazione di rete e utilizza un sistema basato su promise per recuperare le risorse. È abbastanza flessibile da gestire diversi formati di dati e richieste complesse, rendendola una scelta eccellente per lo sviluppo di applicazioni web.

La firma di base è fetch(url, options). Restituisce una promise che si risolve in un oggetto Response non appena il server risponde con gli header — prima che il body abbia terminato il download. Successivamente si legge il body separatamente con un metodo come .json() o .text(), ognuno dei quali restituisce la propria promise.

Un aspetto critico da tenere a mente: fetch() viene rigettata soltanto in caso di errore di rete (nessuna connessione, errore DNS, blocco CORS). Non viene rigettata per status HTTP di errore come 404 o 500 — questi si risolvono comunque con successo. Occorre quindi verificare response.ok (o response.status) manualmente.

Utilizzo di base di Fetch

Vediamo un esempio di base per recuperare dati da un post di JSONPlaceholder:

Questo snippet recupera i dati da un post specifico, dimostrando come Fetch restituisca una promise che si risolve nella risposta della richiesta. La risposta viene poi analizzata come JSON e mostrata nella console.

Ispezione della risposta

L'oggetto Response contiene metadati utili prima ancora di leggere il body. Le proprietà più importanti sono:

• response.ok — un boolean che è true per codici di stato compresi tra 200 e 299.
• response.status — il codice di stato HTTP numerico (ad es. 200, 404, 500).
• response.statusText — il messaggio testuale associato allo status (ad es. "OK").
• response.headers — un oggetto Headers che si può interrogare con .get().

Lettura del body: .json() vs .text()

Il body di una risposta può essere letto in diversi formati. Ogni metodo restituisce una promise e può essere chiamato una sola volta per risposta — il body è uno stream che viene consumato:

• response.json() — analizza il body come JSON e si risolve in un object o array JavaScript.
• response.text() — si risolve nel body grezzo come string. Utile per testo semplice, HTML, o quando si vuole gestire autonomamente il parsing del JSON.
• response.blob() — si risolve in un Blob, per dati binari come immagini o file.

Gestione degli errori in Fetch

La gestione degli errori è fondamentale quando si lavora con richieste di rete. Poiché fetch() non genera eccezioni per gli status HTTP di errore, il pattern standard prevede di verificare response.ok e lanciare un errore personalizzato quando è false. Ecco un esempio con la gestione degli errori:

In questo esempio verifichiamo se la risposta ha avuto successo; in caso contrario, viene lanciato un errore. Il metodo .catch() intercetta qualsiasi errore, preservando l'integrità dell'applicazione.

Implementare una richiesta POST

La Fetch API non si limita alle richieste GET; è altrettanto capace di gestire richieste POST per inviare dati a un server. Si passa un secondo argomento con method, un body e gli headers. Quando si invia JSON, è necessario sia serializzare il body con JSON.stringify() sia impostare l'header Content-Type in modo che il server sappia come analizzarlo. Ecco come creare un nuovo post con JSONPlaceholder:

Questo snippet dimostra l'invio di una richiesta POST con dati JSON, specificando il metodo, il body e gli header. Illustra la versatilità della Fetch API nel gestire diversi tipi di richiesta.

Invio di header di richiesta personalizzati

Gli header servono a informare il server sulla richiesta — il tipo di contenuto, il formato di risposta atteso o le credenziali di autenticazione come un bearer token. Puoi passare gli header come oggetto semplice, oppure costruirli con la classe Headers per maggiore controllo:

Nota: una richiesta verso un'altra origine avrà successo soltanto se quel server lo consente tramite CORS. Consulta Fetch: Richieste Cross-Origin per capire come le regole cross-origin influenzano header e credenziali.

Utilizzare Async/Await con Fetch

Per un approccio più elegante al codice asincrono, la Fetch API può essere combinata con async e await. Questo metodo offre una sintassi più leggibile, simile al codice sincrono:

Usando async e await, questo esempio recupera un post, attendendo la risposta e processandola all'interno di un blocco try/catch per la gestione degli errori. Mostra come le funzionalità moderne di JavaScript possano semplificare l'uso della Fetch API.

Gestione degli errori con Async/Await

Quando si tratta di gestione degli errori in async/await, si ricorre tipicamente ai blocchi try-catch.

Per gestire gli errori che possono verificarsi durante le operazioni asincrone, puoi racchiudere le chiamate await all'interno di un blocco try e intercettare gli errori con un blocco catch. Ecco come aggiungere la gestione degli errori alla funzione fetchData:

Propagazione degli errori

La propagazione degli errori è il modo in cui un errore "si muove" o viene trasmesso da una parte del programma a un'altra. Pensala come il percorso che un errore compie dopo che si è verificato. Quando si verifica un errore, è come far cadere una palla. La propagazione degli errori riguarda dove va la palla dopo essere caduta: qualcuno la raccoglie, o tocca terra?

In JavaScript, questo avviene tipicamente tramite il concatenamento di rigetti delle promise, dove un rigetto non gestito risale lo stack delle chiamate finché un blocco catch o un gestore globale lo intercetta.

Nell'esempio seguente, se si vuole che gli errori siano gestiti dalla funzione chiamante (come viewData), occorre evitare di intercettarli in fetchData oppure rilanciare l'errore dopo averlo catturato:

Come si vede, lo stesso oggetto errore viene catturato in entrambe le funzioni perché viene rilanciato da fetchData a viewData.

Argomenti correlati

Per approfondire la Fetch API, esplora questi capitoli correlati:

• JavaScript Promise — le fondamenta su cui è costruita Fetch.
• Async/Await — il modo più pulito per scrivere chiamate Fetch.
• Fetch: Abort — annullare una richiesta con AbortController (utile per timeout e ricerca durante la digitazione).
• Fetch: Richieste Cross-Origin — come CORS controlla le richieste verso altri domini.

Conclusione

La Fetch API è uno strumento indispensabile per gli sviluppatori JavaScript, che arricchisce le applicazioni web grazie al suo approccio basato su promise per le richieste di rete. Attraverso esempi pratici, questa guida mostra come la Fetch API possa essere utilizzata efficacemente per recuperare dati, gestire errori ed effettuare richieste POST, sfruttando la API JSONPlaceholder per applicazioni reali. Padroneggiare la Fetch API permette agli sviluppatori di creare applicazioni web più reattive, dinamiche e robuste.

Esercitazione