El módulo de diseño terminó con una lista de preguntas pendientes, y la primera era la más concreta: cómo hablan exactamente los servicios. Tenemos decidido que POST /pedidos responde 202 Accepted, que Pedidos consulta el catálogo con GET /productos?ids=, que Inventario expone POST /reservas; pero un contrato no es un nombre de ruta: es la forma exacta de la petición, la respuesta, los códigos de estado, el formato de los errores y las cabeceras que ambos lados se comprometen a respetar. Esta lección convierte esas decisiones de diseño en contratos REST completos.

REST es el estilo de comunicación síncrona que TechCorp usará en dos sitios: en la API pública (lo que la web y la app móvil consumen a través del gateway del puerto 8080) y en las pocas llamadas síncronas internas que 02-02 dejó autorizadas (Pedidos → Catálogo y Pedidos → Clientes). Veremos cómo se modelan recursos y URIs, la semántica de los verbos y su idempotencia, los códigos de estado que usaremos en todo el curso, los cinco contratos clave de TechCorp con ejemplos de petición y respuesta, un formato de error uniforme basado en RFC 7807, paginación, filtrado, HATEOAS a nivel práctico, cabeceras útiles, documentación con OpenAPI 3 y, por último, un endpoint Express y un cliente fetch mínimos que aplican el contrato. El versionado se deja para 03-06, el gateway para 03-04 y la resiliencia (reintentos, circuit breakers) para 06-03: aquí solo aparece el timeout como buena práctica mínima.

1. REST en microservicios: qué es y qué no es
2. Recursos y URIs
3. Verbos HTTP, semántica e idempotencia
4. Códigos de estado que usaremos
5. Los contratos REST clave de TechCorp
6. Formato de errores uniforme: RFC 7807
7. Paginación, filtrado y ordenación
8. HATEOAS a nivel práctico
9. Cabeceras útiles
10. Documentación con OpenAPI 3
11. Un endpoint Express y un cliente fetch que aplican el contrato

REST (Representational State Transfer) no es un protocolo ni una librería: es un conjunto de restricciones de diseño sobre HTTP. Las que nos importan en microservicios son cuatro:

• Recursos identificados por URIs. Un pedido es /pedidos/ped-88213; un producto, /productos/p-501. La URI identifica la cosa, no la acción.
• Manipulación mediante representaciones. El cliente no toca la fila de PostgreSQL: envía y recibe representaciones (JSON) del recurso.
• Interfaz uniforme. Los verbos HTTP (GET, POST, PUT, PATCH, DELETE) tienen el mismo significado en todos los servicios. Nadie inventa POST /pedidos/obtener.
• Sin estado entre peticiones. Cada petición lleva todo lo necesario (autenticación, identificadores). Esto es lo que permite tener ocho réplicas de Catálogo detrás de un balanceador (03-05) sin que importe cuál responde.

Lo que REST no es: no es "cualquier cosa que devuelva JSON por HTTP". La diferencia entre una API REST y una API "RPC sobre HTTP" está en el uso de la interfaz uniforme, y en microservicios importa porque el contrato REST es la única frontera entre equipos: si el equipo de Pedidos (Luis) puede adivinar cómo se comporta un endpoint de Catálogo con solo leer su URI y su verbo, hay menos reuniones, menos documentación y menos sorpresas.

Las reglas de TechCorp para nombrar URIs, alineadas con el principio de 02-01 de que "los contratos expresan negocio":

Un caso que confunde: acciones que no encajan en un verbo. ¿Cómo se cancela un pedido? Hay dos opciones respetables:

• Tratar la cancelación como un cambio de estado: PATCH /pedidos/ped-88213 con {"estado": "CANCELADO"}. Sencillo, pero mezcla en un mismo endpoint cambios muy distintos.
• Modelar la acción como un sub-recurso: POST /pedidos/ped-88213/cancelacion. Crea "una cancelación" del pedido, con su propio cuerpo (motivo) y su propia validación. Es la que usará TechCorp, porque la saga de 02-05 trata la cancelación como un hecho de negocio con motivo, no como una edición de campo.

Lo que nunca haremos es POST /pedidos/ped-88213/cancelar con el verbo en la URI, ni exponer la estructura interna: /pedidos/ped-88213/lineas sí, /lineas_pedido?pedido_id= no.

Cada verbo tiene un significado y dos propiedades que en sistemas distribuidos son críticas: si es seguro (no modifica estado) y si es idempotente (repetirlo N veces tiene el mismo efecto que hacerlo una vez).

