Como Funciona GraphQL - El Nuevo Estandar de Diseno Flexible de APIs

Que es GraphQL

GraphQL es un lenguaje de consulta para APIs y un runtime publicado por Facebook (ahora Meta) en 2015. Su principal caracteristica es que los clientes pueden especificar exactamente los datos que necesitan y obtener respuestas sin exceso ni defecto.

Actualmente, muchos servicios a gran escala como GitHub, Shopify, Twitter (X) y Netflix han adoptado GraphQL.

Por que surgio: Fue desarrollado para resolver el problema que Facebook enfrentaba en el desarrollo de aplicaciones moviles: “Con REST API, era necesario llamar a multiples endpoints, aumentando el trafico de comunicacion”.

Conceptos Basicos de GraphQL

Query (Consulta)

Operacion para obtener datos.

# Obtener informacion del usuario y posts simultaneamente
query {
  user(id: "123") {
    name
    email
    posts {
      title
      createdAt
    }
  }
}

Mutation (Mutacion)

Operacion para modificar datos.

# Crear un nuevo post
mutation {
  createPost(input: { title: "Hello", content: "World" }) {
    id
    title
  }
}

Subscription (Suscripcion)

Operacion para suscribirse a cambios de datos en tiempo real.

# Recibir nuevos mensajes en tiempo real
subscription {
  newMessage(roomId: "456") {
    content
    sender {
      name
    }
  }
}

Definicion de Esquema

En GraphQL, el esquema define la forma de la API.

# Definicion de tipos
type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  createdAt: DateTime!
}

# Definicion de Query y Mutation
type Query {
  user(id: ID!): User
  posts(limit: Int): [Post!]!
}

type Mutation {
  createPost(input: CreatePostInput!): Post!
}

input CreatePostInput {
  title: String!
  content: String!
}

Tipos escalares: ID, String, Int, Float, Boolean estan disponibles como tipos incorporados. ! significa no nulo.

Comparacion con REST API

Over-fetching y Under-fetching

Caso REST API:
GET /users/123         → Informacion del usuario (incluye elementos innecesarios)
GET /users/123/posts   → Lista de posts (requiere solicitud separada)

Caso GraphQL:
query {
  user(id: "123") {
    name              # Solo los elementos necesarios
    posts { title }   # Obtenidos en 1 solicitud
  }
}

Mecanismo de Resolvers

Los resolvers son funciones que transforman las consultas GraphQL en datos reales.

const resolvers = {
  Query: {
    user: async (parent, args, context) => {
      return await context.db.users.findById(args.id);
    },
    posts: async (parent, args, context) => {
      return await context.db.posts.findMany({ take: args.limit });
    },
  },
  User: {
    posts: async (parent, args, context) => {
      return await context.db.posts.findMany({
        where: { authorId: parent.id }
      });
    },
  },
};

Problema N+1: Al resolver campos anidados, las consultas a la base de datos pueden aumentar rapidamente. Se contrarresta con mecanismos de batching y caching como DataLoader.

Ventajas y Consideraciones de GraphQL

Ventajas

• Obtencion eficiente de datos: Obtener solo los datos necesarios en una solicitud
• Tipado seguro: Definicion estricta de tipos mediante esquema
• Experiencia del desarrollador: Generacion automatica de documentacion mediante introspeccion
• Facil evolucion: Agregar campos no afecta a clientes existentes

Consideraciones

• Cache HTTP dificil: Porque las solicitudes POST son la base
• Control de consultas complejas: Necesidad de medidas contra consultas maliciosas
• Costo de aprendizaje: Se requiere aprender nuevos conceptos
• Carga de archivos: No incluido en la especificacion estandar

Resumen

GraphQL es un patron de diseno de API que permite optimizar la obtencion de datos liderada por el cliente. No reemplaza a REST API, sino que es importante usarlos segun el caso de uso. Es especialmente efectivo para aplicaciones con relaciones de datos complejas o cuando se necesita soportar diversos clientes.