Herramientas y Guías 3 minutos de lectura

REST vs RESTful: diferencias reales que casi nadie explica bien

Introducción

En entrevistas técnicas, documentación y charlas es habitual escuchar “API REST” y “API RESTful” como si fueran sinónimos. No lo son.

La confusión no es solo semántica: lleva a APIs inconsistentes, difíciles de mantener y con comportamientos impredecibles para clientes humanos y máquinas.

Entender la diferencia no es postureo arquitectónico: es diseñar mejor.

Qué es REST (el concepto original)

REST (Representational State Transfer) no es un estándar, ni un protocolo, ni “usar JSON sobre HTTP”. Es un estilo arquitectónico definido por Roy Fielding.

Para que una arquitectura sea REST debe cumplir una serie de restricciones:

  • Arquitectura cliente-servidor.
  • Comunicación stateless.
  • Capacidad de cacheo.
  • Interfaz uniforme.
  • Sistema en capas.
  • (Opcional) Código bajo demanda.

Restricciones REST explicadas con ejemplos conceptuales

1) Cliente-servidor

El cliente (frontend, móvil, integrador) y el servidor (API) tienen responsabilidades separadas. El cliente se ocupa de interfaz/consumo; el servidor de reglas, datos y seguridad. Eso permite evolucionar cada parte sin romper la otra.

2) Stateless (sin estado en servidor)

“Stateless” no significa “sin sesión”, significa que cada request debe traer lo necesario. Ejemplo: no dependas de que el servidor recuerde “en qué paso ibas”. Si necesitas autenticación, el token/cabeceras deben ser suficientes para procesar la petición.

3) Cacheable

REST contempla que algunas respuestas puedan cachearse. No es obligatorio en todas, pero sí relevante cuando hay lecturas frecuentes. Ejemplo: GET /productos puede cachearse con cabeceras; POST /pedidos no.

4) Interfaz uniforme

Es el núcleo de REST: recursos bien definidos, métodos HTTP con semántica, representación coherente y códigos de estado correctos. Ejemplo: GET /usuarios/123 devuelve “el usuario”; no “un mensaje genérico” y no “acciones”.

5) Sistema en capas

Puedes tener capas intermedias (proxy, gateway, caché, WAF) sin que el cliente lo sepa. Ejemplo: un API Gateway delante de microservicios sin cambiar el contrato de la API.

6) Código bajo demanda (opcional)

Es la restricción menos usada hoy (por seguridad y mantenimiento). Sería, por ejemplo, enviar código ejecutable al cliente (scripts). En la práctica, casi nadie lo considera requisito en APIs modernas.

Qué significa realmente que una API sea RESTful

Una API es RESTful cuando respeta de forma consistente los principios REST en su diseño y comportamiento.

REST es la teoría. RESTful es la aplicación práctica, con todas sus implicaciones.

REST vs RESTful vs “REST-like”

Aspecto REST (teoría) RESTful REST-like habitual
Modelo Estilo arquitectónico Implementación coherente Convención informal
Recursos Obligatorios Bien definidos Mezcla recursos y acciones
Métodos HTTP Semánticos Usados correctamente POST para todo
Estado Stateless Stateless real Estado implícito

Cuándo importa ser “RESTful”… y cuándo no

Cuándo SÍ importa (mucho)

  • APIs públicas o con múltiples clientes (web, móvil, terceros): coherencia y predictibilidad reducen fricción.
  • Integraciones a largo plazo: cuanto más dura un contrato, más duele romperlo.
  • Ecosistemas con muchos equipos: RESTful actúa como “idioma común” para evitar APIs caóticas.
  • Necesidad de caché y escalado de lecturas: REST facilita cacheabilidad cuando se diseña bien.

Cuándo NO es crítico ser “REST puro”

  • APIs internas de bajo impacto con un solo cliente controlado (por ejemplo, un BFF simple).
  • Sistemas orientados a eventos donde el flujo principal no es request/response.
  • Casos con alta complejidad de consulta donde GraphQL puede encajar mejor.
  • Operaciones muy específicas (RPC real) donde la semántica de “recursos” no encaja sin forzar el diseño.

