La lección anterior resolvió media promesa: Nómada Tareas ya sobrevive a F5. Pero Marta, Iván y Lucía siguen teniendo cada uno su propio localStorage, con su propia versión del tablero, sin manera de verse. La otra mitad —que el tablero sea el mismo para todo el equipo— exige que los datos vivan en un servidor y que el navegador sepa hablar con él sin recargar la página. Eso es AJAX, y la herramienta moderna para hacerlo es fetch. En esta lección aprenderás qué cambió AJAX en la web, repasarás el HTTP que necesitas de verdad (verbos, códigos y cabeceras), dominarás fetch y el objeto Response con su trampa más famosa —un 404 no rechaza la promesa—, enviarás datos en JSON y en FormData, construirás URLs con parámetros, entenderás CORS lo suficiente para no perder una tarde, y escribirás js/datos/api-tareas.js, el hermano de red del repositorio local. Y por fin retirarás aquellas leerBacklogSimulado() y guardarInformeSimulado() de 05-06 que fingían latencia con setTimeout.

1. Qué es AJAX y qué cambió
2. XMLHttpRequest, el antepasado
3. HTTP en diez minutos: verbos, rutas, códigos y cabeceras
4. fetch: la petición mínima
5. El objeto Response y los métodos de cuerpo
6. La trampa fundamental: fetch no rechaza con 404 ni 500
7. Enviar datos: method, headers y body
8. Enviar FormData y archivos
9. Parámetros de consulta con URL y URLSearchParams
10. CORS: por qué el navegador te bloquea
11. Autenticación: Authorization y credentials
12. Nómada Tareas: js/datos/api-tareas.js
13. Practicar de verdad: json-server en tu máquina
14. Errores Comunes y Consejos
15. Ejercicios
16. Conclusión

AJAX son las siglas de Asynchronous JavaScript And XML, un nombre acuñado en 2005 que hoy es medio mentira: casi nadie usa XML —se usa JSON— y la técnica se aplica a mucho más que XML. Lo que la sigla nombra sigue vigente: pedir datos al servidor desde JavaScript, sin recargar la página, y actualizar solo la parte del DOM que cambia.

Compara los dos modelos:

Lo que AJAX hace posible, en términos de Nómada Tareas: Marta pulsa el botón de avanzar estado, la tarjeta se mueve de columna, y ni el scroll ni el filtro por responsable ni el foco se pierden. El ciclo estado → render → evento → nuevo estado → render que montaste en 06-06 sigue mandando; lo único que cambia es que ahora una parte del "nuevo estado" llega del servidor.

Y hay algo que no cambia y conviene decir pronto: el servidor sigue mandando. Una petición AJAX no es más segura que un formulario; el usuario puede fabricar la que quiera desde la consola. Toda validación del cliente es una cortesía; la de verdad está en el servidor.

Antes de fetch había XMLHttpRequest (XHR), disponible desde principios de los 2000. Lo verás en código antiguo y merece la pena reconocerlo:

Es el estilo de callbacks de 05-05 llevado al extremo: nada de promesas, nada de async/await, y el famoso readyState con sus cinco valores numéricos. La comparación:

Hoy se usa fetch salvo en dos casos: cuando necesitas una barra de progreso de subida de un archivo grande, o cuando mantienes código antiguo. Los dos huecos de fetch —timeout y cancelación— se cubren con AbortController, y esa es la lección siguiente.

Una petición HTTP tiene cuatro partes: un verbo, una ruta, unas cabeceras y a veces un cuerpo. La respuesta tiene un código de estado, sus propias cabeceras y su cuerpo.

Idempotente significa que repetir la misma petición deja el sistema igual que hacerla una vez. PUT de la tarea 6 con los mismos datos, mil veces, deja una tarea 6 con esos datos. POST mil veces crea mil tareas. Esa distinción parece teórica hasta que en 07-03 decidas qué peticiones se pueden reintentar sin miedo.

Una API REST nombra cosas, no acciones, y deja que el verbo diga qué hacer con ellas:

Un antipatrón habitual es POST /v1/crearTarea o GET /v1/borrarTarea?id=6. El segundo es especialmente malo: un GET no debe cambiar nada, y cualquier buscador o precargador del navegador podría dispararlo.

El dominio https://api.tallernomada.example/v1 que usaremos en toda la lección es ficticio. El TLD .example está reservado por la IANA precisamente para documentación y jamás resolverá. En el apartado 13 montarás un servidor real en tu máquina para practicar.

Se agrupan en familias, y con saber las familias vas sobrado:

