APIs REST vs GraphQL: cuando usar cada una

GitHub migro su API publica de REST a GraphQL en 2017. Shopify hizo lo mismo con su API de storefront. Pero Amazon, Google Cloud y la mayoria de servicios de infraestructura siguen usando REST exclusivamente. Netflix abandono Falcor (su alternativa interna a GraphQL) y ahora usa una combinacion de REST y GraphQL segun el caso de uso.

Estos datos desmontan la narrativa simplista de que GraphQL es “el sucesor de REST.” No lo es. Son herramientas diferentes que resuelven problemas diferentes. La pregunta correcta no es “cual es mejor” sino “cual encaja mejor en mi contexto.”

En esta guia vas a encontrar una comparativa tecnica honesta, con trade-offs reales, y un framework de decision que puedes aplicar a tu proximo proyecto.

Que es REST y que es GraphQL

REST: el estandar de facto

REST (Representational State Transfer) es un estilo arquitectonico para disenar APIs. No es un protocolo ni una especificacion formal. Es un conjunto de principios:

Recursos: Todo se modela como recursos identificados por URLs. Un usuario es /users/123, un pedido es /orders/456.

Metodos HTTP: Las operaciones se mapean a metodos HTTP estandar: GET para leer, POST para crear, PUT/PATCH para actualizar, DELETE para eliminar.

Sin estado: Cada peticion contiene toda la informacion necesaria para ser procesada. El servidor no mantiene estado entre peticiones.

Respuestas estructuradas: Tipicamente JSON, con codigos de estado HTTP que indican el resultado (200 OK, 404 Not Found, 500 Internal Server Error).

Un endpoint REST tipico:

GET /api/users/123

Devuelve todos los campos del usuario 123: nombre, email, direccion, historial de pedidos, preferencias… Todo. Siempre.

GraphQL: consultas a la carta

GraphQL es un lenguaje de consulta para APIs creado por Facebook en 2012 y liberado como open source en 2015. Su principio fundamental es que el cliente define exactamente que datos necesita.

Schema tipado: La API define un schema con tipos, campos y relaciones. El cliente sabe exactamente que puede pedir.

Un unico endpoint: En lugar de multiples URLs, todo pasa por un unico endpoint (tipicamente /graphql).

Consultas flexibles: El cliente especifica exactamente que campos necesita en cada peticion.

Una consulta GraphQL tipica:

query {
  user(id: "123") {
    name
    email
    orders(last: 5) {
      id
      total
    }
  }
}

Devuelve solo nombre, email y los ultimos 5 pedidos del usuario. Nada mas, nada menos.

Las diferencias reales que importan

Over-fetching y under-fetching

El problema con REST: Cuando pides un recurso, obtienes todos sus campos. Si solo necesitas el nombre y el email de un usuario, igualmente recibes la direccion, las preferencias, el historial y todo lo demas. Esto es over-fetching.

Lo contrario tambien ocurre. Si necesitas datos de un usuario y sus pedidos, necesitas hacer dos peticiones: una a /users/123 y otra a /users/123/orders. Esto es under-fetching, y genera el problema del N+1: para mostrar una lista de 20 usuarios con sus pedidos, necesitas 21 peticiones HTTP.

La solucion de GraphQL: El cliente pide exactamente lo que necesita. Un campo, veinte campos o datos de multiples entidades relacionadas, todo en una sola peticion.

Pero hay matices:

REST puede mitigar el over-fetching con campos sparse (por ejemplo, ?fields=name,email). OpenAPI soporta esta funcionalidad. No es tan elegante como GraphQL, pero funciona.

REST puede mitigar el under-fetching con includes (por ejemplo, ?include=orders). Es una solucion parcial que anade complejidad al endpoint.

GraphQL introduce el riesgo de under-querying: el cliente puede pedir demasiados pocos datos y necesitar hacer consultas adicionales. Tambien introduce el riesgo de over-querying: consultas que piden datos profundamente anidados pueden ser mas costosas que el equivalente REST.

Rendimiento y caching

REST tiene ventaja en caching. Las URLs son identificadores unicos perfectos para caches HTTP. Los CDNs, proxies y navegadores cachean respuestas REST de forma nativa. Si pides GET /api/products/123, la respuesta se puede cachear a todos los niveles.

GraphQL complica el caching. Como todas las peticiones van al mismo endpoint (POST /graphql), los caches HTTP estandar no funcionan. Necesitas caching a nivel de aplicacion (Apollo Client, urql) o a nivel de resolucion de campos.

Datos reales:

• Una API REST bien cacheada puede responder en 5-15ms desde CDN
• Una consulta GraphQL tipica tarda 50-200ms desde el servidor
• Para APIs publicas con alto trafico de lectura, la diferencia de caching es significativa
• Para APIs internas con datos que cambian frecuentemente, la diferencia es irrelevante