El criterio Gondor aquí es simple: no conviertas REST en religión. Si el coste de “ser RESTful” supera el beneficio, aplica REST-like coherente y documentado.

Tabla de decisión rápida

Tu contexto Recomendación Por qué
API pública / muchos clientes RESTful Contrato estable, semántica clara, reduce fricción y sorpresas
API interna con 1–2 clientes controlados REST-like coherente Menos burocracia, suficiente si hay disciplina y documentación
Operaciones complejas de consulta (datos muy “grafosos”) GraphQL (si se gobierna bien) Consultas flexibles, reduce over/under-fetching
Acciones muy específicas y transaccionales RPC explícito (bien nombrado) Mejor ser honesto que “fingir REST” con endpoints raros

Qué NO es REST (errores comunes)

  • Usar JSON o HTTP.
  • Tener endpoints.
  • Usar Spring Boot, Express o FastAPI.
  • Exponer acciones como URLs.

Ejemplos incorrectos: 


POST /login
POST /activarUsuario
GET /getAllProducts

Principios RESTful explicados con ejemplos

1. Recursos, no acciones

En REST todo es un recurso: 


/usuarios/123
/productos/42
/pedidos/2024

La acción la define el método HTTP, no la URL.

2. Uso correcto de métodos HTTP

Método Uso correcto
GET Obtener representación
POST Crear nuevo recurso
PUT Reemplazar recurso completo
PATCH Modificar parcialmente
DELETE Eliminar recurso

3. Stateless (de verdad)

Cada petición debe ser autosuficiente. El servidor no debe recordar contexto entre llamadas.

Tokens, cabeceras y payloads contienen toda la información necesaria.

4. Respuestas predecibles y semánticas

No solo importa el cuerpo, también:

  • Códigos HTTP correctos.
  • Estructuras consistentes.
  • Errores bien definidos.

Y HATEOAS… ¿es obligatorio?

Técnicamente, REST completo incluye HATEOAS. En la práctica, muchas APIs RESTful prescinden de él por complejidad.

No usar HATEOAS no invalida una API, pero sí la aleja del REST “puro”.

Anti-patrones comunes: RPC disfrazado de REST

Muchísimas APIs dicen ser REST, pero en realidad hacen RPC (llamar acciones) con URLs bonitas. No es “ilegal”, pero sí suele traer inconsistencias y clientes frustrados.

Señales típicas

  • Verbos en la URL: /activarUsuario, /getAllProducts.
  • POST para todo: se usa POST incluso para lecturas, borrados o cambios simples.
  • Acciones “tunelizadas”: POST /usuarios/123/doSomething sin semántica clara.
  • Estados ocultos: el servidor “recuerda pasos” sin que el request lo exprese.

Qué hacer en su lugar

  • Si es recurso: modela recurso y usa métodos HTTP correctamente.
  • Si es acción legítima: modela un recurso de “operación” (ej.: /usuarios/123/activacion) o asume RPC y documéntalo.
  • Define un estándar de errores y respuestas: consistencia > dogma.

Checklist rápida

  1. ¿Tus URLs representan recursos?
  2. ¿Usas métodos HTTP con semántica correcta?
  3. ¿Cada request es stateless?
  4. ¿Tus respuestas son coherentes y predecibles?
  5. ¿Evitas exponer acciones en la URL?

Conclusión

REST no es enviar JSON ni seguir una moda. Es una forma concreta de pensar y diseñar APIs.

RESTful es aplicar esa filosofía con coherencia, sin dogmas pero con rigor, para construir sistemas claros, mantenibles y fáciles de consumir.

¿Tu empresa necesita modernizarse sin perderse en tecnopalabrería?

En Gondor Solutions te ayudamos a elegir tecnología útil, reducir complejidad y construir sistemas que funcionan en la vida real.

Impulsa tu negocio