Por qué importa la idempotencia: en 01-02 vimos que la red no es fiable. Si Pedidos llama a PUT /clientes/c-1024/direccion y la respuesta se pierde, puede repetir la llamada sin miedo: la dirección quedará igual. Si repite un POST /reservas que ya se procesó, habrá dos reservas y el stock de p-501 bajará dos veces. Por eso, en 02-05 introdujimos la cabecera Idempotency-Key para POST /pedidos: convierte un POST en repetible sin cambiar su semántica. La aplicaremos igual a POST /reservas.

Sobre PATCH: {"precio": 54.90} es idempotente (repetirlo deja el mismo precio); {"incrementarStock": 5} no lo es. Regla de TechCorp: los PATCH describen el estado deseado, nunca deltas.

No hace falta memorizar los ~60 códigos HTTP. TechCorp usa un subconjunto cerrado, y todos los servicios lo aplican igual (lo empaquetaremos en @techcorp/comun-http, la librería técnica de 02-02):

Dos matices que TechCorp fija por convenio para que todos los equipos respondan igual:

• 400 frente a 422. 400 es "no entiendo tu petición" (no es JSON, falta un campo, un número viene como texto). 422 es "la entiendo pero no tiene sentido" (cantidad 0, fecha de entrega en el pasado). La distinción ayuda al cliente a saber si el error es de serialización o de negocio.
• 404 frente a 409 en errores de negocio. Del monolito heredamos cuatro errores: CLIENTE_NO_EXISTE → 404, PRODUCTO_NO_DISPONIBLE → 400, SIN_STOCK → 409, PAGO_RECHAZADO → 402. En la arquitectura nueva POST /pedidos responde 202 antes de saber si hay stock o si el pago pasa, así que SIN_STOCK y PAGO_RECHAZADO dejan de ser respuestas HTTP de ese endpoint y pasan a ser motivos de pedido.cancelado. SIN_STOCK sigue siendo un 409 de POST /reservas (Inventario). PRODUCTO_NO_DISPONIBLE pasa a 422 (la petición es correcta, pero pide algo que no está a la venta).

Es el contrato más importante del curso. Petición: el cliente envía solo lo que sabe: qué quiere y a dónde. No envía nombres ni precios de producto (los congela Pedidos consultando Catálogo, como fija el agregado de 02-03), ni el total (lo calcula Pedidos).

Respuesta: 202 Accepted porque, como decidimos en 02-05, la saga (reserva de stock, cobro, confirmación) sigue en curso. Location dice dónde consultar el progreso. El cuerpo devuelve el pedido tal y como quedó guardado, con los precios ya congelados y el estado PENDIENTE.

Comportamiento con Idempotency-Key: si el mismo cliente repite la petición con la misma clave (porque perdió la respuesta), Pedidos consulta claves_idempotencia (02-05) y devuelve exactamente la misma respuesta, sin crear otro pedido. Si la clave se reutiliza con un cuerpo distinto, responde 422 con código CLAVE_IDEMPOTENCIA_REUTILIZADA.

Errores posibles de este endpoint (todos en el formato del apartado 6):

Es la lectura que sigue al 202: la web hace polling (o recibe una notificación) hasta que el estado deja de ser PENDIENTE.

Si el pedido no cambió desde la versión "v3", el servidor responde 304 Not Modified sin cuerpo (ahorra ancho de banda en el polling). Si el pedido es de otro cliente, 403; si no existe, 404.

Es la llamada síncrona interna más frecuente: Pedidos necesita nombre, precio y disponibilidad de cada línea para congelarlos. Diseñar GET /productos/{id} y llamarlo una vez por línea sería el clásico problema N+1: un pedido de 20 líneas serían 20 viajes de red. Por eso el contrato acepta un lote:

Decisiones de contrato que conviene explicar:

• Los ids que no existen no provocan 404. Un lote es una consulta a la colección; que falte uno de los ids no hace fallar la petición. Se devuelven en noEncontrados y es Pedidos quien decide qué hacer (responder 422 PRODUCTO_NO_DISPONIBLE).
• Límite de lote. Máximo 100 ids; por encima, 400. Sin límite, alguien acabaría pidiendo 5.000 productos en una URL.
• Cache-Control: max-age=30. El catálogo cambia poco; permitir 30 s de caché al cliente reduce carga en los picos ×20.
• Este JSON es el published language de 02-03; Pedidos lo traduce con su traductorProducto a su propio modelo, de modo que si Catálogo cambia precio (lo veremos en 03-06), solo cambia el traductor.

