REST Bien Entendido

Audiencia

Esta guia es para desarrolladores que quieren entender lo que REST realmente significa:

• Desarrolladores backend que construyen APIs y quieren tomar decisiones arquitectonicas informadas
• Desarrolladores frontend que consumen APIs y quieren entender por que las APIs se comportan de ciertas formas
• Disenadores de APIs que necesitan explicar las restricciones de REST a sus equipos
• Cualquiera confundido sobre que hace que una API sea “RESTful” (y cansado de escuchar definiciones contradictorias)

Deberias estar familiarizado con conceptos basicos de HTTP. Si no, comienza con HTTP para APIs REST.

Objetivo

Despues de leer esta guia, entenderas:

• Que es REST realmente (un estilo arquitectonico, no un protocolo)
• Las seis restricciones que Roy Fielding definio y por que cada una importa
• La diferencia entre recursos y representaciones
• Por que statelessness es innegociable y que posibilita
• Que significa HATEOAS y por que casi nadie lo implementa
• Como evaluar si una API es verdaderamente RESTful
• Por que “API REST” es frecuentemente un nombre equivocado (y por que eso podria estar bien)

Esta guia construye criterio—la capacidad de evaluar el cumplimiento de REST y hacer trade-offs conscientes.

1. El Malentendido de REST

Comencemos con una verdad incomoda: la mayoria de las “APIs REST” no son REST.

Cuando los desarrolladores dicen “API REST,” usualmente quieren decir:

• Usa HTTP
• Devuelve JSON
• Tiene URLs como /users/123
• Usa GET, POST, PUT, DELETE

Eso no es REST. Eso es “HTTP con JSON.”

REST (Representational State Transfer) es un estilo arquitectonico definido por Roy Fielding en su tesis doctoral del 2000. Es un conjunto de restricciones que, aplicadas juntas, crean sistemas con propiedades especificas: escalabilidad, simplicidad, portabilidad y evolucionabilidad.

graph TB
    subgraph "Lo Que La Gente Cree Que Es REST"
        A[HTTP + JSON] --> B[Endpoints CRUD]
        B --> C[/users, /products]
    end

    subgraph "Lo Que REST Realmente Es"
        D[Estilo Arquitectonico] --> E[6 Restricciones]
        E --> F[Propiedades Emergentes]
        F --> G[Escalabilidad]
        F --> H[Evolucionabilidad]
        F --> I[Simplicidad]
    end

    style A fill:#ffccbc
    style D fill:#c8e6c9

Por que importa esto? Porque entender el verdadero REST te ayuda a:

• Tomar mejores decisiones de diseno de APIs
• Saber cuando seguir REST y cuando romperlo conscientemente
• Comunicarte con precision con tu equipo
• Dejar de copiar patrones sin entender por que

2. De Donde Vino REST

Roy Fielding no invento REST en el vacio. Fue uno de los autores principales de HTTP/1.1 y co-fundo el proyecto Apache HTTP Server. REST emergio de su experiencia construyendo la web.

La Web Como el Sistema Distribuido Definitivo

La World Wide Web es posiblemente el sistema distribuido mas exitoso jamas creado:

• Miles de millones de usuarios
• Millones de servidores
• Decadas de evolucion sin romper la compatibilidad hacia atras
• Construido sobre estandares abiertos que cualquiera puede implementar

Fielding pregunto: Que principios arquitectonicos hacen que la web funcione?

Su tesis fue un analisis de lo que hizo exitosa a la web. REST es el estilo arquitectonico que el extrajo de ese analisis.

REST Es un Conjunto de Restricciones

Aqui esta la idea clave: REST no es una especificacion que implementas. Es un conjunto de restricciones que aplicas a tu arquitectura. Cada restriccion proporciona beneficios especificos, y aplicarlas juntas crea propiedades emergentes.

Piensalo como la construccion de edificios:

• Una “cimentacion” no es un producto especifico—es una restriccion de que los edificios necesitan bases estables
• Diferentes edificios implementan cimentaciones de manera diferente (losa de concreto, pilares, sotano)
• La restriccion guia el diseno sin dictar la implementacion

REST funciona de la misma manera. Te dice que propiedades debe tener tu sistema, no como implementarlas.

3. Las Seis Restricciones de REST

Fielding definio seis restricciones. Examinemos cada una y que pasa cuando la violas.

Restriccion 1: Cliente-Servidor

La restriccion: Separar las preocupaciones de interfaz de usuario de las preocupaciones de almacenamiento de datos.

