En la lección anterior diseñamos el contrato: trece endpoints, sus verbos, sus códigos de estado y las reglas de las URLs. Ahora escribimos el código que lo cumple. Un controlador de Spring es una clase engañosamente sencilla —recibe objetos Java y devuelve objetos Java— pero entre la petición HTTP y ese método hay una maquinaria de resolución de argumentos y conversión de mensajes que conviene dominar, porque es la que explica el 90% de los "no me llega el parámetro" y "el JSON no sale como esperaba". En esta lección desmontamos @RestController, aprendemos a extraer cada pieza de una petición (ruta, cadena de consulta, cabeceras, cuerpo), controlamos cómo Jackson serializa nuestros objetos, decidimos cuándo usar ResponseEntity y terminamos con un EstacionController completo, con filtros y paginación, probado desde la terminal y desde el IDE.

1. @RestController: qué es exactamente
2. @RequestMapping y los atajos por verbo
3. @PathVariable: variables de plantilla
4. @RequestParam: parámetros de consulta
5. @RequestBody, @RequestHeader y compañía
6. Serialización JSON con Jackson
7. Configuración global de Jackson en YAML
8. ResponseEntity frente a devolver el objeto
9. El EstacionController completo
10. Probar la API: curl y ficheros .http
11. CORS y @CrossOrigin
12. Errores Comunes y Consejos
13. Ejercicios

Abrimos la anotación, como hicimos con @SpringBootApplication en la lección 02-01:

Dos anotaciones combinadas, nada más:

• @Controller es uno de los cinco estereotipos de 02-01: un @Component especializado que además hace que RequestMappingHandlerMapping inspeccione la clase buscando métodos con @RequestMapping.
• @ResponseBody cambia la interpretación del valor devuelto. Sin ella, un método que devuelve el String "estaciones" se interpreta como el nombre de una vista y Spring busca una plantilla estaciones.html. Con ella, ese String es el cuerpo de la respuesta.

Un error frecuentísimo en quien empieza es anotar con @Controller un controlador de API y encontrarse con un error de resolución de vista o un 404 críptico. Si la respuesta debe ser JSON, es @RestController.

@RequestMapping es la anotación base de mapeo. Sus atributos:

Desde Spring 4.3 existen atajos que fijan method: @GetMapping, @PostMapping, @PutMapping, @PatchMapping, @DeleteMapping. @GetMapping("/{id}") es idéntico a @RequestMapping(path = "/{id}", method = RequestMethod.GET), y siempre preferible por legibilidad.

El patrón habitual combina @RequestMapping a nivel de clase —que fija el prefijo común— con los atajos a nivel de método:

Concentrar el prefijo en un solo sitio evita repetirlo en cada método y hace trivial cambiar la versión de la API. Sobre produces y consumes: no son obligatorios —Spring Boot ya negocia JSON por defecto— pero declararlos hace el contrato visible en el código, produce respuestas correctas (415, 406) en lugar de errores confusos, y springdoc los usa para generar la documentación (03-07).

Una variable de plantilla es un segmento de la ruta que actúa como parámetro. Se declara entre llaves y se captura con @PathVariable.

Spring extrae el segmento, lo convierte al tipo declarado usando su ConversionService y lo pasa como argumento. La conversión funciona con Long, int, UUID, LocalDate, enums y cualquier tipo para el que exista un conversor.

El nombre debe coincidir. Si el parámetro Java se llama distinto que la plantilla, hay que decirlo: @GetMapping("/{idEstacion}") con @PathVariable("idEstacion") Long id. Cuando coinciden, el nombre puede omitirse solo si el código se compila con información de parámetros. Los proyectos generados por Spring Initializr lo hacen (el spring-boot-maven-plugin añade -parameters), pero si alguna vez ves un IllegalArgumentException: Name for argument of type [java.lang.Long] not specified, la causa es esa. Escribir el nombre siempre es una costumbre barata y robusta.

Una ruta puede tener varias variables (@GetMapping("/{idEstacion}/bicicletas/{idBicicleta}")), y una variable puede ser opcional declarándola como @PathVariable Optional<Integer> anio y registrando dos patrones en la misma anotación: @GetMapping({"/estadisticas", "/estadisticas/{anio}"}).

Patrones y expresiones regulares. La sintaxis {nombre:regex} restringe qué valores captura el segmento. Es muy útil para desambiguar rutas:

Sin las expresiones regulares, /estaciones/RIB-001 intentaría convertirse a Long y fallaría con un error de tipo. Con ellas, cada ruta va a su método. Los comodines de rutas de Spring:

