Arquitectura REST

Que Es REST? #

REST (Representational State Transfer) es un estilo arquitectonico para disenar aplicaciones en red, definido por Roy Fielding en su disertacion doctoral del 2000. No es un protocolo ni un estandar — es un conjunto de restricciones que, al aplicarse a servicios web, los hacen escalables, simples y confiables.

REST se ha convertido en el enfoque dominante para APIs web porque aprovecha el protocolo HTTP existente, haciendolo facil de entender e implementar. Cuando las personas dicen “REST API” o “API RESTful”, se refieren a un servicio web que sigue los principios arquitectonicos REST.

REST vs. Otros Estilos #

Antes de que REST se convirtiera en dominante, la mayoria de los servicios web usaban SOAP (Simple Object Access Protocol), que requeria mensajes XML, esquemas estrictos y a menudo era complejo. REST simplifico todo usando metodos HTTP estandar y permitiendo formatos de datos flexibles (principalmente JSON).

Las Seis Restricciones REST #

Roy Fielding definio seis restricciones que una API debe seguir para considerarse RESTful. Entenderlas es esencial para el testing porque las violaciones de estas restricciones a menudo indican problemas de diseno o bugs potenciales.

1. Separacion Cliente-Servidor #

El cliente (frontend) y el servidor (backend) deben ser independientes. El cliente solo sabe como hacer requests; el servidor solo sabe como procesarlos y retornar respuestas. Esta separacion permite que cada uno evolucione independientemente.

Implicacion para testing: Puedes testear la API independientemente de cualquier cliente especifico. Una app movil, una app web o un comando cURL deberian obtener los mismos resultados para el mismo request.

2. Stateless (Sin Estado) #

Cada request del cliente debe contener toda la informacion que el servidor necesita para procesarlo. El servidor no almacena estado de sesion entre requests. Tokens de autenticacion, preferencias de usuario y cualquier contexto deben enviarse con cada request.

Implicacion para testing: Puedes enviar cualquier request de forma aislada sin necesidad de enviar requests previos primero (excepto por dependencias de datos). Cada request deberia ser verificable independientemente.

3. Cacheable #

Las respuestas deben indicar si pueden ser cacheadas. El caching adecuado reduce la carga del servidor y mejora el rendimiento. HTTP proporciona headers de cache (Cache-Control, ETag, Last-Modified) para manejar esto.

Implicacion para testing: Verifica que los headers de cache esten configurados correctamente. Los GET requests para datos estaticos deberian ser cacheables; las respuestas POST/PUT/DELETE tipicamente no deberian serlo.

4. Interfaz Uniforme #

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

• Identificacion de recursos — cada recurso tiene un URI unico (ej., /users/42)
• Manipulacion de recursos a traves de representaciones — los clientes trabajan con representaciones (JSON, XML) de recursos, no con los recursos directamente
• Mensajes auto-descriptivos — cada mensaje incluye suficiente informacion para describir como procesarlo (Content-Type, methods)
• HATEOAS — las respuestas incluyen enlaces a acciones relacionadas

5. Sistema en Capas #

El cliente no puede saber si esta conectado directamente al servidor o a un intermediario (load balancer, CDN, API gateway). Cada capa solo conoce la capa con la que interactua.

Implicacion para testing: Testea a traves de la infraestructura real (incluyendo load balancers y API gateways) en ambientes de staging, no solo contra el servidor desnudo.

6. Codigo Bajo Demanda (Opcional) #

Los servidores pueden opcionalmente enviar codigo ejecutable (como JavaScript) a los clientes. Esta es la unica restriccion opcional y rara vez se usa en contextos de API.

Diseno de Recursos y Estructura de URLs #

Uno de los aspectos mas visibles de REST es como se estructuran las URLs. Las URLs RESTful representan recursos (sustantivos), no acciones (verbos).

Convenciones de Nomenclatura de Recursos #

Bueno (RESTful):
GET    /users              → Listar todos los usuarios
GET    /users/42           → Obtener usuario 42
POST   /users              → Crear un nuevo usuario
PUT    /users/42           → Actualizar usuario 42
DELETE /users/42           → Eliminar usuario 42

Malo (no RESTful):
GET    /getUsers
POST   /createUser
GET    /getUserById?id=42
POST   /deleteUser

Recursos Anidados #

Cuando los recursos tienen relaciones, anidalos logicamente:

GET /users/42/orders           → Pedidos del usuario 42
GET /users/42/orders/7         → Pedido 7 del usuario 42
POST /users/42/orders          → Crear un pedido para usuario 42

Query Parameters para Filtrado #

