25. Diseño de API: HTTP, REST, OpenAPI y contratos

25.1 Qué vas a poder hacer al terminar

• Explicar la anatomía exacta de una petición y una respuesta HTTP, y describir el recorrido completo desde que el usuario pulsa un botón en Angular hasta que se ejecuta tu método del controlador, pasando por DNS, TLS, proxy inverso y balanceador.
• Justificar qué cambia en la práctica entre HTTP/1.1, HTTP/2 y HTTP/3, y por qué trucos de optimización que eran obligatorios en 2015 hoy son contraproducentes.
• Elegir el método HTTP correcto respondiendo a dos preguntas, y explicar con precisión qué significan seguro e idempotente y qué garantías te da cada propiedad cuando la red falla.
• Distinguir PUT de PATCH sin dudar, y saber si el cuerpo de tu PATCH es un JSON Merge Patch o un JSON Patch, que no es lo mismo ni se comporta igual.
• Devolver el código de estado correcto en cada situación, incluidos los que casi todo el mundo usa mal: 201 con Location, 202 para trabajos asíncronos, 400 frente a 422, 401 frente a 403, 404 defensivo, 409 por conflicto de concurrencia, 410, 429 con Retry-After y la familia 5xx.
• Diseñar URL de recursos que envejezcan bien: sustantivos en plural, jerarquía con criterio, identificadores estables y un plan para las acciones que no encajan en CRUD.
• Especificar el contrato completo de un listado: paginación por desplazamiento o por cursor según el caso, filtrado, ordenación con lista blanca, selección de campos, expansión de relaciones y metadatos de respuesta.
• Escribir errores en formato Problem Details (RFC 9457) con errores de validación campo a campo y un identificador de correlación, sin revelar nunca información que ayude a un atacante.
• Implementar caché HTTP de verdad: Cache-Control con sus directivas, ETag con If-None-Match, respuestas 304 y una estrategia de invalidación, tanto en NestJS como en el HttpClient de Angular.
• Implementar bloqueo optimista sobre HTTP con ETag e If-Match, conectándolo con la columna de versión de MikroORM del capítulo 17, y responder 412 cuando corresponda.
• Implementar claves de idempotencia para operaciones de escritura no idempotentes, con almacenamiento del resultado, ventana de validez y detección de reutilización de clave con cuerpo distinto.
• Diseñar operaciones largas con el patrón 202 más recurso de estado, y decidir entre sondeo, eventos enviados por el servidor y webhooks.
• Definir una estrategia de versionado y deprecación que te permita retirar una versión antigua sin romper a nadie, apoyada en métricas de uso reales.
• Generar el documento OpenAPI desde NestJS, producir con él un cliente tipado para Angular y validar automáticamente en integración continua que un cambio no rompe a los consumidores.

25.2 HTTP en profundidad, que casi nadie estudia y todo el mundo usa

HTTP es el protocolo sobre el que se apoya todo lo que escribes, y sin embargo la mayoría de los desarrolladores lo conoce por acumulación de anécdotas: que 404 es «no encontrado», que hay una cosa llamada CORS que da problemas y que las cabeceras se ponen en un objeto. Esa forma de saber es suficiente para copiar un ejemplo y radicalmente insuficiente para diseñar. Dedicar una hora a entender el protocolo con precisión cambia la calidad de todas las decisiones posteriores, porque casi todas las buenas prácticas de diseño de API no son convenciones arbitrarias: son consecuencias de cómo funciona HTTP.

La definición formal actual está en la RFC 9110, publicada en junio de 2022, que reemplazó y reorganizó la vieja familia RFC 7230–7235 (que a su vez había sustituido a la RFC 2616 de 1999). El cambio importante de esa reorganización es conceptual: la semántica de HTTP —métodos, códigos de estado, cabeceras, el significado de las cosas— se separó de la sintaxis de transporte, que es distinta en HTTP/1.1, HTTP/2 y HTTP/3. Dicho de otro modo: lo que significa un PUT o un 409 es idéntico en las tres versiones; lo que cambia entre versiones es cómo viajan los bytes por el cable.

25.2.1 Anatomía de una petición y de una respuesta

Aunque HTTP/2 y HTTP/3 ya no envían texto plano, el modelo mental sigue siendo el de HTTP/1.1, y todas las herramientas te lo muestran así. Una petición tiene cuatro partes: la línea de petición, las cabeceras, una línea en blanco y el cuerpo opcional. Verlo literalmente, con los bytes que viajan, es el ejercicio que más rápido despeja confusiones:

PATCH /api/v1/projects/9/tasks/42 HTTP/1.1          <- línea de petición: método, destino, versión
Host: api.taskflow.dev                              <- obligatoria desde HTTP/1.1: hosting virtual
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6…
Content-Type: application/merge-patch+json          <- qué formato tiene el cuerpo QUE ENVÍO
Accept: application/json                            <- qué formatos ACEPTO en la respuesta
Accept-Language: es-ES,es;q=0.9,en;q=0.7            <- q = factor de calidad, de 0 a 1
Accept-Encoding: br, gzip
If-Match: "v7-3f21ac"                               <- precondición: solo si sigue en esta versión
Idempotency-Key: 0f1b1a6c-3a2e-4f0b-9d84-2c1c9a0f77e1
Content-Length: 31
                                                    <- línea EN BLANCO: fin de cabeceras
{"estado":"HECHA","horas":3.5}                      <- cuerpo

La respuesta tiene la misma estructura, con una línea de estado en lugar de una línea de petición:

HTTP/1.1 200 OK                                     <- versión, código, frase (decorativa)
Content-Type: application/json; charset=utf-8
Content-Length: 214
ETag: "v8-91cd02"                                   <- versión NUEVA del recurso
Cache-Control: private, no-cache                    <- se puede guardar, pero hay que revalidar
Vary: Accept, Accept-Language, Authorization        <- de qué cabeceras depende esta respuesta
X-Request-Id: 8f2c1d3e-77aa-4b19-9e0c-51a2d0b3e6f4  <- correlación con tus logs
Date: Fri, 31 Jul 2026 17:04:22 GMT

{"id":42,"titulo":"Revisar contrato","estado":"HECHA","horas":3.5,"version":8}

Merece la pena fijarse en tres detalles que producen errores reales. Primero, Content-Type describe el cuerpo de ese mensaje: en la petición describe lo que envías, en la respuesta lo que recibes; no son la misma cabecera repetida. Segundo, Accept es una preferencia con factores de calidad, no una orden: el servidor puede responder con otro tipo o rechazar con 406. Y tercero, las cabeceras que empiezan por If- son precondiciones: le dices al servidor «ejecuta esto solo si se cumple X», y son la base de la caché condicional y del bloqueo optimista que veremos en 25.8 y 25.9.

25.2.2 HTTP/1.1, HTTP/2 y HTTP/3: qué cambia en la práctica

Las tres versiones comparten la misma semántica y difieren en el transporte. El problema que las tres generaciones intentan resolver es siempre el mismo: una página moderna necesita decenas o cientos de recursos, y abrir una conexión cuesta tiempo.

HTTP/1.1 (1997) introdujo las conexiones persistentes: en lugar de abrir y cerrar una conexión TCP por recurso, la conexión se reutiliza (Connection: keep-alive, que es el comportamiento por defecto). Pero mantuvo una limitación grave: en una conexión solo puede haber una petición en curso a la vez. Si la primera respuesta tarda, las siguientes esperan. Es el head-of-line blocking a nivel de aplicación. Los navegadores lo mitigaron abriendo unas seis conexiones por dominio, y de ahí nació el famoso domain sharding: repartir imágenes entre img1.midominio.com, img2… para multiplicar el número de conexiones paralelas.

HTTP/2 (2015, RFC 7540, hoy RFC 9113) cambió la sintaxis a un protocolo binario con multiplexación: sobre una única conexión TCP viajan muchos streams simultáneos, entrelazados en marcos. Añadió HPACK, una compresión de cabeceras con tabla dinámica que evita reenviar en cada petición las mismas cookies y el mismo User-Agent, y priorización de streams. La consecuencia práctica es directa y a menudo se ignora: el domain sharding pasó de optimización a penalización, porque cada dominio adicional obliga a una resolución DNS, un saludo TCP y un saludo TLS nuevos, y fragmenta la tabla de compresión. Lo mismo ocurre con la concatenación agresiva de ficheros y los sprites de imágenes: con multiplexación, muchos ficheros pequeños con caché granular suelen ganar.

HTTP/3 (2022, RFC 9114) sustituye TCP por QUIC sobre UDP. Resuelve el head-of-line blocking que quedaba: en HTTP/2 los streams son independientes en la capa de aplicación, pero comparten una sola conexión TCP, así que la pérdida de un paquete detiene todos los streams hasta la retransmisión. En QUIC cada stream se recupera por separado. Además, TLS 1.3 está integrado en el propio establecimiento de la conexión, lo que reduce el saludo a un solo viaje de ida y vuelta (o cero con reanudación), y la conexión sobrevive a un cambio de red gracias al identificador de conexión: el móvil pasa de wifi a datos sin que la descarga se corte.

25.2.3 Cómo viaja realmente una petición hasta tu controlador

Entre el this.http.patch(...) de un servicio de Angular y la primera línea de tu método de NestJS hay más infraestructura de la que se suele imaginar. Conocer esas etapas es lo que te permite diagnosticar un problema en producción cuando el síntoma es «a veces tarda dos segundos» o «solo falla desde el móvil»:

  NAVEGADOR (Angular)
  taskService.actualizar(42, {estado:'HECHA'})
       │  1 · HttpClient construye la petición y pasa por los interceptores
       │      (auth, reintentos, cabecera de correlación, indicador de carga)
       ▼
  ┌────────────────────────────────────────────────────────────────────────┐
  │ 2 · ¿ES UNA PETICIÓN DE OTRO ORIGEN?                                   │
  │     app.taskflow.dev  ->  api.taskflow.dev  =  SÍ                      │
  │     Si no es "simple", el navegador envía primero OPTIONS (preflight)  │
  │     y NO envía la petición real hasta recibir permiso. Ver 25.17.      │
  └────────────────────────────────────────────────────────────────────────┘
       ▼
  3 · RESOLUCIÓN DNS         api.taskflow.dev -> 203.0.113.10
      caché del navegador -> caché del sistema -> resolutor -> autoritativo
      coste típico: 0 ms si está en caché, 20-120 ms si no
       ▼
  4 · CONEXIÓN TCP (o QUIC)  saludo de 3 vías: SYN, SYN-ACK, ACK
      coste: 1 viaje de ida y vuelta (RTT). Madrid-Fráncfort ~ 30 ms
       ▼
  5 · SALUDO TLS             ClientHello / ServerHello, certificado, claves
      TLS 1.3: 1 RTT (0 con reanudación). TLS 1.2: 2 RTT
      aquí se negocia también el protocolo con ALPN: h2, http/1.1
       ▼
  ┌────────────────────────────────────────────────────────────────────────┐
  │ 6 · CDN / WAF (si existe)                                              │
  │     ¿Hay respuesta cacheada y fresca para esta clave?                  │
  │        SÍ  -> devuelve sin tocar tu servidor (coste: ~10 ms)           │
  │        NO  -> sigue hacia el origen, y quizá guarde la respuesta       │
  │     También: reglas de filtrado, límite de peticiones, bloqueo de IP   │
  └────────────────────────────────────────────────────────────────────────┘
       ▼
  7 · BALANCEADOR DE CARGA   elige una instancia sana
      comprueba /health periódicamente; retira instancias que fallan
      añade X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host
       ▼
  8 · PROXY INVERSO          Nginx / Traefik / Caddy
      termina TLS, aplica gzip o brotli, límites de tamaño y de tasa,
      cabeceras de seguridad, y habla HTTP/1.1 con la aplicación
       ▼
  9 · NODE.JS                el bucle de eventos acepta el socket
      http.Server emite 'request'; Express o Fastify enruta
       ▼
 10 · NESTJS                 middleware, guards, interceptores, pipes  (cap. 10)
       ▼
 11 · TU CONTROLADOR         @Patch(':id') actualizar(@Param() … )
       ▼
 12 · SERVICIO -> MIKROORM -> POSTGRESQL
      y la respuesta deshace todo el camino en sentido inverso

De este recorrido se extraen cuatro lecciones de diseño que van a reaparecer en todo el capítulo. La primera es que los pasos 3, 4 y 5 se pagan una vez por conexión, no por petición: por eso las conexiones persistentes importan tanto, y por eso una API que obliga al cliente a hacer diez llamadas para pintar una pantalla es cara aunque cada llamada sea rápida. La segunda es que hay al menos dos cachés antes de tu código (la del navegador y la del CDN), y si no emites cabeceras de caché correctas las estás desaprovechando por completo; esto es 25.8. La tercera es que tu aplicación no ve la IP real del cliente, sino la del último salto, salvo que confíes explícitamente en las cabeceras X-Forwarded-*, lo cual solo debes hacer si controlas el proxy. Y la cuarta es que el navegador puede negarse a enviar tu petición antes de que exista, por CORS, que es un mecanismo del navegador y no de tu servidor.

// Confiar en el proxy no es opcional cuando hay uno delante: sin esto,
// req.ip devuelve la IP del proxy y todo tu límite de peticiones por IP
// se aplica, en realidad, a una sola IP. Y req.protocol dice "http",
// con lo que las redirecciones y las cookies "secure" se rompen.
const app = await NestFactory.create<NestExpressApplication>(AppModule);

// Número de saltos de confianza, NO "true": confiar en todos permite
// a cualquier cliente falsificar su IP con una cabecera X-Forwarded-For.
app.set('trust proxy', 1);

// Límite de tamaño del cuerpo: la primera línea de defensa contra
// peticiones diseñadas para agotar la memoria del proceso (ver 25.17).
app.use(json({ limit: '256kb' }));

await app.listen(3000);

25.2.4 Conexiones persistentes y por qué te afectan como diseñador

Una conexión persistente es simplemente una conexión TCP que no se cierra al terminar una petición. Suena a detalle de infraestructura, pero tiene dos consecuencias que sí son tuyas. La primera es el agrupamiento de conexiones salientes: cuando tu API de NestJS llama a otro servicio, si no reutilizas conexiones estás pagando DNS, TCP y TLS en cada llamada. En Node, esto se controla con un Agent con keepAlive, y desde Node 19 fetch ya lo hace por defecto con undici.

La segunda es el tiempo de inactividad. Los balanceadores cierran conexiones ociosas pasado un umbral; si el de tu proveedor cierra a los 60 segundos y tu servidor Node cierra a los 5 (el valor por defecto histórico de Node era 5 segundos, hoy son 5 en keepAliveTimeout y 60 en headersTimeout), aparecen errores 502 intermitentes e inexplicables: el balanceador reutiliza una conexión que el servidor acaba de cerrar. La regla es que el tiempo de inactividad del servidor debe ser mayor que el del balanceador.