Cuando varios patrones encajan, Spring elige el más específico: un patrón literal gana a uno con variable, y este gana a uno con comodín.

Los parámetros de la cadena de consulta —lo que va tras el ?— se capturan con @RequestParam.

Por defecto son obligatorios: si falta, Spring responde 400 Bad Request con MissingServletRequestParameterException. Las tres formas de hacerlo opcional:

Un error clásico: @RequestParam(required = false) int capacidad con el tipo primitivo. Si el parámetro falta, Spring intenta asignar null a un int y lanza una excepción. Con required = false, el tipo debe ser siempre un envoltorio.

Listas y valores múltiples. @RequestParam List<Long> ids acepta las dos convenciones habituales: ?ids=1,2,3 y ?ids=1&ids=2&ids=3. También puedes recibir todos los parámetros de golpe con @RequestParam Map<String, String> filtros, pero pierdes el tipado, la validación automática y la documentación OpenAPI: úsalo solo si los parámetros son genuinamente dinámicos.

Agrupar parámetros en un objeto. Cuando un endpoint tiene cinco o seis parámetros, la firma se vuelve ilegible. Spring permite enlazarlos a un objeto sin ninguna anotación:

Spring usa el enlace de datos estándar (nombre del parámetro → componente del record). Es más limpio, se valida con @Valid (03-04) y se documenta bien. Lo usaremos en el ejercicio 2.

@RequestBody toma el cuerpo de la petición y lo deserializa al tipo declarado usando el HttpMessageConverter adecuado según el Content-Type; para application/json, ese conversor es Jackson. Se escribe public Estacion crear(@RequestBody Estacion estacion). Solo puede haber un @RequestBody por método: el cuerpo es uno. Si falta o el JSON está mal formado, se lanza HttpMessageNotReadableException, que traduciremos a una respuesta decente en 03-06. La implementación completa de la creación es el tema de la lección siguiente.

@RequestHeader captura cabeceras, con la misma semántica de defaultValue y required. También admite recibirlas todas: @RequestHeader HttpHeaders cabeceras.

En CicloUrbana lo usaremos para el idioma de los mensajes de error (03-04) y para el If-Match del control de concurrencia (03-03).

@MatrixVariable captura pares clave-valor dentro de un segmento de ruta, separados por punto y coma: /api/v1/estaciones/1;zona=centro. Forma parte del RFC 3986 y Spring la soporta, pero está deshabilitada por defecto y hay que activarla configurando UrlPathHelper. Se menciona por completitud: CicloUrbana no la usa, porque esos mismos datos van mejor en la cadena de consulta.

Además de las anotaciones, un método puede declarar tipos que Spring inyecta directamente: HttpServletRequest, Locale, UriComponentsBuilder, Principal (módulo 5). Acoplan el controlador a la API de servlets, así que conviene reservarlos para cuando no haya alternativa.

Cuando un método de @RestController devuelve un objeto, MappingJackson2HttpMessageConverter lo convierte a JSON. Con un record de Java el proceso es directo: cada componente del record se convierte en una propiedad JSON con el mismo nombre.

Nuestro record Estacion(Long id, String nombre, String direccion, int capacidad, double latitud, double longitud) se convierte, sin ninguna anotación, en:

Jackson soporta record de forma nativa desde la versión 2.12: usa el constructor canónico para deserializar y los accesores para serializar. No hacen falta getters, ni constructor vacío, ni @JsonCreator. Esta es una de las razones por las que el curso usa record para todo lo que viaja por la API.

Las anotaciones de Jackson que usaremos:

Un ejemplo completo aplicado a la representación de una bicicleta, que introduciremos formalmente en la próxima lección:

Punto por punto:

• @JsonInclude(NON_NULL) a nivel de tipo: si estacionId es null porque la bicicleta está en uso, la propiedad no aparece en el JSON. Ojo: obliga al cliente a distinguir ausencia de null, un matiz que retomaremos con PATCH en 03-03.
• @JsonProperty("bateria"): el campo Java sigue el estilo español del proyecto y el JSON expone el nombre acordado con el equipo de la app. Desacoplar ambos nombres permite renombrar en Java sin romper el contrato.
• @JsonFormat: el shape = STRING evita que la fecha se emita como array de números, que es el comportamiento de Jackson sin el módulo JSR-310.
• @JsonIgnore: codigoAnclajeInterno es información operativa de Ribalta que no debe salir al exterior. Aquí asoma un problema serio: el modelo interno contiene datos que la API no debe exponer. Anotar campos con @JsonIgnore funciona a pequeña escala y se convierte en una fuente de fugas en cuanto el modelo crece. La solución estructural son los DTOs (03-05).

