Curso de programación Spring Boot API REST

Una API REST (Representational State Transfer) es un estilo arquitectónico para diseñar servicios web que utiliza los métodos HTTP estándar para realizar operaciones sobre recursos. En el contexto de Spring Boot, estas APIs se implementan mediante controladores que exponen endpoints HTTP, permitiendo que diferentes aplicaciones se comuniquen de manera eficiente y estandarizada.

Los servicios REST siguen principios fundamentales como la ausencia de estado, la identificación única de recursos mediante URLs, y el uso de métodos HTTP semánticamente correctos. Spring Boot facilita enormemente la implementación de estos principios mediante anotaciones y configuraciones automáticas.

Arquitectura de controladores REST en Spring Boot

Los controladores REST en Spring Boot son clases Java anotadas que manejan las peticiones HTTP entrantes. Estos controladores actúan como la capa de presentación de la aplicación, recibiendo datos del cliente, procesándolos a través de la lógica de negocio, y devolviendo respuestas apropiadas.

La arquitectura típica incluye:

• Controladores: Manejan las peticiones HTTP y coordinan las respuestas
• Servicios: Contienen la lógica de negocio
• Repositorios: Gestionan el acceso a datos
• Entidades: Representan los modelos de datos

@RestController
@RequestMapping("/api/usuarios")
public class UsuarioController {
    
    @Autowired
    private UsuarioService usuarioService;
    
    @GetMapping
    public List<Usuario> obtenerUsuarios() {
        return usuarioService.obtenerTodos();
    }
}

Métodos HTTP y operaciones CRUD

Spring Boot proporciona anotaciones específicas para cada método HTTP, permitiendo implementar operaciones CRUD completas de manera intuitiva. Cada método HTTP tiene un propósito semántico específico que debe respetarse para mantener la coherencia de la API.

Operaciones de lectura con GET

Los métodos GET se utilizan para recuperar información sin modificar el estado del servidor. Spring Boot ofrece múltiples formas de manejar parámetros de consulta, variables de ruta y headers de petición.

@GetMapping("/{id}")
public ResponseEntity<Usuario> obtenerUsuario(@PathVariable Long id) {
    Usuario usuario = usuarioService.buscarPorId(id);
    return ResponseEntity.ok(usuario);
}

@GetMapping
public List<Usuario> buscarUsuarios(
    @RequestParam(required = false) String nombre,
    @RequestParam(defaultValue = "0") int pagina) {
    return usuarioService.buscar(nombre, pagina);
}

Creación de recursos con POST

Los métodos POST permiten crear nuevos recursos en el servidor. La validación de datos de entrada y el manejo de errores son aspectos cruciales en estas operaciones.

@PostMapping
public ResponseEntity<Usuario> crearUsuario(@Valid @RequestBody Usuario usuario) {
    Usuario nuevoUsuario = usuarioService.crear(usuario);
    URI ubicacion = ServletUriComponentsBuilder
        .fromCurrentRequest()
        .path("/{id}")
        .buildAndExpand(nuevoUsuario.getId())
        .toUri();
    
    return ResponseEntity.created(ubicacion).body(nuevoUsuario);
}

Actualización con PUT y PATCH

Los métodos PUT y PATCH manejan actualizaciones de recursos existentes. PUT reemplaza completamente el recurso, mientras que PATCH aplica modificaciones parciales.

@PutMapping("/{id}")
public ResponseEntity<Usuario> actualizarUsuario(
    @PathVariable Long id, 
    @Valid @RequestBody Usuario usuario) {
    Usuario actualizado = usuarioService.actualizar(id, usuario);
    return ResponseEntity.ok(actualizado);
}

@PatchMapping("/{id}")
public ResponseEntity<Usuario> actualizarParcial(
    @PathVariable Long id,
    @RequestBody Map<String, Object> campos) {
    Usuario actualizado = usuarioService.actualizarParcial(id, campos);
    return ResponseEntity.ok(actualizado);
}

Eliminación con DELETE

Los métodos DELETE permiten eliminar recursos del servidor, devolviendo códigos de estado apropiados según el resultado de la operación.

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

Documentación automática con OpenAPI

OpenAPI (anteriormente Swagger) proporciona una especificación estándar para documentar APIs REST. Spring Boot se integra perfectamente con OpenAPI mediante la librería springdoc-openapi, generando documentación interactiva automáticamente.

La integración permite:

• Documentación automática de endpoints basada en anotaciones
• Interfaz web interactiva para probar la API
• Generación de esquemas JSON/YAML
• Validación de contratos API

@RestController
@Tag(name = "Usuarios", description = "Gestión de usuarios del sistema")
public class UsuarioController {
    
    @Operation(summary = "Obtener usuario por ID")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "Usuario encontrado"),
        @ApiResponse(responseCode = "404", description = "Usuario no encontrado")
    })
    @GetMapping("/{id}")
    public ResponseEntity<Usuario> obtenerUsuario(@PathVariable Long id) {
        // Implementación
    }
}

Gestión centralizada de errores

El manejo de errores en APIs REST requiere un enfoque sistemático para proporcionar respuestas consistentes y útiles. @RestControllerAdvice permite centralizar la gestión de excepciones en toda la aplicación.

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(UsuarioNoEncontradoException.class)
    public ResponseEntity<ErrorResponse> manejarUsuarioNoEncontrado(
        UsuarioNoEncontradoException ex) {
        ErrorResponse error = new ErrorResponse(
            "USUARIO_NO_ENCONTRADO",
            ex.getMessage(),
            LocalDateTime.now()
        );
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }
    
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> manejarValidacion(
        MethodArgumentNotValidException ex) {
        // Manejo de errores de validación
    }
}

Consumo de APIs externas

Spring Boot ofrece múltiples opciones para consumir APIs externas, siendo RestTemplate y RestClient las más utilizadas. Estas herramientas simplifican las llamadas HTTP salientes y el procesamiento de respuestas.

RestTemplate para llamadas síncronas

RestTemplate ha sido la opción tradicional para realizar llamadas HTTP síncronas, ofreciendo métodos convenientes para cada operación HTTP.

@Service
public class ServicioExterno {
    
    private final RestTemplate restTemplate;
    
    public ServicioExterno(RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }
    
    public Usuario obtenerUsuarioExterno(Long id) {
        String url = "https://api.externa.com/usuarios/{id}";
        return restTemplate.getForObject(url, Usuario.class, id);
    }
    
    public Usuario crearUsuarioExterno(Usuario usuario) {
        String url = "https://api.externa.com/usuarios";
        return restTemplate.postForObject(url, usuario, Usuario.class);
    }
}

RestClient como alternativa moderna

RestClient representa la evolución de RestTemplate, ofreciendo una API más fluida y moderna para realizar llamadas HTTP.

@Service
public class ClienteModerno {
    
    private final RestClient restClient;
    
    public ClienteModerno(RestClient.Builder builder) {
        this.restClient = builder
            .baseUrl("https://api.externa.com")
            .defaultHeader("Content-Type", "application/json")
            .build();
    }
    
    public Usuario obtenerUsuario(Long id) {
        return restClient.get()
            .uri("/usuarios/{id}", id)
            .retrieve()
            .body(Usuario.class);
    }
}