09. APIs REST y Protocolo HTTP [cesguiro]

En la arquitectura por capas, la capa de presentación (Controller) necesita un mecanismo para comunicarse con el exterior. En aplicaciones web y sistemas distribuidos, este intercambio se realiza mediante APIs REST sobre el protocolo HTTP (o HTTPS para comunicaciones cifradas).

La comunicación web sigue el modelo cliente-servidor: el cliente realiza una Petición (Request) y el servidor procesa y devuelve una Respuesta (Response).

Anatomía de una URL / URI

Para localizar un recurso en la red, el cliente utiliza una URL (Uniform Resource Locator), formada por:

Protocolo: http: o https:
Dominio / Host: Identifica al servidor (api.miservidor.com o localhost:8080).
Ruta (Path / URI): Identifica el recurso concreto dentro del servidor (/api/v1/books).
Parámetros de consulta (Query Parameters): Información adicional tras el símbolo ? (/books?page=2&limit=10).

REST (REpresentational State Transfer) es un estilo de arquitectura para diseñar servicios web centrados en recursos.

Un Endpoint es una URL específica expuesta por el servidor a la que el cliente envía peticiones para interactuar con un recurso.

Buenas prácticas en el diseño de Endpoints

Usar sustantivos en plural (nunca verbos): La acción la determina el método HTTP, no la URL.
- Correcto: GET /books
- Incorrecto: GET /getBooks o POST /createBook
Anidar recursos para expresar relaciones jerárquicas:
- GET /books/12/authors (Obtiene los autores del libro con ID 12).
Filtrado y paginación mediante Query Parameters:
- GET /books?category=fiction&page=1

Cada petición HTTP utiliza un verbo o método que define la intención de la operación:

Método	Acción	¿Dónde viajan los datos?	Descripción
`GET`	Lectura	URL (Query / Path Params)	Consulta uno o varios recursos. No debe incluir cuerpo (body).
`POST`	Creación	Cuerpo (Request Body)	Crea un nuevo recurso. El servidor asigna el ID.
`PUT`	Reemplazo	Cuerpo (Request Body)	Reemplaza un recurso existente por completo.
`PATCH`	Modificación parcial	Cuerpo (Request Body)	Actualiza solo los campos especificados del recurso.
`DELETE`	Eliminación	URL (Path Param)	Elimina el recurso especificado.

JSON (JavaScript Object Notation) es el formato estándar para enviar y recibir información en APIs REST debido a su ligereza y facilidad de lectura tanto para humanos como para máquinas.

Cuando el controlador recibe o envía datos, la librería del servidor (parser) convierte automáticamente el texto JSON en nuestras clases Java Record (DTOs) y viceversa.

Objeto JSON simple (Mapea con un DTO)

{
    "isbn": "978-84-376-0494-7",
    "title": "Don Quijote",
    "basePrice": 18.50
}

Colección JSON (Mapea con un List)

[
    {
        "isbn": "978-84-376-0494-7",
        "title": "Don Quijote",
        "basePrice": 18.50
    },
    {
        "isbn": "978-84-204-1214-6",
        "title": "Cien años de soledad",
        "basePrice": 21.00
    }
]

El servidor debe incluir siempre un código de estado numérico en la respuesta para indicar el resultado de la operación:

2xx - Éxito:
- 200 OK: Petición atendida correctamente (usado habitualmente en GET, PUT, PATCH).
- 201 Created: Recurso creado con éxito (usado en POST).
- 204 No Content: Petición correcta pero la respuesta no devuelve cuerpo (común en DELETE).
3xx - Redirección: Indican que el cliente debe realizar una acción adicional para completar la petición (ej. 301 Moved Permanently).
4xx - Errores del Cliente:
- 400 Bad Request: Datos de la petición sintáctica o semánticamente incorrectos (ej. validación de DTO fallida).
- 401 Unauthorized: El cliente debe autenticarse.
- 403 Forbidden: El cliente no tiene permisos para acceder al recurso.
- 404 Not Found: La URL o el recurso solicitado no existe.
5xx - Errores del Servidor:
- 500 Internal Server Error: Excepción o fallo no controlado dentro del código del servidor.