Pedidos suele resolver el cliente en su réplica local clientes_ref (02-04), pero cuando la réplica no lo tiene todavía (cliente recién registrado) hace esta llamada:

Nótese lo que no devuelve: contraseña, tokens, datos de pago. La representación es una vista de negocio del cliente, no un volcado de la tabla.

En la saga por coreografía de 02-05, Inventario reserva stock reaccionando al evento pedido.creado, no por una llamada HTTP. ¿Para qué entonces un POST /reservas? Por tres motivos: para el panel de administración interno, para pruebas, y porque en 02-03 dejamos abierta una relación partnership Pedidos↔Inventario que en el futuro podría pasar a síncrona (gRPC en 03-03). Diseñar el contrato ahora cuesta poco y fija el vocabulario.

Respuesta cuando hay stock. Aquí sí es 201, porque la reserva queda hecha en el mismo instante (una transacción local en la BD de Inventario):

Y cuando no hay stock, un 409 con detalle de qué falta (información que la saga convierte en stock.rechazado):

Usar pedidoId como Idempotency-Key es deliberado: "una reserva por pedido" es exactamente la garantía que queremos.

En el monolito, cada controlador devolvía los errores como le parecía: a veces {"error": "..."}, a veces {"mensaje": "..."}, a veces HTML. Con seis servicios y cuatro equipos, eso se multiplica. RFC 7807 (Problem Details for HTTP APIs) define un formato estándar con tipo MIME application/problem+json:

El campo codigo es la extensión que TechCorp estandariza: un identificador estable en MAYÚSCULAS_CON_GUIONES (CLIENTE_NO_EXISTE, SIN_STOCK, PRODUCTO_NO_DISPONIBLE, PETICION_INVALIDA, DATOS_NO_VALIDOS, DEPENDENCIA_NO_DISPONIBLE, VERSION_OBSOLETA, CLAVE_IDEMPOTENCIA_REUTILIZADA). Los clientes hacen switch sobre codigo, nunca sobre detail, que es texto para humanos y puede cambiar.

Ejemplo de error de validación con detalle por campo (extensión errores):

Mapeo de los errores heredados del monolito al modelo nuevo:

Un consejo de seguridad: en 500 el detail nunca incluye el mensaje de la excepción ni la traza (filtraría rutas, consultas SQL, nombres de host). Se registra en el log con el X-Request-Id y el cliente recibe un detail genérico con ese identificador para poder reportarlo.

Toda colección que pueda crecer se pagina; GET /pedidos sin límite acabaría devolviendo 3.000 pedidos diarios acumulados durante años.

Respuesta paginada por cursor. El cursor es una cadena opaca (habitualmente base64 de {creadoEn, id} del último elemento) que el cliente devuelve tal cual:

Convenios de TechCorp para filtrado y ordenación:

• Filtros como parámetros de query con el nombre del campo: ?estado=CONFIRMADO, ?clienteId=c-1024. Rangos con sufijos: ?creadoDesde=2026-08-01&creadoHasta=2026-08-15.
• Ordenación con orden=campo ascendente y orden=-campo descendente; varios campos separados por coma: orden=-creadoEn,id.
• limite con valor por defecto (20) y máximo (100). Un cliente que pide 10.000 recibe 400.
• Solo se admiten filtros y órdenes documentados en OpenAPI; un parámetro desconocido se ignora (tolerancia, que 03-06 formalizará), pero un valor inválido en uno conocido da 400.

HATEOAS (Hypermedia As The Engine Of Application State) es la restricción de REST que dice que la respuesta debe incluir enlaces a las acciones posibles, de modo que el cliente "navegue" la API en lugar de construir URIs. Llevado al extremo produce APIs difíciles de consumir y pocos lo aplican del todo. TechCorp adopta una versión pragmática:

• Un objeto _links con self siempre.
• Enlaces a acciones que dependen del estado: un pedido PENDIENTE incluye cancelar; uno CONFIRMADO incluye factura pero no cancelar. Así el front-end no duplica la máquina de estados de 02-05 para saber qué botón mostrar.
• Enlaces de paginación (siguiente, anterior).
• Nada más. No se enlazan recursos de otros servicios (un pedido no enlaza al /clientes/{id} de Clientes), porque el cliente entra siempre por el gateway y las URIs internas no le sirven.

Ejemplo de concurrencia optimista: dos administradores editan el precio de p-501 a la vez.

Si el producto ya está en la versión 13 porque el otro administrador guardó antes, Catálogo responde 409 con codigo: VERSION_OBSOLETA y el cliente recarga y decide. Sin If-Match, el segundo guardado pisaría al primero en silencio.

