Durante cinco módulos hemos ido construyendo la API de Tienda Aroma por partes: primero los conceptos, luego el diseño, después el código, la seguridad, la operación y las herramientas. Cada lección resolvía un problema y dejaba el siguiente abierto. Esta lección hace algo distinto: mira el resultado completo y pregunta por qué es así.

No es un resumen. Un resumen repetiría lo que ya sabes; aquí lo que interesa es la justificación en conjunto, que es lo que nunca aparece cuando aprendes pieza a pieza. Por qué el carrito acabó siendo un recurso y el checkout no. Por qué los pedidos se paginan por cursor y los cafés por desplazamiento. Por qué el dinero viaja en euros pero se guarda en céntimos. Y, sobre todo, qué se descartó en cada bifurcación y qué precio se pagó por elegir.

Piensa en esta lección como la memoria técnica que entregarías a un equipo que hereda el proyecto: contexto, decisiones con su alternativa descartada, flujos completos, los casos difíciles que casi nadie documenta, la arquitectura desplegada, los objetivos de nivel de servicio y una autocrítica honesta de lo que no salió bien. Al final tendrás una lista de verificación que puedes aplicar a cualquier API que diseñes.

1. El negocio y sus restricciones
2. Los consumidores: cinco clientes, cinco necesidades distintas
3. Casos de uso críticos y requisitos no funcionales
4. Del modelo de dominio a los recursos
5. El mapa completo de URIs
6. Las decisiones de diseño y sus alternativas descartadas
7. El flujo completo de una compra
8. Casos difíciles y cómo se resolvieron
9. La arquitectura desplegada
10. Métricas y SLO del servicio
11. Lo que haríamos distinto
12. Lista de verificación final del proyecto

Tienda Aroma vende café de especialidad. No es un supermercado: el catálogo tiene entre 40 y 120 referencias vivas, con origen, tueste, notas de cata y lotes que se agotan. El margen es alto, el volumen es moderado y la fidelidad del cliente lo es todo: un comprador habitual pide cada tres o cuatro semanas durante años.

Estas tres características del negocio condicionan la API mucho más de lo que parece:

Ninguna de estas decisiones sale de un libro de estilo. Salen del negocio. Ese es el primer mensaje de la lección: el mismo conjunto de reglas REST produce APIs distintas según el dominio, y en 06-02 lo veremos de forma mucho más brutal.

En 01-01 dijimos que una API se diseña para sus consumidores, no para su base de datos. Tienda Aroma tiene cinco, y cada uno tira del diseño en una dirección.

El detalle importante: los cinco consumen la misma API. No hay una API para móvil y otra para web. Esa fue una decisión consciente, con su coste: la SPA recibe algunos campos que no usa, y el móvil tiene que pedir campos=id,nombre,precioEuros para adelgazar la respuesta. La alternativa —un backend for frontend por cliente— habría dado respuestas perfectas para cada uno a cambio de multiplicar por tres el código, las pruebas y el contrato. Con cinco consumidores y un equipo pequeño, no compensaba. Con veinte consumidores y tres equipos, la respuesta habría sido otra.

Cuatro casos de uso concentran el 95 % del tráfico y todo el riesgo:

1. Buscar un café — GET /cafes con filtros. Es el 70 % de las peticiones. Debe ser rapidísimo y es totalmente cacheable.
2. Comprar — carrito, pedido, pago. Es el 5 % de las peticiones y el 100 % de los ingresos. Debe ser correcto aunque sea lento.
3. Seguir el envío — GET /pedidos/{id} y /envio. Genera sondeo repetido: mucha caché condicional y 304.
4. Moderar reseñas — panel interno. Volumen bajo, autorización estricta.

Y los requisitos no funcionales que acordamos con negocio:

Fíjate en la asimetría deliberada: la lectura se optimiza para velocidad y la escritura para corrección. Un catálogo que tarda 400 ms molesta; un pedido cobrado dos veces es una llamada al banco, una devolución y un cliente perdido.

En 02-02 vimos el método: escribe cómo describe el negocio su trabajo, subraya los sustantivos y pregúntate cuáles tienen identidad propia, estado y ciclo de vida. Aplicado a Tienda Aroma:

