Rutas y primeras consultas del proyecto

Proyecto compartido. En el taller de Intermodular que abre esta semana has trabajado del repositorio vacío a una url pública. En Servidor continúas la implementación del mismo producto.

Se explica

25 minutos · explicación y demostración

Ya tienes rutas que devuelven un texto fijo. Hoy el cliente enviará datos en la URL y un mismo método responderá según esos datos. Un parámetro es un valor de entrada del método; Spring lo obtiene de la ruta o de la consulta. Todavía devolveremos texto, sin buscar registros reales.

Recibir datos distintos en una misma ruta

El endpoint de ayer siempre responde lo mismo:

@GetMapping("/hola")
public String hola() {
    return "Hola, mundo. Te responde mi servidor.";
}

Si mantuviéramos una respuesta fija, no podríamos elegir a quién saludar ni qué incidencia consultar. Para reutilizar el método, el cliente enviará un dato dentro de la petición y el método lo utilizará al construir su respuesta.

Hoy vemos las dos formas de hacerlo con un GET.

Se parecen, pero no significan lo mismo, y elegir mal es el origen de la mitad de las APIs incómodas de usar. Al final de la sesión tendrás una regla para decidir.

La query string, por dentro

Es lo que va después del ?. Son pares clave=valor separados por &:

/incidencias?estado=abierta&prioridad=alta&pagina=2

?              empieza la query string
estado=abierta primer par
&              separador
prioridad=alta segundo par
&              separador
pagina=2       tercer par

Tres cosas que conviene saber desde hoy:

• El orden no importa: ?a=1&b=2 y ?b=2&a=1 son la misma petición.
• Todo llega como texto. pagina=2 no constituye un número, sino la cadena "2". Que acabe siendo un int en tu método es trabajo de Spring, no del navegador.
• Los caracteres raros se codifican. Un espacio viaja como %20 o como +, y una ñ como %C3%B1. Lo verás en el panel de red y no debe alarmarte.

La regla para decidir dónde va cada dato

Esa última fila combina las dos ideas, y es la forma que tendrá casi toda tu API a partir de la UD3.

Se trabaja

140 minutos · implementación guiada sobre el proyecto propio

Paso 1 · Abrir el proyecto y comprobar el punto de partida · 10 min

Antes de añadir rutas, comprueba que puedes ejecutar la versión de la sesión anterior. En este paso trabajarás con HolaController; crearás SaludoController en el paso 2.

1. En el IDE, abre la carpeta del proyecto que contiene pom.xml. Usa tu carpeta habitual de trabajo. Si hiciste la tarea de clonar el repositorio para comprobarlo, evita abrir a la vez las dos copias: podrías editar una y ejecutar la otra.
2. Dentro de src/main/java, despliega tu paquete base y su carpeta controller. Abre HolaController.java. Localiza el método con @GetMapping("/hola") y lee su return: ese es el texto que vas a comprobar. Si elegiste otro paquete base, utiliza su carpeta y conserva el package de tus clases.
3. Arranca la aplicación desde la terminal situada en la carpeta de pom.xml, con el comando correspondiente a tu sistema:

Windows · PowerShell

.\mvnw.cmd spring-boot:run

Linux o macOS

./mvnw spring-boot:run

Si ya está ejecutándose, detén esa ejecución antes de volver a arrancar. Puedes usar Stop si la lanzaste desde el IDE o Ctrl+C en la terminal donde se está ejecutando.

4. Espera al mensaje Started ...Application y abre http://localhost:8080/hola en el navegador. Debe aparecer la frase del return de tu método, incluida la personalización que hiciste en la sesión 1. Si cambiaste el puerto, úsalo en todas las URL de esta sesión.
5. En la tabla de comprobaciones que guardaste con el proyecto, anota la URL y el texto observado. Para ver también el estado HTTP, abre F12 → Red/Network, recarga la página y selecciona la petición a hola: debe mostrar 200.

Antes de continuar: el servidor sigue ejecutándose y /hola responde con tu texto. Si no conecta, revisa el arranque; si devuelve 404, revisa la ruta y que estés ejecutando el proyecto correcto. Los identificadores y filtros de tu aplicación se elegirán al aplicar los ejemplos en el paso 5.

