Axios: cosìì, richieste HTTP e basi del lavoro con API

Cosìì Axios?

Axios è una libreria JavaScript progettata per effettuare richieste HTTP dal browser e dall´ambiente Node.js. È costruita su XMLHttpRequest nel browser e sul modulo http in Node.js, fornendo un´API unificata per entrambe le piattaforme.

Il principale vantaggio di Axios rispetto al fetch nativo è la gestione automatica del JSON, il supporto agli intercettori e una gestione degli errori più comoda. A differenza di fetch, Axios non richiede due chiamate .then per ottenere il corpo JSON della risposta e lancia automaticamente eccezioni in caso di errori HTTP (4xx, 5xx).

La libreria supporta tutti i principali metodi HTTP: GET, POST, PUT, DELETE, PATCH e HEAD. Può essere utilizzata sia in progetti semplici che in grandi applicazioni aziendali con centinaia di migliaia di richieste giornaliere.

Caratteristiche principali di Axios

• Promise API — tutte le operazioni restituiscono una Promise, semplificando il codice asincrono
• Supporto TypeScript — tipizzazione completa per tutti i metodi e configurazioni
• Intercettori — middleware per elaborare richieste e risposte
• Trasformazione — trasformazione automatica dei dati in ingresso e uscita

Architettura di Axios e principio di funzionamento

L´architettura di Axios si basa sul concetto di adattatori. La libreria astrae il livello di trasporto: utilizza XMLHttpRequest nel browser e il modulo http o https in Node.js. Ciò fornisce un´interfaccia unica indipendentemente dall´ambiente di esecuzione.

Ogni richiesta attraversa una catena di intercettori che possono modificare la configurazione della richiesta o della risposta. Dopo gli intercettori, la richiesta viene passata all´adattatore, che esegue la chiamata HTTP effettiva. La risposta attraversa poi gli intercettori di risposta prima di raggiungere il codice dell´applicazione.

Ciclo di vita di una richiesta Axios

1. Creazione configurazione — metodo, URL, intestazioni, corpo della richiesta
2. Intercettore di richiesta — modifica configurazione, aggiunta token
3. Chiamata HTTP — esecuzione tramite adattatore browser o Node.js
4. Intercettore di risposta — trasformazione risposta, gestione errori
5. Restituzione risultato — Promise risolta con dati o respinta

Principali funzionalità di Axios

Axios include molte funzionalità integrate che lo rendono una scelta comoda per lavorare con HTTP in applicazioni mobili e web. Esaminiamo le principali.

Trasformazione automatica dei dati

Durante l´invio di una richiesta, Axios trasforma automaticamente un oggetto JavaScript in una stringa JSON utilizzando JSON.stringify. Durante la ricezione di una risposta, la libreria converte il JSON nuovamente in un oggetto. Ciò evita allo sviluppatore la serializzazione e deserializzazione manuale dei dati.

Protezione CSRF

Nell´ambiente browser, Axios aggiunge automaticamente le intestazioni XSRF-TOKEN dai cookie, proteggendo l´applicazione dalla falsificazione di richieste cross-site. Per farlo, basta configurare il server per inviare il token in un cookie chiamato XSRF-TOKEN.

Timeout e annullamento richieste

La libreria supporta l´impostazione di un timeout tramite il parametro timeout e l´annullamento della richiesta tramite AbortController. Ciò è particolarmente importante nelle applicazioni mobili con connessioni instabili, dove le richieste bloccate consumano batteria e dati.

Installazione e configurazione di Axios

L´installazione di Axios viene effettuata tramite qualsiasi gestore di pacchetti. La libreria è disponibile nel registro npm e può essere utilizzata sia in progetti Node.js che browser. Per TypeScript, i tipi sono inclusi nel pacchetto principale — non sono necessarie dipendenze aggiuntive.

Dopo l´installazione, puoi creare un´istanza con una configurazione di base: URL base, timeout predefinito, intestazioni comuni. Ciò evita di ripetere gli stessi parametri in ogni richiesta e consente di gestire centralmente le impostazioni del client HTTP.

# Installare tramite npm
npm install axios

# Installare tramite yarn
yarn add axios

# Installare tramite pnpm
pnpm add axios

Creazione di un´istanza con configurazione

Si consiglia di creare un´istanza separata di Axios per ogni servizio API. Ciò permette di impostare un URL base, intestazioni standard e timeout che verranno applicati a tutte le richieste di questa istanza senza ripeterli in ogni chiamata.