Esta es la distinción que más cuesta y la que mejor separa a quien ha entendido REST de quien traduce funciones a URLs.

El carrito es un recurso porque cumple las tres pruebas: tiene identidad (car_77), tiene estado que persiste entre peticiones (las líneas que has añadido siguen ahí mañana) y responde con sentido a los métodos HTTP. GET /carritos/car_77 devuelve algo. DELETE /carritos/car_77 significa vaciarlo. Puedes enlazarlo. Puedes cachearlo (mal, porque cambia, pero el verbo tiene sentido).

El checkout no es un recurso porque es un proceso: la transición de un carrito a un pedido. No tiene estado propio que consultar. GET /checkout no significa nada. Y sobre todo: el resultado del proceso sí es un recurso, y ya tiene nombre. El proceso se expresa creando ese recurso:

La alternativa habría sido POST /checkout, que funciona pero no dice qué se ha creado, no puede devolver un Location coherente y no se deja versionar ni enlazar. La regla que sacamos de aquí: si un proceso produce algo con identidad, expón lo producido, no el proceso. Y si un proceso no produce nada nuevo pero cambia el estado de algo existente —pagar, enviar, anular—, expón esa transición como subrecurso con POST, que es exactamente lo que hicimos con /pedidos/{id}/pago.

Este es el contrato completo de la v1, tal como quedó:

Tres regularidades que sostienen todo el mapa y que un consumidor nuevo aprende en cinco minutos:

• Plural siempre, sin excepciones. /cafes, no /cafe ni /coffeeList.
• Sin verbos en la ruta; el verbo es el método HTTP. Las únicas "acciones" son sustantivos de transición (/pago, /anulacion).
• Máximo dos niveles de anidamiento, y el subrecurso siempre pertenece de verdad al padre.

Esta es la tabla que más valor tiene en una memoria técnica. Cada fila es una bifurcación real del proyecto.

Aquí es donde el diseño se pone a prueba. Seguimos a Marta García (cli_842) desde que busca café hasta que descarga su factura. Todas las peticiones son reales según el contrato de la v1.

Sin autenticación: el catálogo es público. Con ETag, para que la siguiente visita reciba un 304 de 150 bytes (04-06). Con Vary: Origin porque la respuesta lleva cabeceras CORS y una caché compartida no debe mezclarlas (04-05).

PUT y no POST. Esta es una de las decisiones más útiles de todo el contrato y merece explicarse. Con POST /carritos/car_77/lineas, si el usuario pulsa dos veces "añadir" acaba con dos líneas del mismo café, o con una lógica de fusión escondida en el servidor. Con PUT sobre la URI de la línea, la operación es idempotente (02-03): "la cantidad de caf_001 en este carrito es 2". Pulsar diez veces deja el mismo resultado. La interfaz del carrito, con su selector de cantidad, encaja de forma natural: cada cambio del selector es un PUT.

Y el subrecurso tiene URI propia, así que quitar un café es DELETE /v1/carritos/car_77/lineas/caf_001, sin cuerpo y sin ambigüedad.

Aquí no se reserva stock. Es deliberado: reservar en el carrito obliga a expirar reservas, complica el inventario y genera falsos "agotado" en campaña. El stock se comprueba y se descuenta al crear el pedido, en una transacción.

Dentro, todo ocurre en una transacción (03-05): se leen las líneas del carrito, se bloquean y comprueban los stocks, se congela el precio unitario en cada línea, se calcula el total en céntimos, se inserta el pedido, se descuenta el stock y se vacía el carrito. Si algo falla, no queda rastro.

Y en _links aparece la hipermedia selectiva de la decisión 5: como el pedido está pendiente_pago, el cliente ve pago y anulacion. No verá envio ni devolucion, porque no son posibles todavía. La SPA no necesita conocer la máquina de estados: le basta con pintar los enlaces que recibe.

Tres mecanismos actuando a la vez, y conviene distinguirlos porque se confunden:

