Spring REST

El desarrollo de APIs REST representa uno de los pilares fundamentales de las aplicaciones web modernas. Spring Boot proporciona un conjunto de herramientas que simplifican enormemente la creación de servicios web RESTful, permitiendo a los desarrolladores centrarse en la lógica de negocio en lugar de la configuración compleja.

REST (Representational State Transfer) es un estilo arquitectónico que define cómo los sistemas distribuidos pueden comunicarse a través de HTTP. En el contexto de Spring Boot, esto se traduce en la capacidad de crear endpoints que respondan a peticiones HTTP y devuelvan datos en formato JSON de manera eficiente y escalable.

Fundamentos de REST en Spring Boot

Spring Boot integra Spring MVC de forma automática, proporcionando todas las funcionalidades necesarias para crear controladores REST sin configuración adicional. El framework maneja automáticamente la serialización y deserialización de objetos Java a JSON, la gestión de códigos de estado HTTP y el enrutamiento de peticiones.

Los controladores REST en Spring Boot se definen mediante anotaciones que indican al framework cómo debe procesar las peticiones entrantes. Estas anotaciones permiten mapear URLs específicas a métodos Java, definir qué tipos de peticiones HTTP acepta cada endpoint y especificar el formato de los datos de respuesta.

@RestController
@RequestMapping("/api/usuarios")
public class UsuarioController {
    
    @GetMapping
    public List<Usuario> obtenerUsuarios() {
        return Arrays.asList(
            new Usuario("Juan", "juan@email.com"),
            new Usuario("María", "maria@email.com")
        );
    }
}

Anotaciones principales para REST

La anotación @RestController combina @Controller y @ResponseBody, indicando que todos los métodos del controlador devuelven datos directamente en el cuerpo de la respuesta HTTP, típicamente en formato JSON. Esta anotación elimina la necesidad de anotar cada método individualmente.

@RequestMapping define la ruta base para todos los endpoints del controlador. Esta anotación puede especificar tanto la URL como el método HTTP, aunque es más común usar las anotaciones específicas para cada verbo HTTP.

@RestController
@RequestMapping("/api/productos")
public class ProductoController {
    
    @GetMapping("/{id}")
    public Producto obtenerProducto(@PathVariable Long id) {
        return new Producto(id, "Laptop", 999.99);
    }
    
    @PostMapping
    public Producto crearProducto(@RequestBody Producto producto) {
        // Lógica para guardar el producto
        return producto;
    }
}

Verbos HTTP y mapeo de endpoints

Cada verbo HTTP tiene un propósito específico en REST. Spring Boot proporciona anotaciones dedicadas que hacen explícita la intención de cada endpoint y mejoran la legibilidad del código.

@GetMapping se utiliza para operaciones de lectura que no modifican el estado del servidor. Estos endpoints deben ser idempotentes, es decir, llamarlos múltiples veces produce el mismo resultado.

@PostMapping maneja la creación de nuevos recursos. Típicamente recibe datos en el cuerpo de la petición y devuelve el recurso creado junto con un código de estado 201 (Created).

@RestController
@RequestMapping("/api/tareas")
public class TareaController {
    
    @GetMapping
    public List<Tarea> listarTareas() {
        return tareaService.obtenerTodas();
    }
    
    @PostMapping
    public ResponseEntity<Tarea> crearTarea(@RequestBody Tarea tarea) {
        Tarea nuevaTarea = tareaService.crear(tarea);
        return ResponseEntity.status(HttpStatus.CREATED).body(nuevaTarea);
    }
    
    @PutMapping("/{id}")
    public Tarea actualizarTarea(@PathVariable Long id, @RequestBody Tarea tarea) {
        return tareaService.actualizar(id, tarea);
    }
    
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> eliminarTarea(@PathVariable Long id) {
        tareaService.eliminar(id);
        return ResponseEntity.noContent().build();
    }
}

Manejo de parámetros y datos

