Neste artigo
- O que exatamente muda entre os dois modelos?
- Overfetching e underfetching: o argumento central do GraphQL
- Cache, autenticação e ferramentas HTTP
- O lado do servidor: resolver e N+1
- Ecossistema e casos reais
- Quatro perguntas que fecham a decisão
- GraphQL substitui REST?
- GraphQL é mais rápido que REST?
- REST exige documentação OpenAPI?
- Como versionar cada modelo?
- Dá para começar por GraphQL direto?
A escolha entre GraphQL e REST depende do formato do consumo dos dados: REST organiza a API em recursos fixos com cache HTTP maduro, e GraphQL entrega um endpoint único em que o cliente desenha a resposta. Nenhum é superior em absoluto, e a decisão vem do perfil dos consumidores da API.
Escolha REST quando os consumidores são muitos, variados e dependentes de cache HTTP, e quando os recursos são estáveis; escolha GraphQL quando há várias telas com necessidades de dados diferentes e o time sofre com overfetching e chamadas encadeadas. Para a base de decisão, os fundamentos para você entender tudo sobre uma API explicam o vocabulário de contrato, versão e cache.
O que exatamente muda entre os dois modelos?
REST expõe recursos por URL, com verbos HTTP e status padronizados, e cada endpoint devolve um formato fixo decidido pelo servidor. GraphQL expõe um schema tipado e um único endpoint, e cada cliente especifica na consulta exatamente os campos que precisa. A consequência é direta: no REST, o servidor decide o pacote; no GraphQL, quem consome desenha a resposta dentro do que o schema permite.
Overfetching e underfetching: o argumento central do GraphQL
Em REST, telas diferentes do mesmo recurso costumam receber campos que não usam, o overfetching, ou precisam encadear chamadas, o underfetching. GraphQL resolve os dois com a consulta que pede só o necessário, em uma única requisição. O ganho aparece em aplicativo móvel com rede limitada: uma consulta devolve a tela inteira, do tamanho exato do que ela exibe.
query {
pedido(id: 42) {
total
cliente { nome }
}
}
A mesma resposta em REST exigiria um endpoint dedicado ou duas chamadas. O custo é o outro lado: o servidor precisa resolver cada campo e cuidar do problema de N+1.
Cache, autenticação e ferramentas HTTP
REST herda o cache HTTP de graça: GET, ETag e status padrão funcionam com proxies e CDNs sem código extra. No GraphQL, tudo passa por POST em um endpoint único, e o cache passa a ser decisão de aplicação, com ferramentas no cliente ou no servidor. No GraphQL, limitar por URL não basta, e o limite passa a considerar a complexidade da consulta.
O lado do servidor: resolver e N+1
Cada campo do schema tem um resolver, e a implementação ingênua dispara uma consulta de banco por campo, o clássico N+1. A solução é agrupar carregamentos em lote, com DataLoader ou mecanismo equivalente. O trabalho de otimização é o mesmo do REST, apenas mais visível: dominar o banco decide a performance, e o guia completo de PostgreSQL para 2026 cobre consulta em lote e índices.
A tabela resume os critérios que costumam decidir:
| Critério | REST | GraphQL |
|---|---|---|
| Formato da resposta | Fixo, definido pelo servidor | Desenhada pelo cliente |
| Cache | HTTP nativo | Ferramentas de aplicação |
| Curva de entrada | Menor | Schema e resolvers |
| Documentação | OpenAPI, mantida à parte | Introspecção do schema |
Ecossistema e casos reais
REST segue dominando APIs públicas e integrações entre empresas, pela simplicidade e pelo suporte universal. GraphQL vem de produtos com muitas superfícies de consumo, como redes sociais e comércio eletrônico com app, web e painel sobre os mesmos dados. Serviços Node têm implementações maduras nas duas abordagens, e o guia de Node.js, Deno e Bun em 2026 compara os runtimes que hospedam essas APIs.
ℹ️ Info: os dois convivem em muitos times: REST para integrações públicas e GraphQL para o aplicativo próprio. API pública estável em REST com GraphQL na borda de consumo é padrão recorrente em produto médio.
Um ponto que costuma decidir na prática e quase nunca aparece nos comparativos é o cache: REST brilha quando entra em CDN com HTTP puro, enquanto GraphQL exige estratégia própria, porque qualquer resposta, por definição variável, é mais difícil de cachear na borda. Se o tráfego for grande e a margem apertada, essa diferença de cache pode pesar mais que elegância de schema na decisão final.
Na dúvida entre os dois, o prototipinho de uma semana com o seu caso real encerra a discussão melhor que qualquer artigo.
Quatro perguntas que fecham a decisão
Primeira: quem consome a API? Poucos consumidores conhecidos empurram para REST; muitas superfícies com necessidades distintas empurram para GraphQL. Segunda: o cache importa no tamanho do tráfego? Se a resposta é sim e o conteúdo é público ou semiaberto, o cache HTTP nativo pesa a favor do REST. Terceira: o time já opera o modelo? Curva de aprendizado é custo real no calendário, e schema com resolvers pede maturidade que não se improvisa na véspera do lançamento. Quarta: a API vai mudar rápido? Contratos que evoluem a cada sprint se beneficiam da evolução sem versão do GraphQL, enquanto recursos estáveis convivem bem com versão por URL.
Quando essas quatro respostas apontam para lados diferentes, a recomendação prática é começar simples: uma API REST bem desenhada entrega o produto, e a migração parcial para GraphQL depois, na borda de consumo, é caminho testado por muitos times. A escolha de tecnologia faz mais sentido quando parte do problema concreto, do mesmo jeito que o guia de como escolher a stack para o primeiro projeto recomenda para a stack inteira.
Perguntas frequentes
GraphQL substitui REST?
Não. REST segue padrão para APIs públicas, integrações e casos em que cache HTTP vale muito. GraphQL é melhor em consumo variado sobre os mesmos dados, não um substituto universal.
GraphQL é mais rápido que REST?
Depende da consulta e da implementação. Uma consulta bem resolvida economiza chamadas e payload; um resolver mal escrito gera N+1 e demora mais que o endpoint REST equivalente bem indexado.
REST exige documentação OpenAPI?
Exige documentação para ser útil, e OpenAPI é o formato padrão. A diferença do GraphQL é que o schema é introspectável e a documentação se atualiza junto com o contrato.
Como versionar cada modelo?
No REST, versiona por URL ou header. No GraphQL, o schema evolui sem versão: campos são descontinuados e removidos quando o consumo cai, o que exige disciplina de deprecação.
Dá para começar por GraphQL direto?
Dá, e é caminho razoável para produto novo com muitas telas. Vale aprender HTTP e REST antes, porque status, cache e autenticação continuam presentes no GraphQL.