REST, GraphQL e gRPC
Três estilos de API, o problema que cada um resolve e como escolher entre eles.
Nenhum dos três estilos é melhor em geral. Cada um foi criado para um tipo de cliente e um tipo de problema, e a escolha depende de quem vai consumir a API.
Comparação direta
| Critério | REST | GraphQL | gRPC |
|---|---|---|---|
| Curva de aprendizado | Baixa | Média | Média |
| Tamanho das mensagens | Maior (JSON com campos fixos) | Sob medida para cada tela | Menor (binário) |
| Pedidos por tela | Vários, com frequência | Um | Um por função |
| Verificação de tipos | Só com OpenAPI e geração de código | No esquema, em tempo de execução e nas ferramentas | Na compilação, nas duas pontas |
| Cache em CDN e navegador | Nativo | Difícil: tudo é POST para um endereço | Não existe |
| Fluxo contínuo de dados | Limitado (SSE) | Assinaturas, sobre WebSocket | Nativo, nos dois sentidos |
| Depuração | curl e o navegador | Ferramentas próprias, boas | Ferramentas próprias; tráfego binário |
| Clientes aceitos | Qualquer um | Qualquer um que fale HTTP | Linguagens com código gerado; navegador só com proxy |
| Evolução do contrato | Versões ou campos novos | Campos novos e marcação de obsoletos | Campos novos com número novo |
REST
Onde brilha. APIs públicas e integrações com terceiros. Qualquer linguagem, ferramenta ou pessoa consegue consumir, a documentação é fácil de escrever e o cache do HTTP funciona sem esforço. A maior parte das APIs do mundo é REST por esse motivo.
O que custa.
- Telas ricas precisam de vários pedidos ou de endpoints sob medida.
- Sem OpenAPI, o contrato vive na documentação e diverge do código.
- Não existe um padrão único para erros, paginação e filtros. Cada API inventa o seu.
Erro comum. Criar um endpoint por tela (/tela-inicial, /resumo-pedido-mobile). A API passa a acompanhar o layout, e cada mudança de interface exige deploy do backend.
GraphQL
Onde brilha. Aplicações com muitas telas e clientes diferentes (web, iOS, Android) sobre os mesmos dados. As equipes de frontend evoluem as telas sem esperar o backend, e o esquema serve de documentação sempre atualizada.
O que custa.
- Consultas N+1. Cada campo tem um resolvedor. Em uma lista de 50 pedidos com o nome do cliente, a implementação direta faz 1 consulta para os pedidos e 50 para os clientes. A solução padrão é agrupar as buscas com um DataLoader.
- Custo imprevisível. O cliente pode pedir uma árvore profunda ou enorme. É preciso limitar a profundidade e a complexidade das consultas, ou aceitar apenas consultas registradas com antecedência.
- Cache. Como tudo é
POSTpara o mesmo endereço, CDNs e navegadores não ajudam. O cache passa a ser feito no cliente e por campo. - Erros. A resposta costuma vir com status
200e os erros dentro do corpo. O monitoramento baseado em códigos de status deixa de enxergar as falhas. - Autorização. A permissão precisa ser conferida em cada campo, porque o mesmo dado é alcançável por vários caminhos da consulta.
Erro comum. Adotar GraphQL em uma API com um único cliente e poucas telas. Paga-se toda a complexidade e não se usa a flexibilidade.
gRPC
Onde brilha. Comunicação entre serviços internos. O contrato gerado elimina uma classe inteira de erros de integração, o formato binário reduz latência e consumo de rede, e os fluxos contínuos atendem casos como acompanhamento em tempo real e envio de grandes volumes.
O que custa.
- Navegadores. O navegador não expõe o controle do HTTP/2 que o gRPC exige. É preciso um proxy com gRPC-Web ou uma camada REST na frente.
- Infraestrutura. Balanceadores precisam entender HTTP/2. Como uma conexão dura muito tempo e carrega muitos pedidos, um balanceador que distribui conexões manda todo o tráfego de um cliente para o mesmo servidor.
- Visibilidade. O tráfego não é legível sem ferramentas. Depurar exige o arquivo
.protoem mãos. - Disciplina no contrato. O número de cada campo é a identidade dele no formato binário. Reusar ou trocar um número corrompe os dados de clientes antigos sem nenhum erro aparente.
Erro comum. Expor gRPC diretamente a parceiros externos, que precisariam adotar a ferramenta de geração e a mesma versão do contrato.
Como escolher
| Situação | Escolha | Motivo |
|---|---|---|
| API pública ou para parceiros | REST | Qualquer um consome; documentação e cache simples |
| CRUD com um cliente web | REST | O ganho do GraphQL não compensa o custo |
| Vários clientes com telas diferentes sobre os mesmos dados | GraphQL | Cada cliente busca o que precisa em um pedido |
| Chamadas entre microsserviços | gRPC | Contrato verificado, baixa latência |
| Fluxo contínuo entre serviços | gRPC | Streaming nativo nos dois sentidos |
| Equipe pequena, prazo curto, sem requisito especial | REST | Menor curva e mais ferramentas prontas |
| Aplicativo móvel em rede lenta, com telas ricas | GraphQL | Menos pedidos e respostas menores |
Combinações que funcionam
Os estilos convivem bem em um mesmo sistema, cada um na camada em que rende mais.
| Arranjo | Como funciona | Quando faz sentido |
|---|---|---|
| REST por fora, gRPC por dentro | A API pública é REST; os serviços internos conversam por gRPC | Microsserviços com API aberta a terceiros |
| GraphQL como camada de agregação | Um servidor GraphQL na borda consulta serviços REST ou gRPC e monta a resposta para as telas | Muitos serviços internos e clientes com necessidades variadas |
| gRPC com tradução para REST | Um gateway gera endpoints REST e JSON a partir do mesmo .proto | Um único contrato atendendo serviços internos e clientes web |
Resumo da decisão
- Quem consome define o estilo: terceiros, telas próprias ou serviços próprios.
- REST é o padrão seguro. Saia dele quando houver um problema concreto que os outros resolvem.
- GraphQL troca simplicidade no servidor por autonomia no cliente. Só vale com vários clientes ou telas que mudam muito.
- gRPC troca alcance por rigor e desempenho. Fica dentro da sua rede.
O próximo nível implementa o mesmo serviço em gRPC nas cinco linguagens e mostra os cuidados de cada estilo no código.
Prompts para aprofundar
Ao abrir no ChatGPT ou no Claude, o prompt é enviado ao serviço escolhido pela URL e também fica copiado na sua área de transferência.
Escolher o estilo para o meu projeto
Preciso escolher entre REST, GraphQL e gRPC para uma API e quero chegar à decisão entendendo os critérios. Faça estas perguntas, uma por vez, e espere as respostas: - Quem vai consumir a API: terceiros, as nossas próprias telas, outros serviços nossos ou uma combinação? - Quantos tipos de cliente existem (web, aplicativo móvel, parceiros) e o quanto as telas diferem entre eles? - Com que frequência as telas mudam, e quem faz essas mudanças? - Qual é o tamanho e a experiência da equipe com cada estilo? - Há requisito de tempo real, grande volume de dados ou latência muito baixa? - Há necessidade de cache em CDN? Com as respostas, avalie cada estilo para o meu caso, apontando o benefício concreto e o custo concreto de cada um. Diga também quando a resposta certa é combinar estilos, e em qual camada cada um ficaria. Termine com uma recomendação, os dois principais riscos dela e os sinais que indicariam, no futuro, que é hora de rever a escolha.
Os custos escondidos do GraphQL
Estou considerando adotar GraphQL e quero entender os custos antes de decidir. Explique cada um destes problemas com um exemplo concreto, mostrando a consulta que causa o problema e a solução usual: 1. Consultas N+1 nos resolvedores e o uso de DataLoader. 2. Consultas muito profundas ou muito largas, e as defesas: limite de profundidade, análise de complexidade e consultas registradas. 3. A perda do cache HTTP e as alternativas no cliente e no servidor. 4. Erros devolvidos com status 200 e o efeito disso no monitoramento. 5. Autorização por campo, e por que conferir a permissão só na entrada da consulta é insuficiente. Depois descreva três projetos e pergunte, para cada um, se eu adotaria GraphQL: - Um painel administrativo com um único cliente web e vinte telas de cadastro. - Um produto com site, aplicativo iOS e aplicativo Android, com telas diferentes sobre os mesmos dados. - Uma API pública para parceiros integrarem seus sistemas. Comente as minhas respostas e diga o que pesou em cada caso.
Arquiteturas que combinam os estilos
Quero entender como REST, GraphQL e gRPC convivem em um mesmo sistema. Explique estes três arranjos, com um desenho em texto do caminho de um pedido em cada um: 1. API pública em REST e comunicação entre serviços internos em gRPC. 2. Um servidor GraphQL na borda, agregando dados de serviços REST ou gRPC. 3. Um único contrato .proto atendendo gRPC e, por um gateway de tradução, REST com JSON. Para cada arranjo, diga qual problema ele resolve, o que acrescenta de complexidade operacional e o que acontece com autenticação, tratamento de erros e rastreamento de um pedido que atravessa as camadas. Pergunte como é a arquitetura do meu sistema hoje e diga qual desses arranjos, se algum, faria sentido para mim, e por onde começar a migração sem reescrever tudo.