Fetch API: cómo consumir APIs con JavaScript (GET, POST y formularios)

La Fetch API es la forma moderna y nativa de pedir y enviar datos en JavaScript, sin librerías externas. Con ella consumes APIs, cargas datos de un servidor y envías formularios sin recargar la página. En esta guía tienes peticiones GET y POST, formularios, cabeceras, tiempo límite y el famoso error de CORS. Todo el código lo he probado en el navegador.

Antes de seguir, conviene que domines la asincronía en JavaScript, porque Fetch devuelve promesas. Este artículo forma parte de la hoja de ruta para aprender JavaScript.

Respuesta rápida: fetch(url) hace una petición y devuelve una promesa con la respuesta. Conviertes el cuerpo con await respuesta.json() y compruebas respuesta.ok, porque un 404 no lanza error. Para enviar datos, pasas un segundo argumento con method, headers y body. Funciona en todos los navegadores actuales y en Node.js 18 o superior sin instalar nada.

Chuleta de Fetch: lo que más vas a usar

Si vienes a por una línea concreta, aquí la tienes. Debajo explico cada caso con un ejemplo completo.

Quiero…Código
Pedir datos (GET)await fetch(url)
Leer la respuesta como JSONawait respuesta.json()
Detectar un 404 o un 500if (!respuesta.ok) throw new Error(respuesta.status)
Añadir parámetros a la URLurl + '?' + new URLSearchParams({ userId: 1 })
Enviar JSON (POST){ method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(datos) }
Enviar un formulario{ method: 'POST', body: new FormData(formulario) }
Mandar un token{ headers: { Authorization: `Bearer ${token}` } }
Poner un tiempo límite{ signal: AbortSignal.timeout(5000) }
Chuleta de la Fetch API en JavaScript: cada tarea con su código.

Una petición GET básica

fetch() recibe una URL y devuelve una promesa. La respuesta hay que convertirla a JSON con .json(), que también es asíncrono.

fetch('https://jsonplaceholder.typicode.com/users')
  .then((response) => response.json())
  .then((datos) => console.log(datos))
  .catch((error) => console.error('Error:', error));

JSONPlaceholder es una API de pruebas gratuita. Esta petición devuelve un array con 10 usuarios; el primero es «Leanne Graham».

Lo mismo con async/await

Más legible y la forma recomendada hoy:

async function cargarUsuarios() {
  const response = await fetch('https://jsonplaceholder.typicode.com/users');
  const datos = await response.json();
  console.log(datos);
}

cargarUsuarios();

Controlar errores de verdad (response.ok)

Aquí está el error más común: fetch no lanza un error si el servidor responde 404 o 500. Solo falla si la petición no llega a completarse: sin conexión, un dominio que no existe o un bloqueo de CORS. Por eso hay que comprobar response.ok a mano.

async function cargarUsuarios() {
  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/users');

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

    const datos = await response.json();
    console.log(datos);
  } catch (error) {
    console.error('No se pudieron cargar los datos:', error);
  }
}

Los fallos de red caen en el catch. Las respuestas de error del servidor las capturas con response.ok. Lo he comprobado pidiendo el usuario 999, que no existe: la promesa se resuelve sin error, con ok: false y status: 404.

Si quieres entender por qué funciona así, en la guía de asincronía en JavaScript tienes los cinco errores más comunes con async/await.

Parámetros en la URL con URLSearchParams

Para filtrar o paginar, muchas APIs piden parámetros en la URL. No los concatenes a mano: URLSearchParams los codifica por ti, con tildes, espacios y comas incluidos.

const parametros = new URLSearchParams({ userId: 1 });
const respuesta = await fetch(`https://jsonplaceholder.typicode.com/posts?${parametros}`);
const posts = await respuesta.json();

console.log(posts.length); // 10, los posts del usuario 1

Enviar datos con POST y JSON

Para enviar datos (crear un recurso, mandar un formulario), pasas un segundo argumento. Lleva el método, las cabeceras y el cuerpo convertido a JSON con JSON.stringify().

async function crearPost() {
  const response = await fetch('https://jsonplaceholder.typicode.com/posts', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      title: 'Mi primer post',
      body: 'Contenido del post',
      userId: 1
    })
  });

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

