Como o GraphQL Funciona - O Novo Padrao para Design de API Flexivel

O Que e GraphQL

GraphQL e uma linguagem de consulta e runtime para APIs lancada pelo Facebook (atual Meta) em 2015. Sua principal caracteristica e permitir que os clientes especifiquem exatamente os dados que precisam e recebam respostas sem excesso nem falta de informacoes.

Atualmente, muitos servicos de grande escala como GitHub, Shopify, Twitter (X) e Netflix adotam GraphQL.

Por que foi criado: Foi desenvolvido para resolver o problema que o Facebook enfrentou no desenvolvimento de aplicativos moveis: “com REST API era necessario fazer multiplas chamadas a diferentes endpoints, aumentando o volume de comunicacao”.

Conceitos Basicos do GraphQL

Query

Operacao para obter dados.

# Obter informacoes do usuario e posts simultaneamente
query {
  user(id: "123") {
    name
    email
    posts {
      title
      createdAt
    }
  }
}

Mutation

Operacao para modificar dados.

# Criar um novo post
mutation {
  createPost(input: { title: "Hello", content: "World" }) {
    id
    title
  }
}

Subscription

Operacao para se inscrever em alteracoes de dados em tempo real.

# Receber novas mensagens em tempo real
subscription {
  newMessage(roomId: "456") {
    content
    sender {
      name
    }
  }
}

Definicao de Schema

No GraphQL, o schema define a forma da API.

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

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

# Definicao de Query e 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 sao tipos embutidos. ! significa nao-nulo.

Comparacao com REST API

Over-fetching e Under-fetching

Caso REST API:
GET /users/123         → Informacoes do usuario (inclui itens desnecessarios)
GET /users/123/posts   → Lista de posts (requisicao separada necessaria)

Caso GraphQL:
query {
  user(id: "123") {
    name              # Apenas itens necessarios
    posts { title }   # Obtidos em uma unica requisicao
  }
}

Mecanismo dos Resolvers

Resolvers sao funcoes que transformam queries GraphQL em dados reais.

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: Ao resolver campos aninhados, queries ao banco de dados podem aumentar rapidamente. Use mecanismos de batching e caching como DataLoader para mitigar isso.

Vantagens e Consideracoes do GraphQL

Vantagens

• Obtencao eficiente de dados: Obtenha apenas os dados necessarios em uma unica requisicao
• Tipagem segura: Definicao estrita de tipos atraves do schema
• Experiencia do desenvolvedor: Geracao automatica de documentacao via introspection
• Facil evolucao: Adicionar campos nao afeta clientes existentes

Consideracoes

• Cache HTTP e dificil: Requisicoes POST sao a base
• Controle de queries complexas: Precaucoes contra queries maliciosas sao necessarias
• Curva de aprendizado: Requer aprender novos conceitos
• Upload de arquivos: Nao incluido na especificacao padrao

Resumo

GraphQL e um padrao de design de API que permite otimizar a obtencao de dados de forma orientada ao cliente. Nao e um substituto para REST API, mas sim uma escolha a ser feita de acordo com o caso de uso. E particularmente eficaz em aplicacoes com relacionamentos de dados complexos ou quando e necessario suportar clientes diversos.