Métodos POST en controladores REST

Recepción de datos con @PostMapping

La anotación @PostMapping permite que nuestros controladores REST reciban datos del cliente a través de peticiones HTTP POST. A diferencia de las peticiones GET que solo envían parámetros en la URL, las peticiones POST pueden transportar información compleja en el cuerpo de la petición, lo que las hace ideales para operaciones de creación y envío de datos estructurados.

Recepción de datos simples con @RequestParam

Para recibir parámetros individuales en una petición POST, utilizamos la anotación @RequestParam. Esta aproximación es útil cuando necesitamos procesar datos simples enviados desde formularios web:

@RestController
@RequestMapping("/api/usuarios")
public class UsuarioController {

    @PostMapping("/crear")
    public ResponseEntity<String> crearUsuario(
            @RequestParam String nombre,
            @RequestParam String email,
            @RequestParam int edad) {
        
        // Lógica para crear el usuario
        String mensaje = "Usuario " + nombre + " creado correctamente";
        return ResponseEntity.ok(mensaje);
    }
}

En este ejemplo, el método recibe tres parámetros que el cliente debe enviar en el cuerpo de la petición como datos de formulario. Spring Boot automáticamente extrae estos valores y los asigna a los parámetros del método.

Recepción de objetos JSON con @RequestBody

Para aplicaciones modernas que intercambian datos en formato JSON, utilizamos @RequestBody. Esta anotación indica a Spring que debe deserializar el JSON recibido en el cuerpo de la petición y convertirlo automáticamente en un objeto Java:

public class Usuario {
    private String nombre;
    private String email;
    private int edad;
    
    // Constructores, getters y setters
    public Usuario() {}
    
    public Usuario(String nombre, String email, int edad) {
        this.nombre = nombre;
        this.email = email;
        this.edad = edad;
    }
    
    // Getters y setters omitidos por brevedad
}

@RestController
@RequestMapping("/api/usuarios")
public class UsuarioController {

    @PostMapping("/registrar")
    public ResponseEntity<Usuario> registrarUsuario(@RequestBody Usuario usuario) {
        
        // Validación básica
        if (usuario.getNombre() == null || usuario.getEmail() == null) {
            return ResponseEntity.badRequest().build();
        }
        
        // Lógica de procesamiento
        System.out.println("Registrando usuario: " + usuario.getNombre());
        
        return ResponseEntity.ok(usuario);
    }
}

El cliente enviaría una petición POST con el siguiente contenido JSON:

{
    "nombre": "Ana García",
    "email": "ana@ejemplo.com",
    "edad": 28
}

Combinando parámetros de ruta y cuerpo de petición

Es común necesitar tanto parámetros de la URL como datos en el cuerpo de la petición. Podemos combinar @PathVariable con @RequestBody para crear endpoints más expresivos:

@PostMapping("/categorias/{categoriaId}/productos")
public ResponseEntity<Producto> agregarProducto(
        @PathVariable Long categoriaId,
        @RequestBody Producto producto) {
    
    // Asignar la categoría al producto
    producto.setCategoriaId(categoriaId);
    
    // Lógica para guardar el producto
    System.out.println("Agregando producto a categoría: " + categoriaId);
    
    return ResponseEntity.status(HttpStatus.CREATED).body(producto);
}

Validación de datos recibidos

Spring Boot integra validación automática utilizando las anotaciones de Bean Validation. Podemos agregar validaciones directamente en nuestras clases de datos:

import jakarta.validation.constraints.*;

public class Usuario {
    @NotBlank(message = "El nombre es obligatorio")
    @Size(min = 2, max = 50, message = "El nombre debe tener entre 2 y 50 caracteres")
    private String nombre;
    
    @NotBlank(message = "El email es obligatorio")
    @Email(message = "El formato del email no es válido")
    private String email;
    
    @Min(value = 18, message = "La edad mínima es 18 años")
    @Max(value = 120, message = "La edad máxima es 120 años")
    private int edad;
    
    // Constructores, getters y setters
}

Para activar la validación, agregamos @Valid antes de @RequestBody:

@PostMapping("/registrar")
public ResponseEntity<?> registrarUsuario(@Valid @RequestBody Usuario usuario) {
    
    // Si llegamos aquí, los datos son válidos
    System.out.println("Usuario válido: " + usuario.getNombre());
    
    return ResponseEntity.ok(usuario);
}

Manejo de errores de validación

Cuando los datos no cumplen las reglas de validación, Spring genera automáticamente una respuesta de error. Podemos personalizar este comportamiento capturando las excepciones:

@PostMapping("/registrar")
public ResponseEntity<?> registrarUsuario(@Valid @RequestBody Usuario usuario, 
                                        BindingResult result) {
    
    if (result.hasErrors()) {
        Map<String, String> errores = new HashMap<>();
        result.getFieldErrors().forEach(error -> 
            errores.put(error.getField(), error.getDefaultMessage())
        );
        return ResponseEntity.badRequest().body(errores);
    }
    
    // Procesar usuario válido
    return ResponseEntity.ok(usuario);
}

Configuración de Content-Type

Los métodos POST pueden recibir diferentes tipos de contenido. Spring Boot maneja automáticamente la deserialización basándose en el header Content-Type de la petición:

• application/json: Para objetos JSON con @RequestBody
• application/x-www-form-urlencoded: Para datos de formulario con @RequestParam
• multipart/form-data: Para formularios con archivos

@PostMapping(value = "/crear", consumes = "application/json")
public ResponseEntity<String> crearConJSON(@RequestBody Usuario usuario) {
    return ResponseEntity.ok("Usuario creado desde JSON");
}

@PostMapping(value = "/crear", consumes = "application/x-www-form-urlencoded")
public ResponseEntity<String> crearConFormulario(@RequestParam String nombre,
                                               @RequestParam String email) {
    return ResponseEntity.ok("Usuario creado desde formulario");
}

La especificación del atributo consumes permite que el mismo endpoint maneje diferentes formatos de entrada, mejorando la flexibilidad de nuestra API REST.