// Un agente nuevo por llamada: DNS + TCP + TLS
// en CADA petición. Con 200 llamadas por minuto
// a un servicio externo, esto son 200 saludos
// TLS por minuto y una latencia añadida de
// 100-200 ms que nadie sabe de dónde sale.
async function notificar(evento: Evento) {
  const agente = new https.Agent();          // nuevo cada vez
  return axios.post(URL, evento, {
    httpsAgent: agente,
  });
}

// Un único agente compartido, con conexiones
// reutilizadas. El primer envío paga el saludo;
// los siguientes reutilizan el socket abierto.
const agente = new https.Agent({
  keepAlive: true,
  maxSockets: 50,        // techo por destino
  maxFreeSockets: 10,    // ociosas que se guardan
  timeout: 30_000,
});

async function notificar(evento: Evento) {
  return axios.post(URL, evento, { httpsAgent: agente });
}

25.3 Métodos y su semántica exacta

El método HTTP no es una etiqueta decorativa: es una promesa sobre el comportamiento de la operación, y hay infraestructura real que actúa según esa promesa. Los navegadores precargan enlaces con GET, los proxies cachean GET, las bibliotecas de cliente reintentan automáticamente los métodos idempotentes, los rastreadores siguen enlaces suponiendo que no cambian nada y los balanceadores reenvían a otra instancia cuando una petición idempotente falla. Si tu GET /tareas/42/borrar borra una tarea, no estás cometiendo un error de estilo: estás mintiendo a toda esa infraestructura, y tarde o temprano alguien pagará el precio.

25.3.1 Seguro, idempotente y cacheable

Son tres propiedades distintas que se confunden constantemente. Conviene definirlas con la precisión de la RFC 9110:

• Seguro (safe): el método es de solo lectura desde el punto de vista del cliente. No promete que el servidor no haga nada —puede registrar la petición, incrementar un contador de visitas o calentar una caché—, promete que el cliente no puede ser considerado responsable de un cambio de estado. Son seguros GET, HEAD y OPTIONS.
• Idempotente: ejecutar la petición una vez o N veces seguidas deja el servidor en el mismo estado. Ojo con la definición: habla del estado final, no de la respuesta. Un DELETE es idempotente aunque la primera vez devuelva 204 y la segunda 404, porque en ambos casos el recurso deja de existir. Todos los métodos seguros son idempotentes; además lo son PUT y DELETE.
• Cacheable: la respuesta se puede almacenar y reutilizar para peticiones futuras. En la práctica es GET y HEAD; POST es cacheable en teoría si la respuesta lo indica explícitamente, pero casi ninguna caché real lo implementa y no conviene apoyarse en ello.

Con estas propiedades en la mano, casi todas las dudas de diseño se resuelven con dos preguntas, en este orden:

  ¿QUÉ MÉTODO USO?

  Pregunta 1 · ¿La operación cambia el estado del servidor?
      NO  ->  GET      (o HEAD si solo quieres las cabeceras)
              y ya has terminado: nunca uses POST para leer.
      SÍ  ->  sigue.

  Pregunta 2 · ¿Repetirla N veces deja el mismo estado que hacerla 1 vez?
      NO  ->  POST     y protégelo con Idempotency-Key si el cliente
                       puede reintentar (pagos, envíos, creación).
      SÍ  ->  ¿estás enviando el recurso ENTERO?
                  SÍ -> PUT      (reemplazo total; ausente = borrado)
                  NO -> PATCH    (modificación parcial)
              ¿la operación es "que deje de existir"?
                  SÍ -> DELETE

  Caso especial · una acción que no encaja en CRUD ("archivar")
      -> conviértela en un recurso y usa POST sobre él.  Ver 25.5.4.

25.3.2 PUT frente a PATCH, y el cuerpo de un PATCH

PUT significa «que el estado de este recurso pase a ser exactamente esto». Es un reemplazo total: los campos que no envíes se consideran ausentes, no «sin cambios». PATCH significa «aplica estas modificaciones al recurso». La diferencia no es cosmética, tiene consecuencias directas sobre los datos:

# El cliente quiere cambiar solo el estado y
# usa PUT enviando únicamente ese campo.
PUT /api/v1/tasks/42
Content-Type: application/json

{"estado": "HECHA"}

# Interpretación correcta de PUT: el recurso
# pasa a ser SOLO eso. titulo, descripcion,
# horas, responsable y etiquetas quedan
# borrados. Si el servidor "es amable" y los
# conserva, está implementando un PATCH bajo
# el nombre PUT, y ahora nadie sabe qué hace
# realmente el endpoint.

# Modificación parcial explícita, con el tipo
# de medio que dice cómo interpretarla.
PATCH /api/v1/tasks/42
Content-Type: application/merge-patch+json
If-Match: "v7-3f21ac"

{"estado": "HECHA"}

# Y si de verdad quieres reemplazo total,
# PUT con el recurso COMPLETO:
PUT /api/v1/tasks/42
Content-Type: application/json

{"titulo":"Revisar contrato","descripcion":"…",
 "estado":"HECHA","horas":3.5,"responsableId":7}

Ahora la pregunta que casi nadie se hace: ¿qué formato tiene el cuerpo de un PATCH? La especificación de PATCH (RFC 5789) no define ninguno; solo dice que el cuerpo es un «conjunto de instrucciones de modificación» y que el Content-Type debe indicar cuál es. Hay dos estándares reales:

// Content-Type: application/merge-patch+json
// Un objeto con la MISMA forma que el recurso.
// Los campos presentes se sustituyen.
// null significa BORRAR el campo.
// Los campos ausentes no se tocan.
{
  "estado": "HECHA",
  "horas": 3.5,
  "responsableId": null
}

// Limitación importante: como null significa
// "borrar", NO puedes asignar el valor null a
// un campo. Y no puedes modificar un elemento
// concreto de un array: hay que enviarlo entero.

// Content-Type: application/json-patch+json
// Un ARRAY de operaciones aplicadas en orden,
// con rutas JSON Pointer (RFC 6901).
[
  { "op": "replace", "path": "/estado",
    "value": "HECHA" },
  { "op": "add", "path": "/etiquetas/-",
    "value": "urgente" },
  { "op": "remove", "path": "/responsableId" },
  { "op": "test", "path": "/version",
    "value": 7 }
]

// Más expresivo: opera sobre elementos concretos
// de un array y "test" permite precondiciones.
// Más complejo de validar y de documentar.

import { PartialType } from '@nestjs/swagger';
import { IsIn, IsInt, IsOptional, Min, ValidateIf } from 'class-validator';

// El truco del Merge Patch en TypeScript: hay que distinguir
// "campo ausente" (no tocar) de "campo con null" (borrar). Como
// undefined y null son cosas distintas, el DTO debe permitir null
// explícitamente en los campos que sean anulables, y el servicio
// debe recorrer las CLAVES PRESENTES, no los valores definidos.
export class PatchTaskDto extends PartialType(CreateTaskDto) {
  @IsOptional()
  @ValidateIf((_, valor) => valor !== null)   // null es válido: borra
  @IsInt()
  @Min(1)
  responsableId?: number | null;

  @IsOptional()
  @IsIn(['ABIERTA', 'EN_CURSO', 'HECHA', 'CANCELADA'])
  estado?: EstadoTarea;
}

async aplicarMergePatch(id: number, parche: PatchTaskDto): Promise<Task> {
  const tarea = await this.em.findOneOrFail(Task, id);

  // Recorremos las claves PRESENTES en el cuerpo recibido. Usar
  // Object.entries del DTO ya validado evita el fallo clásico de
  // hacer `tarea.horas = parche.horas ?? tarea.horas`, que hace
  // IMPOSIBLE borrar un campo poniéndolo a null.
  for (const [clave, valor] of Object.entries(parche)) {
    if (valor === null && !CAMPOS_ANULABLES.has(clave)) {
      throw new UnprocessableEntityException(
        `El campo ${clave} no admite null`);
    }
    (tarea as Record<string, unknown>)[clave] = valor;
  }

  await this.em.flush();   // el Unit of Work calcula el UPDATE mínimo
  return tarea;
}

25.3.3 Los métodos que se olvidan: HEAD y OPTIONS

HEAD devuelve exactamente las mismas cabeceras que un GET pero sin cuerpo. Sirve para comprobar si un recurso existe, conocer su tamaño (Content-Length) o leer su ETag antes de decidir si merece la pena descargarlo. Es especialmente útil con ficheros grandes: en TaskFlow, un cliente que quiera saber si el informe mensual en PDF ha cambiado puede hacer HEAD /reports/2026-07.pdf y comparar el ETag sin transferir cinco megabytes. En NestJS lo tienes gratis: Express responde automáticamente a HEAD ejecutando el manejador de GET y descartando el cuerpo, aunque conviene comprobarlo porque un interceptor que escriba en la respuesta puede estropearlo.

OPTIONS lo envía el navegador solo, como comprobación previa de CORS, y normalmente lo responde el middleware de CORS sin que tú escribas nada. Su otro uso —preguntar qué métodos admite un recurso y recibir la cabecera Allow— es raro en la práctica y no conviene invertir esfuerzo en él.

25.4 Códigos de estado usados con criterio

El código de estado es la parte de la respuesta que las máquinas leen primero, y a menudo la única que leen. Un cliente HTTP decide con él si reintentar, si redirigir, si invalidar su caché, si pedir credenciales o si registrar una alerta. Elegirlo mal no es un detalle estético: es romper el comportamiento automático de bibliotecas, proxies y monitorización.

Las cinco familias tienen un significado que conviene recordar como una frase: 1xx «sigo trabajando», 2xx «hecho», 3xx «mira en otro sitio», 4xx «el problema está en tu petición, no la repitas igual» y 5xx «el problema es mío, quizá funcione si lo intentas de nuevo». Esa última distinción es la más importante de todo el capítulo desde el punto de vista operativo: los 4xx no deben disparar alertas y los 5xx sí, porque un 4xx es el sistema funcionando (rechazando algo que debía rechazar) y un 5xx es el sistema fallando.

25.4.1 Tabla de referencia con el caso de TaskFlow

25.4.2 Los que casi todo el mundo usa mal

200 con un error dentro. Es la peor práctica de este capítulo y, con diferencia, la más extendida. Consiste en responder siempre 200 y meter el resultado real en el cuerpo: {"ok": false, "error": "…"}. Rompe absolutamente todo lo que hay entre el cliente y tú: la monitorización cuenta cero errores mientras los usuarios se quejan, las bibliotecas de cliente no lanzan excepción, la lógica de reintento no se activa, los proxies pueden cachear la respuesta de error, y en Angular el error entra por el camino de éxito del Observable, con lo que cada consumidor debe recordar comprobar un campo que el tipo no le obliga a comprobar.

@Get(':id')
async buscar(@Param('id') id: string) {
  const tarea = await this.tasks.buscar(+id);
  if (!tarea) {
    // 200 OK con un error dentro. El cliente,
    // los proxies y el panel de monitorización
    // creen que todo ha ido bien.
    return { ok: false, error: 'No encontrada' };
  }
  return { ok: true, data: tarea };
}
// Y en Angular, esto obliga a escribir en CADA
// consumidor:  if (!r.ok) { ... }
// Un olvido = un undefined en la plantilla.

@Get(':id')
async buscar(@Param('id', ParseIntPipe) id: number) {
  // El servicio lanza un error de DOMINIO y el
  // filtro global lo traduce a 404 con Problem
  // Details. El controlador no sabe de HTTP más
  // de lo imprescindible.
  return this.tasks.obtenerOFallar(id);
}

// El código de estado ES el canal de error:
//   200 -> hay tarea, y el tipo lo garantiza
//   404 -> no hay, y el cliente HTTP lanza
// Angular lo recibe por el camino de error del
// Observable, sin comprobaciones repetidas.

201 sin Location. Un 201 dice «he creado algo»; la pregunta inmediata del cliente es «¿dónde está?». La cabecera Location con la URL canónica del recurso nuevo es parte del contrato, y es lo que permite que un cliente genérico siga trabajando sin conocer tu convención de URL. Devolver además el recurso en el cuerpo es buena idea: ahorra una petición.

@Post()
@HttpCode(HttpStatus.CREATED)                      // 201, no el 201 por defecto de Nest sin más
@ApiCreatedResponse({ type: TaskDto, headers: {
  Location: { description: 'URL canónica de la tarea creada', schema: { type: 'string' } },
} })
async crear(
  @Param('projectId', ParseIntPipe) projectId: number,
  @Body() dto: CreateTaskDto,
  @Res({ passthrough: true }) res: Response,       // passthrough: Nest sigue serializando
): Promise<TaskDto> {
  const tarea = await this.tasks.crear(projectId, dto);

  // Location con ruta absoluta desde la raíz. Evita construirla a mano
  // concatenando cadenas: si mañana cambia el prefijo global, esto se
  // rompe en silencio. Un helper centralizado es preferible.
  res.setHeader('Location', this.urls.tarea(tarea.id));

  return TaskDto.desde(tarea);                     // cuerpo: ahorra un GET al cliente
}

202 para trabajos asíncronos. Cuando aceptas una petición pero el trabajo aún no ha ocurrido —generar un informe, importar un CSV de mil filas, enviar cien correos—, responder 200 es mentir: sugiere que la operación terminó. El 202 dice explícitamente «lo he aceptado, aún no está hecho», y debe acompañarse de una forma de consultar el progreso, que es el patrón completo de 25.11.

204 sin cuerpo. El 204 significa literalmente «no hay contenido», y la RFC 9110 prohíbe enviar cuerpo. Enviarlo igualmente provoca fallos raros: algunos clientes intentan parsear un JSON vacío y lanzan, y en Angular HttpClient con responseType: 'json' devuelve null, lo cual está bien si lo esperas y produce un TypeError si no. Un DELETE exitoso es el caso canónico de 204.

400 frente a 422. Es la distinción que más discusiones genera. La regla operativa que mejor funciona: 400 si no has podido llegar a entender la petición (JSON malformado, un parámetro que debía ser número y llega como texto, falta un campo obligatorio, el tipo es incorrecto) y 422 si la has entendido perfectamente pero viola una regla de negocio (la fecha de fin es anterior a la de inicio, la transición de estado no está permitida, el descuento supera el máximo de la organización). La diferencia importa porque cada uno indica algo distinto al cliente: un 400 casi siempre es un error de programación en el cliente, y un 422 casi siempre es algo que el usuario puede corregir. Dicho esto, muchas APIs excelentes usan solo 400 y detallan en el cuerpo; lo intolerable es mezclarlos al azar.

