API REST ou GraphQL: qual escolher e quando usar cada uma

A conversa costuma começar numa reunião de projeto. O time técnico precisa expor dados do sistema, para o aplicativo novo, para um parceiro logístico ou para o ERP, e alguém pergunta se a API vai ser REST ou GraphQL. Metade da sala não sabe a diferença, a outra metade tem preferência pessoal, e a decisão acaba sendo tomada pelo gosto de quem vai programar.

Essa escolha, porém, tem consequências que o gestor sente depois: quanto custa manter a integração com parceiros, quanto o aplicativo demora para carregar uma tela, quanto esforço é preciso para proteger os dados e quanto trabalho dá mudar a API sem quebrar quem já depende dela.

Este texto explica as duas em linguagem de negócio, mostra o critério que mais pesa na decisão e aponta os cuidados de segurança e de contrato que mudam bastante entre elas.

Resposta curta: decida por quem consome a API. Se do outro lado estão parceiros externos, clientes ou outros sistemas que precisam de contrato estável, cache simples e documentação fácil de seguir, REST é o caminho mais seguro. Se quem consome são os seus próprios front-ends e aplicativos, que montam telas com dados de muitas entidades ao mesmo tempo, GraphQL tende a render mais. Muitas empresas acabam com as duas: REST para fora, GraphQL para dentro.

REST e GraphQL em linguagem de negócio

Pense na API como o balcão de atendimento do seu sistema. É por ali que outros programas pedem e enviam informação.

REST funciona como um balcão com vários guichês, cada um com uma finalidade clara: um para pedidos, outro para clientes, outro para produtos. Cada guichê entrega um formulário padronizado. Se você pede o pedido de número tal, recebe sempre o mesmo conjunto de campos, definido por quem montou o balcão. É previsível, fácil de explicar e fácil de documentar.

GraphQL funciona como um único guichê com um atendente que conhece todo o catálogo. Você entrega uma lista exata do que quer, por exemplo "o pedido, o nome do cliente, os itens com descrição e o status da entrega", e recebe exatamente isso, numa resposta só. Quem pede tem muito mais liberdade, e quem atende precisa de mais regras para que essa liberdade não vire abuso.

Nenhum dos dois é um produto que se compra: são estilos de construir a API, com bibliotecas maduras nas principais linguagens.

Quem consome a API: parceiro, app próprio ou outro sistema

Esse é o critério que mais pesa, e também o que mais se esquece na discussão técnica.

Parceiros e clientes externos

Quando a API é aberta para um parceiro, um cliente corporativo ou um marketplace, quem integra é outra empresa, com outro time, outro prazo e outra prioridade. Ela quer um contrato que não mude sem aviso, exemplos prontos e respostas previsíveis. REST se encaixa muito bem aqui: cada recurso tem endereço próprio, a documentação segue padrões conhecidos e praticamente todo desenvolvedor já integrou algo parecido. Se esse é o seu cenário, vale ler também como criar uma API para parceiros e clientes integrarem.

Outros sistemas da própria empresa

Integração entre sistemas, como o portal com o ERP ou o WMS com o e-commerce, normalmente troca dados de forma repetitiva: pedidos novos, atualização de estoque, baixa de título. As consultas são conhecidas de antemão e mudam pouco. REST resolve isso com folga, muitas vezes combinado com eventos, como explicado no texto sobre o que é webhook e quando usar. Para o caso específico de ERP, o texto sobre como integrar seu sistema com o ERP detalha fonte da verdade, filas e mapeamento de cadastros.

Front-ends e aplicativos próprios

Aqui o cenário muda. O aplicativo do vendedor, o portal do cliente e o painel interno são feitos pelo mesmo time que faz a API, mudam toda semana e cada tela junta dados de várias entidades. É nesse caso que GraphQL costuma mostrar valor, porque a tela pede exatamente o que precisa, sem esperar o time de back-end criar um endpoint novo a cada ajuste de layout.

Excesso e falta de dados: o problema que o GraphQL resolve

Imagine a tela de detalhe de um pedido no aplicativo do vendedor. Ela mostra dados do pedido, nome e limite de crédito do cliente, itens com foto do produto e a previsão de entrega.

Numa API REST desenhada recurso por recurso, essa tela pode precisar de várias chamadas: uma para o pedido, outra para o cliente, uma para cada produto, outra para a entrega. Isso é a falta de dados: cada resposta traz pouco do que a tela precisa, e o aplicativo faz muitas viagens até o servidor. Em rede móvel instável, cada viagem a mais é espera para o usuário.

Ao mesmo tempo, a resposta de cliente pode trazer dezenas de campos que a tela não usa, como endereço completo, histórico e dados fiscais. Isso é o excesso de dados: tráfego desperdiçado e, pior, informação exposta sem necessidade.

GraphQL ataca os dois problemas de uma vez: a tela descreve o formato da resposta, e o servidor devolve só aquilo, numa única chamada.