graph LR
    subgraph "Cliente"
        A[Interfaz de Usuario]
        B[Experiencia de Usuario]
    end

    subgraph "Servidor"
        C[Almacenamiento de Datos]
        D[Logica de Negocio]
    end

    A <-->|HTTP| C

    style A fill:#e3f2fd
    style C fill:#fff3e0

Por que importa:

• Clientes y servidores pueden evolucionar independientemente
• Puedes tener multiples clientes (web, movil, CLI) para un servidor
• El servidor puede escalar sin afectar el codigo del cliente
• Los equipos pueden trabajar en paralelo

Que se rompe cuando se viola: Si tu “API” requiere comportamiento especifico del cliente o embebe logica especifica del cliente, pierdes portabilidad. Cada nuevo cliente necesita manejo especial.

Restriccion 2: Stateless (Sin Estado)

La restriccion: Cada peticion debe contener toda la informacion necesaria para entenderla y procesarla. El servidor no almacena contexto del cliente entre peticiones.

sequenceDiagram
    participant C as Cliente
    participant S as Servidor

    Note over S: El servidor no sabe nada del Cliente

    C->>S: GET /cart (con token de auth)
    Note over S: Lee token, obtiene carrito, olvida cliente
    S->>C: Contenido del carrito

    C->>S: POST /cart/items (con token + datos del item)
    Note over S: Lee token, agrega item, olvida cliente
    S->>C: Carrito actualizado

    Note over S: Aun no sabe nada del Cliente

Por que importa:

• Cualquier servidor puede manejar cualquier peticion (escalado horizontal)
• No se requiere afinidad de sesion (libertad del balanceador de carga)
• Las peticiones pueden ser cacheadas
• Las fallas no corrompen el estado del servidor
• Depuracion mas facil (cada peticion es autocontenida)

Que se rompe cuando se viola:

Si el servidor almacena estado de sesion:

• Necesitas sesiones sticky (el cliente siempre va al mismo servidor)
• La falla del servidor pierde el estado del usuario
• Escalar requiere replicacion de sesiones
• El caching se vuelve dificil

Malentendido comun: “Stateless significa sin datos de usuario.”

Incorrecto. Stateless significa sin estado de sesion del cliente en el servidor entre peticiones. El servidor puede almacenar estado de recursos (perfiles de usuario, pedidos, etc.). Solo no puede almacenar estado de aplicacion (carrito de compras en memoria, progreso de wizard, etc.) entre peticiones.

El cliente envia todo lo necesario:

GET /cart HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

El token contiene o referencia todo el contexto que el servidor necesita.

Restriccion 3: Cacheable

La restriccion: Las respuestas deben definirse explicitamente como cacheables o no-cacheables.

Por que importa:

• Reduce la carga del servidor (las respuestas cacheadas no llegan al origen)
• Reduce la latencia (el cliente o proxy sirve desde cache)
• Habilita CDNs y caching en el edge
• Escala cargas de trabajo de lectura intensiva dramaticamente

Que se rompe cuando se viola:

Si la cacheabilidad no es explicita:

• Los intermediarios no pueden optimizar
• Los clientes hacen peticiones innecesarias
• Pierdes la mayor palanca de escalado en la web

HTTP/1.1 200 OK
Cache-Control: public, max-age=3600
ETag: "abc123"

{
  "user": {"id": 123, "name": "Alice"}
}

El header Cache-Control le dice a todos: “Cachea esto por 1 hora.” Sin el, el comportamiento de cache es indefinido.

Restriccion 4: Interfaz Uniforme

La restriccion: Todos los componentes se comunican a traves de una interfaz estandarizada.

Esta es la restriccion mas fundamental. Tiene cuatro sub-restricciones:

4.1 Identificacion de Recursos

Cada recurso tiene un identificador unico (URI).

/users/123          <- Usuario 123
/orders/456         <- Pedido 456
/users/123/orders   <- Pedidos pertenecientes al usuario 123

Un recurso es cualquier concepto que puede ser nombrado. Usuarios, pedidos, documentos, busquedas—cualquier cosa.

4.2 Manipulacion a Traves de Representaciones

Los clientes no modifican recursos directamente. Envian representaciones de recursos.

graph LR
    subgraph "Recurso (Abstracto)"
        R[Usuario 123]
    end

    subgraph "Representaciones (Concretas)"
        J[JSON]
        X[XML]
        H[HTML]
    end

    R --> J
    R --> X
    R --> H

    style R fill:#fff3e0
    style J fill:#e3f2fd
    style X fill:#e3f2fd
    style H fill:#e3f2fd

