Fetch API básico

Gran parte del trabajo de una página web consiste en pedir datos a un servidor y mostrarlos en la interfaz. Por ejemplo, una tienda online solicita el catálogo de productos, una aplicación de clima pide la previsión del día o un panel de administración carga la lista de pedidos.

JavaScript ofrece la API Fetch como herramienta estándar del navegador para realizar estas peticiones HTTP. Es una API nativa, no requiere ninguna librería y es la forma recomendada frente al antiguo XMLHttpRequest.

La API Fetch está integrada en todos los navegadores modernos y también en Node.js, lo que permite escribir código que se comporta igual tanto en el cliente como en el servidor.

Primera petición con fetch

La función global fetch recibe la URL de un recurso y devuelve una Promise que se resolverá con la respuesta del servidor. La forma más clara de trabajar con promesas en casos sencillos es usar async y await.

async function obtenerUsuarios() {
    const respuesta = await fetch("https://jsonplaceholder.typicode.com/users");
    const datos = await respuesta.json();
    console.log(datos);
}

obtenerUsuarios();

El código hace dos cosas. Primero espera (await) a que fetch obtenga la respuesta HTTP. Después llama a respuesta.json(), que lee el cuerpo y lo convierte en un objeto o array de JavaScript. Ambos pasos son asíncronos porque implican operaciones que no son inmediatas.

El objeto Response

La respuesta de fetch es un objeto Response con información útil:

async function inspeccionarRespuesta() {
    const respuesta = await fetch("https://jsonplaceholder.typicode.com/users/1");

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

    const usuario = await respuesta.json();
    console.log(usuario.name);
}

inspeccionarRespuesta();

La propiedad status contiene el código HTTP (200, 404, 500, etc.) y ok es true cuando el código está entre 200 y 299, es decir, cuando la petición ha tenido éxito.

Manejo de errores

Un detalle clave: fetch no lanza un error cuando el servidor responde con un código 404 o 500. La Promise se resuelve igualmente y depende de ti comprobar respuesta.ok. Sólo los errores de red (servidor caído, sin conexión, CORS) disparan un rechazo de la Promise.

El patrón recomendado es usar try...catch junto con la comprobación de ok:

async function obtenerUsuario(id) {
    try {
        const respuesta = await fetch(`https://jsonplaceholder.typicode.com/users/${id}`);

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

        const usuario = await respuesta.json();
        return usuario;
    } catch (error) {
        console.error("No se pudo obtener el usuario:", error.message);
        return null;
    }
}

obtenerUsuario(1);

De esta forma la función gestiona tanto errores de red como respuestas con código de error del servidor.

Enviar datos con POST

Por defecto, fetch realiza peticiones GET para obtener datos. Para enviar información al servidor (crear un usuario, publicar un comentario) se usa el método POST y se pasan opciones adicionales como segundo argumento.

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

    const datos = await respuesta.json();
    console.log("Post creado:", datos);
}

crearPost("Mi primer post", "Contenido del post");

Tres elementos son importantes:

• 1. method: indica el verbo HTTP (POST, PUT, DELETE, PATCH).
• 2. headers: el Content-Type le dice al servidor que el cuerpo es JSON.
• 3. body: el objeto JavaScript se convierte a texto con JSON.stringify.

Actualizar y borrar recursos

Los métodos PUT, PATCH y DELETE siguen la misma estructura:

async function actualizarPost(id, cambios) {
    const respuesta = await fetch(`https://jsonplaceholder.typicode.com/posts/${id}`, {
        method: "PUT",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(cambios)
    });
    return await respuesta.json();
}

async function borrarPost(id) {
    const respuesta = await fetch(`https://jsonplaceholder.typicode.com/posts/${id}`, {
        method: "DELETE"
    });
    return respuesta.ok;
}

Estos cuatro patrones (GET, POST, PUT, DELETE) cubren el 90 por ciento de las interacciones con APIs REST en una aplicación web real.

Integración con el DOM

El caso más común en una página web es pedir datos y mostrarlos en pantalla. Combinando fetch con la manipulación del DOM podemos construir interfaces dinámicas:

async function pintarUsuarios() {
    const contenedor = document.querySelector("#lista-usuarios");
    contenedor.textContent = "Cargando...";

    try {
        const respuesta = await fetch("https://jsonplaceholder.typicode.com/users");
        if (!respuesta.ok) throw new Error("Error al cargar usuarios");

        const usuarios = await respuesta.json();

        contenedor.innerHTML = usuarios
            .map(usuario => `<li>${usuario.name} - ${usuario.email}</li>`)
            .join("");
    } catch (error) {
        contenedor.textContent = `Error: ${error.message}`;
    }
}

document.querySelector("#boton-cargar").addEventListener("click", pintarUsuarios);

El patrón es siempre el mismo: mostrar un estado de carga, realizar la petición, pintar los datos o mostrar el error.

Parámetros en la URL

Muchas APIs aceptan parámetros de consulta (query parameters) en la URL para filtrar, paginar o buscar. La clase URLSearchParams ayuda a construir esas URLs de forma segura:

async function buscarProductos(categoria, maximo) {
    const params = new URLSearchParams({
        category: categoria,
        limit: maximo
    });

    const url = `https://api.example.com/products?${params}`;
    const respuesta = await fetch(url);
    return await respuesta.json();
}

buscarProductos("electronica", 10);
// Petición a: https://api.example.com/products?category=electronica&limit=10

Usar URLSearchParams en lugar de concatenar strings evita errores de formato y gestiona automáticamente caracteres especiales.

Flujo básico de una petición

El diagrama mental que conviene retener para usar Fetch es sencillo.

sequenceDiagram
    participant Cliente as Navegador
    participant API as Servidor

    Cliente->>API: fetch(url, opciones)
    API-->>Cliente: Response (status, headers, body)
    Cliente->>Cliente: respuesta.json()
    Cliente->>Cliente: Pintar datos en la pagina

Estos pasos (llamar, comprobar estado, leer cuerpo, actualizar la interfaz) se repiten en todas las aplicaciones web modernas. Dominar este flujo básico es suficiente para comunicar una página con cualquier servicio REST del mercado.

La API Fetch es asíncrona por naturaleza. Acostúmbrate a usar async y await junto con try...catch desde el principio: es la forma más clara de escribir código que habla con servidores.