Construye tu primera API REST con Java y Spring Boot

La aplicación se ejecutará exclusivamente en tu ordenador. Necesitas un JDK, no solo un runtime: el JDK incorpora el compilador y las herramientas que Maven utiliza. Este proyecto fija Java 25 y Spring Boot 4.1.0; el campus PHP nunca compila ni ejecuta el código que escribas.

Comprobación mínima

Instala una distribución OpenJDK 25 de un proveedor de confianza. Abre una terminal nueva y ejecuta java -version y javac -version. Ambas salidas deben comenzar por 25. Si no coinciden, revisa JAVA_HOME y el orden de PATH antes de cambiar el proyecto.

Wrapper reproducible

El repositorio incluye mvnw, mvnw.cmd y .mvn/wrapper/maven-wrapper.properties. Es la modalidad oficial only-script: en la primera ejecución descarga Maven 3.9.16 y posteriormente reutiliza esa distribución. En macOS o Linux usa ./mvnw -version; en Windows PowerShell usa .\mvnw.cmd -version.

Lectura de la estructura

src/main/java contiene código de producción, src/main/resources configuración, src/test/java pruebas y pom.xml el modelo de build. El IDE importa el POM, pero la terminal es la referencia reproducible.

HTTP es el protocolo de intercambio. REST es un estilo para organizar recursos y aprovechar la semántica de HTTP; no significa que cualquier JSON sobre una URL sea REST.

Anatomía de una interacción

Una petición contiene método, URI, cabeceras y, a veces, cuerpo. Una respuesta contiene un estado, cabeceras y una representación. En GET /api/v1/tareas, el cliente pide una colección. En POST /api/v1/tareas, solicita crear un elemento a partir del JSON enviado.

Semántica que importa

GET es seguro: no pretende modificar estado. También es idempotente: repetirlo mantiene el mismo efecto, aunque los datos puedan cambiar entre lecturas. POST no es idempotente por definición; dos envíos pueden crear dos recursos. Una creación correcta devuelve 201 y una cabecera Location. Un JSON inválido pertenece al grupo 400; una ruta inexistente no debe disfrazarse como 200.

Contrato del ejercicio

GET /api/v1/tareas          -> 200 + lista JSON
GET /api/v1/tareas/{id}     -> 200 o 404
POST /api/v1/tareas         -> 201 + tarea + Location
POST con título vacío       -> 400 + problem+json

La versión v1 forma parte de la ruta para hacer visible el contrato. No resuelve por sí sola una estrategia de evolución, pero evita cambiar silenciosamente a los consumidores.

El proyecto ya contiene una base para evitar depender de un generador web. El padre spring-boot-starter-parent:4.1.0 gestiona versiones compatibles. spring-boot-starter-webmvc incorpora Spring MVC y el servidor; spring-boot-starter-validation incorpora Jakarta Validation.

Clase principal y paquetes

PrimeraApiApplication está en el paquete raíz com.kintavor.primeraapi. @SpringBootApplication activa configuración, autoconfiguración y escaneo descendente. Si mueves la clase fuera del paquete raíz, Spring puede dejar de descubrir controllers y servicios.

Primer arranque

Ejecuta ./mvnw spring-boot:run o .\mvnw.cmd spring-boot:run. Busca el puerto 8080 y un arranque sin excepciones. Detén con Ctrl+C; no cierres la terminal a la fuerza si puedes permitir un cierre ordenado.

Qué hace la autoconfiguración

Boot observa clases y configuración disponibles y crea infraestructura razonable. No genera tus reglas de negocio. Si el puerto está ocupado, utiliza temporalmente --spring-boot.run.arguments=--server.port=8081; no mates procesos desconocidos.

Ejecuta ./mvnw test antes y después de cada paso. Una compilación verde no demuestra que el contrato HTTP sea correcto, pero elimina una categoría de fallos.

El controller traduce HTTP; no debe convertirse en almacén ni en regla de negocio. TareaService conserva temporalmente las tareas en memoria y TareaResponse define qué se publica.

Ruta y respuesta

@GetMapping
List<TareaResponse> listar() {
  return service.listar().stream().map(TareaResponse::from).toList();
}