El mismo recurso (Usuario 123) puede tener multiples representaciones:

• JSON para APIs
• XML para sistemas legacy
• HTML para navegadores

El cliente envia una representacion para modificar el recurso:

PUT /users/123 HTTP/1.1
Content-Type: application/json

{"name": "Alice Smith", "email": "[email protected]"}

El servidor actualiza el recurso basandose en esta representacion.

4.3 Mensajes Auto-descriptivos

Cada mensaje contiene suficiente informacion para entender como procesarlo.

GET /users/123 HTTP/1.1
Accept: application/json

---

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=3600

{"id": 123, "name": "Alice"}

El Content-Type te dice como parsear el cuerpo. El Cache-Control te dice como cachearlo. No se requiere conocimiento fuera de banda.

4.4 Hipermedia Como el Motor del Estado de la Aplicacion (HATEOAS)

Aqui es donde REST se pone controversial.

La restriccion: Los clientes deben navegar la aplicacion enteramente a traves de hiperenlaces proporcionados por el servidor.

GET /users/123 HTTP/1.1

---

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 123,
  "name": "Alice",
  "_links": {
    "self": {"href": "/users/123"},
    "orders": {"href": "/users/123/orders"},
    "edit": {"href": "/users/123", "method": "PUT"},
    "delete": {"href": "/users/123", "method": "DELETE"}
  }
}

La respuesta le dice al cliente: “Aqui esta lo que puedes hacer a continuacion.”

Por que importa HATEOAS:

• Los clientes no necesitan URLs hardcodeadas
• El servidor puede cambiar URLs sin romper clientes
• Descubribilidad: nuevas funcionalidades aparecen como nuevos enlaces
• El servidor controla el flujo de navegacion

Por que casi nadie lo implementa:

• Agrega overhead al payload
• Requiere logica de cliente sofisticada
• La mayoria de las APIs tienen documentacion en su lugar
• Las apps moviles prefieren endpoints estaticos por rendimiento

Discutiremos este trade-off mas adelante.

Restriccion 5: Sistema en Capas

La restriccion: La arquitectura puede componerse de capas jerarquicas, cada una solo conociendo la capa con la que interactua directamente.

graph TB
    C[Cliente] --> LB[Balanceador de Carga]
    LB --> CDN[CDN / Cache]
    CDN --> GW[API Gateway]
    GW --> S1[Servicio A]
    GW --> S2[Servicio B]

    style C fill:#e3f2fd
    style LB fill:#fff3e0
    style CDN fill:#fff3e0
    style GW fill:#fff3e0
    style S1 fill:#c8e6c9
    style S2 fill:#c8e6c9

Por que importa:

• Agregar capas de cache sin cambiar clientes o servidores
• Agregar capas de seguridad (API gateway, WAF) transparentemente
• Escalar componentes independientemente
• Reemplazar componentes sin afectar otros

Que se rompe cuando se viola:

Si los clientes necesitan conocer la arquitectura interna (a que servidor conectarse, como se comunican los servicios), has acoplado todo junto. Los cambios se propagan a traves del sistema.

Restriccion 6: Codigo Bajo Demanda (Opcional)

La restriccion: Los servidores pueden extender la funcionalidad del cliente transfiriendo codigo ejecutable.

Esta es la unica restriccion opcional. Ejemplos:

• JavaScript en navegadores web
• Applets de Java (los recuerdas?)
• Modulos WebAssembly

La mayoria de las APIs REST no usan esto. Es principalmente relevante para navegadores.

4. Recursos vs. Representaciones

Esta distincion es fundamental para REST y ampliamente malentendida.

Los Recursos Son Abstractos

Un recurso es cualquier concepto que puede ser nombrado e identificado. Es abstracto—no puedes tocarlo.

Ejemplos de recursos:

• Un usuario especifico (Usuario 123)
• El clima actual en Madrid
• Una version de documento en un punto en el tiempo
• Un resultado de busqueda para “APIs REST”
• El autor de esta guia

Un recurso tiene identidad (URI), pero no es los datos en si.

Las Representaciones Son Concretas

Una representacion es datos concretos que representan el estado actual del recurso.

El mismo recurso puede tener muchas representaciones:

# Representacion JSON
GET /users/123 HTTP/1.1
Accept: application/json

{"id": 123, "name": "Alice", "email": "[email protected]"}