401 frente a 403. El nombre de 401 es históricamente desafortunado: «Unauthorized» debería ser «Unauthenticated». 401 significa «no sé quién eres»: no hay credenciales, están caducadas o son inválidas; reintentar tras autenticarse puede funcionar, y por eso la respuesta debe incluir WWW-Authenticate. 403 significa «sé quién eres y no tienes permiso»: reintentar con las mismas credenciales nunca funcionará. La consecuencia práctica en Angular es directa: ante un 401 el interceptor intenta refrescar el token y, si falla, lleva al usuario al login; ante un 403 muestra un mensaje de permisos y no intenta refrescar nada. Confundirlos produce el bucle infinito de refresco de token, un clásico.

export const authInterceptor: HttpInterceptorFn = (req, next) => {
  const auth = inject(AuthService);
  const router = inject(Router);

  return next(req).pipe(
    catchError((error: HttpErrorResponse) => {
      // 401: problema de IDENTIDAD. Merece la pena refrescar el token.
      if (error.status === 401 && !req.url.includes('/auth/refresh')) {
        return auth.refrescar().pipe(
          switchMap(() => next(req)),          // reintento con el token nuevo
          catchError(() => {
            auth.cerrarSesion();
            router.navigate(['/login']);
            return throwError(() => error);
          }),
        );
      }

      // 403: problema de PERMISOS. Refrescar el token no cambia nada;
      // insistir solo produce ruido y, si hay bloqueo por intentos,
      // puede acabar bloqueando la cuenta del usuario.
      if (error.status === 403) {
        router.navigate(['/sin-permiso']);
      }

      return throwError(() => error);
    }),
  );
};

404 frente a 403 para no revelar existencia. Hay un caso en el que 404 es preferible aunque el recurso exista: cuando el hecho mismo de que exista es información sensible. Si un usuario pide GET /projects/731 y ese proyecto pertenece a otra organización, responder 403 le confirma que el proyecto 731 existe. Recorriendo identificadores puede deducir cuántos proyectos tiene la competencia, cuándo se crean y a qué ritmo crece el sistema. Es una fuga por enumeración. La regla: 403 cuando el usuario sabe legítimamente que el recurso existe pero no puede hacer esa operación concreta; 404 cuando ni siquiera debería saber que existe. Y por encima de todo, identificadores no adivinables (UUID o ULID) para los recursos sensibles, que resuelven el problema de raíz.

409 para conflictos. El 409 cubre tres situaciones distintas que conviene diferenciar en el cuerpo del error: un duplicado (violación de índice único), una transición de estado inválida y una edición concurrente. Para esta última, si estás usando If-Match, el código correcto es 412, no 409; el 409 queda para cuando detectas el conflicto sin precondición explícita, típicamente al capturar la excepción de bloqueo optimista de MikroORM.

410 Gone. Es un 404 con intención: «esto existió y lo eliminamos a propósito». Sirve para dos cosas muy concretas. Una, retirar una versión de la API: GET /api/v1/tasks respondiendo 410 con un mensaje que indique cómo migrar a v2 es infinitamente más útil que un 404. Dos, recursos purgados por política de retención, donde 410 comunica «no lo busques más» y permite a los rastreadores y a las cachés eliminarlo definitivamente.

429 con Retry-After. Un 429 sin indicación de cuándo reintentar convierte al cliente en un adversario: reintentará inmediatamente, empeorando el problema. Retry-After admite segundos (Retry-After: 30) o una fecha HTTP, y acompañado de las cabeceras de límite (25.17) permite a un cliente bien escrito autorregularse.

La familia 5xx. Un 5xx significa «he fallado yo». Por eso nunca debes usar 500 para comunicar un error de validación, y por eso cada 5xx debe generar una entrada de log con traza completa y contar para tu presupuesto de errores. Distinguir 502, 503 y 504 aporta información operativa real: 502 apunta a una dependencia que respondió mal, 503 a una indisponibilidad tuya conocida y 504 a un tiempo de espera agotado. Añadir Retry-After a un 503 durante un despliegue permite que los clientes esperen en lugar de martillear.

25.5 Diseño de recursos y URL

Una URL es la parte más pública y más permanente de tu API. Puedes reescribir el servicio, cambiar de base de datos y migrar de Express a Fastify sin que ningún cliente se entere; cambiar una URL rompe a todo el mundo. Merece por tanto un rato de diseño consciente en lugar de emerger por acumulación de @Get().

La idea central de REST, tal como la formuló Roy Fielding en su tesis doctoral de 2000, es que el sistema se modela como un conjunto de recursos identificados por URI, sobre los que se aplica un conjunto uniforme y pequeño de operaciones. El giro mental que cuesta hacer es dejar de pensar en «qué funciones expongo» para pensar en «qué cosas existen en mi dominio». No expones crearTarea, listarTareas y borrarTarea: expones el recurso tarea, y HTTP ya trae los verbos.

25.5.1 Sustantivos en plural y consistencia

Las convenciones dominantes en la industria, y las que siguen Google, Microsoft, Stripe y GitHub con pequeñas variantes, son estas:

25.5.2 Jerarquía y anidamiento: hasta dónde

El anidamiento expresa pertenencia: /projects/9/tasks son las tareas del proyecto 9. Es útil y comunica bien, pero tiene un techo. La regla empírica, y la recomiendan tanto la guía de Google como la de Microsoft, es no pasar de un nivel de anidamiento. En cuanto llegas a tres, las URL se vuelven frágiles: cualquier reorganización del dominio las invalida, y el cliente necesita conocer toda la cadena de identificadores para acceder a algo que tiene identificador propio.

# Anidamiento profundo: para leer un comentario
# necesitas cuatro identificadores, y tres de
# ellos no aportan nada.
GET /organizations/3/projects/9/tasks/42/comments/7

# Peor aún: la misma cosa accesible por dos
# caminos distintos, con dos cachés distintas
# y dos permisos que hay que mantener iguales.
GET /tasks/42/comments/7
GET /comments/7

# Y verbos disfrazados de recurso:
POST /projects/9/tasks/42/markAsDone
GET  /projects/9/getTaskCount
POST /tasks/search-by-user-and-status

# Un nivel de anidamiento para CREAR y LISTAR,
# donde el padre sí es necesario:
GET  /projects/9/tasks
POST /projects/9/tasks

# Y acceso PLANO al elemento, que ya tiene
# identificador propio y único:
GET    /tasks/42
PATCH  /tasks/42
DELETE /tasks/42
GET    /tasks/42/comments      # un nivel, otra vez

# Filtrar es un parámetro, no una ruta nueva:
GET /tasks?projectId=9&estado=ABIERTA&responsableId=7

La regla que resume todo esto: anida para crear y para listar, aplana para leer, modificar y borrar. Cuando creas una tarea necesitas decir en qué proyecto va, y la URL es el sitio natural para esa información; cuando ya existe y tiene identificador, exigir el proyecto es redundante y además abre una pregunta incómoda: ¿qué haces si /projects/9/tasks/42 se pide y la tarea 42 pertenece al proyecto 5? La respuesta correcta es 404, y tener que implementar y probar esa comprobación en cada endpoint es un coste que se evita aplanando.

25.5.3 Identificadores

La elección del identificador público es una decisión de arquitectura y de seguridad, no un detalle. Tres opciones razonables:

25.5.4 Acciones que no encajan en CRUD

Antes o después aparece «archivar un proyecto», «reabrir una tarea», «duplicar una plantilla», «enviar un recordatorio». No son creaciones, ni lecturas, ni actualizaciones genéricas, ni borrados. Hay tres soluciones válidas, en orden de preferencia:

Opción 1 · Modelar el estado como un campo y usar PATCH. Si «archivar» es simplemente poner archivado = true, entonces PATCH /projects/9 con {"archivado": true} es la respuesta correcta y no hace falta inventar nada. Es la opción por defecto y la que más gente descarta demasiado rápido.

Opción 2 · Convertir la acción en un subrecurso. Cuando la acción tiene entidad propia —porque se puede consultar, porque tiene fecha y autor, porque hay reglas de negocio detrás—, el subrecurso es más expresivo que un campo booleano. «Archivar» pasa a ser un recurso archive que se crea con PUT y se elimina con DELETE:

# Archivar y desarchivar: el archivo es un recurso singular
PUT    /projects/9/archive     -> 204   (idempotente: archivar dos veces = archivado)
DELETE /projects/9/archive     -> 204   (desarchivar)
GET    /projects/9/archive     -> 200 {"archivadoEn":"…","porUsuarioId":7}
                               -> 404 si no está archivado

# Otras acciones frecuentes bien modeladas:
PUT    /tasks/42/assignee      {"userId": 7}     # fijar responsable (idempotente)
DELETE /tasks/42/assignee                        # quitar responsable
POST   /tasks/42/comments      {"texto": "…"}    # comentar crea un recurso
POST   /projects/9/exports     {"formato":"xlsx"} -> 202 + Location del trabajo
POST   /invitations            {"email":"…"}     # invitar crea una invitación
PUT    /tasks/42/read-state    -> 204            # marcar como leída

Opción 3 · El verbo explícito, asumido conscientemente. Para operaciones que de verdad no son un recurso —POST /tasks/42/duplicate, POST /auth/login, POST /payments/17/refund— usar un verbo al final con POST es aceptable y lo hacen APIs muy respetadas. Google lo llama «métodos personalizados» y su guía los admite con la sintaxis recurso:accion. Lo importante es que sea la excepción y no la norma, que siempre sea POST (no es seguro ni idempotente) y que esté documentado como tal.

25.5.5 Qué no poner nunca en una URL

• Tokens, claves de API o contraseñas. Las URL se escriben enteras en los logs del proxy, del CDN y del servidor, quedan en el historial del navegador y viajan en la cabecera Referer hacia terceros. Un token en la query string es un token comprometido. Van en Authorization.
• Datos personales. /users?dni=12345678A deja el DNI en cinco sistemas de logs distintos que probablemente no están en tu registro de tratamiento de datos. Si el criterio de búsqueda es sensible, va en el cuerpo de un POST a un subrecurso de búsqueda.
• Detalles de implementación. /api/v1/TaskEntity o /api/getTasksFromMaterializedView acoplan el contrato público a tu esquema interno. Cuando cambies el esquema, o mientes o rompes.
• Números de versión de la implementación. /api/2.4.1/tasks obliga a que cada despliegue sea un cambio de contrato. La versión de la API es del contrato, no del código: v1, v2, y punto.
• El verbo cuando ya está en el método, y el formato cuando ya está en Accept.
• Filtros infinitos concatenados en la ruta, del estilo /tasks/estado/ABIERTA/responsable/7/orden/fecha. Eso son parámetros de consulta: son opcionales, combinables y no crean recursos nuevos.

25.6 Colecciones: paginación, filtrado, ordenación y expansión

El endpoint de listado es el que más tráfico recibe, el que más consultas caras genera y el que peor suele estar diseñado. Un GET /tasks que devuelve todas las tareas funciona perfectamente durante seis meses y deja de funcionar el día que un cliente importa cincuenta mil filas, normalmente a las tres de la mañana y con la memoria del proceso agotada.

25.6.1 Paginación: desplazamiento frente a cursor

Hay dos familias, y elegir mal tiene consecuencias medibles. La paginación por desplazamiento (offset) usa ?page=3&limit=20 o ?offset=40&limit=20 y se traduce directamente a LIMIT 20 OFFSET 40. La paginación por cursor usa ?cursor=eyJpZCI6NDJ9&limit=20 y se traduce a un WHERE (creado_en, id) < (…, …) ORDER BY creado_en DESC, id DESC LIMIT 20.

// Offset sobre una tabla de 4 millones de filas.
// La página 1 tarda 3 ms; la página 5.000 tarda
// 1,8 s porque PostgreSQL debe leer y descartar
// 100.000 filas antes de empezar a devolver.
// Y si alguien inserta una tarea mientras el
// usuario pasa de página, verá un elemento
// repetido y se perderá otro sin enterarse.
async listar(page = 1, limit = 20) {
  return this.em.findAndCount(Task, {}, {
    offset: (page - 1) * limit,
    limit,
    orderBy: { creadoEn: 'DESC' },   // sin desempate
  });
}

// Cursor con clave compuesta ESTABLE: (creadoEn, id).
// El id desempata las marcas de tiempo idénticas; sin
// él la paginación se salta filas de forma aleatoria.
async listar(cursor?: string, limit = 20) {
  const c = cursor ? decodificarCursor(cursor) : null;

  const where: FilterQuery<Task> = c
    ? { $or: [
        { creadoEn: { $lt: c.creadoEn } },
        { creadoEn: c.creadoEn, id: { $lt: c.id } },
      ] }
    : {};

  // limit + 1: la fila sobrante nos dice si hay más
  // páginas sin necesidad de un COUNT costoso.
  const filas = await this.em.find(Task, where, {
    orderBy: [{ creadoEn: 'DESC' }, { id: 'DESC' }],
    limit: limit + 1,
  });

  const hayMas = filas.length > limit;
  const datos = hayMas ? filas.slice(0, limit) : filas;
  return { datos, siguiente: hayMas
    ? codificarCursor(datos.at(-1)!) : null };
}

El cursor debe ser opaco para el cliente. Se codifica en Base64URL y se documenta como «cadena que devuelve el servidor y que el cliente reenvía sin interpretar». Que sea legible es una invitación a que alguien lo construya a mano y quede acoplado a tu esquema; conviene además firmarlo si el orden puede depender de permisos.

import { createHmac, timingSafeEqual } from 'node:crypto';

export interface Cursor { creadoEn: string; id: number }

export function codificarCursor(t: { creadoEn: Date; id: number }): string {
  const cuerpo = Buffer.from(JSON.stringify({
    creadoEn: t.creadoEn.toISOString(), id: t.id,
  })).toString('base64url');

  // Firma corta: impide que un cliente fabrique cursores arbitrarios
  // para saltarse filtros de visibilidad aplicados en el WHERE.
  const firma = createHmac('sha256', process.env.CURSOR_SECRET!)
    .update(cuerpo).digest('base64url').slice(0, 16);

  return `${cuerpo}.${firma}`;
}

export function decodificarCursor(valor: string): Cursor {
  const [cuerpo, firma] = valor.split('.');
  const esperada = createHmac('sha256', process.env.CURSOR_SECRET!)
    .update(cuerpo ?? '').digest('base64url').slice(0, 16);

  if (!firma || !timingSafeEqual(Buffer.from(firma), Buffer.from(esperada))) {
    throw new BadRequestException('El cursor no es válido');
  }
  return JSON.parse(Buffer.from(cuerpo, 'base64url').toString());
}

25.6.2 Filtrado, ordenación y selección de campos

Los tres se expresan con parámetros de consulta, y los tres tienen la misma trampa: si dejas que el cliente escriba nombres de columna, has expuesto tu esquema y probablemente has abierto una inyección. La defensa es siempre la misma: lista blanca explícita.

