REST vs GraphQL: qual usar na sua API?

Ao construir uma API, uma das decisões mais importantes é escolher o estilo arquitetural. Por anos, o REST dominou o mercado. Mais recentemente, o GraphQL — criado pelo Facebook em 2012 e aberto ao público em 2015 — ganhou força como alternativa. Mas qual usar?

O que é REST?

REST (Representational State Transfer) é um conjunto de convenções arquiteturais baseado em endpoints HTTP. Cada recurso tem sua própria URL e você interage com ele usando os verbos HTTP: GET, POST, PUT, DELETE.

GET /usuarios/42 # busca usuário
POST /usuarios # cria usuário
GET /usuarios/42/pedidos # busca pedidos do usuário

O que é GraphQL?

GraphQL é uma linguagem de consulta para APIs. Em vez de múltiplos endpoints, existe apenas um — geralmente /graphql. O cliente descreve exatamente os dados que precisa na própria requisição.

query {{'{'}}
  usuario(id: 42) {{'{'}}
    nome
    email
    pedidos {{'{'}} total status {{'}'}}
  {{'}'}}
{{'}'}}

Comparação direta

Critério	REST	GraphQL
Curva de aprendizado	Baixa	Média
Over-fetching	Comum	Eliminado
Múltiplos recursos	N chamadas	1 chamada
Cache HTTP nativo	Sim	Complexo
Ideal para	APIs públicas simples	Apps com muitas telas

Quando usar cada um?

Use REST quando: sua API é pública e consumida por terceiros, a equipe é pequena e prefere simplicidade, ou você precisa de cache HTTP nativo.

Use GraphQL quando: seu frontend tem muitas telas com necessidades de dados diferentes (ex: app mobile vs web), você quer evitar múltiplas chamadas, ou está construindo um BFF (Backend for Frontend).

GraphQL na prática: como montar um servidor

Com Node.js e a biblioteca Apollo Server, você pode ter um servidor GraphQL rodando em minutos:

npm install @apollo/server graphql

// Definição do schema (contrato da API)
const typeDefs = `#graphql
type Usuario {{'{'}} id: ID, nome: String, email: String {{'}'}}
type Query {{'{'}} usuario(id: ID!): Usuario {{'}'}}
`;

// Resolvers (onde a lógica vive)
const resolvers = {{'{'}} Query: {{'{'}} usuario: (_, {{'{'}}id{{'}'}}) => buscarUsuario(id) {{'}'}}
{{'}'}};

O problema do over-fetching no REST

Imagine que você tem uma tela de perfil no app mobile que precisa apenas do nome e foto do usuário. Com REST, a chamada GET /usuarios/42 retorna todos os campos — CPF, endereço, histórico de compras, configurações. Isso é over-fetching: você recebe muito mais do que precisa, desperdiçando banda (crítico em mobile) e aumentando o tempo de parsing.

Com GraphQL, você pede exatamente nome e fotoPerfil e recebe apenas esses dois campos.

tRPC: uma terceira opção para TypeScript

Para projetos full-stack em TypeScript, o tRPC é uma alternativa interessante que combina o melhor dos dois mundos: tipagem end-to-end automática (sem schema manual como no GraphQL) e simplicidade de REST. O cliente e o servidor compartilham os mesmos tipos TypeScript, eliminando completamente a necessidade de escrever schemas separados ou gerar código.

Adoção no mercado

GitHub, Shopify, Twitter e Facebook usam GraphQL em produção. Mas grandes APIs públicas como Stripe, Twilio e a maioria dos serviços de pagamento ainda usam REST. A tendência para novos projetos com frontends complexos é GraphQL, mas REST está longe de morrer — especialmente para integrações B2B e APIs públicas simples.

Conclusão

Não há resposta errada — há a resposta certa para o seu contexto. Para projetos novos com frontends complexos e mobile, GraphQL vale o investimento. Para APIs simples, REST ainda é a escolha mais pragmática e amplamente suportada.