Qué es y cómo funciona
GraphQL es un lenguaje de consulta y un entorno de ejecución para APIs. En lugar de muchas direcciones, cada una con su respuesta fija, ofrece normalmente un único punto de entrada y un esquema que describe qué tipos de datos existen y cómo se relacionan. El cliente escribe una consulta indicando exactamente qué campos quiere, y la respuesta tiene la misma forma que la consulta.
Eso permite, por ejemplo, pedir en una sola petición un artículo, su autor y sus categorías, sin encadenar varias llamadas. El esquema está tipado y se puede consultar, por lo que las herramientas pueden autocompletar, validar consultas y generar documentación o tipos de TypeScript.
Además de consultas para leer, define mutaciones para modificar datos. En WordPress, el plugin WPGraphQL expone el contenido de esta manera, y es una de las formas habituales de conectar un front de Next.js con un WordPress headless.
Por qué importa
Su ventaja principal es la precisión. Una página móvil puede pedir tres campos y una de escritorio, diez, usando la misma API, sin transferir de más ni hacer rondas innecesarias. En proyectos con muchas pantallas, varios equipos o apps además de la web, eso reduce tráfico y acelera el desarrollo del front, que no depende de que el backend cree un endpoint nuevo para cada vista.
El coste está en el servidor y en la operación. Como casi todas las consultas se envían por POST a la misma dirección, la caché HTTP clásica funciona peor y hay que resolverla de otra manera, por ejemplo con consultas persistentes o caché en el cliente. Además, una consulta muy anidada puede ser costosa, así que conviene limitar su profundidad y complejidad. Para una API sencilla, REST sigue siendo más directo.
Un ejemplo
Una web de contenidos conectada a WordPress necesita, en la portada, el título, la imagen destacada y el nombre del autor de los seis últimos artículos. Con una consulta GraphQL pide exactamente esos campos en una sola petición. En la página de cada artículo pide otros distintos, como contenido completo y categorías. El front controla qué datos llegan y el backend no necesita endpoints adaptados a cada pantalla.
Errores y confusiones frecuentes
- Creer que GraphQL sustituye siempre a REST. Resuelve problemas concretos, pero para APIs pequeñas añade complejidad sin un beneficio claro.
- Dar por hecho que la caché HTTP funcionará como en REST. Hay que planificar cómo y dónde cachear las respuestas.
- No limitar la complejidad de las consultas. Sin límites, una consulta muy anidada puede sobrecargar el servidor, incluso sin mala intención.