La frontera entre 4xx y 5xx es la que gobierna tu manejo de errores: un 4xx lo arregla el cliente (corrige los datos, inicia sesión, deja de insistir); un 5xx no lo arregla el cliente (reintenta más tarde y avisa). Dos parejas que se confunden a menudo:

• 401 Unauthorized significa "no sé quién eres" (falta o caducó la credencial). 403 Forbidden significa "sé quién eres y no puedes". El primero pide iniciar sesión; el segundo, no.
• 204 No Content es un éxito sin cuerpo. Llamar a .json() sobre él lanza, porque no hay nada que parsear. Lo tendrás en cuenta en borrarTarea().

El error de novato más frecuente con cabeceras: enviar un body con JSON sin Content-Type: application/json. Muchos servidores lo interpretan como texto plano y devuelven un 400 desconcertante.

fetch(url, opciones) devuelve una promesa que se resuelve con un objeto Response en cuanto llegan las cabeceras de la respuesta. Con lo que sabes de 05-06, se lee sin esfuerzo:

Dos await, y cada uno espera algo distinto. Esto es lo que más cuesta al principio:

La primera promesa se resuelve con las cabeceras; el cuerpo puede seguir llegando. Por eso respuesta.json() es otra operación asíncrona y necesita su propio await. Olvidarlo produce el error más común de todos:

Response describe la respuesta completa:

Y los métodos de cuerpo, todos asíncronos porque todos devuelven promesas:

Los nombres de cabecera no distinguen mayúsculas: headers.get('Content-Type') y headers.get('content-type') son lo mismo.

Una regla que sorprende: el cuerpo solo se puede leer una vez. Es un flujo, y una vez consumido, se acabó.

Si necesitas leerlo dos veces —por ejemplo, intentar json() y, si falla, mirar el text() para depurar—, clona antes:

Ese patrón te salvará el día que un proxy devuelva una página HTML de error donde esperabas JSON.

Esta es la cosa que hay que saber de fetch, y la que más código roto ha producido:

La promesa de fetch solo se rechaza si la petición no llegó a completarse: red caída, DNS que no resuelve, CORS bloqueado, petición cancelada. Si el servidor responde —aunque responda 404, 403 o 500— la promesa se resuelve con normalidad.

El catch no se ejecuta. respuesta.json() parsea el cuerpo del error sin quejarse, y tu aplicación sigue adelante con basura. La corrección es siempre comprobar ok:

La tabla que explica el porqué del diseño:

La lógica del diseño es defendible: fetch promete hacer la petición HTTP, y un 404 es una petición HTTP realizada con éxito cuya respuesta es "no existe". Que sea defendible no quita que sea la primera causa de bugs de red. En el apartado 12 encapsularemos la comprobación una sola vez para no volver a olvidarla.

Fíjate además en el detalle de la última fila del diagnóstico: cuando CORS bloquea una petición, JavaScript recibe un TypeError genérico sin detalles. El motivo real solo aparece en la consola del navegador. Es intencionado —dar detalles sería filtrar información entre orígenes— y significa que la consola es tu única fuente de verdad ante un fallo de CORS.

El segundo parámetro de fetch es un objeto de opciones. Para crear una tarea:

Cuatro puntos:

• body nunca es un objeto. Si le pasas { titulo: '…' } directamente, el navegador lo convierte con String() y envía '[object Object]', exactamente el mismo desastre que en localStorage. JSON.stringify es obligatorio.
• JSON.stringify usa el toJSON de tus instancias, así que puedes pasarle una Tarea directamente y viajará completa, campos privados incluidos. Otra vez 05-03 rindiendo.
• El id lo asigna el servidor, no el cliente. Es la regla R1 del proyecto, y en un sistema con varios usuarios es la única forma de no colisionar.
• fetch no lanza si el servidor rechaza los datos. Un 422 Unprocessable Entity con la lista de campos inválidos llega como respuesta normal; hay que comprobar ok y leer el cuerpo del error.

Las opciones que más usarás:

Cuando hay un archivo de por medio —Iván quiere adjuntar la foto del boceto—, JSON no sirve: es texto. Se usa FormData, que ya conoces de 06-07:

No pongas Content-Type cuando envías FormData. El navegador lo genera solo, y añade el boundary —un separador aleatorio— que el servidor necesita para trocear el cuerpo. Si lo escribes tú, el boundary falta y el servidor no puede leer nada. Es un fallo desconcertante, porque el código "parece más completo" con la cabecera puesta.

Comparación rápida de los tres formatos de cuerpo:

