REST, GraphQL e gRPC
Três estilos de API, o problema que cada um resolve e como escolher entre eles.
O que é um estilo de API
Uma API é o contrato entre quem oferece um serviço e quem o consome: quais operações existem, quais dados entram e quais saem. O estilo da API é a forma desse contrato. Ele define quem decide o formato da resposta, como o contrato é descrito e como os dados trafegam.
Três estilos dominam o backend hoje. Eles partem de perguntas diferentes:
| Estilo | Pergunta central | Unidade do contrato |
|---|---|---|
| REST | Quais recursos existem e o que posso fazer com cada um? | Recursos com endereço, manipulados pelos métodos do HTTP |
| GraphQL | Quais dados o cliente precisa nesta tela? | Um esquema de tipos, consultado por uma linguagem própria |
| gRPC | Quais funções o serviço oferece? | Funções remotas, com mensagens definidas em Protobuf |
Para comparar, vamos usar a mesma necessidade nos três: buscar o pedido 981 com os itens e o nome do cliente.
REST: recursos e os verbos do HTTP
No REST, cada coisa do sistema é um recurso com endereço próprio. As operações são os métodos do HTTP, e o resultado é comunicado pelos códigos de status. O servidor decide o formato de cada resposta.
GET /pedidos/981 HTTP/1.1
Host: api.loja.com.br{
"id": "981",
"status": "enviado",
"clienteId": "42",
"itens": [{ "produto": "teclado", "quantidade": 2 }],
"enderecoEntrega": { "cidade": "Curitiba", "cep": "80000-000" },
"criadoEm": "2026-03-10T14:02:00Z"
}A resposta trouxe o endereço e a data, que a tela não pediu, e não trouxe o nome do cliente. Para obtê-lo, o cliente faz um segundo pedido:
GET /clientes/42 HTTP/1.1Esses dois efeitos têm nome:
- Excesso de dados (over-fetching): a resposta carrega campos que o cliente não usa.
- Falta de dados (under-fetching): uma tela precisa de vários pedidos para montar o que mostra.
Em troca, o REST herda tudo o que o HTTP já oferece: cache em navegadores e CDNs, códigos de status entendidos por qualquer ferramenta, e um pedido que se testa com um comando curl.
GraphQL: o cliente descreve o que quer
No GraphQL, o servidor publica um esquema com todos os tipos e as relações entre eles. O cliente envia uma consulta dizendo exatamente quais campos quer, e recebe uma resposta com o mesmo formato da consulta. Tudo passa por um único endereço.
query {
pedido(id: "981") {
status
itens {
produto
quantidade
}
cliente {
nome
}
}
}{
"data": {
"pedido": {
"status": "enviado",
"itens": [{ "produto": "teclado", "quantidade": 2 }],
"cliente": { "nome": "Marina Souza" }
}
}
}Um único pedido trouxe o pedido e o cliente, sem campos sobrando. Quando a tela mudar, o cliente altera a consulta e o servidor não precisa de um endpoint novo.
O custo fica no servidor. Ele deixa de saber de antemão quais consultas vai receber, e cada campo é resolvido por uma função separada. Uma consulta de aparência inocente pode disparar centenas de acessos ao banco ou pedir uma árvore de dados enorme.
gRPC: chamar uma função em outra máquina
O gRPC trata a comunicação como chamada de função remota. O contrato é escrito em um arquivo .proto, que define os serviços e as mensagens:
service Pedidos {
rpc BuscarPedido (BuscarPedidoRequest) returns (Pedido);
}
message BuscarPedidoRequest {
string id = 1;
}
message Pedido {
string id = 1;
string status = 2;
repeated Item itens = 3;
string nome_cliente = 4;
}A partir desse arquivo, uma ferramenta gera o código do cliente e do servidor em cada linguagem. No código de quem chama, o pedido parece uma função local:
const pedido = await pedidos.buscarPedido({ id: "981" });Os dados trafegam em formato binário (Protobuf) sobre HTTP/2. As mensagens são menores que o JSON equivalente, o contrato é verificado na compilação e o protocolo aceita fluxos contínuos nos dois sentidos. Em compensação, o tráfego não é legível a olho nu, e um navegador não consegue falar gRPC diretamente.
O que realmente diferencia os três
| REST | GraphQL | gRPC | |
|---|---|---|---|
| Quem define o formato da resposta | O servidor | O cliente, dentro do esquema | O contrato .proto |
| Contrato | Opcional (OpenAPI) | Obrigatório (esquema) | Obrigatório (.proto) |
| Formato dos dados | JSON, em geral | JSON | Binário (Protobuf) |
| Endereços | Um por recurso | Um só | Um por função |
| Cache do HTTP | Funciona direto | Exige trabalho extra | Não se aplica |
| Uso pelo navegador | Direto | Direto | Só com um proxy |
A diferença mais importante é a primeira linha. No REST, mudar o que uma tela recebe exige mudar o servidor. No GraphQL, o cliente muda sozinho. No gRPC, as duas pontas mudam juntas, a partir do mesmo arquivo.
Por que isso importa quando a IA escreve o código
Um assistente gera uma API nos três estilos com a mesma facilidade. O que ele não avalia sozinho é qual estilo combina com os seus clientes e a sua equipe, nem os riscos próprios de cada um:
- Em REST, ele cria um endpoint por tela, e a API vira uma coleção de casos especiais.
- Em GraphQL, ele escreve os resolvedores do jeito mais direto, e uma lista de 50 pedidos dispara 51 consultas ao banco.
- Em gRPC, ele renumera os campos do
.protoao reorganizar o arquivo, e quebra todos os clientes que já estão em produção.
O próximo nível compara os três em detalhe e mostra como decidir.
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.
REST, GraphQL e gRPC em cinco minutos
Explique a diferença entre REST, GraphQL e gRPC em no máximo cinco minutos de leitura, para alguém que já consumiu uma API mas nunca precisou escolher um estilo. Para cada estilo, diga em duas ou três frases como ele funciona, quem decide o formato da resposta e em que situação ele é a melhor escolha. Use o mesmo exemplo nos três: buscar um pedido com o nome do cliente. No final, me descreva três projetos curtos e pergunte qual estilo eu usaria em cada um. Corrija as minhas respostas explicando o motivo.
A mesma operação nos três estilos
Quero entender a diferença entre REST, GraphQL e gRPC vendo o mesmo problema resolvido de três formas. Aja como um mentor de backend. Use como exemplo uma loja virtual e a necessidade de mostrar uma tela com um pedido, seus itens e o nome do cliente. Conduza assim: 1. Pergunte qual é a minha experiência com APIs e qual estilo eu já usei. 2. Mostre como essa tela seria atendida em REST: os pedidos HTTP necessários e as respostas. Pergunte o que eu acho que sobra e o que falta nas respostas antes de explicar os conceitos de excesso e falta de dados. 3. Mostre a mesma tela em GraphQL: o esquema, a consulta e a resposta. Pergunte o que mudou para o cliente e o que mudou para o servidor. 4. Mostre a mesma operação em gRPC: o arquivo .proto e a chamada no código do cliente. Pergunte o que se ganha e o que se perde em relação aos dois anteriores. Explique um estilo por vez e só avance depois da minha resposta. Ao final, peça que eu diga em uma frase quem decide o formato da resposta em cada estilo, e corrija se estiver impreciso.
Entender o contrato em cada estilo
Quero entender o papel do contrato em APIs e como ele difere entre REST, GraphQL e gRPC. Explique: 1. O que é o contrato de uma API e o que acontece quando ele não está escrito em lugar nenhum. 2. Como o contrato é expresso em cada estilo: OpenAPI no REST, o esquema no GraphQL e o arquivo .proto no gRPC. Mostre um exemplo curto de cada um para a mesma operação. 3. Em que momento um erro de contrato é detectado em cada estilo: na compilação, no início da execução, na chamada ou só quando o usuário reclama. 4. O que é geração de código a partir do contrato, e por que ela é opcional no REST e central no gRPC. Depois me apresente quatro mudanças em uma API (adicionar um campo, remover um campo, renomear um campo e mudar o tipo de um campo) e pergunte, para cada uma e em cada estilo, se os clientes antigos continuam funcionando. Corrija as minhas respostas explicando o mecanismo por trás.
Por que o gRPC não funciona direto no navegador
Explique como o gRPC funciona por baixo: o que é o Protobuf, como uma mensagem é codificada em binário, o papel do número de cada campo e como o gRPC usa o HTTP/2 (fluxos, cabeçalhos finais e conexões de longa duração). Use um exemplo de mensagem pequena e mostre lado a lado o JSON equivalente e a representação binária, explicando de onde vem a diferença de tamanho. Em seguida, explique por que um navegador não consegue fazer uma chamada gRPC diretamente e quais são as saídas: gRPC-Web com proxy, um gateway que traduz para REST e JSON, ou uma camada própria na frente. Por fim, explique os quatro tipos de chamada do gRPC (simples, fluxo do servidor, fluxo do cliente e fluxo nos dois sentidos) com um caso de uso real para cada um. Faça perguntas de verificação ao longo da explicação e espere as minhas respostas antes de continuar.