// El cliente decide el ORDER BY. Dos problemas:
// 1) Acoplas la API a los nombres de columna.
// 2) Según el ORM y cómo se construya, puede
//    acabar concatenado en el SQL.
// Y aunque no haya inyección, ?sort=descripcion
// sobre 4 millones de filas sin índice tumba
// la base de datos: es una denegación de
// servicio que ofreces tú amablemente.
@Get()
listar(@Query('sort') sort = 'id') {
  return this.em.find(Task, {}, {
    orderBy: { [sort]: 'ASC' },
  });
}

// Lista blanca: solo campos del CONTRATO, con
// nombre público, traducidos a columna, y solo
// los que tienen índice que los soporte.
const ORDENABLES = {
  creadoEn:    'creadoEn',
  vencimiento: 'vencimiento',
  prioridad:   'prioridad',
  titulo:      'titulo',
} as const;

function traducirOrden(sort?: string) {
  // Formato:  ?sort=-vencimiento,titulo
  const partes = (sort ?? '-creadoEn').split(',');
  return partes.map((p) => {
    const desc = p.startsWith('-');
    const clave = desc ? p.slice(1) : p;
    if (!(clave in ORDENABLES)) {
      throw new BadRequestException(
        `No se puede ordenar por "${clave}"`);
    }
    return { [ORDENABLES[clave]]: desc ? 'DESC' : 'ASC' };
  });
}

Para el filtrado hay dos estilos. El plano, ?estado=ABIERTA&responsableId=7, es legible y suficiente para el noventa por ciento de los casos. El estructurado, ?filter[vencimiento][lte]=2026-08-31 o ?vencimiento_lte=2026-08-31, aparece cuando necesitas operadores. Elige uno, documéntalo y no lo mezcles. Y define desde el principio dos cosas que siempre se olvidan: qué ocurre con un parámetro desconocido (recomendación: 400, para que los errores tipográficos del cliente sean visibles en lugar de silenciosos) y cómo se expresan los valores múltiples (?estado=ABIERTA,EN_CURSO o ?estado=ABIERTA&estado=EN_CURSO; el primero es más compacto, el segundo más estándar).

La selección de campos (?fields=id,titulo,estado) reduce el tamaño de la respuesta y es útil en móviles, pero tiene un coste alto: multiplica las variantes de la respuesta, complica la caché (hay que añadir fields a la clave), rompe la tipificación del cliente generado y dificulta la documentación. Ofrécela solo si tienes una necesidad medida. La expansión de relaciones (?expand=responsable,proyecto) resuelve el problema contrario —evitar que el cliente haga N peticiones— y suele aportar más valor, siempre que impongas un límite estricto de qué se puede expandir y a qué profundidad, porque cada expansión es un JOIN o una consulta adicional, y ahí acecha el problema N+1 del capítulo 16.

25.6.3 Contrato completo del listado de tareas

GET /api/v1/projects/9/tasks
      ?estado=ABIERTA,EN_CURSO      # filtro múltiple, valores del enum
      &responsableId=7              # filtro por relación
      &vencimiento_lte=2026-08-31   # filtro con operador
      &q=contrato                   # búsqueda de texto en titulo y descripcion
      &sort=-prioridad,vencimiento  # lista blanca; el guion indica descendente
      &expand=responsable           # expansión permitida, un nivel
      &limit=20                     # 1..100, por defecto 20
      &cursor=eyJjcmVhZG…           # opaco, lo devuelve el servidor
Accept: application/json
Authorization: Bearer …

{
  "data": [
    {
      "id": 42,
      "titulo": "Revisar contrato del proveedor",
      "estado": "EN_CURSO",
      "prioridad": "ALTA",
      "vencimiento": "2026-08-14",
      "horas": 3.5,
      "responsable": { "id": 7, "nombre": "Ana Ruiz" },
      "proyectoId": 9,
      "version": 8,
      "creadoEn": "2026-07-02T09:14:00.000Z",
      "actualizadoEn": "2026-07-30T16:22:11.000Z"
    }
  ],
  "meta": {
    "limit": 20,
    "contadoEnPagina": 20,
    "hayMas": true,
    "totalAproximado": 1483
  },
  "links": {
    "self": "/api/v1/projects/9/tasks?limit=20&estado=ABIERTA,EN_CURSO",
    "next": "/api/v1/projects/9/tasks?limit=20&estado=ABIERTA,EN_CURSO&cursor=eyJjcmVhZG…"
  }
}

Cuatro decisiones de este contrato merecen justificación. Primera: la lista va dentro de data, nunca en la raíz. Devolver un array desnudo impide añadir metadatos más adelante sin romper el contrato, y históricamente fue vector de un ataque de robo de JSON en navegadores antiguos. Segunda: hayMas es booleano en lugar de un total exacto, porque un COUNT(*) con filtros sobre una tabla grande puede costar más que la propia consulta; si el cliente necesita un total, ofrécelo como aproximación o como parámetro opcional. Tercera: links.next viene ya construido, de modo que el cliente no tiene que saber montar el cursor. Y cuarta: los campos de fecha van en ISO 8601 con zona UTC, y las fechas sin hora (vencimiento) sin zona, porque son fechas de calendario y no instantes; confundir ambas cosas es el origen del clásico «la fecha se muestra un día antes» del capítulo 29.

@Injectable({ providedIn: 'root' })
export class TaskApiService {
  private readonly http = inject(HttpClient);
  private readonly base = inject(API_BASE_URL);

  listar(proyectoId: number, filtros: FiltrosTareas): Observable<PaginaTareas> {
    // HttpParams escapa correctamente los valores; concatenar la cadena a
    // mano rompe con acentos, espacios y con el carácter + en las fechas.
    let params = new HttpParams()
      .set('limit', String(filtros.limit ?? 20))
      .set('sort', filtros.orden ?? '-creadoEn');

    if (filtros.estados?.length) params = params.set('estado', filtros.estados.join(','));
    if (filtros.responsableId)   params = params.set('responsableId', filtros.responsableId);
    if (filtros.cursor)          params = params.set('cursor', filtros.cursor);

    return this.http.get<PaginaTareas>(
      `${this.base}/projects/${proyectoId}/tasks`, { params });
  }

  // El scroll infinito consume "links.next" tal cual: el cliente no
  // reconstruye la URL, solo la sigue. Si mañana cambias el formato del
  // cursor o añades un parámetro, el cliente no se entera.
  siguientePagina(url: string): Observable<PaginaTareas> {
    return this.http.get<PaginaTareas>(url);
  }
}

25.7 Errores: el contrato que se diseña el último y se usa el primero

Los errores son la parte de la API que más se usa en el peor momento: cuando algo va mal, cuando hay usuarios esperando y cuando el desarrollador que integra tu API no tiene tiempo. Un error bien diseñado ahorra horas; un {"message": "Error"} con un 500 las consume.

Un buen error responde a cuatro preguntas: qué ha pasado (de forma que una máquina pueda decidir), por qué (de forma que una persona lo entienda), qué campo concreto está mal si aplica, y cómo puedo rastrear este caso concreto cuando escriba al soporte.

25.7.1 Problem Details, RFC 9457

En lugar de inventar un formato por proyecto, existe uno estándar: RFC 9457, «Problem Details for HTTP APIs», que en 2023 sustituyó a la RFC 7807 (los cambios son menores; el campo instance se aclaró y se añadieron los tipos de error registrados). Se identifica con el tipo de medio application/problem+json y define estos campos:

// Cada endpoint con su propio formato.
// Imposible de tratar genéricamente.
{ "error": "Algo ha fallado" }

// Otro endpoint, otro formato:
{ "success": false, "msg": "bad state",
  "code": -17 }

// Y el peor de todos: la traza en el cuerpo.
{
  "statusCode": 500,
  "message": "duplicate key value violates
     unique constraint \"task_slug_uq\"",
  "stack": "at TaskRepo.save (/srv/app/dist/
     tasks/task.repository.js:88:15) …",
  "query": "INSERT INTO task (…) VALUES (…)"
}
// Regalo para quien busque vulnerabilidades:
// nombres de tablas, restricciones y rutas.

// Content-Type: application/problem+json
{
  "type": "https://api.taskflow.dev/errors/
           transicion-no-permitida",
  "title": "Transición de estado no permitida",
  "status": 422,
  "detail": "Una tarea CANCELADA no puede pasar
             a HECHA. Reábrela primero.",
  "instance": "/api/v1/tasks/42",

  "code": "TASK_TRANSICION_INVALIDA",
  "estadoActual": "CANCELADA",
  "estadoSolicitado": "HECHA",
  "transicionesPermitidas": ["ABIERTA"],
  "requestId": "8f2c1d3e-77aa-4b19-9e0c-51a2…",
  "timestamp": "2026-07-31T17:04:22.812Z"
}
// La máquina lee "type" o "code"; la persona
// lee "detail"; el soporte usa "requestId".

25.7.2 Errores de validación campo a campo

Un formulario de Angular necesita saber qué campo está mal para pintar el mensaje debajo del control correcto. Un error global obliga a la interfaz a adivinar, o a mostrar un aviso genérico que empeora la experiencia. La extensión habitual es un array errors con una entrada por problema:

{
  "type": "https://api.taskflow.dev/errors/validacion",
  "title": "La solicitud contiene campos inválidos",
  "status": 422,
  "detail": "Revisa los 3 campos indicados en errors.",
  "instance": "/api/v1/projects/9/tasks",
  "requestId": "8f2c1d3e-77aa-4b19-9e0c-51a2d0b3e6f4",
  "errors": [
    { "campo": "titulo",      "code": "MIN_LENGTH",
      "mensaje": "Debe tener al menos 3 caracteres", "recibido": "ab" },
    { "campo": "vencimiento", "code": "FECHA_ANTERIOR",
      "mensaje": "No puede ser anterior a la fecha de inicio del proyecto" },
    { "campo": "etiquetas[2]", "code": "NO_PERMITIDO",
      "mensaje": "La etiqueta \"urgente!\" contiene caracteres no permitidos" }
  ]
}

Fíjate en tres detalles del diseño. El nombre del campo usa la ruta del cuerpo, con notación de índice para los arrays (etiquetas[2]) y de punto para lo anidado (responsable.email), de modo que el cliente puede localizar el control sin ambigüedad. Cada entrada lleva un code simbólico además del mensaje, para que el cliente pueda traducir a su idioma o mostrar un texto propio. Y recibido aparece solo cuando el valor no es sensible: nunca eches en un mensaje de error la contraseña que el usuario escribió mal.

interface ErrorCampo { campo: string; code: string; mensaje: string }

// Vuelca los errores del servidor sobre el FormGroup para que cada
// mensaje aparezca bajo su control. Es la razón práctica por la que el
// contrato de errores debe incluir la RUTA del campo: sin ella, esta
// función no puede existir y la interfaz muestra un aviso genérico.
export function aplicarErroresServidor(form: FormGroup, errores: ErrorCampo[]): void {
  for (const e of errores) {
    // "etiquetas[2]" -> ["etiquetas", "2"]  para AbstractControl.get()
    const ruta = e.campo.replace(/\[(\d+)\]/g, '.$1');
    const control = form.get(ruta);

    if (control) {
      control.setErrors({ ...(control.errors ?? {}), servidor: e.mensaje });
      control.markAsTouched();
    } else {
      // Campo que no existe en el formulario: no lo perdemos, lo
      // mostramos arriba. Suele indicar que el contrato cambió.
      form.setErrors({ ...(form.errors ?? {}), servidor: e.mensaje });
    }
  }
}

25.7.3 Identificador de correlación

Cuando un usuario llama a soporte y dice «me da error al guardar», el equipo tiene que encontrar esa petición entre millones. El identificador de correlación resuelve exactamente eso: un valor único por petición que aparece en la respuesta, en todos los registros del servidor y, si usas trazado distribuido, en el intervalo de la traza. El usuario copia un código de la pantalla de error y el soporte encuentra la petición en segundos.

La implementación tiene tres piezas. En el servidor, un middleware genera el identificador (o reutiliza el que llegue en X-Request-Id si viene de un proxy de confianza), lo guarda en un almacenamiento de contexto asíncrono y lo devuelve como cabecera. En el filtro de errores, se incluye en el cuerpo del Problem Details. En el cliente, se muestra en la pantalla de error con un botón de copiar. Merece la pena adoptar además la cabecera estándar traceparent del W3C si tienes OpenTelemetry, porque entonces el identificador enlaza con la traza completa.

@Catch()
export class ProblemDetailsFilter implements ExceptionFilter {
  private readonly log = new Logger('HTTP');

  constructor(private readonly config: ConfigService) {}

  catch(excepcion: unknown, host: ArgumentsHost): void {
    const ctx = host.switchToHttp();
    const res = ctx.getResponse<Response>();
    const req = ctx.getRequest<Request>();
    const requestId = contextoActual()?.requestId ?? 'desconocido';

    const problema = this.traducir(excepcion, req, requestId);

    // 4xx: el sistema funcionando. Nivel warn, sin traza, no alerta.
    // 5xx: el sistema fallando. Nivel error, con traza, sí alerta.
    if (problema.status >= 500) {
      this.log.error({ requestId, ruta: req.url, err: excepcion },
        'Error no controlado');
    } else {
      this.log.warn({ requestId, ruta: req.url, code: problema.code },
        problema.title);
    }

    res.status(problema.status)
       .type('application/problem+json')   // NO application/json
       .json(problema);
  }

  private traducir(e: unknown, req: Request, requestId: string): ProblemaHttp {
    const base = { instance: req.originalUrl, requestId,
                   timestamp: new Date().toISOString() };

    if (e instanceof ErrorDeDominio) {          // capítulo 20: errores propios
      return { ...base, status: e.estadoHttp, type: `${TIPOS}/${e.slug}`,
               title: e.titulo, detail: e.mensajePublico, code: e.code };
    }

    if (e instanceof UniqueConstraintViolationException) {
      // Traducimos el error del ORM SIN filtrar el nombre de la restricción,
      // que revelaría el esquema de la base de datos.
      return { ...base, status: 409, type: `${TIPOS}/recurso-duplicado`,
               title: 'El recurso ya existe', code: 'RECURSO_DUPLICADO',
               detail: 'Ya existe un elemento con esos datos únicos.' };
    }

    if (e instanceof HttpException) {
      const status = e.getStatus();
      return { ...base, status, type: `${TIPOS}/${slugDe(status)}`,
               title: mensajeEstandar(status), detail: detalleSeguro(e) };
    }

    // Desconocido: 500 con mensaje genérico SIEMPRE, en cualquier entorno.
    // El detalle está en el log, indexado por requestId.
    return { ...base, status: 500, type: `${TIPOS}/error-interno`,
             title: 'Error interno del servidor', code: 'ERROR_INTERNO',
             detail: `No hemos podido completar la operación. `
                   + `Si vuelve a ocurrir, indica el código ${requestId}.` };
  }
}