Construir la cadena de consulta a mano es una fuente inagotable de bugs de codificación:

Las clases URL y URLSearchParams codifican por ti:

Los miembros útiles de URLSearchParams:

Un ayudante que usarás en el proyecto, saltándose los filtros vacíos:

Ese new URL(ruta, BASE) con dos argumentos resuelve rutas relativas contra una base, igual que lo hace un <a href>. Muy cómodo para no concatenar barras.

Antes o después escribirás una petición perfecta y la consola dirá algo como:

CORS (Cross-Origin Resource Sharing) es el mecanismo que decide si una página de un origen puede leer respuestas de otro origen. Por defecto, el navegador aplica la same-origin policy: puedes enviar peticiones a otros orígenes, pero no leer sus respuestas salvo que ese servidor lo autorice.

¿Por qué existe? Porque el navegador envía automáticamente las cookies del usuario. Sin esta política, cualquier página maliciosa que visitaras podría pedir https://tubanco.example/api/saldo con tus cookies y leer la respuesta.

Hay dos tipos de petición cruzada, y la diferencia importa mucho:

Petición simple: el navegador la envía directamente y luego decide si te deja leer la respuesta. Se considera simple si usa GET, HEAD o POST, y sus cabeceras son las corrientes, con un Content-Type limitado a text/plain, multipart/form-data o application/x-www-form-urlencoded.

Petición con preflight: cualquier otra cosa —PUT, PATCH, DELETE, o un POST con Content-Type: application/json, o una cabecera Authorization— obliga al navegador a preguntar antes con una petición OPTIONS.

Ese OPTIONS extra explica dos cosas que desconciertan: por qué en la pestaña Network aparecen dos entradas por una sola llamada, y por qué a veces el fallo ocurre "antes" de que el servidor vea tu petición real.

Las cabeceras que controla el servidor:

Y la conclusión que ahorra tardes enteras:

CORS no se arregla desde el cliente. Ni con mode, ni con cabeceras, ni con trucos. Lo aplica el navegador según lo que responde el servidor. Solo hay tres salidas legítimas: que el servidor añada las cabeceras, poner un proxy en tu mismo origen que reenvíe las peticiones, o servir API y web bajo el mismo origen.

Dos matices que se malinterpretan:

• mode: 'no-cors' no desactiva CORS. Te devuelve una respuesta opaca: status 0, ok false y cuerpo ilegible. Sirve para casos muy concretos (precachear en un service worker), no para saltarse nada.
• Las extensiones tipo "Allow CORS" del navegador solo desactivan la comprobación en tu máquina. Tu código seguirá roto para todos los demás. Úsalas, como mucho, para diagnosticar.
• Access-Control-Allow-Origin: * es incompatible con credenciales. Si envías cookies, el servidor debe nombrar tu origen exacto.

Hay dos formas de que la API sepa quién eres.

Token en la cabecera Authorization, el patrón habitual de las APIs:

Cookies, que el navegador gestiona solo. Con fetch hay que pedirlas explícitamente cuando la API está en otro origen:

¿Cuál elegir? Retomando la advertencia de 07-01:

La recomendación no ha cambiado: para una sesión de usuario real, cookie HttpOnly; Secure; SameSite=Lax, emitida y validada por el servidor. Si tu API impone un token en localStorage —cosa habitual—, asume que un XSS es un robo de cuenta y trata la prevención de XSS (06-02: textContent en lugar de innerHTML) como parte de la seguridad de la autenticación.

Tres reglas más, cortas y no negociables:

• HTTPS siempre. Sobre http://, cabeceras y cuerpos viajan legibles para cualquiera en la red. Un token enviado por HTTP es un token público.
• Nunca metas claves de API en el código del cliente. Todo lo que llega al navegador es visible. Si una clave debe permanecer secreta, la petición la hace tu servidor, no la página.
• Ante un 401, limpia la sesión local y manda a iniciar sesión. Reintentar con un token caducado solo genera ruido.

Ya puedes escribir el hermano de red de RepositorioLocal. La misma responsabilidad —traducir entre el mundo exterior y el modelo— con otro medio.

Cuatro decisiones a subrayar:

• La frontera del modelo se respeta. El módulo devuelve instancias de Tarea, no objetos planos, exactamente como hacía RepositorioLocal. El resto de la aplicación no sabe de dónde vienen los datos. Ese es el sentido de tener una carpeta datos/.
• comprobar está escrita una sola vez. La trampa del apartado 6 se neutraliza encapsulándola, no recordándola.
• borrarTarea no llama a json(). Un 204 No Content no tiene cuerpo y json() lanzaría.
• No hay try/catch aquí. Este módulo traduce y propaga; quien decide qué mostrar al usuario es la vista. Cómo clasificar y presentar esos errores es justo el tema de 07-03.