Anotar campo a campo no escala. Spring Boot expone la configuración global de Jackson bajo spring.jackson.*, y esa es la forma correcta de fijar políticas de todo el proyecto.

Las decisiones importantes de esta configuración:

• write-dates-as-timestamps: false es probablemente la propiedad de Jackson más relevante de un proyecto. Sin ella, un Instant se serializa como 1756645500.000000000: ilegible y frágil. Spring Boot ya la pone a false, pero conviene declararla. Requiere jackson-datatype-jsr310, que spring-boot-starter-web incluye y Spring Boot registra solo.
• default-property-inclusion: non_null aplica a toda la aplicación lo que @JsonInclude hacía a una clase, y evita repetir la anotación en cada DTO.
• fail-on-unknown-properties: false (valor por defecto) es una decisión de compatibilidad: si un cliente antiguo envía un campo retirado, la petición no falla. Es justamente el comportamiento que en 03-01 hacía compatible añadir y retirar campos.
• fail-on-null-for-primitives: true sí cambia el valor por defecto. Sin él, {"capacidad": null} se convierte silenciosamente en capacidad = 0, y una estación con capacidad cero es un error de datos difícil de rastrear. Mejor un 400 inmediato.

Si necesitas algo que las propiedades no cubren, personaliza con un Jackson2ObjectMapperBuilderCustomizer en com.ciclourbana.comun:

El detalle se deduce de lo aprendido sobre @ConditionalOnMissingBean: si declaras un bean ObjectMapper propio, JacksonAutoConfiguration se aparta y pierdes de golpe todas las propiedades spring.jackson.*, el módulo de fechas y los conversores registrados. Personaliza siempre con el customizer, no reemplazando el ObjectMapper.

Un método puede devolver el objeto directamente o envolverlo en un ResponseEntity<T>, que representa la respuesta HTTP completa: estado, cabeceras y cuerpo.

La política de CicloUrbana para todo el módulo: devolver el objeto directamente cuando el caso de éxito es único y el estado es 200 (todos los GET de listado); usar ResponseEntity cuando la respuesta necesita una cabecera (Location en los POST, ETag en las condicionales) o cuando el estado varía; y no usar ResponseEntity para devolver errores. Esto último es clave y aún no es evidente: escribir ResponseEntity.notFound() en cada método esparce la lógica de error por todos los controladores. Desde 03-06 lanzaremos RecursoNoEncontradoException y un manejador global la convertirá en un 404 bien formado. En esta lección todavía usamos ResponseEntity para el 404, con un TODO para no olvidarlo.

Formas útiles de construir un ResponseEntity:

Existe además @ResponseStatus sobre el método, que fija el código de éxito sin ResponseEntity; lo aplicaremos a los POST en la lección siguiente.

Reunimos todo. Primero ampliamos EstacionService (paquete com.ciclourbana.estaciones) con los métodos que el controlador necesita:

Y ahora el controlador:

Detalles que merecen comentario:

• @GetMapping("/{id:\\d+}"): la restricción a dígitos evita que /api/v1/estaciones/resumen, si algún día lo añadimos, intente convertirse a Long.
• Los límites de paginación en el controlador son provisionales y feos a propósito: 03-04 los sustituye por @Min(0) y @Max(100), y el contraste hace evidente qué aporta la validación declarativa.
• El logging usa el patrón de sustitución de SLF4J ({}), no concatenación: con concat, el String se construye aunque DEBUG esté desactivado. Y el 404 va a log.info, no a log.error: es información operativa, no un fallo del sistema (se detalla en 03-06).

Arrancamos con ./mvnw spring-boot:run y CargadorEstacionesDemo deja las cuatro estaciones de Ribalta en el repositorio en memoria.

Con curl, la herramienta universal:

La última llamada devuelve HTTP/1.1 404 con Content-Length: 0. Y el filtro por capacidad mínima 24:

Aparecen ordenadas por nombre, como impone el Comparator del servicio; "Estación Norte" (30), "Plaza Mayor" (24) y "Universidad" (36) superan el filtro, pero con tamanio=2 solo llegan las dos primeras.

Para el trabajo diario es más cómodo un fichero .http en src/test/http/estaciones.http, que IntelliJ IDEA y la extensión REST Client de VS Code ejecutan directamente. Se versiona con el código, así que la API queda documentada y probable desde el propio repositorio:

La última petición es interesante. Spring intenta convertir "mucho" a Integer, falla y lanza MethodArgumentTypeMismatchException, que se traduce en un 400 Bad Request con una respuesta por defecto poco informativa. Guárdala en el fichero: la mejoraremos en 03-06.

