APIs REST vs GraphQL: cuándo usar cada una sin caer en el hype

GraphQL apareció en el radar de muchos equipos como “la evolución de REST”. La narrativa era simple: REST tiene problemas (over-fetching, under-fetching, versioning), GraphQL los resuelve. Usa GraphQL.

La realidad, como siempre, es más matizada.

Los problemas reales de REST (y cuándo importan)

REST tiene problemas conocidos:

Over-fetching: un endpoint /usuarios/:id devuelve nombre, email, foto, dirección, configuraciones, historial — cuando el cliente solo necesita el nombre y el email. Estás transfiriendo más datos de los necesarios.

Under-fetching: para mostrar un perfil completo, el cliente necesita llamar /usuarios/:id, luego /usuarios/:id/pedidos, luego /productos/:id para cada pedido. Tres requests donde podría ser uno.

Versioning: cuando cambias la estructura de una respuesta, necesitas crear /api/v2/... para no romper clientes existentes. Con el tiempo, mantienes múltiples versiones.

Estos son problemas reales. La pregunta es: ¿son problemas reales para tu caso?

Cuándo REST es la elección correcta

Para la mayoría de APIs de aplicaciones web y móviles, REST sigue siendo la opción más pragmática.

CRUD simple: si tu API es mayormente crear, leer, actualizar y eliminar recursos — usuarios, productos, pedidos — REST es natural y fácil de entender para cualquier desarrollador.

Equipos pequeños: el overhead de configurar GraphQL (schema, resolvers, herramientas de introspección, manejo de errores diferente) tiene un costo real en tiempo de desarrollo. Para equipos de 2-3 personas, ese tiempo generalmente no se justifica.

APIs públicas: REST con buena documentación (OpenAPI/Swagger) es más accesible para desarrolladores externos que GraphQL. Stripe, Twilio, GitHub usan REST porque es el estándar que cualquier desarrollador puede integrar.

Caché HTTP: REST puede aprovechar el caché HTTP estándar. Una respuesta de GET /productos se puede cachear fácilmente en el browser, en un CDN o en un proxy. GraphQL, al usar POST para queries, no se beneficia del caché HTTP de forma nativa.

Cuándo GraphQL resuelve un problema real

Múltiples clientes con necesidades diferentes: una app móvil que necesita datos mínimos (para ahorrar ancho de banda) y un dashboard web que necesita datos completos. Con REST, necesitas endpoints específicos para cada caso o aceptar over-fetching. Con GraphQL, cada cliente pide exactamente lo que necesita.

Datos altamente relacionados y anidados: un feed social donde cada post tiene un autor, el autor tiene seguidores, cada seguidor tiene sus posts… Navegar esa estructura con REST requiere múltiples requests o endpoints personalizados. GraphQL lo resuelve con una sola query.

Desarrollo frontend/backend paralelo: el equipo de frontend puede comenzar a trabajar con un schema definido sin esperar a que el backend implemente todos los endpoints específicos.

Sistemas con muchas entidades relacionadas: plataformas complejas tipo ERP o CRM donde las relaciones entre entidades son profundas y los reportes requieren combinar muchos recursos.

Lo que no te dicen de GraphQL

La complejidad se mueve al servidor: el over-fetching desaparece del cliente, pero el servidor ahora tiene que resolver consultas arbitrariamente complejas. Sin control, un cliente puede hacer una query que tarda minutos y destruye la base de datos.

El manejo de errores es diferente (y confuso al inicio): GraphQL siempre responde con status 200 — los errores van dentro del JSON de respuesta. Esto rompe las convenciones de monitoreo y logging que los equipos tienen para REST.

El caché es más complejo: sin el caché HTTP estándar, necesitas soluciones específicas (Apollo Client cache, Relay). Son buenas herramientas, pero añaden complejidad.

N+1 queries: sin cuidado, GraphQL puede generar docenas de queries a la base de datos para resolver una sola petición. El patrón DataLoader existe para resolverlo, pero hay que implementarlo.

Nuestra decisión en proyectos reales

Para el 80% de proyectos usamos REST. Los criterios:

• CRUD estándar → REST
• API consumida por un solo cliente con necesidades estables → REST
• Equipo pequeño, tiempo limitado → REST

Elegimos GraphQL cuando:

• Múltiples tipos de clientes con necesidades muy diferentes
• El producto es una plataforma donde terceros construirán sobre nuestra API
• Las relaciones entre entidades son profundas y el equipo tiene experiencia con GraphQL

Lo que nunca hacemos: elegir GraphQL porque “es lo moderno” o REST porque “es lo que siempre usamos”. La arquitectura tiene que servir al producto, no al revés.