• Idempotency-Key protege contra el reintento del mismo cliente: si la respuesta se perdió, repetir la petición devuelve la respuesta guardada sin volver a cobrar.
• If-Match protege contra la escritura sobre una versión obsoleta: si otro proceso ya cambió el pedido, responde 412 (04-06 y 03-05).
• La transición de estado protege contra lo semánticamente imposible: pagar dos veces con claves distintas responde 409 pedido_ya_pagado.

Y observa cómo cambian los _links: han desaparecido pago y anulacion, y han aparecido factura y envio. Los enlaces son la máquina de estados.

El pago dispara un evento. La API no llama a RápidoEnvíos dentro de la transacción; encola el evento y lo entrega después, porque un transportista lento no puede bloquear un cobro.

La firma es HMAC-SHA256 del cuerpo crudo con el secreto compartido. RápidoEnvíos la verifica, responde 2xx y encola su trabajo. Si responde 5xx o no responde, reintentamos con espera exponencial. Aroma-Evento-Id permite a RápidoEnvíos descartar duplicados: la entrega es "al menos una vez", así que el receptor debe ser idempotente.

Cuando RápidoEnvíos recoge el paquete, un empleado (o su integración) marca el envío:

Marta consulta el estado. Como sondea cada minuto, la caché condicional hace su trabajo:

Y la factura, que es un recurso con otra representación:

immutable porque una factura emitida no cambia jamás. Es uno de los pocos sitios de toda la API donde esa directiva está plenamente justificada.

Un diseño se juzga por lo que hace cuando las cosas van mal. Estos seis casos son los que de verdad costaron reuniones.

El problema. Quedan 2 unidades de caf_001 y dos clientes crean un pedido de 2 en el mismo instante. Si comprobamos el stock y luego lo descontamos en dos pasos separados, ambos leen 2, ambos ven suficiente y ambos venden. Sobreventa.

La solución. Todo dentro de una transacción, y el descuento con la condición incorporada en la propia sentencia:

La comprobación y la escritura son la misma operación atómica. Si changes() devuelve 0, no había stock y se lanza el error:

Por qué 409 y no 400. El 400 dice "tu petición está mal escrita"; reenviarla igual siempre fallará. El 409 dice "tu petición es válida pero choca con el estado actual"; mañana, con stock repuesto, la misma petición funcionará. La diferencia importa para el cliente, que en el segundo caso puede ofrecer "avisarme cuando haya".

El problema. El móvil de Marta pierde cobertura justo después de enviar POST /pago. El servidor cobra; la respuesta no llega. La app reintenta. ¿Se cobra dos veces?

La solución, en dos capas.

La primera es la Idempotency-Key. Antes de procesar, se intenta insertar la clave en una tabla con restricción única, junto al hash del cuerpo:

El reintento devuelve la misma respuesta guardada, con el mismo 201/200 y el mismo cuerpo. No se cobra dos veces.

La segunda capa es la máquina de estados: si llega un pago con una clave nueva sobre un pedido que ya está pagado, responde 409 pedido_ya_pagado. La idempotencia cubre el reintento; el estado cubre el error genuino.

El problema. Marta crea el pedido a las 9:14 con caf_001 a 14,50 €. A las 9:20, un administrador sube el precio a 15,90 €. Marta paga a las 9:25. ¿Cuánto paga?

La solución: precio congelado en la línea. Cada línea de pedido guarda su propio precioUnitarioCentimos, copiado del catálogo en el momento de la creación. El pedido no consulta el precio del café al mostrarse ni al pagar.

Fíjate en que también se copia el nombre. No es redundancia por descuido: si el café se renombra o se retira del catálogo, la factura de Marta debe seguir diciendo lo que compró. Un pedido es un documento histórico, no una vista de datos actuales, y esa distinción cambia cómo se modela la tabla.

La consecuencia que hay que asumir: un carrito viejo puede mostrar precios desactualizados. Se resolvió recalculando los precios del carrito en cada GET /carritos/{id} (el carrito sí es una vista actual) y avisando en la interfaz si algo cambió desde la última visita.

El problema. ¿Puede cli_842 reseñar caf_002 si nunca lo ha comprado?

