REST ou gRPC: quando convém cada um, e por que o core da empresa não fala nenhum dos dois

A pergunta «REST ou gRPC?» costuma ser colocada como se fosse preciso escolher um lado para toda a arquitetura. Na prática, quase nunca se decide uma única vez: decide-se em cada fronteira. Uma API que terceiros recebem, uma chamada entre dois serviços da mesma equipe e a conexão com um sistema de vinte anos atrás pedem respostas diferentes.

É o aprofundamento do ramo «online» do nosso artigo sobre online ou assíncrono: lá se decide quando convém responder na hora, e aqui com qual protocolo fazê-lo e o que fazer quando o sistema do fundo não consegue.

Este artigo é para a equipe técnica que precisa tomar essas decisões: arquitetos, líderes de desenvolvimento e quem integra sistemas em bancos, seguradoras, fintechs ou varejo. Propõe um critério que se resume em uma frase:

REST na fronteira, gRPC no coração, adaptador para o legado.

É um critério, não uma regra; no final aparecem os casos em que convém rompê-lo. Uma primeira glosa: REST é um estilo de API sobre HTTP, orientado a recursos e verbos, quase sempre em JSON; gRPC é um marco de chamadas de procedimento remoto (RPC) de alto desempenho, com contrato em Protobuf (Protocol Buffers).

O que é gRPC, em cinco ideias

gRPC é um marco de chamadas de procedimento remoto (RPC). Em vez de pensar em recursos e URLs, pensa-se em serviços com métodos que são invocados à distância como se fossem locais. Cinco ideias o definem:

1. O contrato vem primeiro. O serviço e as mensagens dele são descritos em um arquivo .proto. Por padrão, o gRPC usa Protocol Buffers (Protobuf) como linguagem de definição de interfaces, tanto para o serviço quanto para a estrutura das mensagens [1]. Do .proto geram-se o cliente e a base do servidor, tipados, nas linguagens que a equipe usar [4].
2. Roda sobre HTTP/2 e viaja em binário. O gRPC foi desenhado para HTTP/2, que oferece empacotamento binário, compressão e multiplexação de várias chamadas sobre uma única conexão TCP. O Protobuf produz mensagens pequenas e é serializado com rapidez. Um detalhe que convém não perder: o HTTP/2 não é exclusivo do gRPC; uma API HTTP com JSON também pode usá-lo [4].
3. Streaming de primeira classe. Além da chamada simples (uma requisição, uma resposta), existem o streaming do servidor para o cliente, do cliente para o servidor e o bidirecional. O gRPC garante a ordem das mensagens dentro de uma mesma chamada [1]. Serve para telemetria, cotações ao vivo ou notificações.
4. Prazos (deadlines) explícitos. O cliente indica quanto está disposto a esperar; se o prazo vence, a chamada termina com o erro DEADLINE_EXCEEDED [1]. Por padrão o gRPC não fixa nenhum prazo, de modo que um cliente pode ficar esperando praticamente para sempre [2]. Ao vencer o prazo, o gRPC cancela a chamada, mas a aplicação deve detectar esse cancelamento e interromper o trabalho que disparou [2]. O prazo pode se propagar às chamadas que esse serviço faz a outros, para não gastar recursos em uma resposta que ninguém mais espera [2][4].
5. Estados de erro com vocabulário próprio. Cada chamada termina com um código de estado de um catálogo de 17 valores, entre eles INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, UNAUTHENTICATED, RESOURCE_EXHAUSTED e UNAVAILABLE [3]. A página oficial de códigos não define uma equivalência com os códigos HTTP. Quem expuser o serviço para fora deve decidir essa tradução por escrito.

O gRPC não é «REST mais rápido»: é outro modelo, com contrato obrigatório e uma especificação estrita que, segundo a Microsoft, evita o debate sobre o formato de URL, verbos e códigos de resposta [4]. Se além disso se expuser HTTP/JSON, essas rotas, verbos e erros precisam ser definidos do mesmo jeito. E não é de graça: o formato binário não se lê a olho nu e exige o contrato para ser interpretado [4].

Quando REST

REST é um estilo de design sobre HTTP orientado a recursos, verbos e representações, quase sempre em JSON. É a opção padrão na fronteira: onde o sistema da empresa encontra quem ela não controla.