Paso 2 · @RequestParam · leer la query string · 30 min

Vas a realizar tres cambios en orden: crear una clase con un saludo, modificar ese saludo para darle un valor por defecto y añadir una consulta con dos parámetros. Prueba cada versión antes de pasar a la siguiente. HolaController se conserva.

2.1 · Crear el saludo con un parámetro obligatorio

Crea SaludoController.java en la misma carpeta que HolaController.java. Con el paquete del ejemplo, la ruta completa es:

src/main/java/com/ejemplo/gestor/controller/SaludoController.java

Copia esta clase completa; si tu paquete base es distinto, adapta la primera línea para que coincida con el de HolaController. Si el archivo ya existe, revisa su contenido en lugar de crear otra clase con el mismo nombre.

package com.ejemplo.gestor.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SaludoController {

    @GetMapping("/saludo")
    public String saludo(@RequestParam(name = "nombre") String nombre) {
        return "Hola, " + nombre + ".";
    }
}

Guarda el archivo, detén la aplicación y vuelve a arrancarla como en el paso 1. Repite esa secuencia después de cada cambio de Java: recargar el navegador solo envía otra petición, no ejecuta el código que acabas de editar.

Abre estas URL, una cada vez, y registra el estado HTTP y la respuesta. Cambiar la URL no requiere reiniciar el servidor.

@RequestParam es obligatorio por defecto. Cuando falta nombre, Spring responde 400 Bad Request antes de ejecutar saludo. En el navegador puedes ver una página HTML de error; otro cliente que solicite JSON puede recibir un objeto con status: 400. Comprueba el estado en Red/Network, sin esperar una apariencia concreta del cuerpo. La consola del servidor también puede indicar que falta nombre.

La petición con ?nombre= permite distinguir ausencia de texto vacío: exigir que el parámetro exista no exige que contenga un nombre válido.

2.2 · Sustituir el método para añadir un valor por defecto

En el mismo archivo SaludoController.java, sustituye únicamente el bloque que empieza en @GetMapping("/saludo") y termina en la llave de cierre del método saludo por este:

@GetMapping("/saludo")
public String saludo(
        @RequestParam(name = "nombre", defaultValue = "mundo") String nombre) {
    return "Hola, " + nombre + ".";
}

Conserva package, los tres imports, @RestController, la declaración public class SaludoController y su última llave. Debe quedar un solo método para GET /saludo. Guarda, detén y arranca de nuevo la aplicación; después repite estas pruebas:

Compara con la versión anterior: la petición sin nombre deja de producir 400 y la petición con nombre= deja de devolver un saludo vacío. defaultValue proporciona "mundo" en ambos casos y hace que el parámetro sea opcional. Este comportamiento está definido en la documentación de RequestParam. Un texto formado por espacios requiere comprobar su contenido; no equivale a enviar nombre=.

@RequestParam(name = "nombre", required = false) String nombre

2.3 · Añadir una consulta con dos parámetros

Ahora añade el siguiente método buscar dentro de SaludoController, debajo del método saludo y antes de la última llave de la clase. Conserva saludo: atienden rutas distintas. Los imports que ya tienes sirven para ambos métodos. En esta práctica reunimos los ejemplos en la misma clase; el paso 4 enseñará a agrupar las rutas por recurso.

@GetMapping("/incidencias")
public String buscar(
        @RequestParam(name = "estado", defaultValue = "todas") String estado,
        @RequestParam(name = "pagina", defaultValue = "1") int pagina) {

    return "Buscando incidencias con estado " + estado
            + ", página " + pagina;
}

Si ya programaste un GET /incidencias en otro controlador, elige cuál conservar antes de arrancar: dos métodos registrados para la misma petición pueden impedir el arranque por un mapeo ambiguo (ambiguous mapping).

Guarda, detén y vuelve a arrancar. Comprueba las tres peticiones:

En la primera petición, & separa los dos parámetros: estado recibe "abierta" y pagina recibe el entero 3. En la última, la conversión falla antes de ejecutar buscar. Un entero negativo sí puede convertirse a int; decidir si es una página admisible requiere una validación adicional.