import axios from 'axios';

const api = axios.create({
  baseURL: 'https://api.example.com/v1',
  timeout: 10000,
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  }
});

Esempi di codice con Axios

Gli esempi di richieste mostrano i principali modelli di utilizzo di Axios. Tutti gli esempi utilizzano la sintassi async/await, che rende il codice asincrono più leggibile rispetto alle catene .then().

Richiesta GET con parametri

Per ottenere dati dal server, viene utilizzato il metodo axios.get. I parametri della richiesta vengono passati tramite l´oggetto params, che viene automaticamente trasformato in una query string. La risposta contiene i dati nel campo data, lo stato in status e le intestazioni in headers.

interface User {
  id: number;
  name: string;
  email: string;
}

async function getUsers() {
  try {
    const response = await api.get<User[]>('/users', {
      params: { page: 1, limit: 10 }
    });
    return response.data;
  } catch (error) {
    console.error('Errore caricamento utenti', error);
    throw error;
  }
}

Richiesta POST con corpo

Per inviare dati al server, viene utilizzato axios.post. Il secondo argomento è un oggetto con dati, che Axios serializza automaticamente in JSON. Il Content-Type viene impostato su application/json per impostazione predefinita.

interface CreateUserDto {
  name: string;
  email: string;
  role: string;
}

async function createUser(data: CreateUserDto) {
  const response = await api.post<User>('/users', data);
  return response.data;
}

Intercettori

Gli intercettori sono funzioni middleware che vengono eseguite per ogni richiesta o risposta. Permettono di aggiungere token di autorizzazione, registrare richieste e gestire errori centralmente. Un intercettore di richiesta aggiunge l´intestazione Authorization con un token recuperato dall´archivio.

// Intercettore di richiesta — aggiunge token di autorizzazione
api.interceptors.request.use(
  (config) => {
    const token = getToken();
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  (error) => Promise.reject(error)
);

// Intercettore di risposta — gestisce errori 401
api.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      redirectToLogin();
    }
    return Promise.reject(error);
  }
);

Gestione degli errori in Axios

La gestione degli errori in Axios si basa sul meccanismo delle eccezioni. A differenza di fetch, Axios intercetta automaticamente gli errori HTTP (4xx, 5xx) e li passa al blocco catch. L´oggetto errore contiene informazioni sulla risposta del server, sulla richiesta e sul contesto di esecuzione.

È importante distinguere tre tipi di errori: errore di risposta del server (response), errore di richiesta (request) ed errore di configurazione (config). Il primo si verifica quando una chiamata HTTP viene eseguita con successo ma restituisce un codice di errore, il secondo quando non cè risposta dal server, e il terzo quando la configurazione della richiesta non è valida.

import axios, { AxiosError } from 'axios';

async function safeRequest() {
  try {
    return await api.get('/data');
  } catch (error) {
    if (error instanceof AxiosError) {
      if (error.response) {
        console.warn('Errore di risposta', error.response.status);
      } else if (error.request) {
        console.warn('Nessuna risposta dal server');
      } else {
        console.warn('Errore di configurazione');
      }
    }
  }
}

Confronto di Axios con Fetch API

Il confronto di Axios con la Fetch API nativa aiuta a capire quando ogni tecnologia è appropriata. Fetch è un´API integrata nel browser che non richiede installazione. Axios è una libreria di terze parti con funzionalità aggiuntive. Per richieste semplici, fetch è sufficiente; per applicazioni complesse con intercettori e gestione centralizzata degli errori, Axios è più comodo.

Fetch non considera gli errori HTTP (4xx, 5xx) come eccezioni — bisogna verificare response.ok. Fetch richiede due chiamate .then() per ottenere il JSON: response.json() restituisce poi una Promise con i dati. Axios lo fa automaticamente. Fetch non supporta il progresso del caricamento file senza polyfill aggiuntivi. Axios ha onUploadProgress e onDownloadProgress integrati.

In Node.js, Fetch è disponibile dalla versione 18 come funzionalità sperimentale, mentre Axios funziona stabilmente da Node.js 10. Per i progetti che supportano versioni precedenti di Node.js, la scelta è chiaramente a favore di Axios. Per progetti browser moderni senza elaborazione complessa delle richieste, fetch può essere sufficiente.