Fetch API in JavaScript: richieste, JSON ed errori

Fetch è un client HTTP basato sulle promise

fetch è integrato nei browser e nelle versioni moderne di Node. Gli passi un URL e ti restituisce una Promise che si risolve in un oggetto Response. Nella sua essenza, l'API è tutta qui:

fetch("https://jsonplaceholder.typicode.com/todos/1")
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(err => console.error("errore:", err));

Ci sono due .then perché i passaggi asincroni sono due: prima arrivano gli header della risposta (è con questi che si risolve la prima promise), poi il body viene letto e analizzato (response.json() è a sua volta una promise). Il body non viene scaricato finché non lo chiedi.

Lo stesso flusso con async/await si legge come normale codice dall'alto in basso:

async function loadTodo() {
    const response = await fetch("https://jsonplaceholder.typicode.com/todos/1");
    const data = await response.json();
    console.log(data);
}

loadTodo();

Due await, due punti di sospensione. Lo stesso lavoro, con un ordine di lettura più chiaro.

L'oggetto Response

Quello che ricevi non è il body: è un oggetto Response con dei metadati e dei metodi per leggere il body in formati diversi:

async function inspect() {
    const response = await fetch("https://jsonplaceholder.typicode.com/todos/1");

    console.log(response.status);       // 200
    console.log(response.ok);           // true for 200-299
    console.log(response.headers.get("content-type"));

    const data = await response.json();
    console.log(data.title);
}

inspect();

Puoi leggere il body con .json(), .text(), .blob(), .arrayBuffer() o .formData(). Ognuno restituisce una promise. Il body si può leggere una volta sola: se chiami .json() due volte sulla stessa risposta, la seconda chiamata lancia un errore.

Il grande tranello: gli errori HTTP non rifiutano la promise

Questo inganna quasi tutti all'inizio con fetch. Una risposta 404 o 500 non è un rifiuto. La promise si risolve normalmente, con response.ok === false. Fetch rifiuta solo quando la richiesta stessa non è riuscita a completarsi: errore DNS, niente rete, blocco CORS.

Quindi un fetch ingenuo ti passa senza problemi una pagina di errore e poi va in crash più avanti su .json():

async function buggy() {
    // This URL returns 404, but fetch resolves anyway.
    const response = await fetch("https://jsonplaceholder.typicode.com/nope/999");
    const data = await response.json();    // might explode or return garbage
    console.log(data);
}

buggy();

La soluzione è controllare tu response.ok e lanciare un errore se il server ha restituito uno status di errore:

async function loadTodo(id) {
    const response = await fetch(`https://jsonplaceholder.typicode.com/todos/${id}`);

    if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return response.json();
}

loadTodo(1).then(console.log).catch(err => console.error(err.message));

Abituati a scrivere quel blocco if (!response.ok). Va messo in ogni wrapper di fetch che scrivi.

Inviare una richiesta POST

GET è il metodo predefinito. Per qualsiasi altro, passa un secondo argomento, un oggetto di opzioni:

async function createPost() {
    const response = await fetch("https://jsonplaceholder.typicode.com/posts", {
        method: "POST",
        headers: {
            "Content-Type": "application/json"
        },
        body: JSON.stringify({
            title: "hello",
            body: "from fetch",
            userId: 1
        })
    });

    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const data = await response.json();
    console.log(data);
}

createPost();

Tre cose da notare:

• method vale "GET" per impostazione predefinita. Impostalo esplicitamente per POST, PUT, DELETE e PATCH.
• body accetta una stringa (oppure FormData, Blob, ecc.): fetch non serializza gli oggetti per te. Il JSON.stringify(...) tocca a te.
• L'header Content-Type dice al server come interpretare il body. Se lo dimentichi, la maggior parte dei server tratterà il body come testo semplice.

Header, query string e altre opzioni

Gli header sono semplicemente un oggetto (o un'istanza di Headers). Le query string le costruisci tu, di solito con URLSearchParams:

async function search(query, token) {
    const params = new URLSearchParams({ q: query, limit: "10" });
    const url = `https://api.example.com/search?${params}`;

    const response = await fetch(url, {
        headers: {
            "Authorization": `Bearer ${token}`,
            "Accept": "application/json"
        }
    });

    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response.json();
}

URLSearchParams si occupa della codifica al posto tuo (spazi, e commerciali, unicode), così non ti ritrovi con URL rotti quando l'input contiene caratteri da fare l'escape.

Altre opzioni che vedrai nel codice reale: credentials: "include" per inviare i cookie tra origini diverse, cache: "no-store" per saltare la cache HTTP, mode: "cors" (di solito il valore predefinito) per controllare il comportamento CORS.

Annullare una richiesta con AbortController

A volte vuoi rinunciare: l'utente ha digitato una nuova ricerca, oppure la richiesta ci mette troppo. Il meccanismo è AbortController:

async function loadWithTimeout(url, ms) {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), ms);

    try {
        const response = await fetch(url, { signal: controller.signal });
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        return await response.json();
    } finally {
        clearTimeout(timeout);
    }
}

loadWithTimeout("https://jsonplaceholder.typicode.com/todos/1", 3000)
    .then(console.log)
    .catch(err => console.error(err.name, err.message));

controller.abort() fa rifiutare la promise di fetch con una DOMException il cui name è "AbortError". Il blocco finally cancella il timeout, così una richiesta andata a buon fine non lascia in giro un timer pendente.

Questo schema (fetch più timeout più pulizia) merita di essere racchiuso in un helper da riutilizzare ovunque.

Un wrapper riutilizzabile

Mettendo tutto insieme ottieni un piccolo helper che gestisce il codice ripetitivo una volta per tutte:

async function apiRequest(url, options = {}) {
    const response = await fetch(url, {
        headers: { "Content-Type": "application/json", ...options.headers },
        ...options
    });

    if (!response.ok) {
        const text = await response.text();
        throw new Error(`HTTP ${response.status}: ${text || response.statusText}`);
    }

    if (response.status === 204) return null;   // No Content
    return response.json();
}

apiRequest("https://jsonplaceholder.typicode.com/todos/1")
    .then(console.log)
    .catch(err => console.error(err.message));

Un solo punto per cambiare gli header, uno per gestire gli errori, uno per occuparsi delle risposte vuote. Ogni applicazione non banale finisce per avere qualcosa del genere.

Prossimo argomento: gestione degli errori nel codice asincrono

Fetch è uno dei posti in cui gli errori asincroni saltano fuori più spesso, e il controllo di response.ok è solo un pezzo del puzzle. La prossima pagina parla della gestione degli errori con le promise e async/await: dove finiscono gli errori, come catturarli e le trappole che li lasciano passare in silenzio.