O GraphQL chegou como resposta ao over-fetching do REST e cruzou o hype entre 2016 e 2020. Em 2026 ele ganha de REST onde o cliente precisa moldar a resposta e perde onde um CRUD simples basta. Três casos reais mostram a decisão.

O que GraphQL entrega

O cliente molda a resposta e elimina over-fetching em redes restritas, situação típica de apps móveis. Uma query única agrega múltiplos recursos em um round trip só, no lugar de três chamadas REST encadeadas. O schema tipado serve como documentação e contrato ao mesmo tempo, validado em CI com ferramentas como graphql-schema-linter.

O que custa

  • N+1 queries sem batching estilo DataLoader; cada campo resolve em round trip separado contra o banco
  • Query depth attacks exigem analisadores de profundidade e limites de complexidade configurados
  • O cache perde a semântica gratuita do HTTP; persisted queries devolvem parte do controle
  • Cada cliente acopla-se ao schema, e o time preserva esse contrato para sempre

Caso 1: produto mobile-first

Schemas desenhados por tela cortaram payload em 60% frente a um REST tagarela de cinco chamadas por view. Bateria e 4G instável transformaram a economia em retenção mensurável.

Caso 2: painel administrativo interno

Cinco usuários batendo em CRUD simples. A cerimônia do GraphQL não entregou nada que REST deixasse de entregar, e o ônus de manutenção ficou do mesmo jeito. REST com OpenAPI resolvia em um fim de semana.

Caso 3: plataforma de API pública

GitHub e Shopify justificam GraphQL pela diversidade de clientes: milhares de integrações terceiras consumindo formas variadas de dados. Times que expõem um frontend único para um backend único colhem pouco desse retorno. Diversidade de consumidores é o gatilho, não moda.

Federação em escala

Apollo Federation e as ferramentas da The Guild compõem graphs entre times, com router central e contratos por subgraph. Potente em escala organizacional, maquinaria pesada abaixo de dez engenheiros: o custo de operar o router supera o benefício em times pequenos.

Alternativas que roubaram casos

  • tRPC dá tipos ponta a ponta em monorepos TypeScript, sem runtime adicional
  • REST com codegen a partir de OpenAPI cobre a maioria dos CRUDs
  • JSON:API resolve sparse fieldsets quando o cliente precisa escolher campos

Regra de decisão

Muitos clientes independentes consumindo formas variadas de dados justificam GraphQL. Um ou dois frontends first-party quase nunca justificam. Decida pelo número de consumidores, não pela empolgação do roadmap.