GraphQL: consultas precisas para tus APIs

¿Qué es GraphQL?

GraphQL es un lenguaje de consulta para APIs, creado por Facebook. Permite que el cliente pida exactamente los datos que necesita en una sola petición, en lugar de recibir estructuras fijas definidas por el servidor.

Su flujo general es:

Cliente
-> Petición GraphQL (query / mutation)
-> Servidor (schema + resolvers)
-> Datos justo como los pidió

A diferencia de REST, donde cada recurso suele tener su propio endpoint, GraphQL expone un único endpoint y el cliente describe qué quiere obtener.

Queries: leer datos

Una query es la operación para leer datos. El cliente especifica los campos que necesita; el servidor responde únicamente con esos campos.

query {
  usuario(id: 1) {
    nombre
    email
    posts {
      titulo
    }
  }
}

El cliente pidió nombre, email y posts.titulo, y solo eso recibe:

{
  "data": {
    "usuario": {
      "nombre": "Ana",
      "email": "ana@ejemplo.com",
      "posts": [
        { "titulo": "Las APIs no son una pieza de museo" }
      ]
    }
  }
}

Mutations: modificar datos

Las mutations son las operaciones para crear, actualizar o eliminar información.

mutation {
  crearUsuario(nombre: "Luis", email: "luis@ejemplo.com") {
    id
    nombre
  }
}

Tipos y esquema

GraphQL es fuertemente tipado. El esquema define los tipos disponibles y las operaciones permitidas.

type Usuario {
  id: ID!
  nombre: String!
  email: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  titulo: String!
}

type Query {
  usuario(id: ID!): Usuario
  usuarios: [Usuario!]!
}

type Mutation {
  crearUsuario(nombre: String!, email: String!): Usuario!
}

El ! indica que el campo es obligatorio. Conocer los tipos de antemano permite validar consultas y ofrecer autocompletado en los clientes.

Resolvers

Los resolvers son las funciones del servidor que calculan el valor de cada campo cuando se consulta.

const resolvers = {
  Query: {
    usuario: (_, args, ctx) => ctx.db.usuarioPorId(args.id),
  },
  Usuario: {
    posts: (usuario, _, ctx) => ctx.db.postsDeUsuario(usuario.id),
  },
};

GraphQL vs REST

  • Endpoints: REST usa varios endpoints, uno por recurso; GraphQL usa uno solo.
  • Datos devueltos: REST devuelve según el endpoint (a veces de más o de menos); GraphQL devuelve exactamente lo que el cliente pide.
  • Over-fetching: puede ocurrir en REST; se evita en GraphQL.
  • Under-fetching: puede requerir varias peticiones en REST; se evita en GraphQL con una sola petición.
  • Tipado: REST depende del diseño; GraphQL es fuertemente tipado y declarado en el esquema.

Consideraciones

GraphQL no es siempre "mejor" que REST: aporta mucha flexibilidad, ideal para clientes que necesitan datos de forma distinta o relaciones complejas, pero agrega complejidad en el servidor y el seguimiento del esquema. Para APIs públicas sencillas, REST sigue siendo una opción muy válida.

© Arturo Juárez Monroy