Un contrato que solo vive en la cabeza de Luis no es un contrato. OpenAPI 3 es la especificación estándar (YAML o JSON) para describir APIs REST: rutas, parámetros, cuerpos, respuestas y esquemas. De ella se generan documentación navegable (Swagger UI, Redoc), clientes, validadores de peticiones y, en 04-05, pruebas. Fragmento de la especificación de Pedidos y Catálogo:

Y el lote de Catálogo, en su propio documento (cada servicio publica su OpenAPI; no hay un fichero global):

Cómo se lee: paths agrupa rutas; dentro de cada verbo, parameters describe query/cabeceras/ruta, requestBody el cuerpo, y responses cada código con su esquema. components evita repetir esquemas y respuestas. En 03-06 veremos que escribir este YAML antes del código (design-first) es la forma de que Pedidos y Catálogo trabajen en paralelo.

No montamos aún el servicio completo (estructura, configuración y arranque son del módulo 4); solo el trozo que materializa el contrato de POST /pedidos.

Explicación paso a paso:

1. validarNuevoPedido separa los dos niveles: si la forma es incorrecta devuelve 400; si la forma está bien pero los valores no, 422 con la lista de campos. Es exactamente la distinción del apartado 4.
2. responderProblema centraliza el formato RFC 7807. En el proyecto real esta función vive en @techcorp/comun-http para que Catálogo, Inventario y el resto respondan idéntico.
3. La ruta comprueba Idempotency-Key, valida, delega en el caso de uso (que ya conocemos de 02-05: guarda el pedido y su pedido.creado en la misma transacción con guardarConEventos()), y responde 202 con Location. Fíjate en que la ruta no sabe nada de RabbitMQ ni de stock: solo traduce HTTP a negocio y negocio a HTTP.
4. Los errores de negocio se mapean a códigos del contrato; cualquier otro va al middleware de errores de Express, que responde 500 sin filtrar detalles.

Y el cliente: cómo Pedidos llama al lote de Catálogo. Node.js 20 incluye fetch de forma nativa, y AbortSignal.timeout es la manera mínima de no quedarse esperando para siempre.

Puntos clave del cliente: la URL base viene de configuración (CATALOGO_URL, cuyo valor por defecto es el nombre estable del servicio que justificaremos en 03-05 y gestionaremos en 04-03); se propaga X-Request-Id; hay un timeout de 2 s (sin él, una caída de Catálogo agotaría las conexiones de Pedidos); se distingue "no respondió" de "respondió con error"; y noEncontrados se traduce al error de negocio del contrato de POST /pedidos. Lo que no hay aquí (reintentos, circuit breaker, fallback) es materia de 06-03.

• Verbos en las URIs (/pedidos/crear, /productos/buscar). Si te sorprendes escribiendo un verbo, pregúntate cuál es el recurso: casi siempre es una colección (POST /pedidos) o un sub-recurso (POST /pedidos/{id}/cancelacion).
• Devolver 200 para todo y meter el error en el cuerpo ({"ok": false}). Rompe la caché HTTP, los monitores del gateway y la intuición de cualquier cliente. Usa la tabla del apartado 4.
• 201 cuando el trabajo no ha terminado. Si al responder aún no sabes si habrá stock, es 202. Un 201 promete que el recurso está completo.
• N+1 por comodidad. GET /productos/{id} en un bucle parece limpio hasta que un pedido de 15 líneas tarda 15 × 40 ms. Diseña lotes (?ids=) desde el principio.
• Idempotency-Key sin persistencia. Guardar las claves en memoria del proceso no sirve con dos réplicas: la tabla claves_idempotencia de 02-05 es obligatoria.
• Mensajes de error como contrato. Los clientes deben mirar codigo, no detail. Cambiar un texto no debería romper a nadie.
• Filtrar internos en errores 500. Nunca detail: err.stack. Log completo con X-Request-Id; al cliente, un mensaje genérico con ese id.
• Olvidar el timeout en el cliente. fetch sin signal espera indefinidamente. Dos segundos para llamadas internas es un buen punto de partida.
• Documentar después. El OpenAPI escrito a posteriori se desactualiza. Escríbelo primero (03-06) y valida las peticiones contra él.

Ejercicio 1. Diseña el contrato REST de "cancelar un pedido" para el servicio de Pedidos: URI y verbo, cuerpo de petición (con motivo), respuestas de éxito y de error con sus códigos y codigo, teniendo en cuenta la máquina de estados de 02-05 (solo se puede cancelar en PENDIENTE, STOCK_RESERVADO o PAGADO; no en CONFIRMADO ni si ya está CANCELADO). Escribe un ejemplo http de petición y de una respuesta de error.

