Axios: qué es, peticiones HTTP y fundamentos del trabajo con API

¿Qué es Axios?

Axios es una biblioteca de JavaScript diseñada para realizar solicitudes HTTP desde el navegador y el entorno Node.js. Está construida sobre XMLHttpRequest en el navegador y el módulo http en Node.js, proporcionando una API unificada para ambas plataformas.

La principal ventaja de Axios sobre el fetch nativo es el manejo automático de JSON, el soporte de interceptores y un manejo de errores más cómodo. A diferencia de fetch, Axios no requiere dos llamadas .then para obtener el cuerpo JSON de la respuesta y lanza excepciones automáticamente en errores HTTP (4xx, 5xx).

La biblioteca admite todos los métodos HTTP principales: GET, POST, PUT, DELETE, PATCH y HEAD. Puede utilizarse tanto en proyectos simples como en grandes aplicaciones empresariales con cientos de miles de solicitudes diarias.

Características clave de Axios

• Promise API — todas las operaciones devuelven una Promise, simplificando el código asíncrono
• Soporte TypeScript — tipado completo para todos los métodos y configuraciones
• Interceptores — middleware para procesar solicitudes y respuestas
• Transformación — transformación automática de datos en entrada y salida

Arquitectura de Axios y principio de funcionamiento

La arquitectura de Axios se basa en el concepto de adaptadores. La biblioteca abstrae la capa de transporte: utiliza XMLHttpRequest en el navegador y el módulo http o https en Node.js. Esto proporciona una interfaz única independientemente del entorno de ejecución.

Cada solicitud pasa a través de una cadena de interceptores que pueden modificar la configuración de la solicitud o la respuesta. Después de los interceptores, la solicitud se pasa al adaptador, que realiza la llamada HTTP real. La respuesta luego pasa a través de los interceptores de respuesta antes de llegar al código de la aplicación.

Ciclo de vida de una solicitud Axios

1. Creación de configuración — método, URL, cabeceras, cuerpo de la solicitud
2. Interceptor de solicitud — modificación de configuración, adición de tokens
3. Llamada HTTP — ejecución a través del adaptador del navegador o Node.js
4. Interceptor de respuesta — transformación de respuesta, manejo de errores
5. Devolución de resultado — Promise se resuelve con datos o se rechaza

Principales características de Axios

Axios incluye muchas características integradas que lo convierten en una opción conveniente para trabajar con HTTP en aplicaciones móviles y web. Veamos las principales.

Transformación automática de datos

Al enviar una solicitud, Axios transforma automáticamente un objeto JavaScript en una cadena JSON usando JSON.stringify. Al recibir una respuesta, la biblioteca convierte JSON nuevamente en un objeto. Esto evita que el desarrollador tenga que realizar serialización y deserialización manual de datos.

Protección CSRF

En el entorno del navegador, Axios agrega automáticamente las cabeceras XSRF-TOKEN de las cookies, protegiendo la aplicación contra falsificación de solicitudes entre sitios. Para ello, basta con configurar el servidor para que envíe el token en una cookie llamada XSRF-TOKEN.

Tiempos de espera y cancelación de solicitudes

La biblioteca admite el establecimiento de un tiempo de espera mediante el parámetro timeout y la cancelación de solicitudes a través de AbortController. Esto es especialmente importante en aplicaciones móviles con conexiones inestables, donde las solicitudes bloqueadas consumen batería y datos.

Instalación y configuración de Axios

La instalación de Axios se realiza a través de cualquier gestor de paquetes. La biblioteca está disponible en el registro npm y puede utilizarse tanto en proyectos Node.js como en proyectos de navegador. Para TypeScript, los tipos están incluidos en el paquete principal — no se requieren dependencias adicionales.

Después de la instalación, puede crear una instancia con una configuración básica: URL base, tiempo de espera predeterminado, cabeceras comunes. Esto permite no repetir los mismos parámetros en cada solicitud y gestionar de forma centralizada la configuración del cliente HTTP.