Y así se sustituyen por fin las funciones simuladas de 05-06:

Ahí está el patrón que hace que una aplicación se sienta rápida: local primero, red después. El almacenamiento de 07-01 y la red de esta lección no compiten; se complementan. (Ese await desnudo, sin try/catch ni estado de carga, todavía está a medias: lo completarás en la lección siguiente.)

api.tallernomada.example no existe. Para practicar necesitas un servidor real, y el más rápido de montar es json-server, que convierte un fichero JSON en una API REST completa.

Con este db.json, que es el backlog canónico del proyecto:

Ese fichero da inmediatamente todas las rutas que necesitas:

Solo tienes que cambiar una línea en tu módulo:

Y json-server ya envía Access-Control-Allow-Origin: *, así que no pelearás con CORS mientras aprendes. Otras opciones para practicar: https://jsonplaceholder.typicode.com (API pública de solo lectura simulada), https://httpbin.org (devuelve tu propia petición, ideal para inspeccionar cabeceras) o https://httpstat.us/500 (devuelve el código que le pidas, perfecto para probar el manejo de errores de la lección siguiente).

• Olvidar comprobar respuesta.ok. El error número uno. Un 404 llega como éxito y tu aplicación procesa un mensaje de error como si fueran datos.
• Olvidar el await de respuesta.json(). Obtienes una Promise y todo lo que hagas con ella da undefined.
• Pasar un objeto como body. Se convierte en '[object Object]'. JSON.stringify siempre.
• Poner Content-Type al enviar FormData. Rompe el boundary y el servidor no puede leer el cuerpo.
• Llamar a .json() sobre un 204. No hay cuerpo; lanza. Comprueba status === 204 o Content-Length.
• Leer el cuerpo dos veces. TypeError: body stream already read. Usa respuesta.clone() antes de la primera lectura.
• Concatenar parámetros a mano. Un espacio, un & o una tilde rompen la URL. Usa URL y URLSearchParams.
• Intentar arreglar CORS desde el cliente. No se puede. Lee la consola, habla con quien mantiene la API o monta un proxy.
• Usar mode: 'no-cors' para "saltarse" CORS. Devuelve una respuesta opaca e ilegible.
• Meter una clave de API en el JavaScript del cliente. Es pública desde el momento en que se descarga.
• Consejo: mira siempre la pestaña Network de las DevTools. Verbo, código, cabeceras, cuerpo enviado y recibido, y el OPTIONS del preflight. Casi todos los problemas de red se diagnostican ahí en treinta segundos.
• Consejo: usa await respuesta.text() cuando json() falle. Verás si el servidor devolvió una página HTML de error en lugar de JSON.
• Consejo: encapsula fetch en un único módulo. Nunca lo llames suelto desde la vista. Así la comprobación de ok, la base de la URL y las cabeceras viven en un solo sitio, y en 07-03 podrás añadir timeouts y reintentos sin tocar el resto.
• Consejo: en el navegador, copy(await (await fetch(url)).json()) en la consola copia la respuesta al portapapeles. Muy útil para inspeccionar formatos.

Ejercicio 1 — El envoltorio que no se puede olvidar. Escribe pedirJson(url, opciones = {}) que: haga el fetch; si respuesta.ok es falso, lea el cuerpo como texto y lance un Error cuyo mensaje incluya el status, el statusText y ese texto; si el estado es 204 devuelva null; y en caso contrario devuelva await respuesta.json(). Reescribe después listarTareas y borrarTarea usándolo, y comprueba que el código queda más corto.

Ejercicio 2 — Buscador de tareas con parámetros. Escribe buscarTareas({ texto, responsable, estados, orden, pagina }) que construya la URL con URLSearchParams, omitiendo los valores vacíos. estados es un array (['pendiente', 'en-curso']) y debe generar ?estado=pendiente&estado=en-curso. La paginación usa _page y _limit, los parámetros de json-server. Devuelve { tareas, total } leyendo el total de la cabecera X-Total-Count.

Ejercicio 3 — Sincronizar el tablero local con el servidor. Escribe sincronizar(repositorio, api) que: cargue el tablero local; pida al servidor la lista de tareas; y devuelva un informe { soloLocal, soloServidor, enAmbos, coinciden } comparando por id, donde coinciden es el número de tareas presentes en ambos lados con el mismo estado. No modifiques nada todavía: solo informa. Usa Map y los métodos de array de 04-05.