25.7.4 Qué no revelar nunca

• Trazas de pila, rutas del sistema de ficheros y nombres de módulos internos. Describen tu arquitectura y a menudo la versión exacta de las dependencias, lo que permite buscar vulnerabilidades conocidas.
• SQL, nombres de tablas, columnas o restricciones. «violates unique constraint task_slug_uq» le dice a un atacante que existe una tabla task con un campo slug único.
• Si un usuario existe o no. En el login y en el «he olvidado mi contraseña», la respuesta debe ser idéntica exista o no la cuenta; si no, tienes un enumerador de usuarios gratuito. El mismo criterio vale para el tiempo de respuesta: comparar siempre el hash, aunque el usuario no exista, evita distinguirlos por temporización.
• Datos de otros usuarios en el mensaje. «Ese correo ya lo usa Ana Ruiz» filtra información personal a quien solo estaba probando correos.
• Valores de campos sensibles en el eco del error: contraseñas, tokens, números de tarjeta, aunque sean inválidos.
• Diferencias entre entornos. Un mensaje detallado «solo en desarrollo» acaba activándose en producción por una variable de entorno mal puesta. Es más seguro que el cuerpo sea siempre genérico y que el detalle viva únicamente en los logs.

25.8 Caché HTTP: la optimización más desaprovechada

La respuesta más rápida es la que no se pide. La segunda más rápida es la que responde un CDN a treinta kilómetros del usuario sin tocar tu servidor. Y sin embargo, la inmensa mayoría de las APIs no emite ninguna cabecera de caché útil, con lo que el navegador, el proxy corporativo y el CDN no tienen más remedio que preguntar siempre. Es dinero y latencia tirados por una línea de configuración que nadie escribió.

Conviene separar dos ideas que se mezclan. La frescura responde a «¿puedo usar mi copia sin preguntar?» y la controla Cache-Control. La validación responde a «mi copia ha caducado, ¿sigue sirviendo?» y la controlan ETag y Last-Modified. Una API bien diseñada usa las dos: frescura corta o nula para datos que cambian, validación siempre.

25.8.1 Cache-Control, directiva a directiva

25.8.2 ETag, revalidación y el 304

Un ETag es un identificador opaco del estado actual de un recurso. Puede ser fuerte ("v8-91cd02": los bytes son idénticos) o débil (W/"v8": semánticamente equivalente, aunque los bytes difieran en detalles irrelevantes). El cliente lo guarda y, en la siguiente petición, lo envía en If-None-Match. Si coincide, el servidor responde 304 Not Modified sin cuerpo, y el cliente reutiliza su copia.

  FLUJO DE REVALIDACIÓN CON ETag

  PRIMERA PETICIÓN (la caché está vacía)
  ─────────────────────────────────────────────────────────────────────────
  Angular ──── GET /api/v1/tasks/42 ─────────────────────────> NestJS
                                                                  │
                                                     calcula el estado y
                                                     su ETag: "v8-91cd02"
                                                                  │
  Angular <─── 200 OK  (2,4 KB) ─────────────────────────────────┘
               ETag: "v8-91cd02"
               Cache-Control: private, no-cache
               {"id":42,"titulo":"Revisar contrato", …}
       │
       └─ el navegador GUARDA cuerpo + ETag
          ("no-cache" = guarda, pero pregunta antes de usar)


  SEGUNDA PETICIÓN (el usuario vuelve a la pantalla)
  ─────────────────────────────────────────────────────────────────────────
  Angular ──── GET /api/v1/tasks/42 ─────────────────────────> NestJS
               If-None-Match: "v8-91cd02"                          │
                                                     ┌─────────────┴──────┐
                                                     │ ¿el ETag actual    │
                                                     │  sigue siendo      │
                                                     │  "v8-91cd02"?      │
                                                     └──┬──────────────┬──┘
                                                       SÍ             NO
                                                        │              │
  Angular <─── 304 Not Modified (0 bytes) ──────────────┘              │
               ETag: "v8-91cd02"                                       │
       │                                                               │
       └─ usa su copia local. Ahorro: 2,4 KB y toda                    │
          la serialización del servidor.                               │
                                                                       │
  Angular <─── 200 OK  (2,4 KB) ───────────────────────────────────────┘
               ETag: "v9-4ab7de"   <- nuevo estado, nueva etiqueta
       │
       └─ reemplaza su copia y guarda el ETag nuevo


  LO QUE SE AHORRA Y LO QUE NO
  ─────────────────────────────────────────────────────────────────────────
  SE AHORRA   ancho de banda, serialización JSON, tiempo de parseo en el
              cliente, y el repintado si el marco compara referencias.
  NO SE AHORRA  el viaje de ida y vuelta ni, si lo calculas mal, la
              consulta a la base de datos. Para ahorrar la consulta, el
              ETag debe salir de un dato BARATO: una columna de versión
              o un updated_at indexado, nunca del JSON ya construido.

Ese último matiz es el que separa una implementación útil de una decorativa. Si calculas el ETag haciendo un hash del JSON final, has hecho todo el trabajo caro —consultar, cargar relaciones, serializar— y solo te ahorras el envío. Está bien si el cuello de botella es la red, pero el verdadero premio es calcular la etiqueta a partir de un dato que puedas obtener con una consulta mínima.

// Hash del cuerpo ya serializado: hemos hecho
// TODO el trabajo caro antes de descubrir que
// no hacía falta. La base de datos ha sufrido
// exactamente igual que sin caché.
intercept(ctx: ExecutionContext, next: CallHandler) {
  return next.handle().pipe(map((cuerpo) => {
    const etag = createHash('sha1')
      .update(JSON.stringify(cuerpo)).digest('hex');
    const res = ctx.switchToHttp().getResponse();
    res.setHeader('ETag', `"${etag}"`);
    return cuerpo;
  }));
}

// El ETag sale de la columna de versión, que se
// obtiene con un SELECT de dos columnas. Si el
// cliente ya la tiene, cortamos ANTES de cargar
// relaciones y de serializar nada.
@Get(':id')
async obtener(
  @Param('id', ParseIntPipe) id: number,
  @Headers('if-none-match') ifNoneMatch: string | undefined,
  @Res({ passthrough: true }) res: Response,
) {
  const { version, actualizadoEn } =
    await this.tasks.versionDe(id);      // SELECT barato
  const etag = `"v${version}-${+actualizadoEn}"`;

  res.setHeader('ETag', etag);
  res.setHeader('Cache-Control', 'private, no-cache');

  if (ifNoneMatch === etag) {
    res.status(HttpStatus.NOT_MODIFIED);
    return undefined;                    // 304 SIN cuerpo
  }
  return this.tasks.obtenerCompleta(id); // solo si hace falta
}

Last-Modified e If-Modified-Since son la alternativa basada en tiempo, y funcionan igual salvo por dos limitaciones: su resolución es de un segundo, así que dos cambios en el mismo segundo son indistinguibles, y el formato de fecha HTTP es incómodo de manejar. Se usan sobre todo con ficheros estáticos, donde la fecha de modificación es natural. Cuando el servidor envía las dos cabeceras y el cliente las dos precondiciones, If-None-Match tiene prioridad y If-Modified-Since se ignora.

25.8.3 Caché privada, compartida e invalidación

La diferencia entre la caché del navegador y la del CDN no es solo de ubicación: es de quién puede ver la respuesta. La del navegador es privada por naturaleza; la del CDN sirve a miles de usuarios. De ahí que la decisión más importante sea private frente a public, y que la respuesta por defecto para una API autenticada deba ser private.

La invalidación tiene fama de ser uno de los dos problemas difíciles de la informática, y en HTTP hay cuatro estrategias, en orden de fiabilidad:

• Caducidad corta. No invalidas: dejas que expire. max-age=30 significa aceptar hasta treinta segundos de desfase. Es la más simple y suficiente muchas más veces de las que parece.
• Revalidación con ETag. No hay nada que invalidar: la caché pregunta siempre y el servidor decide. Es la estrategia por defecto recomendada para datos de negocio.
• URL con huella. El contenido inmutable se sirve en una URL que cambia cuando cambia el contenido (/assets/main.9f8b2c.js). Invalidar consiste en publicar otra URL. Es la única estrategia perfecta, y solo aplica a recursos versionables.
• Purga activa. Llamar a la API del CDN para borrar una clave tras una escritura. Es potente y frágil: hay retardo de propagación, hay que acertar con todas las variantes de la clave y crea un acoplamiento entre tu código de negocio y tu proveedor de CDN.

// Caché en memoria de corta vida con deduplicación de peticiones en vuelo.
// Resuelve un problema concreto: tres componentes que piden el mismo
// catálogo al arrancar generan tres peticiones idénticas simultáneas.
const enCurso = new Map<string, Observable<HttpEvent<unknown>>>();
const almacen = new Map<string, { evento: HttpEvent<unknown>; hasta: number }>();

export const cacheInterceptor: HttpInterceptorFn = (req, next) => {
  // Solo GET: cachear una escritura sería un error grave.
  if (req.method !== 'GET' || req.headers.has('x-sin-cache')) return next(req);

  const clave = req.urlWithParams;
  const guardado = almacen.get(clave);
  if (guardado && guardado.hasta > Date.now()) return of(guardado.evento);

  // Deduplicación: si ya hay una petición idéntica en vuelo, nos unimos.
  const vuelo = enCurso.get(clave);
  if (vuelo) return vuelo;

  const peticion = next(req).pipe(
    tap((evento) => {
      if (evento instanceof HttpResponse) {
        almacen.set(clave, { evento, hasta: Date.now() + 30_000 });
      }
    }),
    finalize(() => enCurso.delete(clave)),
    shareReplay({ bufferSize: 1, refCount: true }),
  );

  enCurso.set(clave, peticion);
  return peticion;
};

25.9 Concurrencia: bloqueo optimista sobre HTTP

Ana y Luis abren la misma tarea. Ana cambia la prioridad a ALTA y guarda. Luis, que tenía la pantalla abierta desde antes, cambia el título y guarda treinta segundos después. Con una implementación ingenua, el guardado de Luis escribe el objeto completo tal como él lo tenía y el cambio de Ana desaparece sin dejar rastro. Nadie ve un error. Es la actualización perdida, y es el problema de concurrencia más común en aplicaciones de gestión.

HTTP tiene una solución nativa y elegante: peticiones condicionales de escritura. El mismo ETag que sirve para la caché sirve para el control de concurrencia. El cliente envía If-Match: "v8-91cd02", que significa «aplica este cambio solo si el recurso sigue en la versión que yo leí». Si no coincide, el servidor responde 412 Precondition Failed y no escribe nada.

# 1 · Ana y Luis leen la misma tarea
GET /api/v1/tasks/42
<- 200 OK   ETag: "v8-91cd02"      (los dos reciben el mismo ETag)

# 2 · Ana guarda primero
PATCH /api/v1/tasks/42        If-Match: "v8-91cd02"
{"prioridad":"ALTA"}
<- 200 OK   ETag: "v9-4ab7de"      (la versión avanza)

# 3 · Luis guarda con el ETag que leyó hace treinta segundos
PATCH /api/v1/tasks/42        If-Match: "v8-91cd02"
{"titulo":"Revisar contrato marco"}
<- 412 Precondition Failed         (no se escribe NADA)
   {
     "type":"https://api.taskflow.dev/errors/conflicto-edicion",
     "title":"La tarea ha cambiado desde que la abriste",
     "status":412,
     "detail":"Ana Ruiz la modificó hace 30 segundos.",
     "versionActual":9,
     "camposCambiados":["prioridad"]
   }

La conexión con MikroORM es directa: la columna anotada con @Property({ version: true }) del capítulo 17 es el estado del que deriva el ETag. El ORM ya incrementa esa columna en cada flush y ya añade WHERE version = ? al UPDATE, lanzando OptimisticLockError si no afecta a ninguna fila. Lo único que falta es traducir esa mecánica de persistencia al lenguaje de HTTP.

@Patch(':id')
async actualizar(
  @Param('id', ParseIntPipe) id: number,
  @Body() dto: PatchTaskDto,
  @Headers('if-match') ifMatch: string | undefined,
  @Res({ passthrough: true }) res: Response,
): Promise<TaskDto> {
  // 428: exigimos la precondición en un recurso con edición concurrente.
  // Es preferible a aceptar la escritura a ciegas: obliga al cliente a
  // participar en el control de concurrencia en lugar de ignorarlo.
  if (!ifMatch) {
    throw new PreconditionRequiredException(
      'Se requiere la cabecera If-Match con el ETag obtenido en el GET');
  }

  const versionEsperada = extraerVersion(ifMatch);   // "v8-…" -> 8

  try {
    // MikroORM comprueba la versión dentro del UPDATE, de forma atómica.
    // Comprobarla antes con un SELECT dejaría una ventana de carrera.
    const tarea = await this.tasks.actualizarConVersion(id, dto, versionEsperada);
    res.setHeader('ETag', etagDe(tarea));
    return TaskDto.desde(tarea);
  } catch (e) {
    if (e instanceof OptimisticLockError) {
      // 412 y no 409: el cliente envió una precondición y no se cumplió.
      throw new PreconditionFailedException(await this.tasks.detalleConflicto(id));
    }
    throw e;
  }
}

async actualizarConVersion(id: number, parche: PatchTaskDto, version: number) {
  // lockVersion delega en el mecanismo del ORM: el UPDATE resultante
  // lleva "WHERE id = ? AND version = ?", y si afecta a 0 filas se
  // lanza OptimisticLockError. Es una comprobación ATÓMICA en la base
  // de datos, no una comparación en memoria.
  const tarea = await this.em.findOneOrFail(Task, id, {
    lockMode: LockMode.OPTIMISTIC,
    lockVersion: version,
  });

  this.em.assign(tarea, parche);
  await this.em.flush();
  return tarea;
}

25.10 Idempotencia: por qué las redes obligan a pensarla

El usuario pulsa «Crear tarea». La petición llega al servidor, la tarea se crea, y justo entonces se corta la conexión móvil. El cliente no recibe respuesta y no puede distinguir dos escenarios muy distintos: que la petición nunca llegara o que llegara y se perdiera la respuesta. Si reintenta, puede crear una tarea duplicada; si no reintenta, puede perder el trabajo del usuario. Este problema no tiene solución sin cooperación del servidor: es una propiedad fundamental de los sistemas distribuidos, no un fallo de programación.