La decisión de negocio fue: sí, pero con distinción visible. Reseñar es una barrera baja a propósito, porque el volumen de reseñas importa comercialmente. Pero una reseña de un comprador verificado vale más.

La solución técnica. Al crear la reseña, el servicio consulta si existe algún pedido pagado de ese cliente que contenga ese café, y sella el resultado en el recurso:

Y una regla añadida: una reseña por cliente y café, con restricción única en la base de datos. Un segundo intento responde 409. Esa regla vive en el índice, no solo en el servicio, porque con dos instancias de la API en paralelo la comprobación en código no basta.

El problema. Marta ejerce su derecho de supresión (RGPD, artículo 17). Pero sus pedidos son documentos contables que la legislación mercantil obliga a conservar varios años. Dos obligaciones legales que apuntan en direcciones opuestas.

La solución: anonimizar, no borrar. DELETE /clientes/cli_842 no ejecuta un DELETE en la tabla. Sustituye los datos personales por valores neutros, conserva el registro con su identificador y desactiva la cuenta:

La respuesta es 204 No Content. A partir de ahí, GET /clientes/cli_842 responde 404 cliente_no_encontrado a cualquiera que no sea auditoría interna, y el pedido ped_5001 sigue existiendo con su importe, su fecha y su IVA, pero sin ninguna persona detrás.

Advertencia importante. Lo que acabas de leer es una solución técnica plausible, no asesoramiento legal. Qué se puede conservar, durante cuánto tiempo, con qué base jurídica y qué cuenta como anonimización efectiva —frente a mera seudonimización, que sigue siendo dato personal— depende de la jurisdicción, del sector y del caso concreto. En un proyecto real, este diseño se valida con el responsable de protección de datos y con asesoría jurídica antes de escribir la primera línea de código. También hay que decidir qué hacer con las copias de seguridad, con los logs y con los sistemas terceros a los que se envió el dato (aquí, RápidoEnvíos), y eso rara vez lo resuelve un UPDATE.

El problema. Enviamos pedido.pagado y no llega respuesta. ¿Lo recibieron? ¿Lo procesaron? No hay forma de saberlo desde fuera.

La solución: cola persistente con reintentos y desactivación. El evento se guarda en una tabla con su estado, y un proceso lo reintenta con espera exponencial y jitter: 1 min, 2, 4, 8, 16, 32, 64 min. Tras siete intentos fallidos pasa a fallido_permanente, se dispara una alerta y el evento queda disponible para reenvío manual desde el panel.

Tres detalles que hacen que esto funcione en producción:

• Aroma-Evento-Id estable entre reintentos. El mismo evento se reintenta con el mismo identificador, para que el receptor pueda descartar duplicados. Si cambiara, cada reintento parecería un evento nuevo y RápidoEnvíos crearía siete envíos.
• Entrega "al menos una vez", nunca "exactamente una vez". Es imposible garantizar lo segundo sobre una red no fiable, y prometerlo en la documentación es engañar. Lo que se documenta es: reintentamos; sé idempotente.
• Cortocircuito. Si RápidoEnvíos lleva 50 fallos seguidos, se deja de intentar durante unos minutos en vez de castigar a un servicio ya caído.

Cada pieza está donde está por una razón concreta:

Por qué la idempotencia vive en Redis y no en memoria. Con tres instancias detrás del gateway, el reintento del móvil de Marta puede aterrizar en una instancia distinta a la original. Una caché en memoria no lo vería y volvería a cobrar. Es el mismo razonamiento que llevó el rate limiting a Redis en 04-04: cualquier estado compartido entre peticiones debe vivir fuera del proceso, o el escalado horizontal lo rompe en silencio.

Los SLO se derivan de los requisitos del apartado 3, y cada uno tiene su indicador medible (04-07):

Y las alertas que de verdad despiertan a alguien de noche —deliberadamente pocas, porque una alerta que suena sin consecuencia entrena al equipo a ignorarlas—:

ComprasFallando dispara con un solo error, mientras que la tasa general tolera un 1 %. Esa asimetría es intencionada y refleja la del apartado 3: no todos los endpoints valen lo mismo.

