En la lección anterior fijamos el método de trabajo y decidimos, con criterio, qué sustantivos del dominio de Tienda Aroma merecen ser recursos. Ahora toca lo siguiente: darles dirección. La URI es la parte más visible y más duradera de una API —los clientes la escriben en su código, la guardan en marcadores, la copian en tickets— y por eso es también la más cara de cambiar. Esta lección establece las reglas de nombrado, resuelve cuándo anidar y cuándo no, elige el tipo de identificador y afronta el problema que ningún CRUD resuelve por sí solo: cómo se modelan acciones como pagar un pedido o moderar una reseña. Terminaremos con el mapa completo de URIs de Tienda Aroma, que el resto del módulo dará por bueno.

1. Qué es un recurso y qué es una URI
2. Sustantivos y no verbos
3. Colecciones y elementos
4. Reglas de nombrado
5. Jerarquía y anidamiento
6. Recursos singleton
7. Path parameters frente a query parameters
8. Diseño de identificadores
9. Acciones que no son CRUD
10. Mapa de URIs de Tienda Aroma

Recordemos la definición de 01-04: un recurso es cualquier cosa con identidad sobre la que tenga sentido operar; la URI es su identificador estable; la representación es una de sus posibles formas concretas (el JSON que viaja, el PDF, el HTML).

Tres consecuencias prácticas que gobiernan toda esta lección:

• Un recurso puede tener varias representaciones (/pedidos/ped_5001/factura en JSON o en PDF), pero mantiene una sola URI. La representación se elige por negociación de contenido (02-05), no cambiando la URL con .pdf.
• Una URI identifica, no describe la operación. Lo que se hace con el recurso lo dice el método (02-03).
• Las URIs deberían sobrevivir a los cambios internos. Si /cafes/caf_001 deja de funcionar porque se ha refactorizado la base de datos, hemos roto el contrato.

La regla más citada del diseño REST, y la que más se incumple:

Por qué importa, más allá de la estética:

• El método ya es el verbo. GET /obtenerCafes repite el verbo y, peor, permite la incoherencia POST /obtenerCafes.
• Se pierde la semántica de HTTP. GET /borrarResena es una barbaridad funcional: un buscador o un prefetch del navegador podría borrar reseñas al recorrer enlaces, porque GET es seguro por definición (02-03).
• Se pierde la previsibilidad. Con verbos, cada endpoint hay que memorizarlo: obtenerCafes, getPedidos, listarResenas, consultarCliente.

Ojo con un matiz importante: los identificadores del código sí van en español y con verbo (obtenerCafes(), crearPedido()), como fija la guía de estilo. Lo que no lleva verbo es la URI.

Toda API orientada a recursos se estructura sobre dos figuras:

• Colección: un conjunto de recursos del mismo tipo. /cafes.
• Elemento (o recurso individual): un miembro concreto. /cafes/caf_001.

El patrón se lee de izquierda a derecha como una ruta de navegación:

Cada nivel alterna colección → elemento → colección → elemento. Si tu URI rompe esa alternancia (/clientes/pedidos/cli_842), casi siempre hay un error de diseño.

Y cada figura admite operaciones distintas, lo que anticipa 02-03:

Estas son las reglas que Tienda Aroma incorpora a su guía de estilo.

/cafes, /clientes, /pedidos, /resenas, /carritos. Siempre plural, incluso cuando suene raro, porque la alternativa —singular para el elemento y plural para la colección— obliga a recordar dos formas por recurso.

La única excepción son los singleton (sección 6), que por definición no son colección.

El componente de ruta de una URL distingue mayúsculas de minúsculas (a diferencia del nombre de host). /Cafes y /cafes son dos recursos distintos para el estándar, y aceptar los dos duplica la superficie del contrato y estropea la caché.

Motivos: es la convención dominante en la web, es más legible y los buscadores tratan el guion como separador de palabras (relevante si parte de la API se indexa o si compartes enlaces de documentación). Fíjate en la asimetría deliberada: kebab-case en la URI, camelCase en el JSON. Es una inconsistencia aparente, pero son dos mundos con convenciones propias y consolidadas; lo importante es que cada mundo sea coherente consigo mismo.

El formato es una cuestión de representación, y se negocia con cabeceras (02-05). Poner .json mezcla identidad y formato: si mañana añades XML o PDF, cada recurso tiene tres URIs para la misma cosa.