La solución estándar, la que usan Stripe desde 2015 y hoy casi toda pasarela de pago, es la clave de idempotencia: el cliente genera un identificador único por intención —no por intento— y lo envía en una cabecera. El servidor recuerda qué hizo con esa clave y, si la vuelve a ver, devuelve el mismo resultado en lugar de ejecutar la operación otra vez. El IETF está normalizando la cabecera Idempotency-Key; hasta que el documento sea RFC, es un estándar de facto.

  FLUJO DE UNA CLAVE DE IDEMPOTENCIA

  El cliente genera la clave UNA VEZ por intención del usuario
  (al abrir el formulario, no al pulsar el botón: si la genera al pulsar,
   dos pulsaciones = dos claves = dos tareas, y no hemos resuelto nada)

  ┌─ INTENTO 1 ─────────────────────────────────────────────────────────┐
  │ POST /api/v1/projects/9/tasks                                       │
  │ Idempotency-Key: 0f1b1a6c-3a2e-4f0b-9d84-2c1c9a0f77e1               │
  │ {"titulo":"Revisar contrato"}                                       │
  └───────────────────────┬─────────────────────────────────────────────┘
                          ▼
        ┌───────────────────────────────────────────┐
        │ ¿Existe la clave en el almacén?           │
        └───┬───────────────────────────────────┬───┘
           NO                                  SÍ
            │                                   │
            ▼                                   ▼
  ┌─────────────────────┐         ┌──────────────────────────────────┐
  │ RESERVA la clave    │         │ ¿Coincide el hash del cuerpo?    │
  │ estado = EN_CURSO   │         └──┬────────────────────────────┬──┘
  │ (INSERT con índice  │           SÍ                           NO
  │  único: si dos      │            │                            │
  │  peticiones corren  │            ▼                            ▼
  │  a la vez, una      │   ┌──────────────────┐   ┌───────────────────────────┐
  │  pierde y va al     │   │ ¿estado?         │   │ 422 Unprocessable Content │
  │  camino de la       │   ├──────────────────┤   │ "Esa clave ya se usó con  │
  │  derecha)           │   │ EN_CURSO -> 409  │   │  un cuerpo distinto"      │
  └──────────┬──────────┘   │  (aún procesando)│   │ NO se ejecuta nada        │
             ▼              │ HECHO -> devuelve│   └───────────────────────────┘
  ┌─────────────────────┐   │  la respuesta    │
  │ EJECUTA la          │   │  GUARDADA tal    │
  │ operación de        │   │  cual: mismo     │
  │ negocio             │   │  código, mismo   │
  │ (crea la tarea)     │   │  cuerpo, misma   │
  └──────────┬──────────┘   │  cabecera        │
             ▼              │  Location        │
  ┌─────────────────────┐   └──────────────────┘
  │ GUARDA la respuesta │
  │ estado = HECHO      │   Todo dentro de la MISMA transacción que la
  │ + código + cuerpo   │   operación de negocio: si el commit falla,
  │ + Location          │   la clave no queda marcada como HECHO.
  │ caduca en 24 h      │
  └──────────┬──────────┘
             ▼
        201 Created
        Location: /api/v1/tasks/42
        Idempotent-Replay: false        <- en el reintento valdrá true

@Entity({ tableName: 'idempotency_key' })
@Unique({ properties: ['clave', 'usuarioId', 'endpoint'] })
export class ClaveIdempotencia {
  @PrimaryKey() id!: number;

  // La clave se acota por usuario y por endpoint: dos clientes distintos
  // pueden generar el mismo UUID (improbable) y, sobre todo, un usuario no
  // debe poder leer la respuesta guardada de otro reutilizando su clave.
  @Property({ length: 255 }) clave!: string;
  @Property() usuarioId!: number;
  @Property({ length: 255 }) endpoint!: string;

  // Hash del cuerpo: detecta la reutilización de una clave con contenido
  // distinto, que casi siempre indica un error en el cliente.
  @Property({ length: 64 }) hashCuerpo!: string;

  @Enum(() => EstadoClave) estado!: EstadoClave;   // EN_CURSO | HECHO

  @Property({ type: 'int', nullable: true })  codigoRespuesta?: number;
  @Property({ type: 'json', nullable: true }) cuerpoRespuesta?: unknown;
  @Property({ type: 'json', nullable: true }) cabeceras?: Record<string, string>;

  @Property() creadaEn: Date = new Date();

  // Ventana de validez. 24 h es el valor de Stripe y un buen punto de
  // partida: suficiente para cubrir reintentos y cortes de red, y corto
  // para que la tabla no crezca sin control. Un trabajo programado borra
  // las caducadas; sin él, esta tabla acaba siendo la mayor del sistema.
  @Property() caducaEn!: Date;
}

@Injectable()
export class IdempotencyInterceptor implements NestInterceptor {
  constructor(private readonly em: EntityManager) {}

  async intercept(ctx: ExecutionContext, next: CallHandler): Promise<Observable<unknown>> {
    const req = ctx.switchToHttp().getRequest<Request>();
    const res = ctx.switchToHttp().getResponse<Response>();

    // Solo tiene sentido en métodos NO idempotentes por naturaleza.
    const clave = req.header('Idempotency-Key');
    if (req.method !== 'POST' || !clave) return next.handle();

    if (!UUID_V4.test(clave)) {
      throw new BadRequestException('Idempotency-Key debe ser un UUID v4');
    }

    const hash = createHash('sha256')
      .update(JSON.stringify(req.body ?? {})).digest('hex');
    const identidad = { clave, usuarioId: req.user!.id, endpoint: rutaDe(req) };

    const previa = await this.em.findOne(ClaveIdempotencia, identidad);

    if (previa) {
      if (previa.hashCuerpo !== hash) {
        // Misma clave, cuerpo distinto: casi siempre un bug del cliente
        // que reutiliza la clave. Rechazamos SIN ejecutar nada.
        throw new UnprocessableEntityException(
          'Esa clave de idempotencia ya se usó con un cuerpo distinto');
      }
      if (previa.estado === EstadoClave.EN_CURSO) {
        // La primera petición sigue procesándose. 409 con Retry-After
        // para que el cliente espere en lugar de martillear.
        res.setHeader('Retry-After', '2');
        throw new ConflictException('La operación original aún se está procesando');
      }
      // Reproducimos la respuesta guardada: mismo código, mismo cuerpo.
      res.status(previa.codigoRespuesta!);
      for (const [k, v] of Object.entries(previa.cabeceras ?? {})) res.setHeader(k, v);
      res.setHeader('Idempotent-Replay', 'true');
      return of(previa.cuerpoRespuesta);
    }

    // Reserva. El índice único hace de árbitro si dos peticiones idénticas
    // llegan a la vez: la que pierde el INSERT recibe 409 y reintentará.
    const registro = this.em.create(ClaveIdempotencia, {
      ...identidad, hashCuerpo: hash, estado: EstadoClave.EN_CURSO,
      caducaEn: new Date(Date.now() + 24 * 3600_000),
    });
    try {
      await this.em.persistAndFlush(registro);
    } catch (e) {
      if (e instanceof UniqueConstraintViolationException) {
        res.setHeader('Retry-After', '2');
        throw new ConflictException('Operación en curso con esa clave');
      }
      throw e;
    }

    return next.handle().pipe(
      tap(async (cuerpo) => {
        registro.estado = EstadoClave.HECHO;
        registro.codigoRespuesta = res.statusCode;
        registro.cuerpoRespuesta = cuerpo;
        const location = res.getHeader('Location');
        if (location) registro.cabeceras = { Location: String(location) };
        await this.em.flush();
      }),
      catchError((error) => {
        // Un fallo NO debe quedar guardado como resultado definitivo:
        // el cliente tiene derecho a reintentar con la misma clave.
        return from(this.em.nativeDelete(ClaveIdempotencia, identidad))
          .pipe(switchMap(() => throwError(() => error)));
      }),
    );
  }
}

@Component({ /* … */ })
export class CrearTareaComponent {
  private readonly api = inject(TaskApiService);

  // La clave nace con la INTENCIÓN, no con el clic. Si el usuario pulsa
  // tres veces o la red falla y reintentamos, la clave es la misma y el
  // servidor crea UNA tarea. Se renueva solo al empezar una tarea nueva.
  private claveIdempotencia = crypto.randomUUID();

  readonly form = inject(FormBuilder).nonNullable.group({
    titulo: ['', [Validators.required, Validators.minLength(3)]],
  });

  guardar(): void {
    this.api.crear(this.proyectoId(), this.form.getRawValue(), this.claveIdempotencia)
      .pipe(
        // Reintentos con retroceso exponencial: seguros porque la clave
        // garantiza que no se duplicará nada.
        retry({ count: 3, delay: (_e, i) => timer(500 * 2 ** i) }),
      )
      .subscribe({
        next: () => {
          this.claveIdempotencia = crypto.randomUUID();  // nueva intención
          this.form.reset();
        },
        error: (e: HttpErrorResponse) => this.mostrarProblema(e),
      });
  }
}

25.11 Operaciones largas: el patrón del trabajo asíncrono

Generar el informe anual de un proyecto con cuatro mil tareas puede tardar cuarenta segundos. Mantener una petición HTTP abierta durante ese tiempo es una mala idea por cuatro razones concretas: el proxy inverso probablemente la cortará a los treinta segundos con un 504, el navegador ocupa una de sus conexiones, un reintento del cliente dispara el trabajo dos veces, y si el proceso de Node se reinicia durante un despliegue el trabajo se pierde sin que nadie se entere. La respuesta correcta no es subir los tiempos de espera: es separar la aceptación del trabajo de su ejecución.

El patrón tiene tres piezas. Primera: el POST encola el trabajo y responde 202 Accepted con la URL de un recurso de estado en Location. Segunda: ese recurso de estado es un recurso normal, con GET, que informa del progreso. Tercera: cuando termina, el recurso de estado apunta al resultado, normalmente con un 303 See Other hacia la URL de descarga o con un campo resultado en el cuerpo. Fíjate en que el trabajo es un recurso de primera clase: se puede consultar, cancelar con DELETE y listar.

# 1 · Solicitar. La clave de idempotencia evita encolar dos veces
#     el mismo informe si el cliente reintenta.
POST /api/v1/projects/9/exports        Idempotency-Key: 0f1b1a6c-…
{"formato":"xlsx","desde":"2026-01-01","hasta":"2026-07-31"}

<- 202 Accepted
   Location: /api/v1/jobs/7f3a2b
   Retry-After: 5                    # no sondees antes de 5 segundos
   {"jobId":"7f3a2b","estado":"ENCOLADO","progreso":0}

# 2 · Sondear el recurso de estado, respetando SIEMPRE Retry-After
GET /api/v1/jobs/7f3a2b
<- 200 OK   Retry-After: 5
   {"jobId":"7f3a2b","estado":"EN_CURSO","progreso":42,
    "iniciadoEn":"2026-07-31T17:04:22Z"}

# 3 · Terminado. Dos formas válidas de comunicar el resultado:
#     (a) 303 hacia el recurso producido, que es lo más REST
GET /api/v1/jobs/7f3a2b
<- 303 See Other
   Location: /api/v1/exports/7f3a2b.xlsx

#     (b) 200 con el estado y un enlace, más cómodo para un SPA
<- 200 OK
   {"jobId":"7f3a2b","estado":"COMPLETADO","progreso":100,
    "resultado":{"url":"/api/v1/exports/7f3a2b.xlsx","bytes":184320}}

# 4 · Y si falló, el estado lo dice con un Problem Details dentro.
#     Ojo: el GET del estado devuelve 200, porque CONSULTAR el estado
#     ha funcionado. El fallo está en el trabajo, no en la consulta.
<- 200 OK
   {"jobId":"7f3a2b","estado":"FALLIDO",
    "error":{"type":"…/exportacion-fallida","title":"No se pudo generar",
             "detail":"El proyecto no tiene tareas en ese rango."}}

El punto 4 es el que casi todo el mundo hace mal: responder 500 al GET del estado porque el trabajo falló. Son dos cosas distintas. La consulta del estado ha funcionado perfectamente y debe devolver 200; el fracaso del trabajo es información dentro del cuerpo. Devolver 500 hace que el cliente reintente la consulta indefinidamente y que tu monitorización cuente errores que no existen.

El sondeo es la alternativa más simple y funciona en cualquier cliente, pero desperdicia peticiones: hay que respetar Retry-After y aplicar retroceso exponencial con un techo. Las alternativas son los eventos enviados por el servidor (text/event-stream), que son HTTP normal y corriente, unidireccionales, reconectan solos y encajan muy bien con «notifícame cuando termine»; los WebSockets, que aportan bidireccionalidad a cambio de un protocolo distinto con su propia autenticación y su propio escalado (capítulo 11); y los webhooks, que son la opción correcta cuando quien espera el resultado es otro servidor y no un navegador (25.15). La regla práctica: sondeo si el trabajo dura segundos, eventos del servidor si dura minutos y el usuario está mirando, webhook si el consumidor es una máquina.

25.12 Contenido: negociación, ficheros y compresión

La negociación de contenido es el mecanismo por el que cliente y servidor acuerdan el formato. El cliente expresa preferencias con Accept, Accept-Language y Accept-Encoding, con factores de calidad entre 0 y 1; el servidor elige y lo declara en Content-Type, Content-Language y Content-Encoding, y debe añadir Vary con las cabeceras que influyeron en su decisión, o las cachés compartidas servirán la variante equivocada. Si no puede satisfacer el Accept, responde 406; si no entiende el Content-Type que recibe, responde 415.

Sobre tipos de medio, la recomendación es usar los estándar (application/json, application/problem+json, application/merge-patch+json) y resistirse a inventar tipos propios con versión (application/vnd.taskflow.v2+json) salvo que tengas una razón fuerte: son elegantes sobre el papel y en la práctica dificultan las pruebas manuales, la caché y el trabajo de las herramientas.

La subida de ficheros tiene dos enfoques y la elección importa más de lo que parece. Con multipart/form-data el fichero viaja a través de tu API: es simple de implementar y de probar, pero el fichero atraviesa tu proceso de Node consumiendo memoria o disco temporal, ocupa una conexión durante toda la subida, choca con el límite de tamaño del proxy y con el tiempo de espera del balanceador, y te obliga a escalar la aplicación por un motivo que no tiene nada que ver con tu lógica de negocio. Con URL prefirmada, el cliente pide permiso a tu API, recibe una URL temporal y sube el fichero directamente al almacenamiento de objetos (S3, GCS, R2, MinIO), y después confirma. Tu servidor nunca ve los bytes.

// Un adjunto de 80 MB atraviesa Node entero.
// Con 20 subidas simultáneas son 1,6 GB de
// memoria o de disco temporal, el proxy corta
// a los 30 s y el despliegue de esta tarde
// aborta todas las subidas en curso.
@Post(':id/attachments')
@UseInterceptors(FileInterceptor('fichero'))
async subir(@UploadedFile() f: Express.Multer.File) {
  return this.s3.putObject({          // segunda copia
    Bucket: 'taskflow', Key: f.originalname,
    Body: f.buffer,                   // TODO en memoria
  });
}

