GraphQL explicado a alguien que lleva años haciendo REST
2026-10-27 · 8 min de lectura
Contenido
Llevo muchos años consumiendo y diseñando APIs REST. Suficientes como para que GraphQL me pareciera, durante bastante tiempo, una moda de frontends. Esta entrada es lo que me habría gustado leer entonces: sin evangelizar, con las pegas delante, y partiendo de lo que ya sé de REST.
Es la primera de una serie de tres. Esta es la teoría; en las dos siguientes monto un laboratorio con PostgreSQL y expongo los mismos datos por REST y por GraphQL para ver con un log delante todo lo que aquí cuento de palabra.
El cambio de mentalidad en una frase #
En REST el servidor decide la forma de la respuesta. En GraphQL la decide el cliente.
Eso es todo. El resto son consecuencias.
En REST expones recursos (/usuarios/42, /usuarios/42/pedidos) y cada uno devuelve lo que tú decidiste que devuelve. Si el cliente necesita el nombre del usuario y la fecha de sus tres últimos pedidos, hace dos peticiones y se trae de paso veinte campos que no quería. Si eso duele, acabas creando /usuarios/42?fields=nombre o, peor, /pantalla-inicio-movil, un endpoint hecho a medida de una pantalla concreta. Todos lo hemos hecho.
GraphQL ataca exactamente ese problema. Hay un único endpoint (normalmente POST /graphql) y el cliente manda una descripción de lo que quiere:
{
usuario(id: 42) {
nombre
pedidos(ultimos: 3) {
fecha
total
}
}
}Y recibe exactamente eso, con la misma forma:
{
"data": {
"usuario": {
"nombre": "Ignacio",
"pedidos": [
{ "fecha": "2026-10-20", "total": 31.5 },
{ "fecha": "2026-10-12", "total": 8.0 },
{ "fecha": "2026-09-30", "total": 120.0 }
]
}
}
}Una petición, ni un byte de más, y el cliente puede cambiar lo que pide sin que nadie toque el servidor.
Las piezas, traducidas a vocabulario REST #
El esquema (schema). Es el contrato, y es obligatorio. Si en REST te apoyas en OpenAPI, aquí el esquema no es documentación: es lo que el servidor valida contra cada petición. Se escribe en un lenguaje propio (SDL) y está tipado:
type Usuario {
id: ID!
nombre: String!
email: String
pedidos(ultimos: Int = 10): [Pedido!]!
}
type Pedido {
id: ID!
fecha: String!
total: Float!
}
type Query {
usuario(id: ID!): Usuario
}El ! significa “no nulo”. [Pedido!]! es una lista no nula de pedidos no nulos. Esta precisión sobre la nulabilidad es una de las cosas que más echo de menos cuando vuelvo a JSON “a pelo”.
Query y Mutation. Las queries son tus GET: leer. Las mutations son tus POST/PUT/DELETE: todo lo que escribe. GraphQL no distingue entre crear y modificar; eso lo defines tú en el nombre (crearPedido, cancelarPedido). Hay un tercer tipo, Subscription, para recibir datos en tiempo real, normalmente sobre WebSocket; lo dejo fuera de aquí.
Resolvers. Es donde vive el código. Cada campo del esquema tiene (o hereda) una función que sabe obtener su valor. Query.usuario va a la base de datos a por el usuario; Usuario.pedidos va a por los pedidos de ese usuario. El servidor recorre la petición del cliente campo a campo llamando al resolver que toque.
Si vienes de REST esto se parece a tener un controlador por campo en vez de uno por endpoint. Y es la fuente del problema más famoso de GraphQL, que viene ahora.
Lo que se pierde (y nadie te cuenta en la demo) #
La caché HTTP #
En REST, GET /usuarios/42 es cacheable por cualquier intermediario que entienda HTTP: navegador, CDN, proxy inverso. Es gratis y es enorme.
En GraphQL todo va por POST al mismo endpoint, con la consulta en el cuerpo. Para un proxy, todas las peticiones son iguales y ninguna es cacheable. Las soluciones existen (consultas persistidas con GET, caché normalizada en el cliente, caché de respuestas en el servidor), pero hay que montarlas y ninguna es tan simple como un Cache-Control.
El problema N+1 #
Vuelve a mirar la consulta del principio. El resolver de usuario hace una consulta SQL. Después, para pedidos, otra. Bien. Ahora imagina esta:
{
usuarios(primeros: 100) {
nombre
pedidos(ultimos: 3) { total }
}
}Un resolver ingenuo hace una consulta para los 100 usuarios y luego 100 consultas más, una por usuario, para sus pedidos. 101 viajes a la base de datos para algo que en SQL se resuelve con un JOIN y un LIMIT por ventana.
La solución estándar se llama DataLoader y consiste en agrupar: en lugar de resolver los pedidos usuario a usuario, el servidor acumula los 100 ids y lanza una sola consulta WHERE usuario_id IN (...). Funciona, pero es una capa más que tienes que escribir y entender. En REST el N+1 también existe, pero lo ves venir porque tú escribiste el endpoint; en GraphQL lo provoca el cliente con una consulta que tú nunca anticipaste.
El código de estado es siempre 200 #
Una petición GraphQL con errores devuelve, casi siempre, 200 OK con un bloque errors en el JSON:
{
"data": { "usuario": null },
"errors": [
{ "message": "Usuario no encontrado", "path": ["usuario"] }
]
}Además, los errores son parciales: puede venir la mitad de los datos y errores en la otra mitad. Esto desmonta cualquier monitorización que cuentes por códigos HTTP, y los clientes tienen que mirar siempre errors, no solo el estado.
No hay “recurso” al que apuntar #
En REST, la URL identifica al recurso. Sirve para enlazar, para registrar en logs, para permisos por ruta, para rate limiting por endpoint. En GraphQL nada de eso aplica tal cual: la autorización pasa a ser por tipo o por campo, el rate limiting por coste de la consulta, y los logs tienen que registrar la consulta entera para servir de algo.
El cliente puede pedir demasiado #
Si tu esquema tiene relaciones circulares (usuario → pedidos → usuario → pedidos…), un cliente malintencionado o simplemente torpe puede pedir una consulta de profundidad 50 y tumbarte el servidor. Hay que poner límites de profundidad y de complejidad, y desactivar la introspección (la capacidad de preguntarle al servidor por su propio esquema) en producción si la API no es pública. En REST este problema no existe porque el servidor acota lo que devuelve cada endpoint.
Lo que se gana (de verdad) #
- Un esquema vivo y tipado. Las herramientas (GraphiQL, generadores de clientes) se construyen sobre él. Autocompletado real contra la API, clientes generados con tipos correctos, documentación que no se desactualiza porque es el contrato.
- Evolución sin versiones. Añades campos y nadie se entera; marcas los viejos como
@deprecatedy puedes medir quién los sigue usando porque el servidor ve exactamente qué campos pide cada cliente. El/v2/desaparece. - Agregación de fuentes. Un esquema puede resolver
usuariocontra una base de datos yusuario.saldocontra otro servicio. El cliente ve un grafo; el servidor esconde la fontanería. Esto es lo que antes hacía el backend for frontend, pero sin escribir uno por pantalla. - Varios clientes distintos sobre la misma API. Web, móvil, un panel interno: cada uno pide lo suyo. Este es el caso de uso original (Facebook, 2012) y sigue siendo el más sólido.
Cuándo no merece la pena #
Mi lista, sin pretensiones:
- Una API interna sencilla con dos o tres consumidores que controlas tú. REST, y a otra cosa.
- Integración máquina a máquina con operaciones fijas (“envíame este fichero”, “dame el estado de esta transacción”). No hay nada que el cliente necesite moldear.
- Cuando la caché HTTP es lo que te salva la vida: contenido público, muy leído, poco cambiante.
- Cuando el equipo no va a tener tiempo de montar DataLoader, límites de complejidad y autorización por campo. GraphQL sin eso es una API REST peor, con un agujero de rendimiento y seguridad.
- Si lo que de verdad quieres es “dame solo estos campos”, bastante gente resuelve eso con un parámetro
fieldsen REST y duerme tranquila.
Cuándo sí #
- Varios clientes con necesidades distintas sobre los mismos datos.
- Datos muy relacionados, donde la pantalla típica cruza cuatro o cinco entidades.
- Una capa de agregación delante de servicios heterogéneos.
- Equipos de frontend que avanzan más rápido que los de backend y necesitan dejar de pedir endpoints.
Resumen para quien no haya bajado hasta aquí #
GraphQL no sustituye a REST; cambia quién manda sobre la forma de la respuesta. A cambio de flexibilidad para el cliente, pagas con la caché HTTP, con el N+1, con errores que no son errores HTTP y con una superficie de ataque que tienes que acotar a mano. Si esos cuatro problemas tienen nombre en tu cabeza antes de empezar, GraphQL puede ser una muy buena herramienta. Si no, probablemente no la necesitas todavía.
Lo que viene #
En la segunda entrada monto el laboratorio: PostgreSQL en Podman, una API REST y una API GraphQL en Python sobre las mismas dos tablas, y la primera pantalla comparada. En la tercera pido cien usuarios de golpe, enseño el N+1 en el log de la base de datos, lo arreglo con DataLoader y cierro con la caché. Que es donde todo esto se entiende de verdad.