La API responde con un 201 y te devuelve el objeto con su id nuevo (101). Recuerda: los datos que llegan del servidor vienen como texto JSON y los conviertes a objeto con .json(); los que envías, los conviertes de objeto a texto con JSON.stringify().

Enviar un formulario con FormData

Es el caso que más vas a usar en una web real: un formulario de contacto que se envía sin recargar la página. FormData recoge todos los campos que tengan atributo name.

const formulario = document.querySelector('#contacto');

formulario.addEventListener('submit', async (evento) => {
  evento.preventDefault();
  const aviso = document.querySelector('#aviso');

  try {
    const respuesta = await fetch(formulario.action, {
      method: 'POST',
      body: new FormData(formulario)
    });

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

    aviso.textContent = 'Mensaje enviado. ¡Gracias!';
    formulario.reset();
  } catch (error) {
    aviso.textContent = 'No se ha podido enviar. Inténtalo de nuevo.';
  }
});

Ojo: con FormData no pongas la cabecera Content-Type. El navegador la añade sola, como multipart/form-data con su separador. Si la escribes tú, el servidor no sabrá leer los campos. Si en el formulario hay un campo de archivo, se envía igual, sin cambiar nada.

Cabeceras y tokens de acceso

Muchas APIs piden identificarte con una clave o un token. Se manda en la cabecera Authorization:

const respuesta = await fetch('https://api.ejemplo.com/pedidos', {
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: 'application/json'
  }
});

Importante: nunca pongas una clave secreta en el JavaScript de tu web. Cualquiera la ve en las herramientas de desarrollo del navegador. Si la API exige una clave privada, la petición tiene que salir de tu servidor (Node, PHP o una función serverless), no del navegador.

Tiempo límite y cancelar una petición

Fetch no tiene un tiempo límite propio: si la API se queda colgada, tu código espera. Con AbortSignal.timeout() le pones un máximo en milisegundos:

try {
  const respuesta = await fetch('https://jsonplaceholder.typicode.com/users', {
    signal: AbortSignal.timeout(5000)
  });
  const datos = await respuesta.json();
} catch (error) {
  if (error.name === 'TimeoutError') {
    console.error('La API ha tardado más de 5 segundos');
  } else {
    console.error(error);
  }
}

Para cancelarla tú (por ejemplo, si el usuario cambia de pestaña en un buscador), usa un AbortController. Llamas a controlador.abort() y la promesa falla con un error llamado AbortError:

const controlador = new AbortController();
fetch(url, { signal: controlador.signal });

// Más tarde, si ya no necesitas la respuesta:
controlador.abort();

El error de CORS: qué significa y cómo se arregla

Si en la consola ves «TypeError: Failed to fetch» y un aviso de «blocked by CORS policy», no es un fallo de tu código. Es una protección del navegador. Por defecto, una página no puede leer la respuesta de otro dominio salvo que ese servidor lo permita con la cabecera Access-Control-Allow-Origin.

  • Si la API es tuya, configura esa cabecera en el servidor con el dominio de tu web.
  • Si la API es de otro y no lo permite, haz la petición desde tu servidor y que tu web llame a tu servidor. Es lo mismo que con las claves secretas.
  • No uses mode: 'no-cors'. Quita el error, pero la respuesta llega vacía: estado 0 y sin cuerpo. Lo he probado y no hay forma de leer nada.

Las APIs públicas pensadas para el navegador ya envían esa cabecera: JSONPlaceholder, Open-Meteo o la API REST de WordPress. Por eso los ejemplos de esta guía funcionan desde cualquier web.

Ejemplo real: mostrar las últimas entradas de un WordPress

Todo WordPress tiene una API REST pública en /wp-json/. Con ella puedes mostrar las últimas entradas de tu blog en otra web, en una landing o en una app. Este código pide las tres últimas de este blog y las pinta en una lista:

async function ultimasEntradas(web, cantidad = 3) {
  const parametros = new URLSearchParams({ per_page: cantidad, _fields: 'title,link' });
  const respuesta = await fetch(`${web}/wp-json/wp/v2/posts?${parametros}`);
  if (!respuesta.ok) throw new Error(`Error HTTP: ${respuesta.status}`);
  return respuesta.json();
}