# Representacion XML
GET /users/123 HTTP/1.1
Accept: application/xml

<user><id>123</id><name>Alice</name><email>[email protected]</email></user>

# Representacion HTML (para navegadores)
GET /users/123 HTTP/1.1
Accept: text/html

<html><body><h1>Alice</h1><p>[email protected]</p></body></html>

Mismo recurso, diferentes representaciones.

Por Que Esto Importa

Entender recurso vs. representacion clarifica el diseno de APIs:

Pensamiento incorrecto: “Mi API devuelve objetos de usuario.”

Pensamiento correcto: “Mi API expone recursos de usuario. Los clientes solicitan representaciones en su formato preferido.”

Esto habilita:

• Negociacion de contenido (el cliente solicita formato preferido)
• Multiples clientes (JSON para movil, HTML para web, XML para legacy)
• Representaciones versionadas (mismo recurso, diferentes versiones de esquema)
• Representaciones parciales (parametro fields, sparse fieldsets)

5. El Modelo de Madurez de REST

Leonard Richardson propuso un modelo de madurez para clasificar APIs:

graph TB
    L0[Nivel 0: El Pantano de POX]
    L1[Nivel 1: Recursos]
    L2[Nivel 2: Verbos HTTP]
    L3[Nivel 3: Controles de Hipermedia]

    L0 --> L1
    L1 --> L2
    L2 --> L3

    style L0 fill:#ffccbc
    style L1 fill:#fff9c4
    style L2 fill:#c8e6c9
    style L3 fill:#b3e5fc

Nivel 0: El Pantano de POX

Una URI, un metodo HTTP (usualmente POST). El protocolo HTTP es solo un tunel.

POST /api HTTP/1.1

{"action": "getUser", "userId": 123}

Esto es SOAP, XML-RPC, o “RPC sobre HTTP.” No es REST en absoluto.

Nivel 1: Recursos

Multiples URIs, un metodo. Los recursos estan identificados, pero la semantica HTTP es ignorada.

POST /users/123 HTTP/1.1

{"action": "get"}

POST /users/123 HTTP/1.1

{"action": "delete"}

Tienes recursos, pero todo es POST.

Nivel 2: Verbos HTTP

Multiples URIs, metodos HTTP apropiados. Aqui es donde viven la mayoria de las “APIs REST.”

GET /users/123
POST /users
PUT /users/123
DELETE /users/123

Los metodos HTTP tienen significado semantico. Los codigos de estado se usan correctamente. Esto es “HTTP hecho bien.”

Nivel 3: Controles de Hipermedia (HATEOAS)

Las respuestas incluyen enlaces a acciones relacionadas. La API es auto-descriptiva.

{
  "id": 123,
  "name": "Alice",
  "_links": {
    "self": "/users/123",
    "orders": "/users/123/orders",
    "deactivate": "/users/123/deactivate"
  }
}

Esto es REST completo.

Que Nivel Deberias Apuntar?

Nivel 2 es el punto dulce pragmatico para la mayoria de las APIs:

• Usa HTTP correctamente
• Buena experiencia de desarrollador
• Soporte maduro de herramientas
• Patrones bien entendidos

Nivel 3 es ideal pero costoso:

• Requiere clientes sofisticados
• Aumenta el tamano del payload
• Soporte limitado de herramientas
• La mayoria de los beneficios requieren adopcion del cliente

La mayoria de las APIs publicas exitosas (Stripe, Twilio, GitHub) son Nivel 2. No son “REST puro,” pero son APIs HTTP bien disenadas.

6. Por Que La Mayoria de APIs No Son REST (Y Eso Esta Bien)

Aqui hay una verdad liberadora: no tienes que construir una API REST.

REST es un estilo arquitectonico entre muchos. Optimiza para:

• Sistemas de larga vida
• Muchos clientes independientes
• Evolucionabilidad en el tiempo
• Distribucion a escala web

Si tu sistema no necesita estas propiedades, las restricciones de REST pueden ser overhead.

Cuando REST Tiene Sentido

• APIs publicas consumidas por terceros desconocidos
• Sistemas que deben evolucionar sin romper clientes
• Sistemas distribuidos a gran escala
• APIs que se benefician del caching

Cuando REST Podria No Ser Ideal

• Microservicios internos (gRPC frecuentemente mejor)
• Aplicaciones en tiempo real (WebSockets)
• Consultas complejas (GraphQL)
• Scripts o herramientas simples (solo hazlo funcionar)