Vale a ressalva honesta: REST também resolve isso, com endpoints pensados para a tela (às vezes chamados de "back-end para front-end"), parâmetros para escolher campos ou incluir entidades relacionadas. Funciona bem quando há poucas telas e elas mudam pouco. O ganho do GraphQL aparece quando há muitas telas, vários aplicativos e mudança constante.

Cache, desempenho e limites de consulta

Cache

REST aproveita naturalmente o cache da web. Cada recurso tem um endereço, e navegadores, CDNs e proxies sabem guardar respostas de leitura por endereço. Para catálogos de produtos, tabelas de preço e conteúdos que mudam pouco, isso reduz carga no servidor sem esforço extra.

Em GraphQL, as consultas costumam passar por um único endereço e variar no corpo da requisição, o que dificulta esse cache tradicional. Há técnicas para contornar, como consultas pré-registradas e cache no cliente ou no servidor por entidade, mas elas exigem decisão de arquitetura e trabalho a mais.

Desempenho no servidor

A liberdade do GraphQL tem um custo escondido. Uma consulta aparentemente simples pode pedir pedidos, e de cada pedido os itens, e de cada item o produto, e de cada produto o fornecedor. Sem cuidado no servidor, isso vira uma avalanche de consultas ao banco de dados, o chamado problema N+1: uma busca para a lista e mais uma para cada item dela. Existem padrões conhecidos para agrupar essas buscas em lote, mas eles precisam fazer parte do projeto desde o começo, e não ser descobertos quando o sistema já está lento em produção.

Em REST, o desempenho de cada endpoint é mais fácil de prever e medir, porque cada um faz sempre o mesmo trabalho.

Monitoramento e erros

Em REST, o próprio código de resposta HTTP já diz muito: sucesso, recurso não encontrado, acesso negado, erro no servidor. Ferramentas de monitoramento leem isso sem configuração especial, e um painel por endpoint mostra rapidamente qual parte da API está lenta ou falhando.

Em GraphQL, é comum a resposta voltar com status de sucesso e trazer os erros dentro do corpo, às vezes com parte dos dados preenchida e parte não. Para acompanhar a saúde da API, o monitoramento precisa olhar o conteúdo da resposta e identificar cada consulta pelo nome, e não só pelo endereço. Não é difícil, mas precisa ser configurado de propósito, senão o painel mostra tudo verde enquanto as telas falham.

Limites de consulta

Em REST, limitar uso é relativamente direto: número de requisições por período, por cliente ou por chave de acesso. Em GraphQL, uma única requisição pode custar pouco ou muito, então contar requisições não basta. É preciso limitar profundidade da consulta, quantidade de itens por lista e, idealmente, calcular um custo estimado antes de executar. Sem isso, um front-end mal escrito, ou alguém mal-intencionado, derruba o servidor com uma consulta só.

Versionamento, documentação e contrato com parceiros

Versionamento

Em REST, o caminho comum é versionar a API (por exemplo, uma versão no endereço) e manter a versão antiga funcionando por um período combinado enquanto os parceiros migram. É explícito, fácil de comunicar e fácil de colocar em contrato.

Em GraphQL, a prática mais comum é evoluir um esquema único: adicionar campos novos sem quebrar os antigos e marcar como obsoletos os que vão sair. Funciona muito bem quando você controla os clientes da API, porque consegue ver quem ainda usa cada campo e atualizar os aplicativos. Com parceiros externos, que atualizam no ritmo deles, essa evolução contínua exige mais disciplina de comunicação.

Documentação

GraphQL tem um ponto forte aqui: o esquema é tipado e descreve tudo o que pode ser consultado, e as ferramentas exploram isso para gerar documentação e autocompletar consultas. REST conta com especificações abertas e amplamente adotadas, como a OpenAPI, que geram documentação navegável e até código de cliente. A diferença está em quem vai ler: um parceiro acostumado a REST precisará aprender GraphQL para consumir a sua API, e no contrato de integração será preciso combinar também quais consultas são permitidas e o custo máximo aceito.

Segurança: autorização por campo e consultas abusivas

Segurança de API costuma falhar mais por autorização mal feita do que por falta de criptografia. O texto sobre os erros mais comuns de segurança de APIs detalha esse ponto. Aqui, o que muda entre os dois estilos.

Em REST, a autorização costuma ser checada por endpoint e por objeto: este usuário pode ver este pedido? O risco clássico é esquecer a checagem de objeto e permitir que alguém troque o número na chamada e veja o pedido de outro cliente. O risco é real, mas o mapa de onde verificar é claro: um ponto por endpoint.

Em GraphQL, como o cliente pode navegar entre entidades, a autorização precisa existir em cada tipo e, às vezes, em cada campo. Um usuário pode ter acesso ao pedido, mas não ao limite de crédito do cliente que aparece dentro dele. Se essa regra estiver só na tela, e não no servidor, basta montar a consulta certa para ver o dado. Isso exige uma camada de autorização bem desenhada e testada.

Outros cuidados específicos de GraphQL:

• Consultas abusivas. Profundidade, tamanho de lista e custo precisam de limite, como visto acima.
• Exploração do esquema. O recurso que permite descobrir todo o esquema é ótimo em desenvolvimento, mas em APIs abertas costuma ser restringido em produção.
• Consultas pré-aprovadas. Para aplicativos próprios, aceitar só consultas registradas previamente reduz bastante a superfície de ataque.

Em ambos, os básicos continuam valendo: autenticação forte, chaves por parceiro, registro de acesso, limite de uso e cuidado com dados pessoais, como pede a LGPD.

Tabela comparativa: REST x GraphQL

Quando escolher cada um

Sinais de que REST é a melhor escolha

• A API vai ser usada por parceiros, clientes ou fornecedores que você não controla.
• O objetivo principal é integração entre sistemas, com operações conhecidas e repetitivas.
• Há muita leitura de dados que mudam pouco e se beneficiam de cache.
• O contrato precisa ser simples de explicar, versionar e colocar por escrito.
• O time é pequeno e não tem experiência prévia com GraphQL.
• Você vai integrar com plataformas de mercado que já oferecem API REST e webhooks, o que é o caso de muitos ERPs, gateways e marketplaces. Confirme com cada fornecedor o que a API atual dele oferece.

Sinais de que GraphQL vale a pena

• Você tem vários front-ends próprios, como site, aplicativo e painel interno, consumindo os mesmos dados de formas diferentes.
• As telas juntam muitas entidades, e o aplicativo faz várias chamadas para montar cada uma.
• O front-end muda com frequência e vive esperando endpoints novos.
• O time tem, ou está disposto a construir, a disciplina de autorização por campo e limite de custo de consulta.
• Os aplicativos rodam em rede móvel, onde cada viagem ao servidor pesa.

Quando usar os dois

Um arranjo comum e saudável: REST para a API pública, de parceiros e de integração entre sistemas, e GraphQL como camada interna que atende os front-ends próprios. As duas usam as mesmas regras de negócio no back-end, sem duplicação. O que não vale é adotar GraphQL só porque parece mais moderno, nem manter um REST que obriga o aplicativo a fazer muitas chamadas por tela só porque "sempre foi assim".

E há um caso em que a melhor resposta é não construir API nenhuma: se o sistema que você usa já tem integração pronta com o outro, via conector nativo ou plataforma de integração, e ela atende o volume e as regras do processo, use. Construir API própria só faz sentido quando o pronto não cobre a necessidade ou quando você precisa expor algo que só o seu sistema tem.

Perguntas frequentes

GraphQL é mais rápido que REST?

Depende do uso. GraphQL reduz o número de chamadas em telas que juntam muitas entidades, o que ajuda em rede móvel. Mas, sem agrupar as buscas no servidor, uma consulta pode cair no problema N+1 e ficar lenta. REST aproveita melhor o cache da web e tem desempenho mais previsível em cada endpoint.

GraphQL substitui o REST?

Não. GraphQL e REST são estilos de construir API, cada um com seu ponto forte. Muitas empresas usam REST para parceiros, clientes e integração entre sistemas, que pedem contrato estável e documentação conhecida, e GraphQL como camada interna para os próprios front-ends e aplicativos, com as mesmas regras de negócio no back-end.

GraphQL é menos seguro que REST?

Não é menos seguro, mas exige mais cuidado. Em GraphQL, a autorização precisa existir em cada tipo e às vezes em cada campo, e as consultas precisam de limite de profundidade, tamanho de lista e custo. Em REST, o mapa de verificação é mais simples: autorização por endpoint e por objeto. Os dois exigem autenticação forte.

O que é OpenAPI?

OpenAPI é uma especificação aberta e amplamente adotada para descrever APIs REST: recursos, parâmetros, respostas e erros. A partir dela, ferramentas geram documentação navegável e até código de cliente, o que facilita a integração de parceiros. Versionada junto com o código, a especificação OpenAPI também ajuda a detectar mudanças que quebram integrações.

Sempre é preciso construir uma API própria para integrar sistemas?

Não. Se o sistema que você usa já tem integração pronta com o outro, por conector nativo ou plataforma de integração, e ela atende ao volume e às regras do processo, use essa integração. Construir API própria só faz sentido quando a solução pronta não cobre a necessidade ou quando é preciso expor algo que só o seu sistema tem.

Como a Pervian Tech ajuda a decidir e a desenhar sua API

A decisão começa por um diagnóstico inicial gratuito: quem vai consumir a API, que dados precisam circular, quais sistemas já existem e quais integrações prontas eles oferecem. Quando um conector ou plataforma de mercado resolve, recomendamos e ajudamos a configurar. Quando não resolve, desenhamos a API sob medida, no estilo que faz sentido para cada consumidor, com contrato, versionamento, autorização e limites definidos antes da primeira linha de código.

Esse trabalho faz parte da nossa arquitetura de software e da integração de sistemas. Outros textos sobre o tema estão em integrações. Cronograma e investimento são definidos sob consulta, depois de entender o cenário. Se a sua empresa está prestes a abrir dados para parceiros ou criar um aplicativo novo, fale com a gente.