// La API solo autoriza y firma; los bytes van
// del navegador al almacenamiento. Node no toca
// el fichero, y la subida no depende de tus
// despliegues ni de tu memoria.
@Post(':id/attachments')
async prepararSubida(@Param('id') id: number,
                     @Body() dto: PrepararSubidaDto) {
  await this.tasks.comprobarPermisoEscritura(id);

  const clave = `tasks/${id}/${randomUUID()}`;
  // La firma FIJA tipo y tamaño máximo: sin esto,
  // la URL permite subir cualquier cosa.
  const url = await this.s3.urlDeSubida(clave, {
    contentType: dto.tipoMime,
    maxBytes: 25 * 1024 * 1024,
    expiraEnSegundos: 300,
  });
  return { url, clave, expiraEn: 300 };
}

// Y un POST de confirmación registra el adjunto
// una vez subido, comprobando tamaño y tipo real.

Para las descargas, la cabecera clave es Content-Disposition: attachment; filename="informe.xlsx", y conviene incluir la variante filename*=UTF-8''… para nombres con acentos. Si el fichero es grande, devuélvelo como flujo (StreamableFile en NestJS) en lugar de cargarlo en memoria, y admite Range para permitir descargas reanudables y reproducción de vídeo con respuestas 206. Nunca construyas la ruta del fichero concatenando algo que venga del cliente: es la vía directa al recorrido de directorios.

Sobre compresión: activa gzip o, mejor, brotli, pero hazlo en el proxy inverso y no en Node, porque comprimir es trabajo intensivo de CPU y el bucle de eventos es un recurso demasiado valioso para gastarlo en eso. Un JSON típico se reduce entre un 70 y un 85 por ciento, así que el ahorro es enorme. Dos matices: no comprimas lo que ya está comprimido (imágenes, PDF, ZIP), porque solo gastas CPU; y ten presente que comprimir respuestas que mezclan datos secretos con datos que controla el atacante puede filtrar información por el tamaño, que es la familia de ataques BREACH y CRIME. Para una API JSON autenticada el riesgo es bajo, pero es la razón por la que no debes comprimir respuestas que contengan tokens.

25.13 Versionado y evolución

La pregunta correcta no es «¿cómo versiono mi API?», sino «¿cómo evoluciono sin versionar?». Cada versión activa es una copia del contrato que hay que mantener, probar y documentar; el objetivo es tener las menos posibles. Y para eso hay que saber con precisión qué es un cambio rompedor.

La recomendación para una aplicación como TaskFlow es versión en la ruta, una sola versión activa casi siempre, y disciplina de compatibilidad para todo lo demás. En NestJS se configura con app.enableVersioning({ type: VersioningType.URI, defaultVersion: '1' }) y se marca por controlador con @Controller({ path: 'tasks', version: '2' }), lo que permite convivir v1 y v2 solo en los recursos que realmente cambiaron.

La deprecación es un proceso, no un anuncio. Los pasos que funcionan: primero, publicar la versión nueva y documentar la migración con ejemplos concretos, no con una nota genérica. Segundo, emitir en las respuestas de la versión antigua las cabeceras Deprecation: true y Sunset: Sat, 31 Jan 2027 23:59:59 GMT (RFC 8594) más un Link con rel="deprecation" hacia la guía. Tercero —y este es el paso que se salta todo el mundo— medir quién sigue usándola: un contador por versión, por cliente y por endpoint te dice si puedes retirar algo o si vas a romper la integración de tu mayor cliente. Cuarto, avisar activamente a quienes aparecen en esas métricas. Quinto, un «apagón de ensayo» de una hora en una fecha anunciada, que descubre a los integradores que no leyeron ningún aviso. Y sexto, retirar respondiendo 410 Gone con un cuerpo que explique dónde está la versión nueva.

25.14 El modelo de madurez de Richardson y HATEOAS

Leonard Richardson propuso en 2008 una escala de cuatro niveles que se ha convertido en la forma habitual de discutir cuán «REST» es una API. Es una herramienta de análisis útil, no una nota de examen.

La pregunta honesta es por qué casi nadie llega al nivel 3, cuando en la tesis de Fielding la hipermedia no es un extra sino el rasgo definitorio de REST. Las razones son prácticas. Los clientes reales no descubren: un desarrollador de Angular lee la documentación, escribe la llamada y sigue; nadie programa un cliente que navegue enlaces en tiempo de ejecución, salvo en escenarios muy concretos. La hipermedia añade peso a cada respuesta y complejidad al servidor. Y los generadores de clientes tipados a partir de OpenAPI producen justamente lo contrario: código que conoce las rutas de antemano, que es lo que la gente quiere.

Dicho esto, hay tres casos donde los enlaces sí aportan valor real y merece la pena incluirlos. El primero es la paginación: links.next ya lo usábamos en 25.6 y evita que el cliente sepa construir cursores. El segundo son los flujos con estado, donde las acciones disponibles dependen del estado actual: si la respuesta de una tarea incluye qué transiciones son posibles, la interfaz puede pintar los botones correctos sin duplicar la máquina de estados del servidor, que es una fuente clásica de divergencia entre lo que el botón ofrece y lo que el servidor acepta. El tercero son los recursos relacionados y las descargas temporales, donde una URL firmada con caducidad no puede construirla el cliente.

{
  "id": 42,
  "titulo": "Revisar contrato del proveedor",
  "estado": "EN_CURSO",
  "version": 8,
  "_links": {
    "self":     { "href": "/api/v1/tasks/42" },
    "completar":{ "href": "/api/v1/tasks/42", "method": "PATCH",
                  "body": { "estado": "HECHA" } },
    "archivar": { "href": "/api/v1/tasks/42/archive", "method": "PUT" },
    "adjuntos": { "href": "/api/v1/tasks/42/attachments" }
  }
}
// No aparece "reabrir" porque la tarea no está cerrada: la interfaz
// dibuja los botones que el servidor ofrece y no puede desincronizarse.
// Esto es HATEOAS pragmático: enlaces donde aportan, no en todas partes.

25.15 Webhooks: cuando la API llama al cliente

Un webhook invierte la dirección de la llamada: en lugar de que el cliente pregunte, tu servidor avisa. Es la forma correcta de notificar a otro sistema («la tarea 42 se ha completado») sin obligarlo a sondear cada diez segundos. Y es también una funcionalidad que parece trivial y no lo es, porque al emitir webhooks te conviertes en cliente HTTP de servidores que no controlas, con toda la incertidumbre que eso implica.

El diseño de la entrega empieza por el cuerpo. Un evento debe llevar un identificador único (para que el receptor pueda descartar duplicados), un tipo (task.completed), una marca de tiempo, un número de versión del esquema del evento y los datos. Sobre los datos hay una decisión importante: enviar el objeto completo es cómodo pero puede quedar obsoleto si llegan dos eventos desordenados, mientras que enviar solo los identificadores obliga al receptor a consultar tu API y garantiza que lea el estado actual. Un punto intermedio razonable es enviar el objeto completo más un número de versión, para que el receptor pueda descartar lo viejo.

La firma es obligatoria, no opcional. Sin ella, cualquiera que descubra la URL del receptor puede inventarse eventos: «el pago se ha confirmado» enviado por un desconocido. El mecanismo estándar es un HMAC-SHA256 sobre el cuerpo en crudo más una marca de tiempo, con un secreto compartido por suscripción. Los dos detalles que se hacen mal son firmar el JSON reserializado en lugar de los bytes recibidos —cualquier diferencia de espacios o de orden de claves invalida la firma— y comparar con === en lugar de con una comparación de tiempo constante.

// EMISOR: la marca de tiempo va DENTRO de lo firmado para que un
// atacante no pueda reenviar un evento antiguo capturado (repetición).
export function firmar(cuerpoCrudo: Buffer, secreto: string): string {
  const t = Math.floor(Date.now() / 1000);
  const firma = createHmac('sha256', secreto)
    .update(`${t}.`).update(cuerpoCrudo).digest('hex');
  return `t=${t},v1=${firma}`;          // cabecera X-TaskFlow-Signature
}

// RECEPTOR: verificación en tiempo constante y ventana temporal.
export function verificar(cuerpoCrudo: Buffer, cabecera: string, secreto: string): boolean {
  const partes = Object.fromEntries(
    cabecera.split(',').map((p) => p.split('=') as [string, string]));
  const t = Number(partes['t']);

  // Fuera de la ventana de 5 minutos: se rechaza aunque la firma sea
  // válida. Sin esto, un evento capturado sirve para siempre.
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;

  const esperada = createHmac('sha256', secreto)
    .update(`${t}.`).update(cuerpoCrudo).digest();
  const recibida = Buffer.from(partes['v1'] ?? '', 'hex');

  // timingSafeEqual exige la misma longitud: comprobarla antes evita
  // que lance. Y NUNCA uses === : filtra información por temporización.
  return recibida.length === esperada.length &&
         timingSafeEqual(recibida, esperada);
}

Para que la verificación sea posible, el receptor necesita el cuerpo sin procesar. En NestJS se consigue creando la aplicación con rawBody: true y leyendo req.rawBody; si el analizador de JSON ya ha transformado el cuerpo, los bytes originales se han perdido y la firma nunca coincidirá. Es la causa número uno de «mi verificación de webhook falla siempre».

Los reintentos son la otra mitad del problema. El receptor estará caído alguna vez, así que hay que reintentar con retroceso exponencial y un poco de aleatoriedad —por ejemplo a los 10 segundos, 1 minuto, 5 minutos, 30 minutos, 2 horas y 12 horas— y desistir después, marcando la suscripción como problemática si acumula fallos. Se reintenta ante 5xx, ante tiempo de espera agotado y ante 429 (respetando Retry-After), pero no ante 4xx: un 400 o un 422 significan que el receptor no va a aceptar ese evento por mucho que insistas. Impón además un tiempo de espera corto, de unos cinco segundos, para que un receptor lento no bloquee tu cola.

Como consecuencia inevitable de los reintentos, el receptor recibirá eventos duplicados: la entrega es «al menos una vez», nunca «exactamente una vez». Por eso el identificador del evento es obligatorio y por eso el receptor debe guardarlo y descartar los repetidos, que es exactamente la misma técnica de 25.10 aplicada del otro lado. El otro consejo práctico para el receptor: responder 2xx de inmediato y procesar en segundo plano; procesar de forma síncrona provoca tiempos de espera agotados que el emisor interpreta como fallo, y acabas reprocesando lo que ya funcionó.

25.16 OpenAPI como contrato

Un contrato que solo existe en la cabeza del equipo no es un contrato. OpenAPI (antes Swagger) es la forma estándar de describir una API HTTP en un documento JSON o YAML legible por máquinas, y a partir de ese documento se genera documentación navegable, clientes tipados, servidores simulados, colecciones de pruebas y validaciones automáticas de compatibilidad. La versión 3.1 es la actual y su gran ventaja es que su esquema es JSON Schema completo, lo que elimina las incompatibilidades históricas.

Hay dos filosofías. Contrato primero significa escribir el YAML antes que el código: obliga a diseñar antes de implementar y permite que el equipo de frontend empiece contra un simulador el primer día, a costa de mantener el documento a mano. Código primero significa generarlo desde los decoradores de NestJS: no se desincroniza y cuesta poco, a costa de que el contrato tienda a ser un reflejo de la implementación en lugar de un diseño. Para un equipo full-stack que controla ambos lados, código primero con revisión del documento generado en cada pull request es el equilibrio más práctico.

@ApiTags('Tareas')
@ApiBearerAuth()
@Controller({ path: 'projects/:projectId/tasks', version: '1' })
export class TasksController {
  @Post()
  @ApiOperation({
    summary: 'Crear una tarea en un proyecto',
    description: 'Admite Idempotency-Key para reintentos seguros (ver 25.10).',
  })
  @ApiHeader({ name: 'Idempotency-Key', required: false,
               description: 'UUID v4 generado por el cliente por cada intención' })
  @ApiCreatedResponse({ type: TaskDto, description: 'Tarea creada; Location apunta a ella' })
  @ApiResponse({ status: 422, type: ProblemaValidacionDto,
                 description: 'El cuerpo es válido como JSON pero viola una regla' })
  @ApiResponse({ status: 409, type: ProblemaDto, description: 'Ya existe una tarea igual' })
  crear(/* … */) { /* … */ }
}

// La clave para que el documento sea FIEL sin escribir el doble: el plugin
// de Swagger para la CLI de Nest lee los tipos de TypeScript y los
// decoradores de class-validator, y deriva de ahí los esquemas. Se activa
// en nest-cli.json y evita tener que repetir cada campo con @ApiProperty.
// {"compilerOptions":{"plugins":[{"name":"@nestjs/swagger",
//   "options":{"classValidatorShim":true,"introspectComments":true}}]}}

La fidelidad del documento es el punto crítico: un contrato que miente es peor que no tener contrato, porque la gente confía en él. Tres prácticas la garantizan. Una, generar el documento en el arranque y escribirlo en un fichero versionado con un script, de modo que cualquier cambio en la API aparezca como diferencia en la revisión de código y alguien tenga que aprobarlo conscientemente. Dos, validar en las pruebas de integración que las respuestas reales cumplen el esquema publicado. Y tres, documentar también los errores: una API cuyo OpenAPI solo describe el camino feliz obliga a cada integrador a descubrir los fallos en producción.

# 1 · Generar el documento y guardarlo en el repositorio
npm run api:openapi          # arranca Nest en modo documento y escribe openapi.json

# 2 · Comprobar que no hay cambios rompedores respecto a la rama principal
npx oasdiff breaking origin/main:openapi.json openapi.json --fail-on ERR

# 3 · Generar el cliente tipado de Angular a partir del contrato
npx openapi-generator-cli generate \
    -i openapi.json -g typescript-angular \
    -o libs/api-client/src/generated \
    --additional-properties=providedInRoot=true,fileNaming=kebab-case

# 4 · Verificar que lo generado compila y que nadie lo ha editado a mano
git diff --exit-code libs/api-client/src/generated || \
    (echo "El cliente generado está desactualizado: ejecuta npm run api:client" && exit 1)

El paso 2 es el que convierte el contrato en una red de seguridad real. Herramientas como oasdiff comparan dos documentos OpenAPI y clasifican las diferencias: si alguien elimina un campo, cambia un tipo o hace obligatorio un parámetro opcional, la construcción falla con un mensaje que dice exactamente qué se rompió y para quién. Es infinitamente más barato que descubrirlo cuando la aplicación móvil deja de funcionar.