Usa query parameters para filtrado, ordenamiento y paginacion — no para identificar recursos:

GET /users?role=admin          → Filtrar usuarios por rol
GET /users?sort=name&order=asc → Ordenar usuarios por nombre
GET /users?page=2&limit=20     → Paginar resultados
GET /orders?status=pending&from=2025-01-01  → Filtros combinados

Modelo de Madurez REST (Richardson) #

Leonard Richardson definio un modelo de madurez que clasifica las APIs por que tan bien implementan los principios REST. Esto es util para evaluar las APIs que testeas.

Nivel 0: El Pantano de POX #

Un solo endpoint, un solo metodo HTTP (generalmente POST), acciones codificadas en el body del request. Esencialmente RPC sobre HTTP.

POST /api
Body: { "action": "getUser", "userId": 42 }

Nivel 1: Recursos #

Diferentes URLs para diferentes recursos, pero aun usando un solo metodo HTTP.

POST /users/42
Body: { "action": "get" }

Nivel 2: Metodos HTTP #

Uso adecuado de metodos HTTP (GET, POST, PUT, DELETE) con URLs basadas en recursos. La mayoria de las APIs que dicen ser RESTful estan en este nivel.

GET    /users/42
POST   /users
PUT    /users/42
DELETE /users/42

Nivel 3: HATEOAS (Controles Hypermedia) #

Las respuestas incluyen enlaces a acciones y recursos relacionados. Este es el nivel mas alto de madurez REST y rara vez se implementa completamente.

{
  "id": 42,
  "name": "Alice",
  "links": [
    { "rel": "self", "href": "/users/42" },
    { "rel": "orders", "href": "/users/42/orders" },
    { "rel": "update", "href": "/users/42", "method": "PUT" },
    { "rel": "delete", "href": "/users/42", "method": "DELETE" }
  ]
}

Testing de Conformidad REST #

Al testear una API, evalua su adherencia a los principios REST con esta checklist:

Tests de Estructura de URL #

• Las URLs usan sustantivos (recursos), no verbos (acciones)
• Los recursos estan en plural (/users, no /user)
• Los recursos anidados reflejan relaciones reales
• Los query parameters se usan para filtrado, no para identificacion de recursos
• Las URLs son en minusculas y usan guiones para legibilidad (/order-items, no /orderItems)

Tests de Metodos HTTP #

• Los GET requests nunca modifican datos
• POST crea nuevos recursos y retorna 201
• PUT reemplaza el recurso completo
• PATCH actualiza parcialmente un recurso
• DELETE elimina un recurso y retorna 204 o 200

Tests de Statelessness #

• Los requests funcionan sin configuracion previa de sesion
• La autenticacion se envia con cada request (no se almacena en el servidor)
• Enviar el mismo request dos veces produce el mismo resultado (idempotencia para GET, PUT, DELETE)

Tests de Formato de Respuesta #

• El header Content-Type coincide con el formato real de la respuesta
• Las respuestas JSON siguen una estructura consistente
• Las respuestas de error incluyen mensajes significativos y status codes apropiados
• Las respuestas de colecciones incluyen metadata de paginacion

Anti-Patrones REST Comunes #

Que buscar al testear:

Ejercicio Practico #

Analiza estas tres APIs publicas en cuanto a conformidad REST:

1. JSONPlaceholder (https://jsonplaceholder.typicode.com)

   • Envia GET /posts, GET /posts/1, POST /posts, PUT /posts/1, DELETE /posts/1
   • Califica su nivel de madurez REST (0-3)

2. GitHub API (https://api.github.com)

   • Examina la respuesta de GET / — incluye enlaces HATEOAS?
   • Revisa /repos/{owner}/{repo}/issues para anidamiento adecuado de recursos

3. Crea un reporte de conformidad REST cubriendo: convenciones de URL, uso de metodos HTTP, codigos de respuesta, statelessness y presencia de HATEOAS

Puntos Clave #

• REST es un estilo arquitectonico con seis restricciones: cliente-servidor, stateless, cacheable, interfaz uniforme, sistema en capas y codigo bajo demanda
• Las URLs RESTful usan sustantivos (recursos) en lugar de verbos (acciones) y siguen patrones consistentes
• El Modelo de Madurez de Richardson clasifica las APIs desde Nivel 0 (estilo RPC) hasta Nivel 3 (HATEOAS completo)
• La mayoria de las APIs en produccion operan en Nivel 2 — recursos apropiados y metodos HTTP
• Testear la conformidad REST ayuda a identificar problemas de diseno, inconsistencias y bugs potenciales tempranamente