De Cero a API: Crea tu Controller REST en Spring Boot (Paso a Paso)

 Aprende a crear tu primer Controller API REST en Spring Boot. Te enseñamos a usar DTOs con Records, @RestController y @GetMapping para servir datos reales.

¡Felicidades! En la guía anterior, encendimos el motor de nuestro microservicio con un endpoint de status. Ahora, es momento de pisar el acelerador y darle una utilidad real: servir datos.

En este tutorial, vamos a construir el corazón de cualquier API: el Controller. Aprenderás a definir "contratos" de datos limpios usando DTOs, a manejar peticiones de clientes y a crear endpoints que devuelvan información útil en formato JSON.

Pasaremos de tener un simple "hola mundo" a una API REST funcional que puede listar y buscar usuarios. ¡Vamos a construir algo increíble!

Paso 1: El Plano de Nuestros Datos (Creando el DTO)

Antes de construir, un buen ingeniero diseña el plano. En el mundo de las APIs, este plano se llama DTO (Data Transfer Object). Un DTO define exactamente qué campos y qué estructura de datos vamos a enviar o recibir. Esto es crucial para la seguridad y la claridad, ya que nos permite exponer solo la información que queremos, sin revelar detalles internos de nuestra base de datos.

Para esta tarea, usaremos una de las características más elegantes de Java moderno: los Records.

Organización primero: En tu proyecto, dentro de la estructura src/main/java/com/tublog/serviciousuarios, crea un nuevo paquete (click derecho -> New -> Package) y nómbralo dto. Mantener los DTOs en su propio paquete es una práctica estándar de la industria.

Crea el Record: Dentro del paquete dto, crea un nuevo archivo Java. Al crearlo, en lugar de Class, selecciona Record si tu IDE te da la opción. Nómbralo UsuarioDTO.java.

Define el Contrato: Abre el archivo y añade el siguiente código.

¡Listo! Con una sola línea hemos definido un "contrato" de datos robusto, inmutable y limpio. Cualquier dato de usuario que viaje a través de nuestra API tendrá esta forma.

Paso 2: El Cerebro de la API (Configurando el Controller)

Ahora que tenemos el plano, construyamos el componente que interactúa con el mundo exterior: el UsuarioController. Este será el cerebro que escucha las peticiones y decide qué información devolver.

• Organización: De vuelta en src/main/java/com/tublog/serviciousuarios, crea otra clase nueva llamada UsuarioController, si no lo hiciste en la guía anterior.
• Anotaciones Clave: Añade dos anotaciones justo encima de la declaración de la clase.

Con estas dos anotaciones, le hemos dicho a Spring Boot: "Esta clase es un cerebro de API REST, y todas las rutas que maneja comenzarán con /api/usuarios".

Nuestro trabajo está hecho. Como tenemos Spring Boot DevTools instalado, cada vez que guardaste los archivos, el servidor se reinició automáticamente. ¡Es hora de probar!

Abre tu navegador o, mejor aún, una herramienta de cliente API como Postman o Insomnia.

Prueba 1: Obtener todos los usuarios

• Método: GET
• URL: http://localhost:8080/api/usuarios
• Resultado esperado: Deberías ver una lista en formato JSON con los tres pioneros de la informática que definimos.

Prueba 2: Obtener un usuario específico

• Método: GET
• URL: http://localhost:8080/api/usuarios/2
• Resultado esperado: Deberías ver un único objeto JSON con los datos de Ada Lovelace.

Misión Cumplida y Próximos Pasos

¡Excelente trabajo! 👏 Ya no tienes solo un servicio que dice "estoy vivo", sino una API REST funcional que sigue las mejores prácticas de la industria, con una estructura limpia y endpoints que sirven datos.

Has aprendido a:

• Definir contratos de datos con DTOs y Records.
• Estructurar tu código en paquetes (dto, controller).
• Crear un Controller con rutas base.
• Implementar endpoints con @GetMapping y capturar variables de la URL con @PathVariable.