async function pintarEntradas() {
  const lista = document.querySelector('#ultimas-entradas');
  try {
    const entradas = await ultimasEntradas('https://recursoswebyseo.com');
    for (const entrada of entradas) {
      const titulo = new DOMParser()
        .parseFromString(entrada.title.rendered, 'text/html').body.textContent;
      const enlace = document.createElement('a');
      enlace.href = entrada.link;
      enlace.textContent = titulo;
      const li = document.createElement('li');
      li.append(enlace);
      lista.append(li);
    }
  } catch (error) {
    console.error('No se pudieron cargar las entradas:', error);
  }
}

pintarEntradas();

Solo necesitas un <ul id="ultimas-entradas"></ul> en tu HTML. Dos detalles: el parámetro _fields pide solo el título y el enlace, así la respuesta pesa mucho menos. Y el título se convierte a texto con DOMParser porque WordPress lo envía con entidades HTML, como las comillas tipográficas. Usar textContent en lugar de innerHTML evita inyectar código ajeno en tu página.

Lo he probado desde otro dominio y funciona sin problemas de CORS. Si te interesa llevar esta idea más lejos, tienes la guía de WordPress headless.

Fetch, Axios o XMLHttpRequest

FetchAxiosXMLHttpRequest
InstalaciónNativoLibrería (npm o CDN)Nativo
SintaxisPromesasPromesasEventos y callbacks
Convierte el JSON soloNo, usas .json()SíNo
Error en 404 y 500No, compruebas okSí, por defectoNo
Tiempo límiteAbortSignal.timeout()Opción timeoutPropiedad timeout
Cuándo usarloCasi siempreProyectos grandes con muchas llamadasSolo en código antiguo
Comparativa entre Fetch, Axios y XMLHttpRequest.

Para seguir practicando

La mejor forma de asentar Fetch es montar algo con una API real. La app del tiempo de mis 10 proyectos de JavaScript usa Open-Meteo, que es gratis y no pide clave.

Si prefieres un libro: «Eloquent JavaScript», de Marijn Haverbeke, dedica un capítulo a HTTP y formularios: fetch, CORS y campos de formulario, con ejercicios. Tiene edición en papel en español, «JavaScript elocuente» de Anaya, y una traducción online gratis por si quieres probarlo antes.

¿Vas a montar tu primera app con una API?

Los datos los traes con Fetch, pero la interfaz hay que maquetarla. Mi pack CSS gratis trae más de 40 estilos listos para copiar, formularios y botones incluidos. Apúntate y te lo envío al correo.

Preguntas frecuentes

¿Fetch reemplaza a XMLHttpRequest?

Sí, para casi todo. XMLHttpRequest es el sistema antiguo, más verboso. Fetch es más limpio, usa promesas y está soportado en todos los navegadores modernos. Solo verás XMLHttpRequest en código heredado.

¿Por qué mi fetch no captura el error 404?

Porque fetch solo rechaza la promesa ante fallos de red, no ante respuestas de error del servidor. Debes comprobar response.ok (o response.status) y lanzar tú el error, como en el ejemplo de arriba.

¿Qué significa «TypeError: Failed to fetch»?

Que la petición no llegó a completarse. Las causas típicas son tres: no hay conexión, la URL apunta a un dominio que no existe o el navegador la ha bloqueado por CORS. Mira la pestaña Consola: si es CORS, lo dice expresamente.

¿Necesito Axios si tengo Fetch?

No es imprescindible. Axios añade comodidades: convierte el JSON solo y maneja los errores HTTP por defecto. Pero para la mayoría de proyectos Fetch nativo es suficiente y no suma peso a tu web.

¿Fetch envía las cookies?

Por defecto, solo a tu propio dominio (credentials: 'same-origin'). Para enviarlas a otro dominio usa credentials: 'include', y ese servidor tiene que permitirlo de forma explícita.

¿Puedo usar Fetch en Node.js?

Sí. Desde Node.js 18, fetch viene incluido de serie, con la misma sintaxis que en el navegador. Ya no hace falta instalar node-fetch.

Siguiente paso: llevar tu JavaScript al backend con Node.js y npm. Y para el temario completo, la hoja de ruta de JavaScript.

Este artículo incluye un enlace de afiliado de Amazon: si compras a través de él, recibo una pequeña comisión sin coste adicional para ti.

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

Scroll al inicio