===== 09. APIs REST y Protocolo HTTP =====

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).

==== 1. El protocolo HTTP ====

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'').\\ \\

==== 2. Servicios REST y Diseño de Endpoints ====

**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''\\ \\

==== 3. Métodos HTTP y transmisión de datos ====

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. |

==== 4. Formato de Intercambio: JSON ====

''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) ===

<sxh javascript>
{
    "isbn": "978-84-376-0494-7",
    "title": "Don Quijote",
    "basePrice": 18.50
}
</sxh>

=== Colección JSON (Mapea con un List) ===

<sxh javascript>
[
    {
        "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
    }
]
</sxh>
==== 5. Códigos de Estado HTTP ====

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.\\ \\