Solución 1

La comprobación del content-type es la que evita el peor de los fallos: un proxy corporativo o una pantalla de inicio de sesión devuelven HTML con estado 200, y sin esa línea el json() lanzaría un SyntaxError incomprensible. Esta función es el germen del pedirJson completo que construirás en 07-03.

Solución 2

La diferencia entre set y append es la clave: set reemplaza, así que un bucle con set dejaría solo el último estado. Y ojo con X-Total-Count: en una API de otro origen, esa cabecera solo será legible si el servidor la expone con Access-Control-Expose-Headers. Con json-server en localhost no hay problema.

Solución 3

Los dos Map convierten la comparación en operaciones de coste constante en lugar de recorrer el array remoto por cada tarea local. Y fíjate en lo que revela el resultado: hay un conflicto. Qué hacer con él —quién gana cuando local y servidor discrepan— es una decisión de producto, no técnica, y volverás sobre ella en 07-04 al hablar de edición simultánea.

Nómada Tareas ya sabe hablar con un servidor. Entiendes qué significa AJAX y por qué cambió la web: pedir datos en segundo plano y actualizar solo lo que cambia, conservando scroll, foco y filtros, con un JSON de unos cientos de bytes en lugar de un documento HTML completo. Conoces a XMLHttpRequest lo justo para reconocerlo, y sabes que fetch lo sustituye en todo salvo en el progreso de subida, y que sus dos huecos —timeout y cancelación— se rellenan con AbortController.

Tienes el HTTP que se usa a diario: los verbos con su significado y su idempotencia (GET, PUT y DELETE sí, POST no), las rutas que nombran recursos y no acciones, las cinco familias de códigos con la frontera decisiva entre el 4xx que arregla el cliente y el 5xx que no, y las cabeceras Content-Type, Accept y Authorization. Dominas fetch y su doble espera —la primera promesa trae las cabeceras, la segunda el cuerpo—, el objeto Response con ok, status, headers y los cinco métodos de cuerpo, y la regla de que el cuerpo se lee una sola vez salvo que lo clones. Y llevas grabada la trampa que define a esta API: fetch no rechaza con 404 ni con 500; solo rechaza si la petición no llegó a completarse. Por eso la comprobación de respuesta.ok no se recuerda, se encapsula.

Sabes enviar datos con method, headers y body —JSON.stringify obligatorio, y Content-Type prohibido cuando el cuerpo es FormData—, construir URLs con URL y URLSearchParams distinguiendo set de append, y explicar CORS: la same-origin policy, la petición simple frente al preflight OPTIONS que duplica las entradas en la pestaña Network, las cabeceras Access-Control-* que decide el servidor, y la conclusión que ahorra tardes enteras —no se arregla desde el cliente, y mode: 'no-cors' solo te da una respuesta opaca—. Y tienes clara la parte de seguridad: HTTPS siempre, tokens preferiblemente en cookie HttpOnly y no en localStorage, ninguna clave secreta en el código del cliente, y ninguna confianza en la validación del navegador.

En código, el módulo js/datos/api-tareas.js con listarTareas, obtenerTarea, crearTarea, actualizarTarea y borrarTarea, que devuelve instancias de Tarea y no objetos planos, igual que hacía RepositorioLocal: la capa datos/ es una frontera, y el resto de la aplicación no sabe si los datos vienen del disco o de la red. Y un json-server en localhost:3000 con el backlog canónico para que puedas practicar contra un servidor de verdad, porque api.tallernomada.example es y seguirá siendo ficticio.

Ahora bien: ese código funciona solo cuando todo va bien. Y en la red nada va bien todo el tiempo. El wifi del taller se cae a mitad de un POST; la API tarda quince segundos y Marta pulsa el botón tres veces; el servidor devuelve un 503 porque están desplegando; Iván escribe en el buscador y se lanzan ocho peticiones de las que llega antes la penúltima, dejando en pantalla resultados que no corresponden a lo que escribió. Ninguna de esas situaciones la cubre lo que has escrito hoy: no hay timeout, no hay cancelación, no hay reintentos, no hay estado de carga y no hay forma de decirle al usuario qué ha pasado. Eso es exactamente lo que separa una demo de una aplicación, y es el tema de Peticiones Robustas: Errores, Timeouts y AbortController, donde AbortController —presentado de pasada en 06-04— por fin ocupará el lugar que le corresponde.