Complejidad del backend

REST es mas simple de implementar. Cada endpoint es una funcion que lee o escribe datos. La logica esta localizada y es facil de entender.

GraphQL anade complejidad significativa:

• Necesitas definir y mantener un schema tipado
• Los resolvers pueden generar problemas de rendimiento si no se optimizan (problema N+1 a nivel de resolucion)
• Necesitas herramientas adicionales como DataLoader para batch queries
• La autorizacion es mas compleja (tienes que controlar acceso a nivel de campo, no solo de endpoint)
• El monitoring y debugging es mas dificil (todas las peticiones son POST al mismo endpoint)

Dato revelador: Segun la encuesta State of JavaScript 2024, el 42% de los desarrolladores que usan GraphQL reportan que la complejidad del servidor es el mayor desafio. Solo el 18% reporta problemas con el over-fetching de REST.

Experiencia del frontend

GraphQL mejora la experiencia del frontend significativamente:

• El frontend puede pedir exactamente los datos que necesita sin esperar cambios en el backend
• Los tipos generados automaticamente (TypeScript codegen) eliminan errores de integracion
• Herramientas como Apollo DevTools facilitan el debugging
• Los fragmentos permiten reutilizar patrones de consulta

REST requiere mas coordinacion:

• El frontend depende de la estructura de los endpoints del backend
• Cambios en los datos necesarios requieren cambios en el backend (nuevo endpoint o modificar uno existente)
• Los tipos hay que definirlos manualmente o generar desde OpenAPI

Pero atencion: Si tu equipo de backend y frontend son las mismas personas (comun en proyectos pequenos), la ventaja de GraphQL se reduce. La coordinacion no es un problema cuando te coordinas contigo mismo.

Evolucion de la API

REST maneja la evolucion con versionado. /api/v1/users y /api/v2/users pueden coexistir. Es simple pero puede llevar a mantener multiples versiones.

GraphQL evoluciona sin versionado. Puedes anadir campos nuevos sin romper clientes existentes. Puedes deprecar campos y eliminarlos gradualmente. No necesitas versiones porque el cliente solo pide lo que usa.

La ventaja de GraphQL aqui es real, especialmente para APIs publicas con muchos clientes que no puedes controlar. Para APIs internas donde controlas todos los clientes, el versionado de REST es suficiente.

Cuando usar REST

APIs publicas con alto trafico

Si estas construyendo una API que sera consumida por muchos clientes externos y el trafico de lectura es alto, REST con caching agresivo es dificil de superar.

Ejemplos: APIs de datos (clima, financieros, geograficos), APIs de contenido (CMS headless), APIs de infraestructura.

Equipos con experiencia en REST

Si tu equipo conoce REST bien y no tiene experiencia con GraphQL, la curva de aprendizaje de GraphQL (server-side especialmente) puede retrasar el proyecto 2-4 semanas. Para proyectos con deadline ajustado, esto es un riesgo real.

Operaciones CRUD simples

Si tu API es basicamente CRUD (crear, leer, actualizar, eliminar) sin relaciones complejas entre entidades, REST es mas directo. No necesitas la flexibilidad de GraphQL si tus consultas son predecibles.

Microservicios y comunicacion entre servicios

La comunicacion servicio-a-servicio es diferente a la comunicacion cliente-servidor. Los servicios saben exactamente que datos necesitan de otros servicios. GraphQL no aporta ventaja aqui, y anade latencia por la capa de resolucion.

Para comunicacion entre servicios: REST, gRPC o mensajeria asincrona.

Cuando usar GraphQL

Aplicaciones con UI complejas

Aplicaciones tipo dashboard, plataformas de datos o interfaces ricas que necesitan combinar datos de multiples fuentes en una sola vista. GraphQL permite al frontend obtener exactamente los datos que necesita sin orquestar multiples llamadas REST.

APIs consumidas por multiples clientes

Si tu API la consumen una web, una app movil y quiza terceros, cada cliente necesita datos diferentes. Con REST, terminas con endpoints personalizados por cliente o con over-fetching generalizado. GraphQL resuelve esto de forma natural.

Equipos donde frontend y backend trabajan de forma independiente

GraphQL actua como contrato entre equipos. El frontend puede avanzar con datos mock mientras el backend implementa los resolvers. El schema es la documentacion viva.

Rapid prototyping con schema-first

Si empiezas por el schema antes de implementar, puedes validar la estructura de datos con stakeholders antes de escribir una linea de codigo de backend. Herramientas como Apollo Sandbox permiten explorar el schema y probar consultas.

