Descomplicando GraphQL

Introdução

Podemos dizer que o GraphQL é o filhote de dois conceitos fundamentais na programação: API e Linguagens de Query/SQL

É uma linguagem de consulta para APIs e um runtime para executar essas consultas. É uma alternativa ao REST que dá ao cliente controle preciso sobre os dados que recebem.

O problema que ele resolve

Com REST, os desenvolvedores frequentemente enfrentam dois problemas:

1. Over-fetching: receber mais dados do que precisa (ex: buscar um usuário e receber 20 campos quando só quer o nome)
2. Under-fetching: fazer múltiplas requisições para montar uma tabela (ex: buscar → post → buscar autor → buscar comentários)

Com GraphQL, você pede exatamente o que precisa, em uma única requisição.

Conceitos fundamentais

1. Schema

O coração do GraphQL. Define os tipos de dados e as operações disponíveis

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

type Post {
  id: ID!
  title: String!
  body: String!
  author: User!
}

2. Query (leitura)

O cliente especifica exatamente o que quer:

query {
  user(id: "1") {
    name
    posts {
      title
    }
  }
}

Resposta:

3. Mutation (escrita)

Para criar, atualizar ou deletar dados:

mutation {
  createPost(title: "Novo Post", body: "Conteúdo aqui") {
    id
    title
  }
}

4. Subscription (em tempo real)

Para ouvir eventos em tempo real via WebSocket:

subscription {
  newMessage(chatId: "42") {
    text
    sender { name }
  }
}

Quando usar?

✅ Boa escolha quando:

• Múltiplos clientes (web, mobile) consomem os mesmos dados de formas diferentes
• O frontend precisa de flexibilidade para evoluir sem depender do backend
• Você tem dados interconectados (grafos de relacionamentos

⚠️ Talvez não valha a pena quando:

• API simples com poucos endpoints
• Time pequeno sem familiaridade com o ecossistema
• Caching HTTP simples é suficiente (REST se beneficia mais disso)