GraphQL

¿Qué es GraphQL?

GraphQL es un lenguaje de consulta para APIs y un entorno de ejecución que resuelve esas consultas. Un servidor publica un esquema fuertemente tipado y el cliente envía una consulta que nombra exactamente los campos que quiere. La respuesta refleja la forma de la consulta. A diferencia de una API REST típica, un servicio GraphQL suele servirse desde una única URL, a menudo /graphql. El lenguaje está definido en la especificación de GraphQL.

Cómo funciona GraphQL

Esquema y operaciones

El esquema describe los tipos y campos que un cliente puede pedir. Hay tres tipos de operación: una query lee datos, una mutation cambia datos y provoca efectos secundarios, y una subscription entrega actualizaciones en tiempo real. Las consultas pueden usar argumentos, variables, alias y fragmentos, y la validación rechaza una consulta que no encaje con el esquema antes de ejecutarla. Después, los resolvers producen los datos de cada campo.

Una petición, una forma de respuesta

Una consulta por el nombre y el correo de un usuario devuelve solo esos dos campos bajo la clave data de nivel superior. Si algo falla, la respuesta incluye una clave errors. Una petición suele ser un POST HTTP con un cuerpo JSON que contiene query, operationName y variables. Un servidor también puede aceptar GET, pero solo para consultas, nunca para mutaciones. Los detalles están en servir GraphQL sobre HTTP.

Introspección

La introspección permite a un cliente consultar el propio esquema mediante campos como __schema y __type. Sirve de base a los exploradores de documentación y al autocompletado de los editores. La documentación de GraphQL señala que las API usadas solo por tus propias aplicaciones a menudo no la necesitan en producción, y que desactivarla es habitual porque reduce la superficie de ataque.

Ejemplo

Una pantalla móvil necesita el nombre de un producto y sus tres últimas reseñas. Con REST eso puede significar una llamada para el producto y otra para las reseñas. Con GraphQL el cliente envía una consulta product(id: "42") { name reviews(first: 3) { text } } y recibe exactamente eso. El coste se traslada al servidor, que debe resolver cada campo anidado de forma eficiente.

Errores comunes y compromisos

• El problema N+1. Resolver una lista de elementos y luego pedir datos relacionados para cada uno provoca una llamada extra al backend por elemento. El procesamiento por lotes, por ejemplo con DataLoader, reúne esas búsquedas en una sola petición.
• Consultas sin límite. Como el cliente da forma a la consulta, una muy anidada o muy amplia puede cargar mucho el servidor. Pagina los campos de lista (paginación de API) y usa límites de profundidad, anchura y complejidad, además de tiempos de espera.
• Caché HTTP más débil. REST da a cada recurso una URL que las cachés HTTP entienden. GraphQL no tiene esa identidad integrada, así que la API debería exponer un id único global que los clientes puedan usar para construir una caché. Consulta la caché de API.
• Suponer que HTTP 200 significa éxito. Una respuesta con datos puede contener errors, y HTTP no tiene un estado para el éxito parcial. Revisa el cuerpo, no solo el código de estado.
• Dejar la seguridad solo al esquema. La autenticación, la autorización y los límites de operación siguen siendo necesarios. Lee seguridad de API.

GraphQL, pruebas de carga y monitorización de API

Cada operación GraphQL es una petición HTTP a un endpoint, así que un resolver lento o un patrón N+1 se nota como tiempo de respuesta bajo carga, no como una URL que falla. Usa pruebas de carga con consultas realistas, porque una consulta barata y una cara comparten la misma URL. Para comprobaciones continuas, las preguntas frecuentes de la monitorización de APIs indican que GraphQL es compatible como un POST con cuerpo JSON. Añade una aserción sobre el cuerpo de la respuesta para que un 200 que contenga errors haga fallar igualmente la comprobación, y consulta qué es la monitorización de APIs. Lecturas relacionadas: 10 problemas comunes de rendimiento de API y cómo detectarlos y cómo ayuda la monitorización de APIs a tu negocio.

Preguntas frecuentes (FAQ)

¿Es GraphQL una base de datos?

No. GraphQL es un lenguaje de consulta y un entorno de ejecución para APIs. Se sitúa delante de tus fuentes de datos existentes, como bases de datos, servicios y otras API, y los resolvers deciden de dónde sale cada campo.

¿Cuál es la diferencia entre GraphQL y REST?

REST expone muchas URL, cada una con una forma de recurso fija. GraphQL suele exponer un único endpoint donde el cliente elige los campos. GraphQL reduce la obtención de datos de más, pero traslada más trabajo y complejidad de caché al servidor.

¿GraphQL usa POST para todo?

Las consultas y las mutaciones se envían normalmente como peticiones POST con cuerpo JSON. La guía para servir sobre HTTP permite GET solo para consultas, y las mutaciones deben usar POST.

¿Debo desactivar la introspección en producción?

Para las API que usan solo tus propias aplicaciones, normalmente no hace falta en producción y desactivarla es habitual. Es solo una parte de un enfoque más amplio que incluye autenticación, autorización, límites de profundidad y análisis de coste.

¿Puedo monitorizar una API GraphQL con LoadFocus?

La página de monitorización de APIs de LoadFocus indica que GraphQL es compatible como un POST con cuerpo JSON. Añade una aserción sobre el cuerpo para detectar los errores que se devuelven con estado 200.