# Instalar mediante npm
npm install axios

# Instalar mediante yarn
yarn add axios

# Instalar mediante pnpm
pnpm add axios

Creación de una instancia con configuración

Se recomienda crear una instancia separada de Axios para cada servicio API. Esto permite establecer una URL base, cabeceras estándar y tiempo de espera que se aplicarán a todas las solicitudes de esta instancia sin repetirlos en cada llamada.

import axios from 'axios';

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

Ejemplos de código con Axios

Los ejemplos de solicitudes muestran los patrones principales de uso de Axios. Todos los ejemplos utilizan la sintaxis async/await, que hace que el código asíncrono sea más legible en comparación con las cadenas de .then().

Solicitud GET con parámetros

Para obtener datos del servidor se utiliza el método axios.get. Los parámetros de la solicitud se pasan mediante el objeto params, que se transforma automáticamente en una cadena de consulta. La respuesta contiene los datos en el campo data, el estado en status y las cabeceras en 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('Error al cargar usuarios', error);
    throw error;
  }
}

Solicitud POST con cuerpo

Para enviar datos al servidor se utiliza axios.post. El segundo argumento es un objeto con datos, que Axios serializa automáticamente a JSON. El tipo de contenido Content-Type se establece en application/json por defecto.

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

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

Interceptores

Los interceptores son funciones middleware que se ejecutan para cada solicitud o respuesta. Permiten agregar tokens de autorización, registrar solicitudes y manejar errores de forma centralizada. Un interceptor de solicitud agrega la cabecera Authorization con un token obtenido del almacenamiento.

// Interceptor de solicitud — agrega token de autorización
api.interceptors.request.use(
  (config) => {
    const token = getToken();
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  (error) => Promise.reject(error)
);

// Interceptor de respuesta — maneja errores 401
api.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      redirectToLogin();
    }
    return Promise.reject(error);
  }
);

Manejo de errores en Axios

El manejo de errores en Axios se basa en el mecanismo de excepciones. A diferencia de fetch, Axios captura automáticamente los errores HTTP (4xx, 5xx) y los pasa al bloque catch. El objeto de error contiene información sobre la respuesta del servidor, la solicitud y el contexto de ejecución.

Es importante distinguir tres tipos de errores: error de respuesta del servidor (response), error de solicitud (request) y error de configuración (config). El primero ocurre cuando la llamada HTTP se ejecuta con éxito pero devuelve un código de error, el segundo cuando no hay respuesta del servidor, y el tercero cuando la configuración de la solicitud es incorrecta.

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('Error de respuesta', error.response.status);
      } else if (error.request) {
        console.warn('Sin respuesta del servidor');
      } else {
        console.warn('Error de configuración');
      }
    }
  }
}

Comparación de Axios con Fetch API

La comparación de Axios con la Fetch API nativa ayuda a entender cuándo es adecuada cada tecnología. Fetch es una API integrada en el navegador que no requiere instalación. Axios es una biblioteca externa con funcionalidades adicionales. Para solicitudes simples, fetch es suficiente; para aplicaciones complejas con interceptores y manejo centralizado de errores, Axios es más conveniente.

Fetch no considera los errores HTTP (4xx, 5xx) como excepciones — hay que verificar response.ok. Fetch requiere dos llamadas .then() para obtener JSON: response.json() luego devuelve una Promise con los datos. Axios hace esto automáticamente. Fetch no admite el progreso de carga de archivos sin polyfills adicionales. Axios tiene onUploadProgress y onDownloadProgress integrados.

En Node.js, Fetch está disponible desde la versión 18 como función experimental, mientras que Axios funciona de forma estable desde Node.js 10. Para proyectos que soportan versiones antiguas de Node.js, la elección es claramente a favor de Axios. Para proyectos modernos de navegador sin procesamiento complejo de solicitudes, fetch puede ser suficiente.