Ninguna memoria técnica honesta termina sin esta sección. Cuatro decisiones que, con el proyecto ya en producción, no repetiríamos.

Qué hicimos. {"datos": [...], "total": 42}.

Qué falló. El envoltorio fue acertado —dejó sitio para metadatos— pero se quedó a medias. Los metadatos de paginación acabaron repartidos entre la cabecera Link y el campo total, y cada consumidor tuvo que aprender un sitio distinto para cada cosa. Peor: total obliga a un COUNT(*) en cada listado, que en /pedidos con filtros amplios es la consulta más lenta de toda la API. Y en una colección paginada por cursor, un total exacto es además conceptualmente dudoso.

Qué haríamos. Un objeto meta explícito, y total opcional bajo demanda:

Coste de arreglarlo ahora. Es un cambio rompedor para los cinco consumidores. Va a la lista de la v2, y ese es exactamente el tipo de deuda de contrato que se trata en 06-03.

Qué hicimos. Formato propio: {"error": {"codigo", "mensaje", "detalles"}}.

Qué falló. Es un formato razonable, coherente y bien documentado. Pero es nuestro. Existe un estándar, RFC 9457, con type, title, status, detail e instance, que las bibliotecas de cliente, los gateways y las herramientas de monitorización ya entienden. Al integrar CataBox tuvimos que explicar nuestro formato desde cero y escribir un adaptador; con problem+json habría sido una línea de configuración. Y el Content-Type habría sido autodescriptivo, que es justo la restricción de REST que más nos gusta citar (01-04).

Qué haríamos. problem+json con extensiones propias, que el estándar permite:

La lección general: antes de inventar un formato, comprueba si ya existe uno estándar. Que el tuyo sea coherente no compensa que el mundo entero hable otro idioma.

Qué hicimos. POST /cafes/{id}/resenas para crear, GET /resenas para moderar, GET /cafes/{id}/resenas para listar las de un café.

Qué falló. Acabamos con dos rutas para el mismo recurso, y eso se paga en sitios inesperados: dos entradas en el OpenAPI que hay que mantener sincronizadas, dos rutas en las métricas por ruta —lo que dificulta responder "¿cuántas reseñas se crean al día?"—, dos reglas de rate limiting, dos rutas en el gateway, dos conjuntos de pruebas. Cuando llegó POST /resenas/{id}/respuestas, la asimetría se hizo evidente: las respuestas cuelgan de la reseña plana, no del café. Y algún cliente empezó a usar GET /resenas?cafeId=caf_001, que devuelve lo mismo que GET /cafes/caf_001/resenas pero con otra forma de paginar.

Qué haríamos. Colección plana /resenas como única fuente, con POST /resenas incluyendo cafeId en el cuerpo, y GET /cafes/{id}/resenas conservado solo como atajo de lectura documentado como tal —o eliminado, sustituido por GET /resenas?cafeId=caf_001—.

El matiz honesto: hay un argumento sólido a favor de lo que hicimos, y es que POST /cafes/{id}/resenas hace imposible crear una reseña sin café y deja el cafeId fuera del cuerpo, donde no puede falsificarse. No es una decisión obviamente mala; es una decisión cuyo coste no valoramos bien de antemano.

Qué hicimos. El stock se comprueba y descuenta solo al crear el pedido.

Qué falló. En el pico de Navidad, con lotes pequeños, aumentaron los 409 stock_insuficiente justo en el paso final de la compra. Desde el punto de vista del usuario, es la peor experiencia posible: has llegado hasta el pago y entonces te dicen que no hay.

Qué haríamos. Mantener la decisión de fondo —reservar en el carrito trae más problemas de los que resuelve— pero avisar antes: mostrar el stock restante en el carrito, avisar cuando quedan pocas unidades y comprobar disponibilidad al abrir el proceso de compra, no solo al confirmarlo. El error 409 seguiría existiendo, pero dejaría de ser la primera noticia.

La lección general: algunos problemas de diseño de API se resuelven mejor con información temprana que con más maquinaria transaccional.