Los parámetros de ruta se capturan mediante @PathVariable, permitiendo extraer valores dinámicos de la URL. Esta anotación es fundamental para crear endpoints que trabajen con recursos específicos identificados por un ID u otro valor único.

Los parámetros de consulta se manejan con @RequestParam, útiles para filtros, paginación y opciones adicionales que no forman parte de la estructura principal de la URL.

@RestController
@RequestMapping("/api/libros")
public class LibroController {
    
    @GetMapping("/{id}")
    public Libro obtenerLibro(@PathVariable Long id) {
        return libroService.buscarPorId(id);
    }
    
    @GetMapping
    public List<Libro> buscarLibros(
            @RequestParam(required = false) String autor,
            @RequestParam(defaultValue = "0") int pagina,
            @RequestParam(defaultValue = "10") int tamaño) {
        
        return libroService.buscar(autor, pagina, tamaño);
    }
    
    @PostMapping
    public Libro crearLibro(@RequestBody Libro libro) {
        return libroService.guardar(libro);
    }
}

Respuestas HTTP y códigos de estado

ResponseEntity proporciona control completo sobre la respuesta HTTP, incluyendo códigos de estado, headers y cuerpo de la respuesta. Esta clase es especialmente útil cuando necesitas devolver códigos de estado específicos o manejar casos de error de manera explícita.

Los códigos de estado HTTP comunican el resultado de la operación al cliente. Spring Boot puede manejar estos códigos automáticamente, pero usar ResponseEntity permite un control más granular y expresivo.

@RestController
@RequestMapping("/api/pedidos")
public class PedidoController {
    
    @GetMapping("/{id}")
    public ResponseEntity<Pedido> obtenerPedido(@PathVariable Long id) {
        Optional<Pedido> pedido = pedidoService.buscarPorId(id);
        
        if (pedido.isPresent()) {
            return ResponseEntity.ok(pedido.get());
        } else {
            return ResponseEntity.notFound().build();
        }
    }
    
    @PostMapping
    public ResponseEntity<Pedido> crearPedido(@RequestBody Pedido pedido) {
        try {
            Pedido nuevoPedido = pedidoService.procesar(pedido);
            return ResponseEntity.status(HttpStatus.CREATED).body(nuevoPedido);
        } catch (Exception e) {
            return ResponseEntity.badRequest().build();
        }
    }
}

Serialización automática con Jackson

Spring Boot incluye Jackson como biblioteca de serialización por defecto, convirtiendo automáticamente objetos Java a JSON y viceversa. Esta integración transparente permite trabajar con objetos Java nativos sin preocuparse por la conversión manual de formatos.

La serialización ocurre automáticamente cuando un método del controlador devuelve un objeto. Jackson inspecciona las propiedades del objeto y genera el JSON correspondiente, respetando las convenciones de nomenclatura y tipos de datos.

public class Evento {
    private Long id;
    private String nombre;
    private LocalDateTime fecha;
    private String ubicacion;
    
    // Constructores, getters y setters
    public Evento(String nombre, LocalDateTime fecha, String ubicacion) {
        this.nombre = nombre;
        this.fecha = fecha;
        this.ubicacion = ubicacion;
    }
    
    // Jackson utilizará estos getters para la serialización
    public Long getId() { return id; }
    public String getNombre() { return nombre; }
    public LocalDateTime getFecha() { return fecha; }
    public String getUbicacion() { return ubicacion; }
}

@RestController
@RequestMapping("/api/eventos")
public class EventoController {
    
    @GetMapping("/{id}")
    public Evento obtenerEvento(@PathVariable Long id) {
        // Jackson convertirá automáticamente este objeto a JSON
        return new Evento("Conferencia Spring", 
                         LocalDateTime.now().plusDays(7), 
                         "Madrid");
    }
}

La deserialización funciona en sentido inverso cuando se reciben datos JSON en el cuerpo de una petición POST o PUT. Jackson mapea automáticamente los campos JSON a las propiedades del objeto Java, siempre que los nombres coincidan y existan los setters apropiados.