Guías

GraphQL es un lenguaje de consulta para API y, a la vez, un motor de ejecución que responde a esas consultas con tus datos. Creado en Facebook en 2012 y publicado como open source en 2015, ofrece al cliente — una interfaz web, una app móvil u otro servicio — una forma única y precisa de pedir a un servidor exactamente los datos que necesita, ni más ni menos. En lugar de que el servidor decida la forma de cada respuesta, el cliente describe lo que quiere y el servidor devuelve los datos con esa misma forma.

Esa única idea es lo que distingue a GraphQL del estilo REST que lo precedió. Con REST normalmente llamas a varios puntos de acceso, cada uno devolviendo una estructura fija que el servidor definió de antemano. Con GraphQL envías una sola petición a un único punto de acceso y especificas los campos que quieres; la respuesta refleja tu petición. El objetivo no es dejar obsoleto a REST, sino resolver problemas concretos que los puntos de acceso fijos generan a medida que crecen una aplicación y sus datos.

Cómo funciona GraphQL: el esquema

En el corazón de GraphQL está el esquema, un contrato fuertemente tipado que describe cada tipo de dato disponible y cómo se relacionan esos tipos. Como el esquema es explícito y tipado, ambas partes saben de antemano lo que es posible: las herramientas pueden validar una consulta antes incluso de ejecutarla, los editores pueden autocompletar los campos y la documentación puede generarse automáticamente a partir del esquema. Esta naturaleza autodescriptiva es una de las ventajas más prácticas de GraphQL.

Una consulta de GraphQL se lee casi como el JSON que devuelve. Nombras los campos que quieres, anidas dentro los campos relacionados y el servidor recorre el esquema para resolver cada uno. El mismo punto de acceso acepta también mutaciones, que cambian los datos, y suscripciones, que permiten al servidor enviar actualizaciones al cliente mediante una conexión persistente. Consultas, mutaciones y suscripciones son los tres tipos de operación que define la especificación.

Sobre-obtención e infra-obtención

Dos problemas de los puntos de acceso REST fijos explican buena parte del atractivo de GraphQL: la sobre-obtención y la infra-obtención. La sobre-obtención ocurre cuando un punto de acceso devuelve muchos más datos de los que una pantalla necesita, desperdiciando ancho de banda. La infra-obtención es lo contrario: un único punto de acceso no devuelve lo suficiente, por lo que el cliente debe hacer varias idas y vueltas para componer una sola vista. Como un cliente GraphQL pide con precisión los campos que necesita en una petición, evita ambos a la vez.

• Lenguaje de consulta para API: el cliente pide exactamente los campos que necesita
• Esquema fuertemente tipado = autodocumentado, validado, con autocompletado
• Tres operaciones: consultas (lectura), mutaciones (escritura), suscripciones (push)
• Resuelve la sobre- e infra-obtención de REST en una sola petición
• Contrapartidas: caché HTTP más difícil, salvaguardas de coste; REST más simple para API pequeñas

GraphQL y los frameworks front-end

Esta precisión es especialmente valiosa para frameworks front-end como React, Vue, Svelte y Angular, donde un componente suele necesitar una porción concreta de datos. Un componente puede pedir exactamente los campos que renderiza, y a medida que la interfaz evoluciona, la consulta evoluciona con ella, sin esperar a que un equipo de back-end cree un nuevo punto de acceso. Bibliotecas cliente maduras añaden por encima caché, agrupación de peticiones y gestión de estado, lo que explica que GraphQL se popularizara en los front-ends orientados a componentes.

Las contrapartidas honestas

GraphQL no es automáticamente la opción correcta, y ser honesto sobre sus contrapartidas importa. Su único punto de acceso dinámico dificulta la sencilla caché HTTP de la que disfruta REST, así que la caché suele trasladarse al cliente o a una capa especializada. Consultas escritas con descuido pueden pedir datos profundamente anidados y sobrecargar el servidor, por lo que las API en producción añaden límites de profundidad, análisis de coste y otras salvaguardas. Para una API pequeña con necesidades estables y predecibles, REST suele ser más simple y perfectamente suficiente.

Lo que GraphQL no es

También conviene tener claro lo que GraphQL no es. No es una base de datos ni un motor de almacenamiento: se sitúa delante de tus fuentes de datos existentes — ya sean bases de datos, API REST u otros servicios — y los resolvers obtienen los datos de ellas. Tampoco está atado a un único lenguaje o framework; hay servidores y clientes en todo el ecosistema, y la especificación la mantiene la GraphQL Foundation, neutral respecto a proveedores, y no una sola empresa.

GraphQL vs REST: cómo elegir

Elegir entre GraphQL y REST depende de la forma de tu aplicación, no de la moda. GraphQL destaca cuando muchos clientes distintos necesitan porciones diferentes de un grafo de datos complejo e interconectado, cuando los equipos de front-end y back-end quieren avanzar de forma independiente, o cuando reducir las idas y vueltas en conexiones lentas es prioritario. REST sigue siendo una excelente opción por defecto para servicios más simples, API públicas que se benefician de la caché HTTP y equipos que valoran su ubicuidad y simplicidad.

Dicho con claridad, GraphQL es una manera de dejar que el cliente pida exactamente los datos que quiere, descritos por un esquema tipado, servidos desde un único punto de acceso. No reemplaza ni las bases de datos, ni REST, ni tus servicios existentes; organiza cómo los clientes hablan con ellos. Saber qué problemas resuelve — y los costes de caché y complejidad que introduce — es lo que te permite recurrir a él cuando encaja de verdad y dejarlo de lado cuando REST es la mejor herramienta.