Los navegadores aplican la política del mismo origen: una página servida desde https://panel.ribalta.es no puede llamar por JavaScript a https://api.ciclourbana.es salvo que el servidor lo autorice. Ese permiso es CORS (Cross-Origin Resource Sharing). El mecanismo, en corto: antes de una petición "no simple" (con Content-Type: application/json, o con verbo PUT/DELETE, o con cabeceras propias), el navegador envía un preflight y el servidor debe autorizarlo:

Dos aclaraciones que ahorran horas de depuración:

• CORS es cosa del navegador. curl, Postman y las apps móviles nativas lo ignoran por completo. Si tu curl funciona y el frontend no, es CORS.
• CORS no es seguridad del servidor. No protege la API de nadie: solo impide que el navegador entregue la respuesta a un script de otro origen. La protección real es la autenticación (módulo 5).

En Spring, la forma rápida es @CrossOrigin(origins = "https://panel.ribalta.es") sobre la clase o el método. Y la forma correcta para un proyecto, centralizada en com.ciclourbana.comun:

exposedHeaders merece atención: por defecto, el JavaScript del navegador solo puede leer un puñado de cabeceras de la respuesta. Si el frontend necesita el Location de un POST o el ETag para una petición condicional, hay que exponerlas aquí explícitamente.

Nunca uses allowedOrigins("*") junto con credenciales: la especificación lo prohíbe y Spring lanzará un error de configuración. El endurecimiento de CORS junto con Spring Security se retoma en la lección 05-05.

Usar @Controller en lugar de @RestController. El método devuelve "Plaza Mayor" y Spring busca una plantilla con ese nombre: error de resolución de vista o un 404 desconcertante.

@RequestParam(required = false) con un tipo primitivo. int no admite null. Usa Integer, Optional<Integer> o, mejor, defaultValue.

Olvidar el nombre en @PathVariable. Si el proyecto se compila sin -parameters, falla en tiempo de ejecución con un mensaje sobre el nombre del argumento. Escríbelo siempre.

Rutas ambiguas. @GetMapping("/{id}") con id de tipo Long y una llamada a /estaciones/abc produce un 400 confuso. La restricción {id:\\d+} lo evita.

Definir un bean ObjectMapper propio. Anula JacksonAutoConfiguration y con ella todas las propiedades spring.jackson.* y el módulo de fechas. Usa Jackson2ObjectMapperBuilderCustomizer. Síntoma relacionado: si ves fechas como [2026,8,31,14,5] o 1756645500.000000000, falta write-dates-as-timestamps: false o el módulo JSR-310.

Poner lógica de negocio en el controlador. El controlador traduce HTTP a llamadas Java y nada más. Si aparece un if sobre reglas del negocio de Ribalta, ese código pertenece a EstacionService. La prueba: cuando llegue un consumidor de mensajes, ¿podría reutilizar la lógica sin pasar por HTTP?

Consejo: un controlador por agregado. EstacionController, BicicletaController, AlquilerController. No un ApiController con veinte métodos.

Consejo: guarda las peticiones en un .http versionado. Cada caso raro que descubras —un tipo incorrecto, un filtro vacío— añádelo. Ese fichero es documentación viva y el borrador de las pruebas de integración del módulo 6.

Añade a EstacionController el endpoint GET /api/v1/estaciones/cercanas?lat=41.38&lon=2.17&radioMetros=800, que devuelve las estaciones dentro del radio indicado, ordenadas por distancia. radioMetros es opcional con valor por defecto 500; lat y lon son obligatorios. Implementa el cálculo en EstacionService y asegúrate de que la ruta no entre en conflicto con /{id}.

La firma de listar ya tiene cuatro parámetros y crecerá. Refactorízala para (a) agrupar los filtros en un record FiltroEstaciones y (b) devolver, además de la lista, el total de elementos y el número de páginas, usando cabeceras HTTP en lugar de envolver el cuerpo.

El equipo de la app móvil de Ribalta pide tres cambios en la respuesta de estación:

1. Que capacidad se llame capacidadTotal en el JSON, sin renombrar el campo Java.
2. Que se añada un campo coordenadas con el formato "41.3851,2.1734" y que latitud y longitud dejen de aparecer por separado.
3. Que las propiedades salgan siempre en el orden id, nombre, capacidadTotal, coordenadas, direccion.

Resuélvelo solo con anotaciones de Jackson y explica por qué esta solución no escala.

Solución 1.

En EstacionService:

En el controlador:

Sobre el conflicto de rutas. /cercanas es un patrón literal y /{id} uno con variable; Spring da prioridad al literal, así que no hay ambigüedad. Aun así, la restricción {id:\\d+} hace la intención explícita y protege de descuidos futuros.

