REST vs GraphQL vs gRPC: uma estrutura de decisão para 2026

Sua equipe inicia um novo serviço. Alguém abre um tópico no Slack: “Devemos usar GraphQL?” Outra pessoa responde com um link para um benchmark gRPC. O tópico se divide em três campos. Duas horas depois, nenhuma decisão.

O problema não é a falta de informação. O problema é a falta de critérios. REST, GraphQL e gRPC cada resolver uma forma diferente de problema. Escolha o errado e você pagará o imposto sobre cada solicitação durante anos. Escolha o caminho certo e a arquitetura ficará em segundo plano.

Este guia fornece uma estrutura de decisão concreta, e não "depende". Cada protocolo recebe um específico caso de uso em que ele vence, um exemplo de código que você pode executar e uma tabela de comparação na qual você pode inserir um documento de design.

A estrutura de 30 segundos

Comece com três perguntas:

1. Quem chama essa API? Desenvolvedores externos, seus próprios clientes front-end ou serviços internos?
2. De quantas formas de dados o cliente precisa? Uma forma fixa ou muitas variações?
3. O que é mais importante: capacidade de cache, flexibilidade de consulta ou rendimento bruto?

As respostas são mapeadas diretamente para um protocolo:

• DESCANSAR ganha quando o público é externo, o formato dos dados é fixo e o armazenamento em cache é importante.
• GráficoQL ganha quando vários clientes precisam de diferentes fatias do mesmo gráfico de dados.
• gRPC vence quando os serviços internos conversam entre si e o rendimento é mais importante do que a legibilidade humana.

Aqui está a mesma lógica do código:

REST: o padrão universal

REST mapeia operações para verbos HTTP e recursos para URLs. Toda linguagem de programação possui um cliente HTTP. Cada CDN entende cabeçalhos de cache. Todo desenvolvedor usou curl.

REST é a escolha certa para APIs públicas onde você controla o formato dos dados e os clientes esperam estabilidade, pontos de extremidade documentados. Todos os mais de 150 endpoints de API do botoi usam REST. Aqui está uma pesquisa de DNS:

Resposta:

A solicitação é um único POST. A resposta é um objeto JSON simples. Você pode testá-lo com curl, canalizá-lo através jq, ou chame-o de qualquer idioma com fetch. Nenhum arquivo de esquema para compilar, nenhuma linguagem de consulta para aprender, nenhuma etapa de geração de código.

Onde REST brilha

• APIs públicas para desenvolvedores. Desenvolvedores terceirizados esperam REST. O custo de integração é zero.
• Recursos armazenáveis ​​em cache. O cache HTTP funciona em todas as camadas: navegador, CDN, proxy reverso. UM GET /users/123 a resposta com cabeçalhos de cache adequados não custa nada em solicitações repetidas.
• Integrações de webhook. Webhooks são solicitações HTTP POST. REST se ajusta ao modelo mental.
• Operações CRUD simples. Quando cada endpoint faz algo com um formato de entrada e um formato de saída, REST não adiciona sobrecarga.

Onde REST fica aquém

• Busca excessiva. Um aplicativo móvel que precisa de três campos de um perfil de usuário ainda baixa o objeto completo de 40 campos.
• Busca insuficiente. Um painel que mostra um usuário, sua equipe e suas atividades recentes faz três chamadas HTTP sequenciais. A latência aumenta.
• Nenhuma evolução de esquema integrada. Seus URLs de versão (/v1/, /v2/) ou adicione campos e espere que os clientes ignorem chaves desconhecidas.

GraphQL: consultas orientadas ao cliente

GraphQL permite que o cliente especifique exatamente quais campos ele precisa em uma única solicitação. O servidor expõe um esquema digitado. O cliente escreve uma consulta nesse esquema e recebe de volta uma resposta moldada para corresponder.

A API pública do GitHub demonstra isso bem. Uma consulta busca seu nome de usuário e os três principais repositórios com contagem de estrelas e idioma principal. Em REST, isso exigiria pelo menos 2 chamadas.

Resposta:

O cliente pediu name, stargazerCount, e primaryLanguage. O servidor retornou exatamente esses campos. Nenhum dado extra transferido. Nenhum segundo pedido.

Onde o GraphQL brilha