El paso 3 elimina de un plumazo una clase entera de errores: el cliente de Angular deja de escribirse a mano y pasa a derivarse del contrato, con sus interfaces, sus enumerados y sus servicios inyectables. Si el servidor renombra un campo, el proyecto de Angular no compila. Esa es exactamente la clase de error que quieres tener: ruidoso, temprano y en tu máquina.

25.17 Seguridad del contrato

La seguridad del capítulo 12 (autenticación, JWT, OAuth2, autorización) se da por sabida. Aquí interesan las decisiones de seguridad que forman parte del diseño del contrato y que, si se dejan para el final, obligan a cambios rompedores.

Autenticación. El token va en Authorization: Bearer …, nunca en la URL. Un 401 debe incluir WWW-Authenticate: Bearer realm="taskflow", error="invalid_token", que es lo que permite a un cliente genérico saber qué hacer. Y toda la API va por HTTPS: sin cifrado, el token viaja en claro y todo lo demás es decoración.

CORS, explicado de verdad. Es el mecanismo con peor prensa de la web, casi siempre por un malentendido: CORS no protege tu servidor, protege al usuario del navegador. La política del mismo origen impide que una página maliciosa lea las respuestas de otro origen usando las credenciales del usuario; CORS es la forma que tiene tu servidor de decir «para este origen concreto, autorizo la lectura». Nada de esto afecta a curl, a Postman ni a otro servidor: esos clientes no aplican la política porque no hay usuario al que proteger.

Una petición de otro origen es simple —y se envía directamente— si el método es GET, HEAD o POST, si solo lleva cabeceras de una lista muy corta y si su Content-Type es text/plain, multipart/form-data o application/x-www-form-urlencoded. En cuanto envías application/json, o una cabecera Authorization, o usas PATCH, PUT o DELETE, deja de ser simple y el navegador hace una comprobación previa: un OPTIONS con Access-Control-Request-Method y Access-Control-Request-Headers, y solo si la respuesta lo autoriza envía la petición real. Es decir: prácticamente toda llamada de una SPA a una API JSON en otro dominio implica dos viajes, y por eso Access-Control-Max-Age importa tanto: sin él, se paga la comprobación previa en cada petición.

// Combinación prohibida y peligrosa: comodín
// con credenciales. Los navegadores la rechazan,
// y el "arreglo" habitual es peor: reflejar el
// origen recibido, que equivale a permitir a
// CUALQUIER web leer los datos del usuario.
app.enableCors({
  origin: '*',
  credentials: true,
});

// Variante igual de mala:
app.enableCors({
  origin: (o, cb) => cb(null, true),  // refleja todo
  credentials: true,
});

// Lista blanca explícita desde configuración, sin
// comodines y sin reflejar lo que llegue.
const permitidos = config.get<string[]>('CORS_ORIGENES');

app.enableCors({
  origin: (origen, cb) =>
    !origen || permitidos.includes(origen)
      ? cb(null, true)
      : cb(new Error('Origen no permitido')),
  credentials: true,
  methods: ['GET', 'POST', 'PATCH', 'PUT', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization',
                   'If-Match', 'Idempotency-Key'],
  // Sin esto, el cliente NO puede leer estas
  // cabeceras aunque el servidor las envíe.
  exposedHeaders: ['ETag', 'Location', 'Retry-After',
                   'X-Request-Id', 'RateLimit'],
  maxAge: 86_400,     // cachea la comprobación previa
});

Límite de peticiones. Protege de abusos y de errores ajenos (un bucle infinito en un cliente puede tumbarte igual que un ataque). El borrador del IETF ya casi estándar define las cabeceras RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset, que junto con el 429 y su Retry-After permiten que un cliente educado se autorregule. Tres consejos de diseño: limita por identidad autenticada y no solo por IP, porque una oficina entera comparte IP; aplica límites distintos por endpoint, porque el login y un listado no merecen el mismo trato; y comprueba el límite antes de tocar la base de datos, o el límite no te está protegiendo de nada.

Tamaño máximo del cuerpo. Un límite explícito y bajo (256 KB para JSON es generoso en una API de gestión) responde 413 y corta la petición antes de acumularla en memoria. Debe estar en dos sitios: en el proxy inverso, que es quien puede rechazarla sin gastar un proceso de Node, y en la aplicación, por si algún día alguien la despliega sin proxy delante. Conviene además limitar la profundidad de anidamiento del JSON y el número de elementos de los arrays de entrada: un array de cien mil identificadores en un POST de operación por lotes es un ataque perfectamente válido si no lo acotas.

Validación estricta. Es la defensa que más rentabilidad ofrece por línea escrita. whitelist: true descarta lo que no está en el DTO y cierra la puerta a la asignación masiva; forbidNonWhitelisted: true convierte el descarte silencioso en un 400 explícito, que es lo que quieres durante el desarrollo; y validar también los parámetros de consulta —con topes en limit, lista blanca en sort y rechazo de parámetros desconocidos— evita que el listado se convierta en una consulta arbitraria contra tu base de datos. Y una regla que resume todas las demás: no expongas entidades de MikroORM directamente; usa DTO de salida, porque el día que alguien añada un campo tokenRecuperacion a la entidad, ese campo aparecerá en la respuesta de tu API sin que nadie lo haya decidido.

25.18 Errores comunes y cómo solucionarlos

25.19 Buenas y malas prácticas

25.20 Preguntas frecuentes

25.21 Ejercicios

paths:
  /projects/{projectId}/tasks/{taskId}/comments:
    get:
      summary: Listar comentarios de una tarea
      parameters:
        - { name: limit,  in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
        - { name: cursor, in: query, schema: { type: string }, description: Opaco, lo devuelve el servidor }
      responses:
        '200':
          description: Página de comentarios
          headers:
            ETag:          { schema: { type: string } }
            Cache-Control: { schema: { type: string, example: 'private, no-cache' } }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaginaComentarios' }
        '304': { description: Sin cambios desde el ETag enviado en If-None-Match }
        '403': { $ref: '#/components/responses/Prohibido' }
        '404': { $ref: '#/components/responses/NoEncontrado' }
    post:
      summary: Crear un comentario
      parameters:
        - { name: Idempotency-Key, in: header, required: false, schema: { type: string, format: uuid } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [texto]
              properties:
                texto:      { type: string, minLength: 1, maxLength: 5000 }
                respondeA:  { type: integer, nullable: true }
      responses:
        '201':
          description: Comentario creado
          headers:
            Location: { schema: { type: string }, description: URL canónica del comentario }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Comentario' }
        '409': { description: Clave de idempotencia en curso }
        '422': { $ref: '#/components/responses/ErrorValidacion' }

  /comments/{id}:                     # PLANO: ya tiene identificador propio
    patch:
      parameters:
        - { name: If-Match, in: header, required: true, schema: { type: string } }
      requestBody:
        content:
          application/merge-patch+json:      # el tipo de medio DECLARA la semántica
            schema:
              type: object
              properties: { texto: { type: string, minLength: 1, maxLength: 5000 } }
      responses:
        '200': { description: Comentario actualizado }
        '412': { description: El comentario cambió desde que lo leíste }
        '428': { description: Falta la cabecera If-Match }
    delete:
      responses:
        '204': { description: Eliminado, sin cuerpo }
        '404': { description: No existe, o no tienes por qué saber que existe }

// La pieza que evita repetir la lógica en cada controlador: un decorador
// de parámetro que extrae y valida la precondición, más un helper que
// deriva el ETag de la entidad. El ETag NO se inventa: es la versión.
export const etagDe = (e: { version: number }) => `W/"v${e.version}"`;

export const IfMatch = createParamDecorator((_d, ctx: ExecutionContext): number => {
  const req = ctx.switchToHttp().getRequest<Request>();
  const valor = req.header('if-match');

  // 428 y no 400: la petición está bien formada, lo que falta es la
  // precondición que ESTE endpoint exige. El código lo dice con precisión.
  if (!valor) throw new PreconditionRequiredException(
    'Este recurso requiere If-Match con el ETag obtenido en el GET');

  const m = /^W\/"v(\d+)"$/.exec(valor.trim());
  if (!m) throw new BadRequestException('If-Match mal formado');
  return Number(m[1]);
});

@Patch(':id')
async actualizar(
  @Param('id', ParseIntPipe) id: number,
  @Body() dto: PatchTaskDto,
  @IfMatch() version: number,
  @Res({ passthrough: true }) res: Response,
) {
  try {
    // La comprobación es ATÓMICA: MikroORM añade "AND version = ?" al
    // UPDATE. Hacer un SELECT previo y comparar en memoria dejaría una
    // ventana de carrera entre la lectura y la escritura.
    const tarea = await this.em.findOneOrFail(Task, id, {
      lockMode: LockMode.OPTIMISTIC, lockVersion: version,
    });
    this.em.assign(tarea, dto);
    await this.em.flush();

    res.setHeader('ETag', etagDe(tarea));   // versión YA incrementada
    return TaskDto.desde(tarea);
  } catch (e) {
    if (e instanceof OptimisticLockError) {
      // Enriquecemos el 412 con lo que el cliente necesita para fusionar.
      const actual = await this.em.fork().findOneOrFail(Task, id);
      throw new PreconditionFailedException({
        type: `${TIPOS}/conflicto-edicion`,
        title: 'La tarea ha cambiado desde que la abriste',
        status: 412, versionActual: actual.version,
        camposCambiados: this.tasks.diferencias(version, actual),
      });
    }
    throw e;
  }
}

// Test de las dos ediciones concurrentes:
it('rechaza la segunda escritura con el ETag antiguo', async () => {
  const primera = await request(app).get('/api/v1/tasks/42');
  const etag = primera.headers['etag'];

  await request(app).patch('/api/v1/tasks/42')
    .set('If-Match', etag).send({ prioridad: 'ALTA' }).expect(200);

  // Luis usa el ETag que leyó ANTES del cambio de Ana.
  const segunda = await request(app).patch('/api/v1/tasks/42')
    .set('If-Match', etag).send({ titulo: 'Otro título' }).expect(412);

  expect(segunda.body.versionActual).toBe(9);
  // Y lo más importante: no se ha escrito nada.
  const tarea = await orm.em.fork().findOneOrFail(Task, 42);
  expect(tarea.titulo).not.toBe('Otro título');
});

// La prueba que de verdad valida una implementación de idempotencia no es
// la del reintento secuencial: es la de las peticiones SIMULTÁNEAS, que es
// donde se ven las condiciones de carrera.
describe('claves de idempotencia', () => {
  it('veinte peticiones simultáneas con la misma clave crean una tarea', async () => {
    const clave = randomUUID();
    const cuerpo = { titulo: 'Revisar contrato' };

    const respuestas = await Promise.all(
      Array.from({ length: 20 }, () =>
        request(app.getHttpServer())
          .post('/api/v1/projects/9/tasks')
          .set('Idempotency-Key', clave)
          .set('Authorization', `Bearer ${token}`)
          .send(cuerpo)),
    );

    const creadas  = respuestas.filter((r) => r.status === 201);
    const enCurso  = respuestas.filter((r) => r.status === 409);
    const repetida = respuestas.filter((r) => r.headers['idempotent-replay'] === 'true');

    // Exactamente una ejecuta; el resto o esperan (409) o reciben la
    // respuesta guardada. Ninguna combinación produce dos tareas.
    expect(creadas.length + enCurso.length + repetida.length).toBe(20);
    expect(await orm.em.fork().count(Task, { titulo: 'Revisar contrato' })).toBe(1);

    // Todas las que devuelven 201 apuntan al MISMO recurso.
    const destinos = new Set([...creadas, ...repetida].map((r) => r.headers['location']));
    expect(destinos.size).toBe(1);
  });

  it('rechaza la misma clave con un cuerpo distinto y NO ejecuta nada', async () => {
    const clave = randomUUID();
    await request(app.getHttpServer()).post('/api/v1/projects/9/tasks')
      .set('Idempotency-Key', clave).send({ titulo: 'Primera' }).expect(201);

    await request(app.getHttpServer()).post('/api/v1/projects/9/tasks')
      .set('Idempotency-Key', clave).send({ titulo: 'Segunda' }).expect(422);

    expect(await orm.em.fork().count(Task, { titulo: 'Segunda' })).toBe(0);
  });

  it('permite reintentar con la misma clave si la primera vez falló', async () => {
    const clave = randomUUID();
    jest.spyOn(TasksService.prototype, 'crear')
        .mockRejectedValueOnce(new Error('fallo transitorio'));

    await request(app.getHttpServer()).post('/api/v1/projects/9/tasks')
      .set('Idempotency-Key', clave).send({ titulo: 'Reintento' }).expect(500);

    // La clave NO quedó marcada como HECHO: el cliente puede reintentar.
    await request(app.getHttpServer()).post('/api/v1/projects/9/tasks')
      .set('Idempotency-Key', clave).send({ titulo: 'Reintento' }).expect(201);
  });
});

25.22 Resumen del capítulo

25.23 Recursos adicionales

• RFC 9110 · HTTP Semantics — la referencia definitiva de métodos, códigos de estado y cabeceras. Densa, pero es la fuente de la verdad cuando hay una discusión de diseño.
• RFC 9457 · Problem Details for HTTP APIs — el formato de error de 25.7, sucesor de la RFC 7807.
• RFC 9111 · HTTP Caching y RFC 7386 · JSON Merge Patch — la letra pequeña de 25.8 y de 25.3.2.
• MDN · HTTP — la mejor referencia práctica, en español, con una página por cabecera y por código de estado. Especialmente recomendables sus artículos sobre CORS y caché.
• Especificación de OpenAPI 3.1 y NestJS · OpenAPI — el estándar y su integración con los decoradores del framework.
• Google · API Improvement Proposals — la guía de diseño de API más completa que existe en abierto: nombrado, métodos personalizados, paginación, errores y operaciones largas, cada tema en su documento.
• Microsoft · Guía de diseño de API web — más breve que la de Google y disponible en español; muy buen punto de partida para acordar convenciones en equipo.
• Zalando · RESTful API Guidelines — cientos de reglas numeradas y justificadas, escritas por un equipo que mantiene miles de endpoints. Útil como lista de verificación.
• RFC 8594 · The Sunset HTTP Header — la cabecera de retirada anunciada que usa la estrategia de deprecación de 25.13.
• Stripe · Idempotent requests — la implementación de referencia de las claves de idempotencia, con su ventana de 24 horas y su tratamiento de la clave reutilizada.
• oasdiff y OpenAPI Generator — la detección de cambios rompedores y la generación del cliente tipado de Angular de 25.16.
• Pact · Contract testing — el marco de referencia para verificar qué necesita de verdad cada consumidor antes de cambiar nada.
• OWASP API Security Top 10 — los diez riesgos más frecuentes en APIs, encabezados por la autorización a nivel de objeto de 25.5.3.