Creación de controladores REST con la anotación @RestController

Bienvenido a la clase donde empezaremos a meternos en la creación de REST API con Spring. Hoy nos centraremos directamente en los controladores REST, que son la base para trabajar con REST API. Si soñabas con hacer tu primera interacción completa cliente-servidor, esta clase es para ti.

¿Qué es un controlador REST en Spring?

Un controlador REST en Spring es un componente que permite manejar solicitudes HTTP (GET, POST, PUT, DELETE, etc.) y devolver datos al cliente en el formato necesario (normalmente JSON). El controlador es el "eslabón" entre el cliente y los componentes del servidor de tu aplicación, como servicios y repositorios.

El punto clave es el uso de la anotación @RestController. Esta le dice automáticamente a Spring que esa clase manejará solicitudes HTTP y devolverá datos en formato JSON u otro tipo (XML, texto, etc.).

Diferencia entre @Controller y @RestController

Para entenderlo mejor, vamos a ver la diferencia entre estas anotaciones:

Si necesitas interactuar con el cliente mediante JSON, por ejemplo para aplicaciones móviles o SPA (Single Page Applications), entonces @RestController es la mejor opción. Elimina el trabajo extra con vistas y te permite centrarte en los datos.

Configuración de un controlador REST básico

Paso 1: Crear una nueva clase de controlador

Vale, vamos a crear un controlador REST básico para manejar solicitudes. Imagina que tenemos la entidad Customer y queremos gestionar los datos de esa entidad.

package com.example.demo.controller;

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

@RestController
@RequestMapping("/api/customers")
public class CustomerController {

    @GetMapping
    public String getAllCustomers() {
        return "¡Aquí estará la lista de clientes!";
    }

}

1. @RestController: Marcamos la clase como controlador REST.
2. @RequestMapping("/api/customers"): Definimos la ruta base (URI) para todas las solicitudes relacionadas con clientes.
3. @GetMapping: Indicamos que el método maneja solicitudes HTTP de tipo GET.
4. Devolver una cadena: Esto es un ejemplo temporal, más adelante reemplazaremos la cadena por objetos reales.

Ahora, si arrancas la aplicación y abres el navegador en http://localhost:8080/api/customers, verás: ¡Aquí estará la lista de clientes!.

Paso 2: Devolver datos en formato JSON

Las REST API suelen devolver datos en formato JSON. En el mundo de Spring esto lo maneja la librería Jackson, que convierte automáticamente objetos Java a JSON y viceversa.

Vamos a modificar nuestro ejemplo para devolver una lista de clientes:

package com.example.demo.controller;

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

import java.util.List;

@RestController
@RequestMapping("/api/customers")
public class CustomerController {

    @GetMapping
    public List<String> getAllCustomers() {
        return List.of("Ivan Ivanov", "Petr Petrov", "Svetlana Smirnova");
    }

}

Ahora, si vuelves a http://localhost:8080/api/customers, obtendrás el siguiente JSON:

[
  "Ivan Ivanov",
  "Petr Petrov",
  "Svetlana Smirnova"
]

¿Qué ha pasado?

• Hemos devuelto una lista de cadenas con los nombres de los clientes.
• Jackson convirtió automáticamente List<String> en un array JSON.

Configuración de rutas usando anotaciones

Anotaciones principales de rutas

Spring ofrece anotaciones cómodas para trabajar con los distintos métodos HTTP:

Ejemplo: trabajar con operaciones CRUD

Vamos a crear un controlador completo para gestionar clientes usando todos los métodos HTTP listados. Para mantenerlo simple por ahora usaremos datos en memoria:

package com.example.demo.controller;

import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

@RestController
@RequestMapping("/api/customers")
public class CustomerController {

    private final List<String> customers = new ArrayList<>(List.of("Ivan Ivanov", "Petr Petrov"));

    @GetMapping
    public List<String> getAllCustomers() {
        return customers;
    }

    @PostMapping
    public String addCustomer(@RequestBody String customer) {
        customers.add(customer);
        return "Cliente añadido: " + customer;
    }

    @PutMapping("/{index}")
    public String updateCustomer(@PathVariable int index, @RequestBody String customer) {
        customers.set(index, customer);
        return "Cliente actualizado: " + customer;
    }

    @DeleteMapping("/{index}")
    public String deleteCustomer(@PathVariable int index) {
        String removed = customers.remove(index);
        return "Cliente eliminado: " + removed;
    }
}

1. Trabajo con métodos HTTP: hemos creado métodos para todas las operaciones CRUD.
2. @RequestBody: lo usamos para obtener datos del cuerpo de la solicitud (por ejemplo, POST o PUT).
3. @PathVariable: extraemos parámetros de la ruta (por ejemplo, el índice del cliente en la lista).

Probar el controlador

Añadir un nuevo cliente:

curl -X POST -H "Content-Type: application/json" -d "Svetlana Smirnova" http://localhost:8080/api/customers

Respuesta:

Cliente añadido: Svetlana Smirnova

Actualizar un cliente:

curl -X PUT -H "Content-Type: application/json" -d "Mikhail Mikhailov" http://localhost:8080/api/customers/0

Respuesta:

Cliente actualizado: Mikhail Mikhailov

Eliminar un cliente:

curl -X DELETE http://localhost:8080/api/customers/1

Respuesta:

Cliente eliminado: Petr Petrov

Ventajas y uso práctico

Hoy has aprendido a crear controladores REST usando @RestController. Esta es una habilidad fundamental para trabajar con REST API. La usarás constantemente, ya sea desarrollando microservicios, un API para una app móvil o una aplicación web completa.

Errores típicos

Uno de los errores más comunes es olvidar añadir @RestController o @ResponseBody. En ese caso Spring no generará respuestas en formato JSON, y el cliente puede recibir un cuerpo vacío o un 404.

También se suele olvidar configurar rutas (URI) correctamente, por lo que las solicitudes no llegan al método correcto. No olvides usar anotaciones de ruta exactas como @GetMapping o @PostMapping.