## glossário

O que é GraphQL?

GraphQL é uma linguagem de consulta para APIs criada pelo Facebook em 2012 e aberta ao público em 2015. Sua proposta é inverter quem decide o formato da resposta: em vez de o servidor definir o que cada endpoint devolve, é o cliente que descreve os campos que quer receber.

A motivação foi prática. O app mobile do Facebook precisava de menos dados que a versão web, mas ambos consumiam os mesmos endpoints — resultando em respostas grandes demais para o celular e em várias chamadas encadeadas para montar uma única tela.

Uma query e sua resposta

O formato do pedido espelha o formato da resposta

# query
{
  usuario(id: "42") {
    nome
    posts(ultimos: 2) {
      titulo
    }
  }
}

# resposta
{
  "data": {
    "usuario": {
      "nome": "Ana",
      "posts": [
        { "titulo": "Introdução a testes" },
        { "titulo": "Refatorando legado" }
      ]
    }
  }
}

Note dois pontos. Primeiro, a resposta tem exatamente a forma da pergunta — nada além. Segundo, usuário e posts vieram juntos, numa única viagem à rede; em REST isso normalmente seriam duas chamadas.

Os problemas que o GraphQL resolve

Over-fetching — receber campos que a tela não usa, gastando banda à toa. Com GraphQL, você pede só o necessário.
Under-fetching — precisar de várias chamadas encadeadas para montar uma tela. Uma query resolve o grafo inteiro.
Proliferação de endpoints — cada nova tela pedindo um endpoint sob medida. O schema é único e flexível.
Documentação desatualizada — o schema é tipado e introspectável, então a documentação nasce do próprio código.

Schema, queries e mutations

Toda API GraphQL começa por um schema: a declaração tipada de quais dados existem e como se relacionam. As queries leem dados; as mutations alteram; e as subscriptions mantêm um canal aberto para receber atualizações em tempo real. Diferente do REST, tudo isso trafega por um único endpoint, normalmente /graphql.

Definição de schema

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

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

type Mutation {
  criarPost(titulo: String!, autorId: ID!): Post!
}

Os custos que vêm junto

GraphQL não é gratuito em complexidade. O cache deixa de ser trivial, porque não há URL distinta por recurso para o HTTP cachear. Uma query mal escrita pode disparar o problema N+1, gerando centenas de consultas ao banco. E como o cliente controla a forma da consulta, é preciso limitar profundidade e complexidade para evitar que uma query maliciosa derrube o servidor. Para APIs simples e estáveis, uma REST API costuma entregar o mesmo resultado com menos peças móveis.

## faq

Perguntas frequentes

GraphQL substitui o REST?

Não necessariamente. GraphQL faz sentido quando há muitos clientes com necessidades de dados diferentes ou relações complexas entre entidades. Para APIs pequenas, públicas ou com forte dependência de cache HTTP, REST continua sendo a escolha mais simples e frequentemente a melhor.

GraphQL usa qual método HTTP?

Quase sempre POST, para um único endpoint. Isso acontece porque a query vai no corpo da requisição. Algumas implementações aceitam GET com a query na URL, o que permite aproveitar cache HTTP, mas o limite de tamanho da URL restringe o uso.

O que é o problema N+1 em GraphQL?

É quando resolver uma lista de N itens dispara uma consulta ao banco para cada item, mais a consulta original — N+1 no total. A solução padrão é o DataLoader, que agrupa as requisições feitas no mesmo ciclo de execução em uma única consulta em lote.