• Terceiros e integradores. Quem consome a API não tem por que adotar a ferramenta de geração de código da empresa. REST/JSON reduz a dependência de SDKs gerados e facilita a inspeção e os testes manuais; um parceiro pode testar uma chamada com curl em um minuto.
• Frontend no navegador. Nenhum navegador dá o controle sobre HTTP/2 de que o gRPC precisa, por isso não se pode chamar um serviço gRPC diretamente de uma página [4]. Mais adiante vê-se o que fazer quando mesmo assim se quer gRPC na web.
• Depuração humana. Uma requisição REST se lê, se copia, se cola em um ticket e se reproduz. Com gRPC são necessárias ferramentas que entendam o formato [4].

Quando gRPC

Considere o gRPC quando a empresa controlar o provedor e o consumidor, aceitar governar os .proto e tiver uma restrição medida de latência, tamanho de mensagem ou volume. Os cenários que a documentação da Microsoft recomenda são microsserviços de baixa latência e alto desempenho, comunicação ponto a ponto em tempo real, ambientes com várias linguagens, redes com restrições de largura de banda e comunicação entre processos de uma mesma máquina [4].

• Serviços internos. Entre serviços do mesmo domínio de confiança, o contrato forte e o cliente gerado evitam uma categoria inteira de erros: campos que mudam de nome, tipos interpretados de forma diferente, clientes escritos à mão que ficam defasados.
• Contrato forte entre equipes. Quando várias equipes e linguagens compartilham serviços, o .proto funciona como um acordo executável: se não compila, não se integra.
• Volume. Quando se fazem muitas chamadas pequenas, o tamanho da mensagem e a multiplexação sobre uma conexão se notam. Meça com a carga real antes de justificar a mudança pela velocidade.
• Streaming. Se o caso de uso é um fluxo (preços, eventos de dispositivos, andamento de um processo longo), o gRPC o oferece como parte do contrato, não como um acréscimo.

Há um caso que a Microsoft exclui: a difusão em massa para muitos clientes conectados; o gRPC não tem o conceito de «broadcast» e cada chamada transmite separadamente [4].

O navegador e o gRPC-Web

Como o navegador não consegue falar gRPC nativo, existe o gRPC-Web: um protocolo adaptado, com um cliente gerado em JavaScript e um proxy compatível (o tutorial oficial usa o Envoy) entre o navegador e o serviço gRPC; pode exigir ainda configuração de CORS [5].

Tem limites que convém conhecer antes de decidir. No repositório do projeto, o streaming do servidor para o cliente só é aceito no modo grpcwebtext, e o streaming do cliente e o bidirecional não são suportados [6]. A Microsoft o classifica entre as razões para preferir outro marco quando a API precisa ser acessível a partir do navegador: o gRPC-Web oferece suporte, mas com limitações e com um proxy de servidor adicional [4].

Regra prática: gRPC-Web se a aplicação web é da própria empresa e a plataforma já usa Protobuf; REST/JSON se terceiros a consumirão.

Expor gRPC como REST sem escrever a lógica duas vezes

Não é preciso escolher entre as duas faces. O contrato .proto pode levar anotações HTTP (google.api.http) que dizem qual rota e verbo correspondem a cada método. Um componente intermediário, normalmente o gateway ou um proxy, converte a requisição HTTP/JSON em chamada gRPC e devolve a resposta em JSON. Esse mecanismo se chama transcoding [4][7][18]:

Cliente REST  → gateway (transcoding) → serviço gRPC → adaptador → core legado
Cliente gRPC  ──────────────────────→ serviço gRPC → adaptador → core legado

Dois exemplos de gateways que o oferecem, como categoria e não como recomendação:

• Envoy tem o filtro gRPC-JSON transcoder, que permite que um cliente REST com JSON envie requisições por HTTP e elas sejam encaminhadas a um serviço gRPC. Exige conhecer o descritor Protobuf do serviço e as anotações HTTP no contrato [7].
• Apache APISIX tem o plugin grpc-transcode, que transforma requisições e respostas entre HTTP e gRPC. Os protos são registrados pela API de administração dela, como texto ou como descritor binário [8]. A documentação consultada não menciona streaming; confirme na versão em uso.

A ideia: uma única implementação, duas formas de chamá-la.

Dois cuidados, que o transcoding não resolve sozinho:

• Erros. O conversor traduz códigos, mas a política do que cada um significa para um terceiro é definida pela empresa. Um UNAVAILABLE interno deve aparecer como erro de serviço indisponível ou ser reenviado antes?
• Segurança. Autenticação, autorização fina e cotas são preocupações do gateway e do serviço, não do formato.

Ferramentas de teste: o que segue vigente

Testar um serviço gRPC à mão pede uma ferramenta que entenda Protobuf. Este é o estado que verificamos em 6 de outubro de 2026; qualquer mudança posterior pode alterá-lo.

A reflexão de servidor permite descobrir métodos sem o .proto, mas precisa ser habilitada no serviço e, em produção, convém decidir para quem ela é exibida.

Java: Spring Boot e Quarkus

Java é um caso útil porque ambos os marcos têm um caminho documentado até o gRPC. As versões a seguir são as verificadas em 6 de outubro de 2026.

Spring Boot. Spring gRPC é um projeto oficial do Spring, com a versão 1.0.0 publicada em 4-dez-2025. No corte, a versão estável mais recente no GitHub é a 1.1.1 (21-ago-2026) [15]. A 1.1.0 (10-jun-2026) migrou a autoconfiguração para o Spring Boot 4.1.0, e os ramos 1.0.x apontam para o Boot 4.0 [15]. Para uma base nova em Spring Boot 4.1 há caminho oficial; com versões anteriores, revise a compatibilidade com a linha 1.0.x.

Quarkus. O gRPC se incorpora com a extensão quarkus-grpc: implementa e consome serviços, gera código a partir do .proto, integra-se ao modelo reativo, aceita TLS e TLS mútuo, xDS e comunicação em processo [16]. O Quarkus recomenda o servidor gRPC baseado em Vert.x porque é mais flexível e está mais bem integrado ao ecossistema, e esse servidor pode atender HTTP e gRPC pela mesma porta, se for configurado quarkus.grpc.server.use-separate-server=false [16]. No Maven Central, a última versão 3.x da extensão no corte é a 3.40.1 (30-set-2026); também há uma 4.0.0.Beta1 desse mesmo mês, que é uma versão prévia [16].

Os dois funcionam: decide o marco que a equipe já domina.

Seja qual for o marco, importam as mesmas práticas: um repositório único de contratos, interceptadores para identidade e rastros, política de erros comum, health checks e prazos obrigatórios em cada cliente.

Evolução de contratos Protobuf: como não quebrar ninguém

O contrato é o produto. Mudá-lo sem cuidado quebra os clientes que não ficaram sabendo. O guia oficial do Protobuf estabelece regras claras [17]:

• Adicionar campos é seguro. O código antigo ignora os campos novos ao ler, e o novo usa valores padrão com mensagens antigas.
• Adicionar valores a um enum é seguro no formato binário; mesmo assim, valide que os clientes e as regras de negócio contemplem o valor novo (em linguagens com enums fechados, como Java, um valor desconhecido chega como um caso à parte).
• O número de um campo não se altera nem se reutiliza uma vez que a mensagem está em uso, porque esse número identifica o campo no formato de transmissão.
• Ao retirar um campo, reserva-se o número dele (e, se for usado JSON, também o nome) para que ninguém o reutilize por acidente.
• Mover campos para dentro ou para fora de um oneof existente é arriscado: pode perder-se informação ao serializar e ler.

O guia de design de APIs do Google se aplica tanto a REST quanto a RPC e remete às propostas AIP-180 (compatibilidade) e AIP-185 (versões) [18]. A regra operacional é curta:

1. Publicar os .proto como produto versionado.
2. Validar a compatibilidade na integração contínua (com uma ferramenta de detecção de mudanças que quebram).
3. Manter testes de contrato entre o serviço e os consumidores.
4. Tratar qualquer mudança não aditiva como uma versão nova da API, com período de convivência.

Por que o core da empresa não fala nenhum dos dois

Aqui está o ponto que quase nenhum comparativo de protocolos aborda. Os sistemas centrais de uma seguradora, de um banco ou de um comércio com décadas de história costumam não falar nem REST nem gRPC, e as limitações desses sistemas explicam por quê:

• Não expõem APIs que possam ser chamadas, nem avisam quando algo muda.
• Só aceitam dados em uma zona de troca, tabelas ou arquivos, e os processam no próprio ritmo, muitas vezes em lotes, disparando um processo próprio.
• Suportam pouca carga: uma rajada de chamadas online os satura.
• A resposta chega quando o processo termina, não quando a requisição foi enviada, e às vezes só se encontra voltando a ler outra tabela ou arquivo.

Escolher REST ou gRPC para a camada de cima não muda isso. O que se precisa no meio é um adaptador: um componente que fala o idioma do core para dentro e o contrato novo para fora. E quando o modelo, os erros, a segurança ou as transações dos dois lados não coincidem, o adaptador deve ser uma camada anticorrupção, o padrão que Eric Evans descreveu em Domain-Driven Design [19].

É uma fachada entre subsistemas que não compartilham semântica, para que as dependências externas não limitem o design da aplicação; pode ser um componente interno ou um serviço independente [19].

A diferença em relação a um proxy é importante:

Quatro tarefas costumam cair no adaptador, e convém escrevê-las antes que se diluam no código (critério de design; o padrão em si é descrito em [19]):

• Traduzir os objetos de dados e validar invariantes nessa fronteira, incluída a sanitização das entradas.
• Normalizar erros: um código de retorno proprietário ou uma linha em uma tabela de erros vira um estado gRPC e, daí, se for o caso, um código HTTP, com a política explícita de que se falou acima.
• Proteger o core. Um core tem um ritmo que suporta. Se uma emissão em massa envia milhares de movimentos e o core processa algumas dezenas por minuto, a chamada online não é a forma de entregá-los: é necessária uma fila ou um mecanismo de nivelamento de carga [20], salvo se quem chama exigir uma resposta síncrona de baixa latência. Uma fila exige definir idempotência, reenvios, tratamento de mensagens com falha, ordem quando se aplicar e consulta de estado por identificador de correlação [20]. Esse é o tema do próximo artigo desta série.
• Observar: um identificador de correlação em cada chamada, para reconstruir o que aconteceu entre o contrato novo e o core, e registros estruturados para diagnosticar falhas de tradução.

Custos: mais latência, um serviço a mais para operar e decidir se a camada é permanente [19]. A Microsoft recomenda que ela se limite a traduzir e não concentre regras de negócio nem orquestração [19].

Tabela de decisão

Quando romper a frase-guia

«REST na fronteira, gRPC no coração, adaptador para o legado» funciona como ponto de partida. Há casos razoáveis em que convém sair dela:

• Tudo REST. Com equipe pequena, volume moderado e sem streaming, o Protobuf pode custar mais do que dá.
• gRPC até a fronteira. Se os consumidores externos são poucos e aceitam SDKs gerados, evita-se uma camada.
• Sem adaptador. Se o core já oferece uma API moderna e estável, o adaptador se reduz a um mapeamento fino.
• Assíncrono em vez de síncrono. Se o problema é o ritmo do core e não o protocolo, o que ajuda é uma fila, um evento ou um callback com identificador de correlação.

O que convém manter: decidir por fronteira, medir antes de justificar e escrever o contrato antes de escrever o código.

Fechamento: o que convém levar para a próxima reunião

Antes de escolher o protocolo, três perguntas organizam a discussão: quem consome a interface e quem controla os clientes, que idioma fala o sistema do fundo e que ritmo ele suporta. Se o sistema do fundo não fala nenhum dos dois ou é mais lento que quem o chama, e a carga medida exige desacoplar a entrada do processamento, convém priorizar o adaptador e considerar uma fila antes de trocar de protocolo.

O que a Hábil faz

A Hábil trabalha no espaço entre os sistemas existentes e as camadas novas: busca que um core que não fala REST nem gRPC possa atender aos canais e aos parceiros da empresa sem frear a operação. Para unir as APIs e os canais, veja a página Unificar a operação e os canais; para atualizar o core no ritmo dele, Modernizar o core sem frear o negócio. A primeira conversa, sem custo, parte do mapa das integrações da empresa e dos pontos onde um contrato ou um core com ritmo limitado poderiam custar dinheiro, tempo ou evidência. Escreva para nós pelo WhatsApp.

Consultadas em 6-out-2026. As versões e datas de ferramentas e de projetos mudam; as marcadas [provedor] são números ou estados que o próprio fornecedor publica.