Al terminar el paso 2: HolaController conserva /hola. SaludoController contiene dos métodos: saludo, con valor por defecto, y buscar, con estado y pagina. Guarda en tu tabla las comprobaciones de ambas versiones del saludo y de la consulta. Estos métodos devuelven texto construido con los parámetros recibidos; todavía no consultan incidencias ni aplican paginación sobre datos reales.

Paso 2-bis · Otros tipos que Spring convierte · 15 min

El paso anterior ha convertido "3" en un int. El mecanismo no se limita a los números: Spring construye el tipo declarado siempre que sepa interpretar el texto recibido. Añade este método a SaludoController, con import java.time.LocalDate; entre los imports.

@GetMapping("/informes")
public String informes(
        @RequestParam(name = "desde") LocalDate desde,
        @RequestParam(name = "activo", defaultValue = "true") boolean activo) {

    return "Desde " + desde + " (día " + desde.getDayOfMonth()
            + " del mes " + desde.getMonthValue() + "), activo=" + activo;
}

Reinicia y comprueba las cuatro peticiones:

Dos observaciones sobre lo que acaba de ocurrir:

• desde.getMonthValue() devuelve 9. Lo que recibe el método no es el texto de la URL, sino un objeto LocalDate con sus operaciones disponibles. La conversión no es un cambio de apariencia.
• El formato que se interpreta por defecto es el de la norma ISO 8601, aaaa-mm-dd. Una fecha escrita como 13-09-2026 produce un 400 por el mismo motivo que pagina=abc: la petición no encaja con lo declarado y se rechaza antes de ejecutar el método. Cuando un cliente imponga otro formato, habrá que declararlo de forma explícita en el parámetro.

Paso 3 · @PathVariable · leer un trozo de la ruta · 20 min

Crea UsuarioController.java con el bloque completo. Las llaves de {id} pertenecen a la anotación Java: en el navegador escribe un valor concreto, como /usuarios/3. El método de rutas anidadas se añade dentro de esa clase, antes de su última llave; conserva los métodos existentes mientras las combinaciones de método y ruta sean distintas. Prueba un número y luego texto para observar la conversión a int.

package com.ejemplo.gestor.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UsuarioController {

    @GetMapping("/usuarios/{id}")
    public String usuario(@PathVariable(name = "id") int id) {
        return "Ficha del usuario " + id;
    }
}

Prueba /usuarios/3, /usuarios/41, /usuarios/999. Un solo método admite esos tres números y devuelve un texto con cada uno. Todavía no consulta una colección, por lo que no comprueba si existe ese usuario.

Las llaves marcan un hueco: {id} no es texto literal, es una variable. Lo que aparezca ahí se captura y se entrega al parámetro que lleva ese mismo nombre.

Puede haber varias, y se anidan con toda naturalidad:

@GetMapping("/proyectos/{proyectoId}/incidencias/{incidenciaId}")
public String incidenciaDeProyecto(
        @PathVariable(name = "proyectoId") int proyectoId,
        @PathVariable(name = "incidenciaId") int incidenciaId) {

    return "Incidencia " + incidenciaId + " del proyecto " + proyectoId;
}

/proyectos/7/incidencias/41 se lee de un vistazo: la incidencia 41, que pertenece al proyecto 7. Esa legibilidad no es casualidad, y es justo lo que vamos a convertir en regla ahora.

Paso 4 · Agrupar rutas con @RequestMapping · 15 min

Sustituye la versión anterior de UsuarioController por la clase que aparece aquí. Hemos movido el prefijo común a @RequestMapping: comprueba que los métodos ya no repiten /usuarios, o la dirección resultante sería /usuarios/usuarios/.... Después de reiniciar, vuelve a probar listado y detalle para comprobar que la agrupación no ha cambiado sus direcciones.

package com.ejemplo.gestor.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/usuarios")
public class UsuarioController {

    @GetMapping
    public String lista(
            @RequestParam(name = "rol", defaultValue = "todos") String rol) {
        return "Lista de usuarios con rol " + rol;
    }

