Que es GraphQL?

TL;DR

GraphQL acaba con el drama de recibir datos de más (over-fetching) o tener que hacer mil llamadas para completar una vista (under-fetching). Con una sola Query pides exactamente los campos que necesitas, usas Mutations para modificar datos y Subscriptions para el tiempo real, todo bajo un Schema estrictamente tipado que funciona como un contrato entre el servidor y el cliente. Aunque añade algo de complejidad inicial con sus resolvers, es la herramienta definitiva para aplicaciones con datos relacionados complejos donde la eficiencia y la flexibilidad del frontend son la prioridad.

GraphQL

A diferencia de REST, donde el servidor decide qué datos devuelve en cada endpoint, con GraphQL el cliente especifica exactamente qué campos necesita. El resultado es menos datos transferidos, menos llamadas al servidor y una experiencia de desarrollo mucho más fluida.

Una analogía que me gusta mucho: REST es como pedir el menú del día y que te traigan todo lo que incluye. GraphQL es como ordenar a la carta y solo llega a tu mesa lo que pediste.

El problema que GraphQL resuelve

Over-fetching

Imagina que tienes un endpoint GET /usuarios/42 y solo necesitas el nombre del usuario para mostrarlo en un avatar. La respuesta REST te devuelve todo:

{
  "id": "42",
  "name": "Ana García",
  "email": "[email protected]",
  "age": 28,
  "bio": "Desarrolladora full stack...",
  "avatar": "https://cdn.ejemplo.com/ana.jpg",
  "createdAt": "2023-01-15T10:30:00Z"
}

Recibiste 7 campos cuando solo necesitabas 1. Eso es over-fetching.

Under-fetching

Ahora necesitas mostrar el perfil del usuario con sus últimos posts. Con REST necesitas:

GET /usuarios/42 → datos del usuario
GET /usuarios/42/posts → posts del usuario 3 Quizás GET /posts/8/comentarios → comentarios del primer post

Tres peticiones al servidor. Eso es under-fetching.

La solución de GraphQL

Con GraphQL haces una sola petición y pides exactamente lo que necesitas:

query {
  user(id: "42") {
    name
    avatar
    posts {
      title
      publishedAt
    }
  }
}

Las tres operaciones de GraphQL

GraphQL tiene tres tipos de operaciones que cubren todo lo que necesitas hacer con una API.

Query

Es la operación más común. Equivalente a un GET en REST.

query GetUser {
  user(id: "42") {
    name
    email
    posts {
      title
      publishedAt
    }
  }
}

Mutation

Para crear, editar o eliminar. Equivalente a POST, PUT, PATCH y DELETE.

mutation CreatePost {
  createPost(input: {
    title: "Mi primer post con GraphQL"
    content: "Hoy aprendí a usar mutations..."
  }) {
    id
    title
    createdAt
  }
}

Subscription

Para escuchar eventos del servidor vía WebSockets. Perfecto para chats, notificaciones o feeds en vivo.

subscription NewMessage {
  newMessage(chatId: "sala-devs") {
    text
    author
    timestamp
  }
}

El Schema

Antes de que un cliente pueda hacer consultas, el servidor define su schema. Es el contrato que describe todos los tipos de datos y operaciones disponibles.

Se escribe en SDL (Schema Definition Language):

type User {
  id:      ID!
  name:  String!
  email:   String!
  age:    Int
  posts:   [Post!]
}

type Post {
  id:        ID!
  title:    String!
  content: String!
  published: Boolean!
  author:     Usuario!
}

type Query {
  user(id: ID!): User
  users: [User!]!
}

type Mutation {
  createPost(title: String!, content: String!): Post!
}

El signo ! indica que el campo es obligatorio (non-null). Si no lo tiene, puede ser nulo.

4 ventajas concretas de GraphQL

Precisión: Solicitas solo lo que necesitas, sin over-fetching ni under-fetching.
Eficiencia: Una sola petición para datos relacionados, todo en una query.
Seguridad: Fuertemente tipado garantizado por el schema.
Herramientas: Documentación automática con herramientas como Apollo Studio.

¿Cuándo NO usar GraphQL?

Si tu API es sencilla, con pocos recursos y un solo cliente, REST puede ser más que suficiente. GraphQL agrega complejidad con los schemas y resolvers.

GraphQL no vino a reemplazar REST, sino a resolver problemas específicos que REST maneja con dificultad: datos sobreabundantes, múltiples peticiones y APIs que sirven a clientes muy distintos entre sí.

Mi recomendación es que aprendas los fundamentos, crea un schema básico con Apollo Server, haz tus primeras queries y mutations. Puedes comenzar por la documentación oficial donde esta muy bien explicado y con ejemplos: graphql.org/learn/introduction.

Blog