Definición
GraphQL es un lenguaje de consulta para APIs y un runtime de servidor creado por Meta (entonces Facebook) en 2012 y liberado como código abierto en 2015. A diferencia de REST, donde el servidor decide qué datos devuelve en cada endpoint, en GraphQL el cliente describe exactamente la forma y los campos que necesita mediante un único endpoint (/graphql) y recibe una respuesta con esa estructura idéntica.
En el contexto DTC y Headless Commerce, GraphQL se ha convertido en el estándar de facto para conectar el frontend (Next.js, Hydrogen, Vue Storefront, apps móviles) con el backend de comercio (Shopify Storefront API, commercetools, Saleor, Magento GraphQL, BigCommerce). Plataformas como Shopify lo adoptaron como API principal para storefronts: su Storefront API es 100 % GraphQL y permite consultar productos, variantes, inventario, carrito y checkout en una sola llamada.
La idea central: una petición, exactamente los datos necesarios, nada más.
Analogía: el restaurante a la carta vs. el menú cerrado
Imagina que pides comida a domicilio.
- REST es un menú cerrado: el restaurante solo ofrece "Combo 1", "Combo 2", "Combo 3". Si quieres solo la hamburguesa sin patatas ni bebida, pagas el combo completo. Además, para conseguir el postre tienes que hacer un segundo pedido a otro número.
- GraphQL es un menú a la carta: escribes tu pedido exacto ("1 hamburguesa, sin cebolla, con extra de queso, y solo la salsa") y el mismo repartidor te lo trae todo junto en una sola entrega.
Traducido a eCommerce: en REST, para pintar una ficha de producto con variantes, precio, stock y reseñas suelen hacer falta 3-5 llamadas a endpoints distintos. En GraphQL, 1 sola query devuelve todo lo necesario. Esto reduce latencia, ahorra ancho de banda móvil y simplifica el código del frontend.
Fórmula: cómo se mide el impacto
El beneficio de GraphQL se calcula comparando payload y número de round-trips:
$$
\text{Ahorro de payload} = \frac{\text{Bytes REST} - \text{Bytes GraphQL}}{\text{Bytes REST}} \times 100
$$
$$
\text{Reducción de requests} = \frac{N_{\text{REST}} - N_{\text{GraphQL}}}{N_{\text{REST}}} \times 100
$$
Ejemplo real con datos:
- Ficha de producto en REST (Shopify REST Admin): 4 llamadas (producto, variantes, inventario, metafields), ~48 KB de respuesta.
- Misma ficha en GraphQL (Storefront API): 1 llamada, ~9 KB (solo los campos usados).
- Ahorro de payload: $(48-9)/48 \times 100 = \mathbf{81{,}25\ \%}$
- Reducción de requests: $(4-1)/4 \times 100 = \mathbf{75\ \%}$
En un catálogo de 10.000 SKUs con 50.000 sesiones diarias, esa diferencia se traduce en menos coste de CDN, mejor Core Web Vitals (LCP medio -0,8 s en móvil 4G) y menor tasa de abandono.
Comparativa: GraphQL vs. REST en DTC
| Criterio | GraphQL | REST |
|---|---|---|
| Endpoint | Único (`/graphql`) | Múltiples (`/products`, `/cart`...) |
| Datos devueltos | Solo los campos pedidos | Estructura fija del servidor |
| Over-fetching | No | Frecuente |
| Under-fetching | No (1 query) | Sí (varias llamadas) |
| Versionado | Evolutivo (deprecación de campos) | URLs versionadas (`/v2/`) |
| Caching | Complejo (requiere persisted queries) | Sencillo (HTTP + CDN) |
| Curva de aprendizaje | Media-alta | Baja |
| Ideal para | Headless, móvil, frontends dinámicos | Integraciones simples, webhooks |
| Ejemplo eCommerce | Shopify Storefront API, Saleor | Shopify Admin REST, Stripe API |
Aplicación en escenarios DTC reales
1. Ficha de producto headless: una query con product, variants, priceRange, metafields y recommendations en un solo fetch. El frontend renderiza sin waterfalls.
2. Carrito y checkout: mutaciones (cartCreate, cartLinesAdd, checkoutComplete) que actualizan el carrito en tiempo real, sincronizadas entre web y app móvil.
3. Personalización y CMS: combinar GraphQL de Shopify + Contentful/Sanity en un único gateway (Apollo Router, GraphQL Mesh) para traer producto + contenido editorial en una sola petición.
4. Apps móviles: al pedir solo los campos visibles, el payload baja de ~50 KB a ~8-12 KB por pantalla, crítico en redes 3G/4G en LATAM y España rural.
5. B2B y precios por cliente: consultas con contexto de usuario (@context) que devuelven listas de precios específicas sin duplicar endpoints.
Errores comunes (y cómo evitarlos)
- Consultar todo "por si acaso": pedir 40 campos cuando se usan 8 anula la ventaja. Usa fragmentos y revisa el tamaño real de la respuesta.
- Ignorar el coste de queries: GraphQL permite queries anidadas muy profundas. Sin límites de profundidad ni *rate limiting* por coste, un solo cliente puede tumbar el backend. Configura maxDepth y *query cost analysis*.
- Caching mal resuelto: al ser POST por defecto, no se cachea en CDN. Solución: Persisted Queries (APQ) + CDN (Fastly, Cloudflare) para convertirlas en GET cacheables.
- Confundir GraphQL con una base de datos: no lo es. Es una capa sobre tus servicios; los resolvers siguen llamando a microservicios, SQL o APIs externas.
- Versionado inexistente: en GraphQL no hay /v2. Debes deprecar campos con @deprecated y monitorizar su uso antes de eliminarlos.
- Seguridad descuidada: desactiva introspección en producción, limita *aliases* y aplica autenticación a nivel de campo, no solo de endpoint.
Términos relacionados
- Headless Commerce: arquitectura donde frontend y backend están desacoplados; GraphQL es su lenguaje natural.
- Storefront API: API GraphQL de Shopify para construir storefronts personalizados.
- Apollo Client / urql: librerías de cliente GraphQL con caché normalizada.
- Persisted Queries: técnica para cachear y securizar queries GraphQL.
- Schema / SDL: definición tipada del contrato de la API.
- Resolver: función que obtiene los datos de cada campo.
- REST / Webhooks: alternativas y complementos habituales en integraciones DTC.
- Edge Functions: ejecutan consultas GraphQL cerca del usuario para reducir latencia.