    @GetMapping("/{id}")
    public String detalle(@PathVariable(name = "id") int id) {
        return "Ficha del usuario " + id;
    }
}

La ruta final es la del @RequestMapping de la clase más la del método:

Un @GetMapping sin argumento designa la ruta declarada en la clase, sin segmento adicional.

Paso 5 · Las rutas del gestor · 30 min

Construye el controlador de tu entidad principal siguiendo este orden: crea la clase en controller, anótala con @RestController y @RequestMapping, añade el listado y compruébalo; después añade el detalle y compruébalo; por último incorpora los parámetros opcionales y las rutas anidadas. El controlador ProyectoController de la tabla es el patrón: en reservas sería ReservaController y /reservas. Mantén tus nombres en todos los pasos posteriores. Hoy cada método devuelve una frase con los parámetros, no una lista de registros reales.

Escribe un ProyectoController que atienda estas cuatro:

Condiciones:

1. Usa @RequestMapping a nivel de clase. No repitas /proyectos en cada método.
2. El parámetro estado es opcional, con todos como valor por defecto.
3. El id debe ser un int, no un String. Después comprueba qué pasa con /proyectos/abc y anótalo.

Amplía tu controlador con dos rutas más, decidiendo tú dónde va cada dato:

• Una para consultar una incidencia concreta dentro de un proyecto concreto.
• Una para buscar incidencias filtrando por prioridad y por página.

Para cada una, escribe en un comentario del código la respuesta a esto: qué datos has puesto en la ruta, cuáles en la query string, y qué prueba de la regla has aplicado para decidirlo.

Paso 5-bis · Revisión cruzada del diseño de rutas · 10 min

La regla de esta sesión —lo que identifica al recurso va en la ruta, lo que acota una consulta va en la query string— se verifica cuando alguien ajeno al código interpreta la URL. Intercambia con tu pareja únicamente las URL de las dos rutas que has diseñado, sin mostrar el controlador.

Responde por escrito sobre las que recibas:

1. Qué devuelve cada una, deducido solo de su forma.
2. Qué dato actúa como identificador y cuál como filtro.
3. Si trasladarías alguno al otro sitio, y qué prueba de la regla lo justifica.

Contrastad después las respuestas con el código. Una URL que la otra persona no logra interpretar sin leer el controlador señala un problema de diseño, no de comunicación: dentro de tres semanas su autor estará en la misma situación.

Paso 6 · Comprobar y registrar el resultado del proyecto · 10 min

1. Prueba el saludo con el parámetro ausente, vacío y con un nombre. Con defaultValue="mundo", los dos primeros deben devolver Hola, mundo..
2. Consulta el detalle con 7 y con abc: el primero devuelve el texto que has programado y el segundo produce 400 al no poder convertirse a entero. Un número como 999 todavía no permite saber si existe un registro: esa búsqueda aún no está implementada.

Criterios de diseño de las consultas GET

La regla de la ruta y la query string resuelve dónde colocar cada dato, pero no agota el diseño de una consulta. El método GET tiene un significado fijado por el protocolo, y de ese significado salen los criterios que aplicarás a cada ruta de consulta que escribas durante el curso.

Para qué se usa un GET en una aplicación real

Las pantallas de una aplicación de gestión se sostienen sobre un repertorio corto de consultas. Las cuatro rutas del ProyectoController cubren las tres primeras filas, y la búsqueda por prioridad y página que has añadido en el paso 5 corresponde a las dos últimas.

Las seis comparten una característica que conviene nombrar antes de seguir: ninguna modifica nada.

GET es un método seguro

Método seguro

Un método HTTP es seguro (safe) cuando la petición no solicita ningún cambio en el estado del servidor y se limita a pedir una representación de algo que ya existe. GET, HEAD y OPTIONS son seguros; POST, PUT, PATCH y DELETE no lo son. La definición figura en la RFC 9110, la norma vigente de la semántica de HTTP.

De esa propiedad depende el comportamiento de toda la infraestructura situada entre el cliente y tu servidor.

La URL es el identificador de la consulta