Ejercicio 2. El equipo de Experiencia de compra propone GET /clientes/c-1024/pedidos (en el servicio de Clientes) para que la web muestre el historial de pedidos de un cliente. Razona si ese endpoint debe vivir en Clientes o en Pedidos, qué URI propondrías, y qué estrategia de paginación (offset o cursor) elegirías y por qué. Escribe la respuesta JSON de la primera página con dos pedidos.

Ejercicio 3. Escribe una función Express patch('/productos/:id') para Catálogo que aplique concurrencia optimista con If-Match. Supón que existe repositorio.obtener(id) que devuelve { ...producto, version } y repositorio.actualizarSiVersion(id, cambios, versionEsperada) que devuelve el producto actualizado o null si la versión no coincide. Responde 428 Precondition Required si falta If-Match, 404 si no existe, 409 VERSION_OBSOLETA si la versión no coincide y 200 con nuevo ETag si va bien.

Solución 1.

Contrato: POST /pedidos/{id}/cancelacion. La cancelación es un hecho de negocio con datos propios (motivo, quién cancela), no la edición de un campo, y POST es el verbo para "crear un sub-recurso". Debe aceptar Idempotency-Key (o, más sencillo, ser idempotente por diseño: cancelar un pedido ya cancelado por el mismo motivo devuelve 200 con el mismo cuerpo).

Respuestas:

Se puede argumentar 200 en lugar de 202 si se considera que el pedido queda CANCELADO de forma síncrona y las compensaciones son detalle interno; ambas son defendibles, pero hay que documentar la elegida en OpenAPI y aplicarla igual en toda la API.

Solución 2.

Los pedidos son del bounded context de Pedidos (02-03): el historial debe servirlo el servicio de Pedidos, que es quien tiene los datos y su estado actualizado. Poner el endpoint en Clientes obligaría a Clientes a consultar a Pedidos (acoplamiento innecesario) o a replicar pedidos (que no le pertenecen). URI propuesta: GET /pedidos?clienteId=c-1024&orden=-creadoEn&limite=20 en Pedidos. La ruta anidada /clientes/{id}/pedidos puede ofrecerla el gateway o el BFF (03-04) como comodidad para el front, redirigiéndola internamente a Pedidos, pero el contrato canónico es el filtro sobre la colección /pedidos.

Paginación: cursor. El historial de un cliente crece por un extremo (los nuevos pedidos entran arriba), es una colección potencialmente grande y el caso de uso es "scroll infinito" en la web y la app, no "ir a la página 7". Con offset, un pedido nuevo creado mientras el usuario navega desplazaría todo y repetiría un elemento entre páginas.

Solución 3.

Puntos a comprobar: el ETag de respuesta refleja la nueva versión (13), de modo que un segundo PATCH del mismo cliente puede encadenar; y actualizarSiVersion debe hacer la comprobación en la misma sentencia SQL (UPDATE ... WHERE id = $1 AND version = $2), no en dos pasos, para que la concurrencia optimista sea real.

Hemos convertido las decisiones de diseño del módulo 2 en contratos REST concretos: URIs con sustantivos y jerarquías, verbos con su idempotencia (y Idempotency-Key cuando el verbo no la tiene), una tabla cerrada de códigos de estado que todos los servicios aplican igual, los cinco contratos clave de TechCorp (POST /pedidos con 202 + Location, GET /pedidos/{id} con ETag, GET /productos?ids= en lote para evitar el N+1, GET /clientes/{id}, POST /reservas con 201/409), errores uniformes RFC 7807 con el campo codigo que sustituye a los errores dispersos del monolito, paginación por cursor para colecciones que crecen, HATEOAS mínimo, cabeceras de caché, concurrencia optimista y correlación, OpenAPI 3 como forma escrita del contrato, y una ruta Express y un cliente fetch con timeout que lo aplican.

REST cubre las llamadas síncronas, pero en 02-05 decidimos que el corazón del flujo de pedido (reservar stock, cobrar, confirmar, notificar) viaja por eventos: pedido.creado, stock.reservado, pago.confirmado, pedido.confirmado, pedido.cancelado. Falta ver cómo se publican y consumen de verdad: qué es un exchange y una cola en RabbitMQ, cómo se enruta cada evento a quien le interesa, qué pasa cuando un consumidor falla y cómo garantizamos que un evento no se pierde ni se procesa dos veces. Eso es la mensajería asíncrona, la siguiente lección.