GraphQL

Definición

GraphQL es un lenguaje de consulta para APIs y un runtime para resolver esas consultas con tus datos existentes. Lo creó Facebook en 2012 (open-source desde 2015) para resolver un problema concreto: sus apps móviles necesitaban consumir datos de muchos endpoints distintos y la red móvil era lenta.

A diferencia de REST, donde cada endpoint devuelve una estructura fija, en GraphQL el cliente declara qué datos quiere y el servidor le devuelve exactamente eso, ni más ni menos. Una sola petición puede traer datos de varias entidades relacionadas, sin múltiples round-trips.

GraphQL no es un competidor "mejor" de REST: es una alternativa con trade-offs distintos. Brilla en apps complejas con relaciones profundas (Shopify, GitHub, Twitter), pero añade complejidad operativa que no siempre compensa.

Cómo funciona

GraphQL tiene tres conceptos clave:

1. Schema: define las entidades de tu API y sus relaciones (Producto, Cliente, Pedido) usando un sistema de tipos estricto.
2. Query: el cliente envía una "consulta" que describe la estructura exacta de respuesta que quiere.
3. Resolver: funciones en el servidor que saben cómo obtener cada campo (de base de datos, otra API, caché...).

Solo hay UN endpoint (típicamente /graphql) que recibe POST con la query. El servidor ejecuta los resolvers necesarios y devuelve JSON con la estructura solicitada.

Ejemplo práctico

Query que pide un producto + sus 3 últimas reseñas + el nombre del cliente de cada reseña, todo en una sola petición:

query {
  producto(id: 12345) {
    nombre
    precio
    stock
    resenas(limit: 3) {
      texto
      puntuacion
      cliente {
        nombre
      }
    }
  }
}

Respuesta JSON exacta:

{
  "data": {
    "producto": {
      "nombre": "Fresa carburo Ø10mm",
      "precio": 23.50,
      "stock": 47,
      "resenas": [
        { "texto": "Excelente", "puntuacion": 5, "cliente": { "nombre": "Talleres Ruiz" } },
        { "texto": "Buen filo", "puntuacion": 5, "cliente": { "nombre": "Mecanizados SL" } },
        { "texto": "Vida útil ok", "puntuacion": 4, "cliente": { "nombre": "Industrial Lopez" } }
      ]
    }
  }
}

En REST necesitarías 3+ peticiones: /productos/12345, /productos/12345/resenas?limit=3, y por cada reseña /clientes/{id}.

GraphQL vs REST

Errores comunes

• Implementar GraphQL "porque es moderno": si tu app hace 5 peticiones REST simples, GraphQL solo añade complejidad. Solo justifica el cambio si tienes problemas reales de over/under-fetching.
• N+1 queries en resolvers: si un resolver consulta la base por cada item de una lista, una query puede generar 100 queries SQL. Soluciona con DataLoader (batch + cache).
• No limitar profundidad/complejidad de queries: un cliente malicioso puede mandar queries con 20 niveles de anidamiento y tirar tu servidor. Usa límites (query-complexity, query-depth-limit).
• No pensar en caching: REST se cachea automáticamente en CDN. Con GraphQL necesitas estrategias propias (Apollo Cache, persisted queries, etc.).
• Schema demasiado pegado a la base de datos: el schema debe modelar dominio, no tablas. Si tu schema parece un dump de tu DB, has perdido medio valor de GraphQL.

Cuándo elegir GraphQL

GraphQL brilla cuando:

• Tu app tiene muchas vistas distintas que necesitan combinaciones distintas de datos
• Tienes apps móviles donde minimizar payload y round-trips es crítico
• Hay múltiples clientes (web, iOS, Android, partners) con necesidades de datos distintas
• Tu modelo de dominio tiene muchas relaciones (entidades anidadas)

Quédate con REST cuando:

• Tu API es simple (CRUD básico) y para uso interno
• Las URLs cacheables importan (CDN, edge)
• Tu equipo no tiene experiencia con GraphQL y la operativa extra no compensa
• Necesitas que partners externos se integren rápido sin documentación profunda

Referencias

• graphql.org — documentación oficial
• Apollo GraphQL — frameworks server y client
• GitHub GraphQL API — uno de los mejores ejemplos en producción