El Enfoque Honesto

En lugar de decir “Tenemos una API REST” cuando no la tienes, di:

• “Tenemos una API HTTP siguiendo convenciones tipo REST”
• “Tenemos una API JSON con URLs orientadas a recursos”
• “Seguimos el Nivel 2 del Modelo de Madurez de Richardson”

La precision ayuda a tu equipo a tomar mejores decisiones.

7. Malentendidos Comunes

Abordemos malentendidos frecuentes:

“REST significa CRUD”

No. REST es sobre recursos y representaciones. CRUD (Create, Read, Update, Delete) es una forma de pensar sobre operaciones de recursos, pero REST no lo requiere.

Los recursos pueden soportar operaciones que no mapean a CRUD:

• POST /orders/123/cancel
• POST /documents/456/publish
• POST /users/789/verify-email

Estos son validos en REST si la operacion afecta el estado del recurso.

“REST significa sin versionado”

No. Fielding argumenta que sistemas propiamente RESTful no deberian necesitar versionado porque HATEOAS habilita la evolucion. Pero en la practica, la mayoria de las APIs necesitan versionado porque:

• Son Nivel 2, no Nivel 3
• Los cambios breaking suceden
• Los clientes no siempre se actualizan

El versionado es una necesidad pragmatica para la mayoria de las APIs del mundo real.

“REST significa JSON”

No. REST no especifica un formato de datos. JSON es popular porque:

• Ligero y legible por humanos
• Nativo de JavaScript
• Amplio soporte de herramientas

Pero XML, HTML, o Protocol Buffers son igualmente validos para REST. La clave es auto-descripcion (header Content-Type) y negociacion de contenido (header Accept).

“REST es la unica forma de construir APIs”

Definitivamente no. REST es una herramienta en tu kit de herramientas. Considera:

• GraphQL para consultas complejas con necesidades de datos variables
• gRPC para servicios internos de alto rendimiento
• WebSockets para comunicacion bidireccional en tiempo real
• Server-Sent Events para push del servidor

Elige basandote en tus requerimientos, no en dogma.

8. Conclusiones Practicas

Asi es como aplicar este conocimiento:

Al Disenar APIs

1. Se honesto sobre tus restricciones. Estas construyendo REST completo o “HTTP con JSON”? Ambos son validos.

2. Prioriza el Nivel 2. Usa metodos HTTP correctamente, devuelve codigos de estado apropiados, haz que los recursos sean identificables. Esto te da el 80% del beneficio.

3. Considera HATEOAS selectivamente. Agregar enlaces a recursos relacionados ayuda a la descubribilidad sin comprometerte con HATEOAS completo.

4. Manten statelessness. Esta es la restriccion mas valiosa. Nunca almacenes estado de sesion en el servidor.

5. Habilita el caching. Agrega headers Cache-Control. Esto escala tu trafico de lectura.

Al Evaluar APIs

Haz estas preguntas:

• Estan los recursos claramente identificados por URIs?
• Los metodos HTTP coinciden con su semantica?
• Las respuestas son auto-descriptivas (Content-Type, codigos de estado)?
• La API es stateless?
• Las respuestas pueden ser cacheadas?

Si la respuesta es si a todas, tienes una API HTTP bien disenada—incluso si no es “REST completo.”

Al Discutir REST

Usa lenguaje preciso:

• “RESTful” -> API siguiendo todas las restricciones de REST incluyendo HATEOAS
• “REST-like” o “tipo REST” -> API usando convenciones REST (Nivel 2)
• “API HTTP” -> API usando HTTP correctamente sin claims de REST

Esto previene debates interminables sobre que es o no es REST.

Que Sigue

Esta guia cubrio REST como estilo arquitectonico—lo que realmente significa, por que existe, y como evaluarlo.

Para temas mas profundos como:

• Modelar recursos complejos y relaciones
• Cuando romper conscientemente las restricciones de REST
• Refactorizar APIs mal disenadas
• Patrones avanzados de HATEOAS

Ve el proximo curso: Diseno REST Profesional: Criterio y Trade-offs.

Terminos de Vocabulario Relacionados

Profundiza tu entendimiento:

• REST - El estilo arquitectonico en profundidad
• Resource - La abstraccion central de REST
• Stateless - Por que y como eliminar estado de sesion del lado del servidor
• RESTful API - Que hace que una API sea verdaderamente RESTful
• Client-Server - El patron fundamental de separacion
• HTTP - El protocolo que implementa REST en la web