GraphQL

Resumen

GraphQL es un query language para APIs y también un runtime del lado del servidor que ejecuta esas queries contra un esquema tipado que tú defines para tus datos. En lugar de exponer muchos endpoints orientados a recursos, GraphQL suele exponer un único endpoint donde el cliente declara qué datos necesita y el servidor responde con esa misma forma en JSON.

Importa porque resuelve un problema común en APIs modernas: distintos clientes necesitan formas de datos distintas. Un frontend web quiere lista y totales. Un mobile quiere pocos campos porque le importa el ancho de banda. Un panel interno quiere relaciones anidadas en una sola llamada. GraphQL permite expresar esas necesidades en el request sin crear un endpoint nuevo por cada variación.

Alcance y supuestos

Este paquete cubre GraphQL a nivel conceptual: esquema tipado, tipos y campos, resolvers, queries, mutations, subscriptions, un endpoint único y trade-offs frente a REST y otros estilos de API.

No cubre tutoriales completos con Apollo Server, Yoga, Mercurius o clientes concretos; tampoco entra en federación, persisted queries, caching distribuido ni gobierno de esquemas a gran escala. Asume que ya entiendes APIs, HTTP, JSON y comunicación cliente-servidor.

Modelo mental

Piensa en pedir comida en un restaurante con una carta flexible. En un restaurante tradicional de menú fijo, si pides un combo te llega exactamente lo que el restaurante decidió incluir: bebida, entrada y postre, aunque solo quisieras el plato principal. En un restaurante con carta flexible, puedes decir: "quiero hamburguesa, sin bebida, con papas, y además la salsa aparte". La cocina no inventa un menú nuevo; simplemente prepara exactamente la combinación permitida por la carta.

GraphQL funciona así. La carta es el schema: define qué tipos existen y qué campos son válidos. El cliente no puede pedir cualquier cosa; solo puede pedir campos definidos en ese contrato. Pero dentro de ese contrato sí puede elegir la forma exacta del resultado. Los resolvers son la cocina: funciones que saben cómo obtener cada campo, quizá desde base de datos, servicios REST existentes o varios microservicios.

La consecuencia importante es que GraphQL mueve parte del control de forma desde el servidor al cliente. El backend sigue controlando qué datos existen, cómo se resuelven y qué reglas de autorización aplican, pero el cliente decide qué subconjunto necesita en cada pantalla o caso de uso.

Uso práctico

GraphQL encaja bien cuando varios clientes consumen el mismo dominio con necesidades de datos distintas:

• ✅ Frontends web y mobile que necesitan vistas diferentes del mismo modelo sin multiplicar endpoints.
• ✅ BFFs o capas de agregación que combinan datos de varios servicios detrás de una sola API.
• ✅ Productos donde el schema tipado mejora autocompletado, documentación e introspección.
• ✅ Casos donde quieres evitar overfetching y reducir cadenas de requests para relaciones anidadas.
• ❌ No es automáticamente mejor que REST; si tu dominio es CRUD simple y estable, GraphQL puede añadir complejidad innecesaria.
• ❌ No delegues toda la eficiencia al cliente; sin límites, paginación y control de complejidad, una query flexible puede volverse cara de ejecutar.

Ejemplo trabajado: un dashboard de ecommerce con un solo request

Supón que un dashboard necesita mostrar un pedido, el cliente asociado y los productos del pedido. Con muchos diseños REST, el frontend podría terminar haciendo varias llamadas o recibiendo más datos de los que usa. En GraphQL, el cliente expresa exactamente la forma que necesita:

query OrderDashboard($orderId: ID!) {
  order(id: $orderId) {
    id
    status
    totalCents
    customer {
      id
      fullName
    }
    items {
      quantity
      product {
        sku
        name
      }
    }
  }
}

Un esquema mínimo para soportar eso podría verse así:

type Query {
  order(id: ID!): Order
}

type Order {
  id: ID!
  status: String!
  totalCents: Int!
  customer: Customer!
  items: [OrderItem!]!
}

type Customer {
  id: ID!
  fullName: String!
}

type OrderItem {
  quantity: Int!
  product: Product!
}

type Product {
  sku: String!
  name: String!
}

Qué demuestra este ejemplo:

1. El schema es el contrato fuerte: el cliente sabe qué campos existen y cuáles son obligatorios.
2. El cliente pide solo lo que necesita: no recibe direcciones, historial ni metadata que no usará en esa vista.
3. Las relaciones anidadas forman parte del contrato: order -> customer -> items -> product.
4. El endpoint suele ser único, pero el resultado no es genérico; el resultado refleja la query exacta.
5. La evolución ocurre por adición y deprecación de campos, no necesariamente por versionado de endpoints.

Antes de elegir GraphQL, conviene revisar estas preguntas:

1. ¿Tus consumidores realmente necesitan formas de datos distintas o un conjunto pequeño de endpoints REST ya resuelve bien el problema?
2. ¿Tu backend puede controlar complejidad, autorización y paginación a nivel de campo o de operación?
3. ¿Necesitas agregar datos de varias fuentes bajo un contrato único?
4. ¿Tu equipo está listo para operar schema, resolvers, observabilidad y límites de costo por query?
5. ¿El beneficio de flexibilidad compensa la pérdida de simplicidad operativa frente a una API HTTP más directa?

Evidencia

• GraphQL, Introduction to GraphQL define GraphQL como un query language para APIs y un runtime del servidor basado en un type system, además de explicar que permite pedir exactamente los datos necesarios.
• GraphQL, Serving over HTTP documenta que GraphQL suele exponerse en un único endpoint HTTP, normalmente /graphql, y describe el modelo común de requests y responses JSON.
• GraphQL Specification formaliza el lenguaje, el sistema de tipos, la validación y la ejecución que sostienen el contrato de una API GraphQL.