• Aplicativos móveis. A largura de banda é limitada. O tamanho da carga útil é importante. GraphQL elimina a busca excessiva em todas as telas.
• Painéis e visualizações de agregação. Uma única consulta pode extrair dados de usuários, pedidos e estoque em uma viagem de ida e volta.
• Iteração rápida de front-end. As equipes de front-end alteram suas consultas sem esperar que as equipes de back-end criem novos endpoints.
• Digitação forte. O esquema é o contrato. Ferramentas de geração de código como GraphQL Code Generator produzem tipos TypeScript a partir dele.

Onde o GraphQL fica aquém

• Cache. Cada consulta é um POST para /graphql. O cache HTTP no CDN ou no nível do navegador não funciona sem uma camada de consulta persistente ou consultas baseadas em GET.
• Superfície de segurança. Os clientes podem escrever consultas caras que unem dados profundamente aninhados. Você precisa de análise de custos de consulta e limitação de profundidade para evitar abusos.
• Curva de aprendizado. Os desenvolvedores precisam aprender a linguagem de consulta, design de esquema, resolvedores e padrões DataLoader. O tempo de aceleração é maior que REST.
• Consultas N+1. Os padrões de resolução ingênuos acionam uma consulta ao banco de dados por item em uma lista. O lote do DataLoader corrige isso, mas você mesmo deve construí-lo.

gRPC: velocidade interna

gRPC usa buffers de protocolo para serialização e HTTP/2 para transporte. Você define seu serviço contrato em um .proto arquivo, gerar código de cliente e servidor e obter chamadas RPC com segurança de tipo com cargas binárias.

A partir desta definição, protoc gera stubs de cliente e interfaces de servidor em Go, Java, Python, Rust, C++ ou uma dúzia de outras linguagens. O código gerado lida com serialização, desserialização, e enquadramento HTTP/2.

Onde o gRPC brilha

• Comunicação serviço a serviço. Microsserviços internos que trocam mensagens de alta frequência se beneficiam da serialização binária e de fluxos multiplexados.
• Contratos rígidos. O .proto arquivo é a única fonte da verdade. Mudanças significativas são detectadas em tempo de compilação, não em tempo de execução.
• Transmissão bidirecional. gRPC oferece suporte a streaming de servidor, streaming de cliente e streaming bidirecional. Recursos em tempo real, como feeds de transações ao vivo, se adaptam naturalmente.
• Ambientes poliglotas. Um serviço Go pode chamar um serviço Python por meio de stubs gerados com zero código de serialização manual.

Onde o gRPC fica aquém

• Suporte ao navegador. Os navegadores não podem fazer chamadas gRPC nativas. O proxy grpc-web adiciona uma camada de complexidade e latência.
• Legibilidade humana. Cargas binárias não são inspecionáveis ​​com curl ou ferramentas de desenvolvimento de navegador. A depuração requer ferramentas especializadas como grpcurl ou BloomRPC.
• Maturidade do ecossistema. REST tem décadas de ferramentas: Postman, Swagger, gateways de API, limitadores de taxa. As ferramentas gRPC estão crescendo, mas não no mesmo nível.
• Curva de aprendizado. As equipes devem aprender buffers de protocolo, sintaxe proto3, pipelines de geração de código e padrões de tratamento de erros específicos do gRPC.

Tabela de comparação

Exemplos de decisões do mundo real

Stripe: REST para pagamentos

Stripe processa bilhões de dólares em pagamentos por meio de uma API REST. Seus endpoints seguem previsíveis padrões: POST /v1/payment_intents, GET /v1/charges/:id. Todo desenvolvedor quem integra o Stripe conhece HTTP. O atrito de integração é próximo de zero. Stripe escolheu REST porque seu público são desenvolvedores externos que precisam de endpoints estáveis, documentados e armazenáveis em cache.

GitHub: GraphQL para ferramentas de desenvolvedor

GitHub migrou de REST (v3) para GraphQL (v4) porque seus clientes (aplicativos de desktop, aplicativos móveis, integrações de terceiros) precisavam de dados diferentes dos mesmos objetos. Uma ferramenta de CI precisa de comprometimento status e verificações. Um aplicativo de gerenciamento de projetos precisa de problemas, rótulos e responsáveis. Um aplicativo móvel precisa de uma visão de perfil mínima. Um endpoint REST não poderia servir todos os três sem uma busca excessiva massiva.

Google: gRPC para serviços internos