Confundir "acción" con "recurso" al primer obstáculo. En cuanto aparece una operación que no encaja en CRUD, la tentación es POST /pedidos/{id}/procesarPagoYNotificar. Pregúntate qué cosa produce o qué estado cambia. Casi siempre hay un sustantivo detrás: un pago, una anulación, una devolución.

Coherencia mal entendida. Usar el mismo modelo de paginación en toda la API suena a buena práctica, pero en Tienda Aroma habría sido un error: el catálogo y los pedidos tienen dinámicas opuestas. La coherencia que importa es la de criterios, no la de mecanismos: "colecciones pequeñas y estables por offset, colecciones grandes que crecen por delante por cursor" es una regla coherente que produce dos mecanismos distintos.

Guardar dinero en flotantes. 0.1 + 0.2 da 0.30000000000000004. En una línea no se nota; en un total de campaña, sí. Céntimos como entero por dentro, cadena con dos decimales por fuera.

Un pedido que consulta el catálogo para mostrar precios. Es el error de modelado más caro de este dominio. Un pedido es historia congelada; el catálogo es presente. Copia lo que necesites, aunque parezca redundante.

Enviar webhooks dentro de la transacción. Si la llamada a RápidoEnvíos ocurre antes del COMMIT, un fallo posterior deja notificado un pedido que no existe. Y si ocurre dentro, un transportista lento alarga la transacción y bloquea la base de datos. Confirma primero, encola después.

Prometer "exactamente una vez" en la documentación de webhooks. No es realizable sobre una red no fiable. Documenta "al menos una vez" y exige idempotencia al receptor. Es más honesto y evita integraciones rotas.

Consejo: escribe la tabla de decisiones mientras diseñas, no después. La columna que importa no es "qué hicimos", que se deduce del código, sino "qué descartamos y por qué". Dentro de un año, cuando alguien proponga cambiar el modelo de paginación, esa columna evita repetir la discusión entera.

Consejo: haz el flujo completo antes de escribir código. Escribir las diez peticiones y respuestas de una compra en un fichero de texto, encadenadas, revela huecos que ningún diagrama de recursos muestra: cabeceras que faltan, ids que nadie devolvió, estados imposibles.

Tienda Aroma quiere lanzar suscripciones: el cliente recibe 500 g de un café cada mes, puede pausarla, reanudarla, cambiar el café o cancelarla, y cada mes se genera automáticamente un pedido.

1. Decide si "suscripción" es un recurso y justifícalo con las tres pruebas del apartado 4.
2. Diseña el mapa de URIs completo, incluyendo pausa, reanudación, cancelación y consulta de los pedidos generados.
3. Indica qué _links devolverías para una suscripción en estado activa y en estado pausada.
4. Decide el modelo de paginación de /suscripciones y justifícalo.

Escribe una prueba de integración que demuestre la sobreventa cuando la comprobación de stock y el descuento van en dos pasos separados, y verifica después que la solución del apartado 8.1 la evita. Comprueba también el código y el cuerpo del error.

Toma la tabla del apartado 6 y, para cada una de estas tres filas, argumenta el caso contrario de forma convincente: (a) _links selectivos, (b) versión en la ruta, (c) ids con prefijo. Después decide si mantendrías la decisión original y por qué. El objetivo es distinguir las decisiones bien fundamentadas de las que se sostienen solo por costumbre.

Solución 1

1. ¿Es un recurso? Sí, sin dudarlo. Identidad: sus_301. Estado persistente: activa, pausada, cancelada, más la fecha de la próxima entrega. Ciclo de vida: largo, con transiciones bien definidas. Cumple las tres pruebas mejor que el carrito.

2. Mapa de URIs:

Pausar y reanudar son subrecursos con POST, igual que /pago: son transiciones de estado, no ediciones de campos. Un PATCH {"estado":"pausada"} permitiría saltar a cualquier estado sin control.

Cambiar el café sí es PATCH, porque es una edición de un atributo, no una transición del ciclo de vida. La distinción es exactamente la de la decisión 1 del apartado 6.

3. Enlaces por estado:

Una suscripción cancelada solo tendría self y pedidos: es terminal.