/cafes y /cafes/ son técnicamente rutas distintas. Elige una —Tienda Aroma usa sin barra final— y redirige la otra con 301 (02-04) en lugar de servir las dos.

El nombre de la clase, de la tabla o del patrón de implementación no es asunto del consumidor. Ojo también con /api: si el host ya es api.tiendaaroma.example, repetirlo en la ruta es redundante.

Nada de acentos, ñ, espacios ni mayúsculas en los segmentos de ruta que tú controlas. Por eso la colección es /resenas y no /reseñas: aunque los navegadores modernos codifican los caracteres no ASCII, en la práctica acaban apareciendo como /rese%C3%B1as en logs, ejemplos de curl y clientes antiguos.

Anidar expresa pertenencia: /cafes/caf_001/resenas son las reseñas de ese café.

Anida un subrecurso solo si no tiene sentido fuera de su padre, o si la relación de pertenencia es la forma natural de acceder a él.

Ejemplos en Tienda Aroma:

Una regla que ahorra disgustos: no pases de /coleccion/{id}/subcoleccion/{id}. A partir de ahí la URI se vuelve ilegible, acopla el cliente a una jerarquía que puede cambiar y obliga a validar cadenas de pertenencia largas.

Cuando necesites bajar más, corta la jerarquía y usa una colección de primer nivel con filtro:

Un mismo recurso puede ser alcanzable por dos rutas si cada una sirve a un caso de uso distinto. En Tienda Aroma:

Reglas para que esto no se convierta en un problema:

• El elemento vive en una sola URI canónica: /resenas/res_101. La forma anidada es solo para listar y crear.
• El enlace self de la representación apunta siempre a la canónica, para que dos rutas no generen dos identidades.
• La creación anidada es más cómoda: POST /cafes/caf_001/resenas no necesita repetir cafeId en el cuerpo, porque ya está en la URI.

Un singleton es un recurso del que solo existe una instancia en su contexto. No tiene colección ni identificador propio, y por eso va en singular.

Un singleton típicamente admite GET, PUT y a veces DELETE, pero no POST (no hay colección a la que añadir), con la excepción de los singleton que modelan una acción, que sí usan POST (sección 9).

Cuidado con el singleton mal usado: /clientes/cli_842/direccion está bien si el cliente solo puede tener una; en cuanto pueda tener varias, se convierte en /clientes/cli_842/direcciones y eso es un cambio rompedor (02-07). Si tienes dudas, empieza por colección.

La confusión más habitual del diseño de URIs. La regla es sencilla y casi nunca falla:

La ruta identifica el recurso. La query string modifica cómo se devuelve la colección.

Ejemplo comparado:

Dos matices que conviene conocer:

• Un filtro que devuelve un único elemento sigue siendo una colección. GET /cafes?nombre=Etiopía Yirgacheffe devuelve {"datos": [...], "total": 1}, no el objeto suelto, y devuelve 200 con lista vacía si no hay coincidencias (no 404). La razón: el recurso "colección filtrada" existe aunque esté vacío.
• Los parámetros de query afectan a la caché. Cada combinación distinta es una URL distinta y, por tanto, una entrada de caché distinta. Es un argumento más para no multiplicar parámetros sin necesidad (04-06).

El identificador que pongas en la URI es contrato para siempre. Las opciones:

caf_001, cli_842, ped_5001, res_101, car_77, fac_88, evt_9f2c. Es el estilo que popularizó Stripe y las razones son muy prácticas:

1. Autodescriptivos. Al leer un log o un ticket, ped_5001 se entiende sin contexto. Con 5001 a secas, no sabes de qué es.
2. Imposible cruzar tipos. Si alguien envía POST /v1/pedidos con {"clienteId": "caf_001"}, el servidor detecta el prefijo equivocado y responde 400 con datos_invalidos, en lugar de crear un pedido incoherente.
3. Opacos por contrato. La documentación dice explícitamente: el identificador es una cadena opaca, no lo parsees, no supongas longitud, no supongas que la parte numérica es correlativa. Así podemos migrar mañana a caf_01HQ8ZK... sin romper a nadie.

En producción, la parte que sigue al prefijo debería ser aleatoria y no correlativa. Los caf_001 y ped_5001 del curso son didácticos; en una tienda real, publicar identificadores correlativos tiene dos problemas:

• Fuga de información de negocio. Un competidor que pide un pedido el lunes y otro el viernes sabe cuántos pedidos has recibido esa semana. Es el clásico German tank problem.
• Enumeración. Con ids correlativos, recorrer ped_5001, ped_5002, ped_5003… es trivial. Que un tercero pueda leer pedidos ajenos es un fallo de autorización, no de ids —se llama IDOR y se trata en 04-02—, pero los ids adivinables convierten un fallo puntual en una fuga masiva. La regla es: autoriza siempre, y además no lo pongas fácil.

Sobre los slugs: son excelentes para la web pública (tiendaaroma.example/cafes/etiopia-yirgacheffe) y malos como identidad de API, porque cambian. Si los quieres, el patrón habitual es que el slug sea un campo más de la representación y un filtro (?slug=etiopia-yirgacheffe), mientras la URI canónica sigue siendo el id opaco.

Aquí está el problema de diseño más interesante de la lección. Muchas operaciones del negocio no son "crear, leer, actualizar, borrar":

• Pagar un pedido.
• Anular un pedido.
• Aprobar o rechazar una reseña.
• Vaciar un carrito.
• Reenviar el correo de confirmación.

Hay tres estrategias, y conviene entender las tres antes de elegir.

Es aceptable cuando la transición es puramente un cambio de dato, sin lógica ni efectos.

Se busca el sustantivo que hay detrás del verbo: aprobar → una aprobación; pagar → un pago; anular → una anulación. Ese sustantivo es un recurso que se crea con POST.

Ventajas, que son justo las que buscábamos:

• Sin verbos en la ruta: aprobacion es un sustantivo y el verbo lo pone POST.
• La acción admite cuerpo propio: el motivo del rechazo, la referencia del pago, el importe.
• La acción es un recurso consultable: GET /v1/pedidos/ped_5001/pago devuelve el pago realizado, con su fecha y su referencia.
• Se autoriza por separado: el permiso para crear /aprobacion es distinto del permiso para editar la reseña (04-03).
• Deja sitio a la idempotencia: al ser un POST bien delimitado, se le puede exigir Idempotency-Key (02-03).

Y el mapa de acciones de Tienda Aroma queda así:

Fíjate en la última fila: antes de inventar un subrecurso, comprueba si un método estándar ya lo expresa. Vaciar el carrito es exactamente "borrar todas sus líneas", así que DELETE /carritos/car_77/lineas es más natural que un POST /carritos/car_77/vaciado. Es la excepción a la regla del apartado 3 sobre no usar DELETE en colecciones, y es legítima porque aquí la colección está acotada a un carrito concreto y su borrado completo es una operación de negocio real.

Este es el resultado de la lección y el mapa que el resto del módulo dará por bueno. Los métodos aparecen para dar contexto; su semántica exacta es 02-03 y los códigos de respuesta, 02-04.

Decisiones anotadas para no olvidarlas:

• No hay POST /v1/resenas: una reseña siempre nace asociada a un café, así que solo se crea en /cafes/{cafeId}/resenas. La vista plana es de solo lectura y sirve al panel interno.
• No hay DELETE /v1/pedidos/{id}: un pedido no se borra, se anula. El histórico contable es sagrado.
• /v1/origenes se ha considerado y descartado para la v1: el origen es un atributo y se filtra con ?origen=. Si algún día tiene datos propios (altitud, cooperativa, foto), será una colección y podrá añadirse sin romper nada (02-07).

• Meter el verbo en la ruta "solo para esta operación". Empieza con una excepción y acaba con veinte. Si necesitas una acción, busca su sustantivo.
• Anidar por costumbre. /clientes/cli_842/pedidos/ped_5001 obliga al servidor a validar que ese pedido es de ese cliente y al cliente a conocer dos ids para pedir uno. Anida para listar, usa la URI canónica para el elemento.
• Usar la query string para identificar. /cafes?id=caf_001 rompe la caché por URL, complica los enlaces self y no permite subrecursos.
• Poner .json al final. Mezcla identidad y formato; para eso está Accept.
• Pluralizar mal. /cafes y /cafe/caf_001 conviviendo es el bug de documentación más frecuente del mundo.
• Exponer el id de base de datos por comodidad. Cambiar de motor o fusionar entornos te obligará a romper el contrato. Un id opaco te deja libertad.
• Consejo: escribe las URIs antes que el código y léelas en voz alta. Si al leer /pedidos/ped_5001/anulacion con POST se entiende sin explicar, está bien diseñada.
• Consejo: mantén una tabla como la de la sección 10 en el repositorio. Es el índice del contrato y el sitio donde se discute cualquier endpoint nuevo antes de existir.