Un GET no lleva cuerpo, de modo que la URL contiene todo lo que determina la respuesta. De ahí se derivan dos prácticas.

La primera: una misma URL debe devolver la misma respuesta mientras los datos no cambien. Una consulta cuyo resultado dependa de un estado oculto, como el orden en que se hayan pedido otras rutas antes, no se puede cachear, ni guardar en marcadores, ni compartir con otra persona, ni reproducir en un informe de error.

La segunda afecta a la privacidad:

Criterios para declarar los parámetros

Tres decisiones se repiten cada vez que escribes la firma de un método de consulta:

• Obligatorio solo lo imprescindible. Un parámetro se declara obligatorio cuando la consulta carece de sentido sin él. Para el resto existe defaultValue, y cada 400 evitable es una petición que el cliente había construido con una intención razonable.
• El mismo concepto recibe el mismo nombre en toda la API. Si la página se llama pagina en un controlador, no puede llamarse page en el siguiente. Quien consume la API aprende ese vocabulario una sola vez y lo aplica a todos los recursos.
• Toda colección acaba necesitando un límite superior. Hoy tus listados devuelven una frase fija y el problema no se manifiesta. Cuando los datos procedan de PostgreSQL en la UD5, un GET /incidencias sin acotar recorrerá la tabla entera; la paginación se introduce en la UD7.

Repasa con esta lista las rutas escritas hoy antes de pasar al cierre.

Ampliación si has completado el trabajo

Primero termina y verifica los pasos anteriores. Estos retos profundizan en el mismo contenido; no sustituyen la entrega ni obligan a iniciar otro proyecto.

Reto · Cuatro peticiones sin ejecutar nada

Con este controlador delante:

@RestController
@RequestMapping("/tareas")
public class TareaController {

    @GetMapping("/{id}")
    public String detalle(
            @PathVariable(name = "id") int id,
            @RequestParam(name = "formato", defaultValue = "corto") String formato) {

        return "Tarea " + id + " en formato " + formato;
    }
}

Predice, antes de probarlo, qué devuelve cada petición: el código de estado y el cuerpo si lo hay. Escribe también por qué.

1. GET /tareas/5
2. GET /tareas/5?formato=largo
3. GET /tareas/cinco
4. GET /tareas
5. POST /tareas/5

Después copia el controlador en tu proyecto y comprueba las cuatro primeras en el navegador. La quinta exige enviar un POST, y la barra de direcciones solo emite GET. Para esa, abre la terminal integrada del editor y lanza una única orden:

curl.exe -i -X POST http://localhost:8080/tareas/5

En PowerShell debe escribirse curl.exe, con su extensión: curl a secas es un alias de Invoke-WebRequest, que no admite -X y produce otra salida. En Linux y macOS basta curl. La opción -i muestra la línea de estado y las cabeceras además del cuerpo, que es justo lo que hay que leer aquí. El cliente HTTP que se instala en la sesión 3 hace esto mismo con una interfaz encima. De las cinco, dos suelen fallarse. Cuando una predicción resulte equivocada, no basta con corregirla: escribe qué regla habías aplicado mal.

Cierre

15 minutos · resultado comprobable y explicación individual

Al terminar la sesión:

Las rutas de listado y detalle devuelven textos que incorporan los parámetros recibidos. Debe ser posible localizar el método que atendió cada petición; la consulta de objetos reales comienza en la sesión 3.

Cada integrante explica una decisión del código apoyándose en una de las comprobaciones realizadas.

Antes de cerrar, sube el trabajo a GitHub. Los controladores de hoy no existen fuera de tu equipo mientras no los publiques, y el historial forma parte de lo que se evalúa en Proyecto Intermodular: una sesión sin rastro en el repositorio no se distingue de una sesión sin trabajo.

git status
git add .
git commit -m "Completar sesión 02: parámetros de ruta y de consulta"
git push

git status antes de confirmar evita subir el trabajo a medias: comprueba que aparecen los controladores escritos hoy y que no aparece target/, que el .gitignore excluye. Si el push es el primero desde otro equipo, Git pedirá de nuevo tus credenciales.