El enfoque hibrido: REST y GraphQL juntos

Backend for Frontend (BFF) con GraphQL

Un patron cada vez mas comun: usar REST para la comunicacion entre servicios backend y GraphQL como capa de agregacion para el frontend.

Como funciona:

1. Los microservicios exponen APIs REST internas
2. Un servicio GraphQL actua como gateway que agrega datos de multiples servicios REST
3. El frontend consume la API GraphQL

Ventajas:

• Cada capa usa la herramienta mas adecuada
• Los microservicios mantienen la simplicidad de REST
• El frontend obtiene la flexibilidad de GraphQL
• El caching funciona a nivel de servicio REST

Desventajas:

• Una capa adicional de infraestructura
• Mas complejidad operativa
• Necesitas equipo con experiencia en ambas tecnologias

Federation: GraphQL distribuido

Apollo Federation permite que multiples servicios contribuyan a un unico schema GraphQL. Cada servicio define su parte del schema, y un gateway los combina.

Cuando considerar Federation:

• Multiples equipos trabajando en diferentes dominios
• Schema complejo que seria inmanejable en un solo servicio
• Necesidad de mantener autonomia de equipos

Cuando evitarla:

• Equipos pequenos (menos de 3 equipos backend)
• Schemas simples
• Cuando la complejidad de Federation supera el beneficio

Rendimiento: datos reales

Benchmarks tipicos

Estas cifras son orientativas y dependen enormemente de la implementacion:

Consideraciones de rendimiento

Para REST:

• Implementa caching HTTP agresivo (Cache-Control, ETag)
• Usa campos sparse cuando sea posible
• Considera paginacion con cursor en lugar de offset
• Comprime respuestas con gzip/brotli

Para GraphQL:

• Implementa DataLoader para evitar problemas N+1
• Limita la profundidad de las consultas para evitar abusos
• Usa persisted queries para mejorar el caching
• Implementa cost analysis para controlar consultas costosas

Framework de decision

Preguntas clave

Responde estas preguntas para tu proyecto:

1. Tienes multiples clientes con necesidades diferentes? Si la respuesta es si, GraphQL tiene ventaja.
2. Tu API es mayoritariamente CRUD simple? Si la respuesta es si, REST es mas directo.
3. El caching HTTP es critico para tu rendimiento? Si la respuesta es si, REST es mas simple.
4. El frontend necesita combinar datos de multiples fuentes? Si la respuesta es si, GraphQL reduce la complejidad del frontend.
5. Tu equipo tiene experiencia con GraphQL? Si la respuesta es no, anade 2-4 semanas de curva de aprendizaje.
6. Es una API publica o interna? APIs publicas con muchos consumidores se benefician mas de GraphQL.

Tabla de decision rapida

Errores comunes al elegir

Elegir GraphQL por hype

“Todo el mundo esta migrando a GraphQL” no es un argumento tecnico. Evalua tu contexto. Si tu equipo de 3 personas construye una API CRUD para un solo cliente web, GraphQL anade complejidad sin beneficio proporcional.

Subestimar la complejidad del servidor GraphQL

La experiencia del frontend con GraphQL es excelente. La experiencia del backend puede ser compleja: schemas, resolvers, DataLoaders, autorizacion a nivel de campo, monitoring… Todo esto necesita tiempo y experiencia.

No considerar el enfoque hibrido

REST vs GraphQL no tiene que ser una decision binaria. Muchos proyectos exitosos usan ambos: REST para operaciones simples y comunicacion entre servicios, GraphQL para consultas complejas del frontend.

Ignorar el coste de migracion

Si ya tienes una API REST funcionando, migrar a GraphQL tiene un coste significativo. No migres por moda. Migra cuando los problemas de over-fetching o under-fetching esten causando problemas reales y medibles.

Conclusion

REST y GraphQL son herramientas, no identidades. La mejor API es la que resuelve los problemas de tu equipo y tus usuarios con la menor complejidad posible.

Tres principios para decidir:

1. Empieza con REST. Si no tienes razones claras para usar GraphQL, REST es mas simple, mas conocido y mas facil de operar.
2. Migra a GraphQL cuando tengas problemas reales. Si el over-fetching causa problemas de rendimiento, si multiples clientes necesitan datos diferentes, o si la coordinacion frontend-backend es un cuello de botella, GraphQL los resuelve.
3. Considera el enfoque hibrido. No tiene que ser uno u otro. Usa cada herramienta donde mejor encaja.

Si necesitas ayuda para disenar la arquitectura de APIs de tus proyectos de software a medida, en NERVICO tenemos experiencia con ambos enfoques y podemos ayudarte a elegir el que mejor se adapte a tu contexto.