La anotación de clase aporta /api/v1/tareas. Como la operación termina normalmente, Spring serializa la lista y responde 200 con JSON. Un record es apropiado para un DTO pequeño porque declara sus componentes sin setters.

Separar modelos

Tarea representa el dato interno. TareaResponse representa el contrato exterior. Aunque ahora tengan campos parecidos, separarlos evita que un cambio interno publique accidentalmente información nueva.

Prueba manual

Con la aplicación arrancada ejecuta curl -i http://localhost:8080/api/v1/tareas. Comprueba el estado, Content-Type y que la respuesta sea un array. En Windows puedes usar Invoke-RestMethod. Guarda la petición exacta en tu cuaderno: una captura sin orden no es suficiente para reproducir el resultado.

POST recibe una intención de creación. @RequestBody convierte el JSON a CrearTareaRequest; el servicio asigna identidad y el controller devuelve la representación creada.

Implementación

@PostMapping
ResponseEntity<TareaResponse> crear(
    @Valid @RequestBody CrearTareaRequest request,
    UriComponentsBuilder uris) {
  Tarea creada = service.crear(request.titulo(), request.descripcion());
  URI location = uris.path("/api/v1/tareas/{id}")
      .buildAndExpand(creada.id()).toUri();
  return ResponseEntity.created(location).body(TareaResponse.from(creada));
}

El identificador se asigna en servidor; aceptar un id arbitrario del cliente abriría colisiones y reglas ambiguas. La cabecera Location señala el recurso creado y el cuerpo evita obligar al cliente a realizar otra petición para conocerlo.

Prueba manual

curl -i -X POST http://localhost:8080/api/v1/tareas \
  -H 'Content-Type: application/json' \
  -d '{"titulo":"Leer sobre HTTP","descripcion":"Anotar estados"}'

Repite el envío conscientemente: se crean dos recursos porque no hemos diseñado idempotencia. Esto no es un error del framework, sino una propiedad que un caso de negocio real debe decidir.

Validar evita que datos imposibles entren en la aplicación. El DTO declara forma y tamaño; el servicio normaliza; un manejador global convierte excepciones conocidas en respuestas uniformes.

Restricciones de entrada

public record CrearTareaRequest(
  @NotBlank @Size(max = 80) String titulo,
  @Size(max = 300) String descripcion
) {}

@Valid activa estas restricciones al recibir el cuerpo. Un título compuesto solo por espacios falla. El límite de tamaño protege contrato y recursos, aunque una API real también limitaría el cuerpo total en el servidor.

Problem Details

@RestControllerAdvice transforma MethodArgumentNotValidException en estado 400 y añade errores por campo. La respuesta exterior no contiene stack trace. TareaNoEncontradaException se traduce a 404: la petición era válida, pero el recurso no existe.

Dos niveles

Jakarta Validation comprueba forma en la frontera. Las invariantes que deben cumplirse aun sin HTTP pertenecen al dominio o servicio. Copiar la misma regla en todos los controllers produce inconsistencias.

Prueba un título vacío, uno de 81 caracteres y un id inexistente. Los tres fallos deben ser previsibles y no deben detener el proceso.

Una comprobación manual ayuda a explorar; una prueba automatizada conserva el contrato. La solución usa MockMvc para atravesar routing, JSON, validación y controller sin abrir un puerto, y una prueba unitaria para el servicio en memoria.

Ciclo de verificación

1. Predice el resultado y ejecuta ./mvnw test.
2. Lee el primer fallo, no la última línea.
3. Reduce el cambio y vuelve a ejecutar una prueba concreta.
4. Ejecuta la suite completa antes de cerrar.

Una aserción útil comprueba el estado y datos importantes. Comprobar únicamente que existe una respuesta permitiría errores silenciosos. La prueba de validación demuestra también que el servicio no acepta un cuerpo sin título.

Lo que esta demo no pretende resolver

Los datos desaparecen al reiniciar. No hay PostgreSQL, autenticación, roles, transacciones, paginación, OpenAPI ni despliegue. Esta limitación es deliberada: primero se comprende el flujo HTTP completo y después se sustituye el almacén sin deformar el contrato.

Cierre

Completa los cinco ejercicios, realiza el diagnóstico y compara tu versión con solution.zip solo después de registrar tus decisiones. La solución es una referencia, no la única implementación válida.