Estilo de arquitectura REST
Este artículo es una definición conceptual sobre REST, incluyendo preguntas de examen y etiquetas.
En pocas palabras
REST es un estilo de arquitectura para sistemas de hipermedia distribuidos basados en HTTP. La idea central es que los recursos se direccionan mediante URIs, se manipulan con métodos estandarizados y se transfieren a través de representaciones.
Descripción técnica compacta
REST define seis restricciones: Cliente-Servidor, Sin estado, Cacheable, Interfaz uniforme, Capas y, opcionalmente, Code on Demand. Los recursos son objetos de negocio identificados de forma única mediante URI (por ejemplo, https://api.shop.de/orders/42). Las representaciones transportan el estado, generalmente en JSON o XML, negociadas mediante Content Negotiation con Accept y Content-Type. Los métodos tienen semántica: GET es seguro e idempotente, POST no es idempotente, PUT es idempotente, PATCH no necesariamente idempotente, DELETE es idempotente. Los códigos de estado señalan el resultado (200, 201, 204, 400, 401, 403, 404, 409, 500). HATEOAS incluye enlaces de navegación y acciones en las representaciones. El caching eficiente utiliza Cache-Control, ETag, Last-Modified y solicitudes condicionales.
Puntos clave relevantes para exámenes
- Diseño de API orientado a recursos, sustantivos en plural, URIs estables, sin verbos en la ruta
- Métodos HTTP y semántica, seguro/idempotente/no idempotente, mapeo a CRUD
- Definir idempotencia claramente, especialmente para PUT, DELETE y POST con Idempotency Key
- Usar códigos de estado de forma dirigida, 2xx/3xx/4xx/5xx, cabecera Location en 201
- Requisitos de protección de datos, registro, rastreabilidad, documentar catálogos de errores
- Forzar TLS, OAuth 2/OIDC, JWT, CORS, Rate Limiting, validación de entrada, Logging
- Acoplamiento suelto, reutilización, evolución independiente de cliente y servidor
- Documentación OpenAPI, solicitudes y respuestas de ejemplo, catálogo de errores, estrategia de versionado
Componentes principales
- Diseño de recursos y URIs
- Representaciones, tipos de medios y esquema
- Semántica de métodos: GET, POST, PUT, PATCH, DELETE
- Códigos de estado y cabeceras
- Content Negotiation: Accept, Content-Type, Accept-Language
- Caching: Cache-Control, ETag, Last-Modified, Conditional Requests
- Seguridad: Autenticación, autorización, TLS, CORS
- Versionado: URI, cabeceras, Content-Types
- Observabilidad: Logging, métricas, Tracing, ID de correlación
- Pruebas: Contract Tests, API Tests, casos de error, pruebas de idempotencia
Ejemplo práctico
// Ejemplo: Recurso de pedidos con HATEOAS e idempotencia
Recursos:
GET /orders - Lista de pedidos
POST /orders - crear nuevo pedido
GET /orders/{order-id} - leer pedido individual
PUT /orders/{order-id} - reemplazar pedido completo
PATCH /orders/{order-id} - cambiar pedido parcialmente
DELETE /orders/{order-id} - eliminar pedido
Ejemplo solicitud POST:
{
"customerId": 12345,
"items": [{ "sku": "A1", "qty": 2 }]
}
Respuesta 201 Created, cabecera: Location: https://api.shop.de/orders/42
Cuerpo:
{
"order-id": 42,
"status": "created",
"links": [
{ "rel": "self", "href": "https://api.shop.de/orders/42" },
{ "rel": "confirm", "method": "POST", "href": "https://api.shop.de/orders/42/confirm" }
]
}
Idempotencia en POST: El cliente envía adicionalmente Idempotency-Key: abc-123.
El servidor almacena el resultado por clave y entrega la misma respuesta en reintentos.
Ventajas y desventajas
Ventajas
- Interoperabilidad a través de estándares
- Acoplamiento suelto, buena escalabilidad mediante ausencia de estado
- Caching eficiente, señales de error claras a través de códigos de estado
- Uso simple mediante navegadores y herramientas
Desventajas
- Posibilidad de overfetching y underfetching
- Procesos de escritura complejos requieren idempotencia limpia y estrategias de transacciones
- HATEOAS a menudo se descuida
- La responsabilidad de seguridad recae fuertemente en el diseño de la API
- Las APIs conversacionales aumentan las latencias
Preguntas típicas de examen (con respuesta breve)
- ¿Seis restricciones de REST y su efecto? Cliente-Servidor (evolución independiente), Sin estado (sin estados de sesión), Cacheable (respuestas repetidas eficientemente), Interfaz uniforme (métodos estandarizados), Capas (intermediarios posibles), Code on Demand (opcional, scripts).
- ¿PUT vs. PATCH en idempotencia? PUT reemplaza completamente y es idempotente, PATCH cambia parcialmente y no necesariamente es idempotente.
- ¿Qué significa Safe para métodos HTTP? Safe = sin efectos secundarios que cambien estado, GET y HEAD son seguros (solo lectura).
- ¿ETag y solicitudes condicionales? El servidor proporciona ETag, el cliente envía If-None-Match, si coincide el servidor responde con 304 Not Modified sin cuerpo.
- ¿Versionar una API REST? Versiones en URI (/v1), basadas en cabeceras, Accept basado (application/vnd.firma.resource.v2+json), importante: cambios compatibles hacia atrás.
- ¿HATEOAS y su utilidad? El cliente descubre acciones a través de enlaces en representaciones, reduce acoplamiento y suposiciones rígidas sobre flujos de trabajo.
- ¿Content Negotiation en la práctica? El cliente envía Accept (application/json), el servidor selecciona la representación adecuada o responde con 406 Not Acceptable.
- ¿Operaciones de escritura idempotentes en pagos? POST en recurso de colección con Idempotency Key, recurso de transacción dedicado, reintentos con la misma clave entregan el mismo estado final:
/payments/{payment-id}