Tutorial SpringBoot: Introducción a controladores REST

Fundamento teórico de las API REST

Las API REST (Representational State Transfer) constituyen un estilo arquitectónico que define un conjunto de principios para diseñar servicios web escalables y mantenibles. Este paradigma se basa en la idea de que los recursos del sistema pueden ser identificados, accedidos y manipulados mediante operaciones estándar del protocolo HTTP.

Principios fundamentales de REST

REST se fundamenta en seis restricciones arquitectónicas que garantizan la escalabilidad y simplicidad del sistema:

• Arquitectura cliente-servidor: Separa las responsabilidades entre el cliente (que consume los datos) y el servidor (que los proporciona), permitiendo que evolucionen independientemente.

• Sin estado (Stateless): Cada petición del cliente debe contener toda la información necesaria para ser procesada. El servidor no mantiene información sobre el estado de la sesión entre peticiones.

• Cacheable: Las respuestas deben indicar explícitamente si pueden ser almacenadas en caché para mejorar el rendimiento y reducir la carga del servidor.

• Interfaz uniforme: Define un conjunto consistente de operaciones que simplifican la arquitectura y mejoran la visibilidad de las interacciones.

• Sistema en capas: Permite organizar la arquitectura en capas jerárquicas, donde cada capa solo conoce la inmediatamente inferior.

• Código bajo demanda (opcional): El servidor puede enviar código ejecutable al cliente cuando sea necesario.

Recursos y URIs

En REST, todo se modela como un recurso. Un recurso es cualquier información que puede ser nombrada: un documento, una imagen, un servicio temporal, una colección de otros recursos, o un objeto no virtual. Cada recurso se identifica mediante una URI (Uniform Resource Identifier) única.

https://api.ejemplo.com/usuarios/123
https://api.ejemplo.com/productos
https://api.ejemplo.com/pedidos/456/items

Los recursos se organizan de forma jerárquica, donde las URIs reflejan las relaciones entre entidades. Esta estructura intuitiva facilita la comprensión y navegación de la API.

Métodos HTTP y operaciones CRUD

REST aprovecha los métodos HTTP para definir las operaciones que se pueden realizar sobre los recursos. Cada método tiene una semántica específica que se alinea con las operaciones CRUD:

• GET: Recupera la representación de un recurso. Es idempotente y seguro, no modifica el estado del servidor.

GET /usuarios/123
GET /productos?categoria=electronica

• POST: Crea un nuevo recurso. No es idempotente, cada llamada puede crear un recurso diferente.

POST /usuarios
POST /productos

• PUT: Actualiza completamente un recurso existente o lo crea si no existe. Es idempotente.

PUT /usuarios/123
PUT /productos/789

• DELETE: Elimina un recurso. Es idempotente en cuanto al resultado final.

DELETE /usuarios/123
DELETE /productos/789

Representaciones y tipos de contenido

Los recursos pueden tener múltiples representaciones (JSON, XML, HTML), pero en aplicaciones modernas, JSON se ha convertido en el estándar de facto por su simplicidad y eficiencia. El cliente especifica el formato deseado mediante el header Accept, mientras que el servidor indica el formato de la respuesta con Content-Type.

{
  "id": 123,
  "nombre": "Juan Pérez",
  "email": "juan@ejemplo.com",
  "fechaCreacion": "2024-01-15T10:30:00Z"
}

Códigos de estado HTTP

Las respuestas HTTP utilizan códigos de estado estándar para comunicar el resultado de la operación:

• 2xx (Éxito): La petición fue procesada correctamente

• 200 OK: Operación exitosa

• 201 Created: Recurso creado exitosamente

• 204 No Content: Operación exitosa sin contenido de respuesta

• 4xx (Error del cliente): La petición contiene errores

• 400 Bad Request: Petición malformada

• 404 Not Found: Recurso no encontrado

• 409 Conflict: Conflicto con el estado actual del recurso

• 5xx (Error del servidor): Error interno del servidor

• 500 Internal Server Error: Error interno no especificado

Ventajas de las API REST

La adopción de REST proporciona múltiples beneficios para el desarrollo de aplicaciones distribuidas:

• Simplicidad: Utiliza estándares web existentes (HTTP, URIs, JSON)
• Escalabilidad: La ausencia de estado facilita la distribución horizontal
• Flexibilidad: Permite múltiples representaciones y evolución independiente
• Interoperabilidad: Compatible con cualquier lenguaje o plataforma que soporte HTTP
• Cacheable: Mejora el rendimiento mediante estrategias de caché

Esta base teórica establece los cimientos para implementar servicios web robustos y escalables. Spring Boot proporciona las herramientas necesarias para materializar estos conceptos mediante anotaciones y configuraciones que simplifican significativamente el desarrollo de API REST.

Anotaciones @RestController y @GetMapping para crear un hola mundo

Spring Boot simplifica enormemente la creación de controladores REST mediante anotaciones especializadas que eliminan la configuración manual y permiten centrarse en la lógica de negocio. Las anotaciones @RestController y @GetMapping constituyen los elementos fundamentales para exponer endpoints HTTP de forma declarativa.