Un equipo ha propuesto estas rutas para Tienda Aroma. Corrígelas y justifica cada cambio.

Tienda Aroma quiere que un cliente pueda regalar un pedido: al confirmarlo indica el correo del destinatario y un mensaje, y el sistema envía un aviso y oculta el precio en el albarán.

Modela esta funcionalidad con las tres estrategias de la sección 9 (PATCH, verbo en la URI, subrecurso), muestra la petición HTTP de cada una y elige la que encaja con la guía de estilo, justificándolo.

Para cada necesidad, decide la URI y di si has anidado o no y por qué:

1. El panel interno quiere ver todas las líneas vendidas del café caf_001 en el último mes.
2. Aroma Móvil quiere las reseñas escritas por el cliente cli_842.
3. RápidoEnvíos quiere actualizar el estado del envío del pedido ped_5001.
4. La SPA quiere el histórico de cambios de precio de caf_001.

Solución 1

Solución 2

Estrategia A — PATCH sobre el pedido:

Funciona, pero el envío del aviso queda como efecto oculto de un cambio de campo, y no hay dónde consultar después si el aviso se envió.

Estrategia B — verbo en la URI:

Intención clarísima, pero verbo en la ruta: incumple la guía de estilo y abre la puerta a regalarSinAviso.

Estrategia C — subrecurso (elegida):

Es la elegida: sustantivo (regalo), cuerpo propio para los parámetros de la acción, consultable después con GET, y se puede cancelar con DELETE /v1/pedidos/ped_5001/regalo mientras el pedido no se haya enviado. Encaja exactamente con /pago, /anulacion y /aprobacion.

Solución 3

1. GET /v1/lineas-pedido?cafeId=caf_001&desde=2026-02-14 — sin anidar. Lo que se busca cruza todos los pedidos, así que la jerarquía /pedidos/{id}/lineas no sirve: hace falta una colección plana de primer nivel consultable con filtros. Cuidado con la tentación de escribir /v1/pedidos/lineas: colisionaría con /v1/pedidos/{pedidoId}, porque el enrutador no puede distinguir un id llamado lineas de un segmento fijo. (Alternativa razonable: un recurso de informes /v1/ventas?cafeId=..., si el panel necesita agregados en vez de líneas sueltas.)
2. GET /v1/resenas?clienteId=cli_842 — sin anidar bajo el café, porque el criterio es el autor. Anidarlo como /clientes/cli_842/resenas también sería defendible si "mis reseñas" fuese una pantalla propia de Aroma Móvil; ambas cumplen la regla, y en ese caso convendría elegir una sola para no duplicar contrato.
3. PUT /v1/pedidos/ped_5001/envio — anidado y singleton: un envío no existe fuera de su pedido y solo hay uno. PUT porque RápidoEnvíos envía el estado completo del envío en cada actualización (02-03).
4. GET /v1/cafes/caf_001/historico-precios — anidado: el histórico no tiene sentido fuera de su café y es de solo lectura. Nótese el kebab-case en la palabra compuesta. Si el histórico se consultase globalmente para todo el catálogo, se convertiría en /v1/historico-precios?cafeId=caf_001.

Las URIs son la cara pública y más duradera de la API, y ahora tienes reglas concretas para diseñarlas: sustantivos en plural y minúsculas, kebab-case para palabras compuestas, sin extensiones ni verbos, con anidamiento solo cuando expresa pertenencia real y sin pasar de dos niveles, singleton en singular para lo que es único, identificación en la ruta y modificación de colecciones en la query string, e identificadores opacos con prefijo que no filtren información de negocio. Y sobre todo tienes resuelto el problema que descoloca a todo el mundo: las acciones que no son CRUD se modelan como subrecursos creados con POST, lo que le da a cada acción cuerpo propio, consulta posterior y autorización independiente. El mapa de URIs de Tienda Aroma está cerrado.

Sabemos ya qué recursos existen y dónde viven. Falta decir con precisión qué se puede hacer con cada uno. En la lección siguiente, 02-03 Métodos HTTP, recorreremos GET, POST, PUT, PATCH, DELETE, HEAD y OPTIONS aplicados a este mapa; entenderemos por qué la seguridad y la idempotencia son mucho más que teoría cuando RápidoEnvíos reintenta una petición o un cliente pulsa dos veces el botón de pagar; compararemos a fondo PUT frente a PATCH con JSON Merge Patch y JSON Patch; y diseñaremos las claves de idempotencia del pago de un pedido.