REST

Resumen

REST, Representational State Transfer, es un estilo arquitectónico definido por Roy Fielding en su disertación doctoral. No es un protocolo ni un formato. Es un conjunto de restricciones —client-server, statelessness, cacheability, uniform interface, layered system, code-on-demand— que, aplicadas al diseño de un sistema distribuido, producen propiedades deseables: escalabilidad, simplicidad, visibilidad, confiabilidad y evolución independiente de componentes.

Importa porque REST es el estilo dominante para APIs web. Casi toda API pública moderna sigue principios REST o variantes cercanas. Entender sus restricciones —no solo copiar patrones de URLs— permite diseñar APIs que escalan, se cachean bien, evolucionan sin romper clientes y se integran con infraestructura HTTP estándar.

Alcance y supuestos

Este paquete cubre REST como estilo arquitectónico: sus restricciones, recursos, URIs, métodos HTTP como interfaz uniforme, representaciones, HATEOAS y trade-offs de diseño.

No cubre implementación completa de APIs REST, comparación detallada de frameworks, ni lenguajes de especificación como OpenAPI o RAML. Asume que entiendes HTTP, métodos, códigos de estado, URIs y el modelo cliente-servidor.

Modelo mental

Piensa en una biblioteca universal con un catálogo estándar. Cada libro tiene una ubicación fija (URI). Puedes pedir ver el libro (GET), agregar uno nuevo (POST), reemplazar una edición (PUT) o retirarlo (DELETE). No necesitas saber qué sistema de archivo usa la biblioteca ni en qué idioma está programado su sistema. Solo necesitas conocer las reglas del catálogo y el formato de las fichas.

REST aplica esa misma idea al software. Cada concepto importante del sistema es un recurso con una URI. Los clientes interactúan con recursos mediante una interfaz uniforme (métodos HTTP). Las representaciones (JSON, XML, HTML) son lo que viaja por la red, no los objetos internos del servidor. El servidor no guarda estado de la conversación entre requests; cada request lleva todo lo necesario. Las respuestas declaran si son cacheables. Y el servidor puede indicar qué acciones son posibles desde el estado actual (HATEOAS).

La restricción más incomprendida es HATEOAS: Hypermedia as the Engine of Application State. Significa que el servidor debe guiar al cliente sobre qué puede hacer a continuación mediante links en las representaciones, como una página web guía a un usuario con enlaces. Pocas APIs lo implementan completamente, pero es parte del estilo REST original.

Uso práctico

Aplica REST cuando diseñas APIs que deben ser escalables, cacheables y evolutivas:

• ✅ APIs públicas que múltiples clientes —web, mobile, third-party— consumirán por años.
• ✅ Sistemas donde la separación cliente-servidor permite evolucionar backend y frontend de forma independiente.
• ✅ Recursos bien definidos con operaciones CRUD claras: usuarios, pedidos, productos, documentos.
• ❌ No es la mejor opción para operaciones complejas que no mapean bien a recursos (RPC o GraphQL pueden encajar mejor).
• ❌ No confundas "URLs con nombres en plural y JSON" con REST; REST es sobre las restricciones, no sobre la estética de URLs.

Ejemplo trabajado: diseñar una API REST para pedidos

Supón que necesitas una API para gestionar pedidos. El diseño REST no empieza por las rutas, sino por los recursos y sus relaciones:

// Recurso: pedidos. Colección y elemento individual.
// GET    /orders          → lista pedidos (con filtros vía query params)
// POST   /orders          → crea un pedido nuevo
// GET    /orders/{id}     → obtiene un pedido específico
// PUT    /orders/{id}     → reemplaza un pedido completo
// DELETE /orders/{id}     → elimina un pedido (o lo marca como cancelado)

type Order = {
  id: string;
  customerId: string;
  status: "pending" | "confirmed" | "shipped";
  totalCents: number;
  items: Array<{
    productId: string;
    quantity: number;
    unitPriceCents: number;
  }>;
  _links: {
    self: { href: string };
    customer: { href: string };
    cancel?: { href: string; method: "DELETE" };
    confirm?: { href: string; method: "POST" };
  };
};

// La representación incluye _links (HATEOAS):
// el cliente no necesita saber qué acciones son válidas;
// el servidor se lo dice según el estado actual del pedido.

La interfaz uniforme significa que los mismos métodos HTTP operan sobre todos los recursos:

• GET /orders y GET /orders/{id} son seguros e idempotentes: no modifican estado.
• PUT /orders/{id} es idempotente: dos llamadas iguales producen el mismo efecto.
• DELETE /orders/{id} es idempotente: eliminar algo ya eliminado no debería fallar.
• POST /orders no es idempotente: dos POST crean dos pedidos distintos.

Las representaciones pueden variar según el Accept header:

• Accept: application/json → JSON
• Accept: application/xml → XML
• El mismo recurso, distintas representaciones.

Antes de decir que una API "es REST", revisa las restricciones:

1. ¿Cliente y servidor evolucionan de forma independiente? (client-server)
2. ¿Cada request contiene toda la información necesaria, sin estado en el servidor entre requests? (stateless)
3. ¿Las respuestas declaran si son cacheables y por cuánto tiempo? (cacheability)
4. ¿La interfaz es uniforme? ¿GET, POST, PUT, DELETE se usan con semántica HTTP correcta? (uniform interface)
5. ¿El sistema funciona igual si hay proxies, load balancers o cachés intermedios? (layered system)

Si la respuesta a alguna es no, tu API probablemente no es REST — es una API HTTP con JSON, que está bien, pero no es lo mismo.

Evidencia

• Roy Thomas Fielding, Representational State Transfer (REST) define REST como un estilo arquitectónico para sistemas hipermedia distribuidos, describiendo sus restricciones y propiedades.
• MDN Web Docs, REST Glossary define REST como un conjunto de restricciones de diseño que producen sistemas distribuidos eficientes, confiables y escalables.