La anotación @RestController

La anotación @RestController combina la funcionalidad de @Controller y @ResponseBody, indicando que la clase manejará peticiones HTTP y que los métodos devolverán directamente datos serializados (típicamente JSON) en lugar de vistas. Esta anotación elimina la necesidad de anotar cada método individual con @ResponseBody.

@RestController
public class HolaMundoController {
    // Los métodos aquí devolverán automáticamente JSON
}

Spring detecta automáticamente las clases anotadas con @RestController durante el escaneo de componentes, registrándolas como beans en el contenedor de inversión de control. Esto significa que no necesitas configuración adicional para que Spring reconozca tu controlador.

La anotación @GetMapping

La anotación @GetMapping es una especialización de @RequestMapping que maneja específicamente peticiones HTTP GET. Esta anotación mapea una URL específica a un método del controlador, definiendo así un endpoint de la API.

@RestController
public class HolaMundoController {
    
    @GetMapping("/hola")
    public String saludar() {
        return "¡Hola Mundo desde Spring Boot!";
    }
}

En este ejemplo, cuando un cliente realiza una petición GET a /hola, Spring invoca el método saludar() y devuelve la cadena como respuesta HTTP. Spring automáticamente serializa el valor de retorno al formato apropiado (por defecto JSON para objetos complejos, texto plano para strings).

Creando tu primer controlador REST

Para crear un controlador REST funcional, necesitas seguir estos pasos básicos:

1. Crear la clase del controlador:

package com.ejemplo.demo.controller;

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

@RestController
public class HolaMundoController {
    
    @GetMapping("/")
    public String inicio() {
        return "Bienvenido a la API REST";
    }
    
    @GetMapping("/hola")
    public String hola() {
        return "¡Hola Mundo!";
    }
    
    @GetMapping("/saludo")
    public String saludo() {
        return "Saludos desde Spring Boot";
    }
}

2. Estructura del proyecto:

El controlador debe ubicarse en el paquete base de la aplicación o en un subpaquete para que Spring Boot lo detecte automáticamente. Si tu clase principal está en com.ejemplo.demo, el controlador puede estar en com.ejemplo.demo.controller.

3. Ejecutar y probar:

Una vez que ejecutes la aplicación Spring Boot, los endpoints estarán disponibles en:

http://localhost:8080/
http://localhost:8080/hola
http://localhost:8080/saludo

Devolviendo objetos complejos

Los controladores REST pueden devolver objetos Java que Spring serializa automáticamente a JSON:

@RestController
public class HolaMundoController {
    
    @GetMapping("/usuario")
    public Usuario obtenerUsuario() {
        Usuario usuario = new Usuario();
        usuario.setNombre("Juan");
        usuario.setEmail("juan@ejemplo.com");
        return usuario;
    }
    
    @GetMapping("/mensaje")
    public Mensaje obtenerMensaje() {
        return new Mensaje("¡Hola Mundo!", "Mensaje de bienvenida");
    }
}

class Usuario {
    private String nombre;
    private String email;
    
    // Constructores, getters y setters
    public String getNombre() { return nombre; }
    public void setNombre(String nombre) { this.nombre = nombre; }
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
}

class Mensaje {
    private String texto;
    private String descripcion;
    
    public Mensaje(String texto, String descripcion) {
        this.texto = texto;
        this.descripcion = descripcion;
    }
    
    // Getters
    public String getTexto() { return texto; }
    public String getDescripcion() { return descripcion; }
}

Cuando accedas a /usuario, obtendrás una respuesta JSON como:

{
  "nombre": "Juan",
  "email": "juan@ejemplo.com"
}

Configuración de rutas con @RequestMapping

Puedes organizar mejor tus endpoints utilizando @RequestMapping a nivel de clase para definir un prefijo común:

@RestController
@RequestMapping("/api")
public class HolaMundoController {
    
    @GetMapping("/hola")
    public String hola() {
        return "¡Hola desde /api/hola!";
    }
    
    @GetMapping("/estado")
    public String estado() {
        return "API funcionando correctamente";
    }
}

Con esta configuración, los endpoints serán accesibles en:

http://localhost:8080/api/hola
http://localhost:8080/api/estado

Manejo automático de headers HTTP

Spring Boot configura automáticamente los headers HTTP apropiados para las respuestas REST. Para respuestas JSON, establece Content-Type: application/json, mientras que para texto plano utiliza Content-Type: text/plain.

@RestController
public class HolaMundoController {
    
    @GetMapping("/info")
    public Map<String, String> informacion() {
        Map<String, String> info = new HashMap<>();
        info.put("aplicacion", "Demo Spring Boot");
        info.put("version", "1.0.0");
        info.put("estado", "activo");
        return info;
    }
}

Este endpoint devolverá automáticamente una respuesta JSON con el header Content-Type: application/json.

La combinación de @RestController y @GetMapping proporciona una forma elegante y declarativa de crear endpoints REST funcionales con mínima configuración. Spring Boot maneja automáticamente la serialización, el mapeo de URLs y la configuración de headers, permitiendo que te concentres en implementar la lógica de tu aplicación.