4. Paginación: offset. Un cliente tiene una, dos o tres suscripciones; ni el más entusiasta llegará a veinte. La colección es minúscula, estable y se consulta entera. El cursor añadiría complejidad sin resolver ningún problema. Distinto es /suscripciones/{id}/pedidos, que crece cada mes durante años y hereda el cursor de /pedidos.

Solución 2

Cómo demostrar el fallo primero. Sustituye temporalmente el UPDATE ... WHERE stock >= :cantidad por dos pasos —SELECT stock y luego UPDATE stock = :nuevo— fuera de transacción. Con la versión ingenua verás dos 201 y stock = -2. Restaura la versión correcta y la prueba pasa. Esta prueba es valiosa precisamente porque falla con la implementación ingenua: una prueba que pasa con el código roto no prueba nada.

Nota: con SQLite y better-sqlite3 las escrituras se serializan, lo que ya ayuda; con PostgreSQL o MySQL, el UPDATE ... WHERE condicional dentro de la transacción es lo que garantiza la atomicidad. La condición en la propia sentencia es lo portable.

Solución 3

(a) Caso contrario a los _links selectivos. «La selectividad obliga al servidor a calcular los enlaces en cada respuesta, es más código y más pruebas, y produce una API inconsistente: unos recursos traen enlaces y otros no, lo que confunde a quien la descubre. Además, un cliente que quiera saber si un pedido es anulable debe pedirlo entero. O HATEOAS completo, o ninguno y que el cliente conozca el estado.» Veredicto: se mantiene. El argumento de la inconsistencia es real, pero se resuelve documentándola, no eliminando el valor. Los enlaces de pedido evitan que cinco consumidores reimplementen —y desincronicen— la misma máquina de estados. En los cafés no había nada que evitar.

(b) Caso contrario a la versión en la ruta. «/v1/cafes/caf_001 y /v2/cafes/caf_001 son URIs distintas para el mismo recurso, lo que contradice la identificación de recursos de 01-04. La versión es un detalle de la representación y su sitio natural es Accept. Con la versión en la ruta, cada cliente tiene enlaces hardcodeados y HATEOAS se vuelve imposible de versionar limpiamente.» Veredicto: se mantiene, con el coste reconocido. El argumento es teóricamente correcto y lo asumimos. A cambio: la versión aparece en logs, métricas y configuración del gateway, se prueba desde el navegador, se enruta sin lógica en la aplicación y responde a "¿quién sigue en v1?" con una consulta trivial. En 06-03 verás cuánto vale eso al migrar.

(c) Caso contrario a los ids con prefijo. «El prefijo mezcla el tipo con el identificador, se vuelve mentira cuando un recurso cambia de tipo o se fusiona con otro, ocupa bytes en cada respuesta y tienta a los clientes a parsear el id para deducir el tipo, creando un acoplamiento con un detalle interno.» Veredicto: se mantiene. El riesgo del parseo es real y se mitiga documentando explícitamente que el id es opaco. A cambio, cada mensaje de error, cada log y cada ticket de soporte se leen sin consultar la base de datos, y eso se cobra todos los días.

Una lista aplicable a cualquier API que diseñes, derivada de todo lo recorrido:

Diseño

• [ ] Los consumidores están identificados, y cada uno con su necesidad concreta.
• [ ] Los recursos salen del dominio, no de las tablas.
• [ ] URIs en plural, sin verbos, con anidamiento máximo de dos niveles.
• [ ] Cada método HTTP respeta su semántica: GET seguro, PUT/DELETE idempotentes.
• [ ] Los códigos de estado distinguen 400, 409, 412, 422 y 429 con criterio.
• [ ] Catálogo de errores cerrado, documentado y con códigos estables.
• [ ] Modelo de paginación elegido por dominio y justificado por escrito.
• [ ] Estrategia de versionado y política de deprecación publicadas.

Implementación

• [ ] Validación de toda la entrada en el borde, con esquemas.
• [ ] Transacciones donde hay invariantes; condiciones dentro de la sentencia.
• [ ] Concurrencia optimista con version y ETag/If-Match donde importa.
• [ ] Idempotencia en toda operación con efectos de dinero o de terceros.
• [ ] Errores unificados por un único manejador.
• [ ] Dinero en enteros; fechas en ISO-8601 UTC.
• [ ] Datos históricos copiados, no referenciados.