Nota de diseño. Si faltan lat o lon, Spring responde 400 automáticamente. Pero una latitud de 200 grados pasaría sin problema, y radioMetros=-50 también. Es exactamente el hueco que cubre la lección 03-04 con @DecimalMin/@DecimalMax y @Positive.

Solución 2.

El record de filtros, en com.ciclourbana.estaciones:

El constructor compacto de un record es el sitio ideal para normalizar: se ejecuta siempre, venga el objeto de donde venga, y el resultado es inmutable.

El controlador:

Spring enlaza los parámetros de consulta al record sin ninguna anotación, por coincidencia de nombres: la petición sigue siendo ?nombre=norte&pagina=0&tamanio=10.

Por qué cabeceras y no un cuerpo envolvente. Ambas son legítimas. Las cabeceras mantienen el cuerpo como un array puro de estaciones, que es lo que el recurso "colección" representa; es la elección de GitHub. La alternativa —{"contenido": [...], "totalElementos": 42}— es la que produce Spring Data con Page<T> y la que adoptaremos en el módulo 4, porque llega gratis. Advertencia: si eliges cabeceras, decláralas en exposedHeaders de la configuración CORS, o el JavaScript del navegador no podrá leerlas.

Solución 3.

Resultado:

Por qué esta solución no escala, que es el fondo del ejercicio:

1. Contamina el dominio con el contrato. Estacion es el modelo interno y ahora carga con las preferencias de formato de la app móvil. Si mañana el portal de datos abiertos del ayuntamiento pide latitud y longitud separadas, no hay forma de satisfacer a ambos con una sola clase.
2. @JsonIgnore es una lista de exclusiones, y las listas de exclusiones fallan por omisión. El día que se añada un campo codigoAcceso al record y nadie recuerde anotarlo, se publica sin querer. Una lista de inclusiones —un DTO que enumera lo que sí sale— falla al revés: como mucho olvidas exponer algo, y eso se detecta al instante.
3. Rompe el módulo 4. Cuando Estacion sea una entidad JPA con relaciones perezosas, serializarla directamente provocará LazyInitializationException o consultas en cascada inesperadas.

Todo esto se resuelve con un EstacionResponse distinto de Estacion: el contenido de la lección 03-05.

Ya sabes escribir controladores REST de verdad. Has visto que @RestController no es más que @Controller + @ResponseBody, y por qué confundirlos produce errores de vista incomprensibles. Dominas el mapeo de rutas con @RequestMapping a nivel de clase y los atajos por verbo, incluidas las restricciones con expresiones regulares que evitan rutas ambiguas. Sabes extraer cada parte de una petición —@PathVariable, @RequestParam con obligatoriedad, valores por defecto, listas y objetos de filtro, @RequestBody, @RequestHeader— y conoces las trampas de cada uno, empezando por el required = false sobre un primitivo. Controlas cómo Jackson convierte un record en JSON, campo a campo con @JsonProperty, @JsonIgnore, @JsonFormat y @JsonInclude, y globalmente desde spring.jackson.*, con la regla de oro de personalizar siempre con un Jackson2ObjectMapperBuilderCustomizer en lugar de reemplazar el ObjectMapper. Tienes criterio para decidir entre devolver el objeto y envolverlo en un ResponseEntity. Y entiendes qué es CORS, por qué no es un mecanismo de seguridad y cómo configurarlo de forma centralizada.

Sobre todo, CicloUrbana ya tiene un EstacionController que se parece a uno real: listado con filtro por nombre y por capacidad, paginación, consulta por identificador con su 404, logging con niveles apropiados, y un fichero .http versionado con los casos de prueba, incluidos los que todavía responden mal. El ejercicio 3 ha dejado señalada, con nombre y apellidos, la deuda técnica que arrastramos: estamos exponiendo la clase de dominio directamente.

La lección 03-03, Manejo de Métodos HTTP, completa el CRUD. Implementaremos POST con su 201 Created y la cabecera Location construida con ServletUriComponentsBuilder, PUT como reemplazo total, PATCH con el problema —más sutil de lo que parece— de distinguir un campo ausente de un campo puesto a nulo, y DELETE con su idempotencia. Añadiremos el recurso bicicleta y el subrecurso /estaciones/{id}/bicicletas, modelaremos las acciones que no encajan en el CRUD puro (POST /api/v1/alquileres/{id}/finalizar) sin romper el diseño REST, y resolveremos el problema de las actualizaciones perdidas con ETag e If-Match. La API de Ribalta deja de ser de solo lectura.