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).
Para localizar un recurso en la red, el cliente utiliza una URL (Uniform Resource Locator), formada por:
http: o https: api.miservidor.com o localhost:8080)./api/v1/books).? (/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.
HTTP, no la URL.GET /booksGET /getBooks o POST /createBookGET /books/12/authors (Obtiene los autores del libro con ID 12).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.
{
"isbn": "978-84-376-0494-7",
"title": "Don Quijote",
"basePrice": 18.50
}
[
{
"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.