Métodos DELETE en controladores REST

Borrado con DeleteMapping

La anotación @DeleteMapping permite crear endpoints REST que manejan peticiones HTTP DELETE para eliminar recursos del sistema. Esta anotación forma parte del conjunto de anotaciones especializadas de Spring que simplifican la creación de APIs REST siguiendo las convenciones del protocolo HTTP.

Configuración básica de DeleteMapping

Para implementar un endpoint de borrado, utilizamos @DeleteMapping junto con la ruta del recurso que queremos eliminar. La convención REST establece que las operaciones de borrado deben incluir el identificador del recurso en la URL:

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

    @Autowired
    private UsuarioService usuarioService;

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> eliminarUsuario(@PathVariable Long id) {
        usuarioService.eliminarPorId(id);
        return ResponseEntity.noContent().build();
    }
}

En este ejemplo, el endpoint responde a peticiones DELETE dirigidas a /api/usuarios/{id}, donde {id} representa el identificador único del usuario que se desea eliminar.

Códigos de respuesta HTTP apropiados

Las operaciones de borrado deben devolver códigos de estado HTTP que reflejen el resultado de la operación. Los más comunes son:

204 No Content - Indica que el recurso se eliminó correctamente:

@DeleteMapping("/{id}")
public ResponseEntity<Void> eliminarProducto(@PathVariable Long id) {
    productoService.eliminar(id);
    return ResponseEntity.noContent().build();
}

404 Not Found - Cuando el recurso no existe:

@DeleteMapping("/{id}")
public ResponseEntity<Void> eliminarCategoria(@PathVariable Long id) {
    boolean eliminado = categoriaService.eliminarSiExiste(id);
    
    if (eliminado) {
        return ResponseEntity.noContent().build();
    } else {
        return ResponseEntity.notFound().build();
    }
}

Validación antes del borrado

Es fundamental validar la existencia del recurso antes de intentar eliminarlo. Esto evita errores y proporciona respuestas más informativas al cliente:

@DeleteMapping("/{id}")
public ResponseEntity<String> eliminarPedido(@PathVariable Long id) {
    Optional<Pedido> pedido = pedidoService.buscarPorId(id);
    
    if (pedido.isEmpty()) {
        return ResponseEntity.notFound().build();
    }
    
    // Verificar si el pedido puede ser eliminado
    if (pedido.get().getEstado().equals("PROCESADO")) {
        return ResponseEntity.badRequest()
            .body("No se puede eliminar un pedido ya procesado");
    }
    
    pedidoService.eliminar(id);
    return ResponseEntity.noContent().build();
}

Borrado con confirmación mediante parámetros

En algunos casos, es útil requerir confirmación explícita para operaciones de borrado críticas:

@DeleteMapping("/{id}")
public ResponseEntity<String> eliminarCuenta(
        @PathVariable Long id,
        @RequestParam(required = true) boolean confirmar) {
    
    if (!confirmar) {
        return ResponseEntity.badRequest()
            .body("Debe confirmar la eliminación de la cuenta");
    }
    
    cuentaService.eliminarDefinitivamente(id);
    return ResponseEntity.noContent().build();
}

Borrado lógico vs físico

Muchas aplicaciones implementan borrado lógico en lugar de eliminar físicamente los registros de la base de datos:

@DeleteMapping("/{id}")
public ResponseEntity<Void> desactivarUsuario(@PathVariable Long id) {
    usuarioService.marcarComoEliminado(id);
    return ResponseEntity.noContent().build();
}

@DeleteMapping("/{id}/permanente")
public ResponseEntity<Void> eliminarUsuarioPermanente(@PathVariable Long id) {
    usuarioService.eliminarFisicamente(id);
    return ResponseEntity.noContent().build();
}

Manejo de errores en operaciones de borrado

Las operaciones de borrado pueden fallar por diversas razones. Es importante capturar estas situaciones y devolver respuestas apropiadas:

@DeleteMapping("/{id}")
public ResponseEntity<String> eliminarDocumento(@PathVariable Long id) {
    try {
        documentoService.eliminar(id);
        return ResponseEntity.noContent().build();
    } catch (DocumentoEnUsoException e) {
        return ResponseEntity.status(HttpStatus.CONFLICT)
            .body("El documento no puede eliminarse porque está siendo utilizado");
    } catch (DocumentoNoEncontradoException e) {
        return ResponseEntity.notFound().build();
    } catch (Exception e) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body("Error interno del servidor");
    }
}

Borrado en lote

Para eliminar múltiples recursos de una vez, podemos aceptar una lista de identificadores:

@DeleteMapping("/lote")
public ResponseEntity<Map<String, Object>> eliminarVariosProductos(
        @RequestBody List<Long> ids) {
    
    List<Long> eliminados = new ArrayList<>();
    List<Long> noEncontrados = new ArrayList<>();
    
    for (Long id : ids) {
        if (productoService.existe(id)) {
            productoService.eliminar(id);
            eliminados.add(id);
        } else {
            noEncontrados.add(id);
        }
    }
    
    Map<String, Object> resultado = Map.of(
        "eliminados", eliminados,
        "noEncontrados", noEncontrados
    );
    
    return ResponseEntity.ok(resultado);
}

La implementación de endpoints de borrado con @DeleteMapping requiere considerar aspectos como la validación de datos, el manejo de errores y la elección de códigos de respuesta HTTP apropiados para crear APIs REST robustas y predecibles.