O Google criou o gRPC (o "g" significa uma palavra diferente a cada versão) para lidar com serviço a serviço interno comunicação em escala. Quando sua malha de serviço processa milhões de RPCs por segundo, a diferença entre a análise de texto JSON e a desserialização binária do buffer de protocolo são importantes. O Google escolheu o gRPC porque o público é interno, os contratos são rígidos e o rendimento é a principal restrição.

Por que o botoi escolheu REST para mais de 150 endpoints

A API do botoi atende endpoints de utilitários independentes: pesquisas de DNS, validação de e-mail, formatação JSON, código QR geração, cálculo de hash. Cada endpoint recebe uma entrada específica e retorna uma saída específica. Não há gráfico de dados relacionais conectando um registro DNS a um código QR.

Três fatores tornaram REST a escolha certa:

• Suporte universal ao cliente. Os desenvolvedores chamam botoi de Node.js, Python, Go, Ruby, PHP, scripts de shell e agentes de IA. REST funciona em todos eles sem configuração.
• Cacheabilidade. Pontos de extremidade GET para recursos estáticos (como pesquisas de países ou listas de moedas) se beneficiar do cache HTTP na camada CDN. Isso mantém os tempos de resposta abaixo de 20 ms para solicitações repetidas.
• Descoberta. Cada endpoint possui uma URL estável, uma entrada de especificação OpenAPI e recursos interativos. documentos via Scalar. Novos desenvolvedores encontram e testam endpoints em menos de um minuto.

GraphQL adicionaria complexidade sem benefícios. Não há gráfico de consulta para percorrer. gRPC faria exclua clientes de navegador e scripts de shell. REST é a ferramenta certa para esse tipo de problema.

Misturando protocolos em um sistema

A estrutura se aplica por limite, não por organização. Muitos sistemas de produção combinam protocolos:

• Camada API externa: DESCANSAR. Desenvolvedores terceirizados e webhooks esperam HTTP + JSON.
• Gateway voltado para o cliente: GráficoQL. Os clientes móveis e da web consultam um gateway que agrega dados de vários serviços.
• Malha de serviço interna: gRPC. Os serviços de back-end se comunicam com cargas binárias e contratos rígidos.

Isto não é complexidade pela complexidade. Cada fronteira tem um público diferente com diferentes restrições. O protocolo deve corresponder à restrição, e não o contrário.

Lista de verificação de decisão

Copie isso em seu documento de design. Responda a cada pergunta e a escolha do protocolo se tornará óbvia.

1. Quem são os consumidores da API? Desenvolvedores externos (REST), sua própria equipe de frontend (GraphQL), serviços internos (gRPC).
2. Quantos formatos de dados os clientes solicitam? Uma forma (REST), muitas formas (GraphQL), contratos fixos (gRPC).
3. O cache HTTP é importante? Sim (REST), às vezes (GraphQL com esforço), não (gRPC).
4. Você precisa de streaming? Não (REST está bem), assinaturas (GraphQL), bidirecionais (gRPC).
5. Quais idiomas os clientes usam? Tudo (REST), pesado em JS/TS (as ferramentas GraphQL são mais fortes aqui), poliglota com geração de código (gRPC).
6. Qual é a expertise atual da equipe? Se ninguém conhece os buffers de protocolo, o gRPC terá um custo de aumento acentuado. Se ninguém conhece os resolvedores GraphQL, espere um mês de aprendizado antes de estar pronto para produção.

Erros comuns a evitar

• Escolhendo GraphQL porque parece novo. GraphQL adiciona complexidade de resolução, consulta análise de custos e mitigação N+1. Se sua API tiver 10 endpoints CRUD com formas fixas, REST não o mesmo trabalho com menos código.
• Escolhendo gRPC para uma API pública. Seus usuários não podem chamar gRPC de um navegador, de curl ou de uma ferramenta de baixo código. Você acabará construindo um gateway REST na frente dele de qualquer maneira.
• Escolhendo REST para um gráfico de dados complexo. Se sua equipe de front-end solicitar 5 novos endpoints de "resumo" por sprint porque os existentes retornam muitos ou poucos dados, isso é um sinal de que o GraphQL reduziria a sobrecarga de coordenação.
• Ignorando a experiência da equipe. O protocolo mais rápido para enviar é aquele que sua equipe já sabe. Uma equipe fluente em REST que muda para gRPC gastará semanas trabalhando em ferramentas antes escrever lógica de negócios.