Seguridad

• [ ] Autenticación y autorización por rol y por propiedad del recurso.
• [ ] CORS con lista blanca explícita; nunca * con credenciales.
• [ ] Rate limiting con estado compartido y 429 con Retry-After.
• [ ] Secretos fuera del código; cabeceras de seguridad con helmet.
• [ ] Datos personales minimizados en logs, y borrado con criterio legal validado.

Operación

• [ ] Logs estructurados con identificador de traza propagado.
• [ ] Métricas de las señales de oro y SLO acordados con negocio.
• [ ] liveness y readiness diferenciados.
• [ ] Alertas pocas y accionables, priorizadas por impacto de negocio.
• [ ] Caché HTTP calibrada recurso a recurso.

Contrato y entrega

• [ ] OpenAPI completo, validado con Spectral y publicado.
• [ ] Pruebas unitarias, de integración, de contrato y e2e en CI.
• [ ] Detección automática de cambios rompedores.
• [ ] Despliegue sin corte con migraciones retrocompatibles y vuelta atrás.
• [ ] Decisiones importantes registradas como ADR, con su alternativa descartada.

Has recorrido la API de Tienda Aroma completa, de los requisitos al despliegue, y sobre todo has visto por qué es como es. El carrito es recurso y el checkout no, porque uno tiene estado y el otro es un proceso. El dinero va en céntimos por dentro y en euros por fuera, porque la aritmética y la legibilidad piden cosas distintas. Los cafés se paginan por desplazamiento y los pedidos por cursor, porque son colecciones con dinámicas opuestas y forzar un único mecanismo habría sido coherencia mal entendida. La Idempotency-Key está en el pago porque las redes móviles reintentan solas y un timeout no dice si el servidor cobró.

Has visto también lo que rara vez se enseña: los casos difíciles resueltos con nombre y apellidos —la sobreventa cerrada con una condición dentro del UPDATE, el doble pago cerrado en dos capas, el precio congelado en la línea porque un pedido es historia y no una vista, la anonimización del cliente con la advertencia de que ese diseño lo firma un jurista y no un programador, y los webhooks entregados "al menos una vez" porque prometer más sería mentir—. Y una autocrítica honesta: el envoltorio que se quedó a medias, el problem+json que deberíamos haber usado, las reseñas con dos caminos y el stock que avisaba demasiado tarde. Ese es el material del que están hechas las memorias técnicas útiles: no la lista de aciertos, sino la de bifurcaciones con su precio.

El riesgo de una lección así es sacar la conclusión equivocada: creer que ya tienes la plantilla de una API REST y que basta con cambiar cafes por lo que toque. No es así. Cada decisión de esta lección es correcta para este dominio: un catálogo pequeño y estable, stock finito y transaccional, pocas escrituras de altísimo valor, cinco consumidores conocidos y consistencia fuerte como requisito irrenunciable. Cambia el dominio y varias de esas decisiones dejan de sostenerse.

Eso es exactamente lo que hace la siguiente lección. En 06-02, Caso de estudio: API de una red social, diseñamos CafeSocial, la red de catadores que Tienda Aroma quiere lanzar, y varias certezas de hoy se caen una a una: el grafo de seguidores obliga a modelar la relación como recurso; la línea de tiempo no es una colección normal sino un recurso derivado con el problema del fan-out detrás; la paginación por desplazamiento deja de funcionar directamente —duplicados y saltos— y el cursor opaco pasa de opción a obligación; los contadores de "me gusta" se vuelven aproximados a propósito; las imágenes ya no suben por la API; la autorización deja de ser "de quién es esto" para convertirse en "quién pregunta y qué le dejamos ver", con 404 donde la tienda respondía 403; y el tiempo real deja de ser un extra del panel para ser el producto. Terminaremos con la tabla que da sentido a los dos casos juntos, decisión a decisión, y con el motivo de que en ese dominio GraphQL sea una alternativa mucho más defendible de lo que era aquí.