REST, GraphQL e agentes de IA: o contrato da API ganha peso

A evolução dos padrões e o uso de ferramentas por agentes aumentam a importância de definir o que cada integração pode fazer.

A OpenAPI Initiative publicou em 10 de setembro de 2026 a versão 3.2.1 de sua especificação, o padrão que descreve interfaces de comunicação pela web para pessoas e programas. O documento organiza operações, entradas e respostas que permitem entender um serviço sem abrir seu código. Para quem contrata tecnologia, a publicação recoloca uma questão concreta: a integração vem com regras que outra equipe consegue compreender e testar? (OpenAPI Initiative, 2026)

API é a interface pela qual um sistema pede algo a outro, como calcular frete ou consultar estoque. Funciona como um balcão de atendimento com pedidos e respostas definidos. Quando um agente de inteligência artificial passa a fazer esses pedidos, o contrato precisa continuar claro: quais ações estão autorizadas, quanto custam e o que acontece quando a conexão falha.

Essa demanda aparece no Model Context Protocol, ou MCP, um protocolo que conecta modelos a ferramentas externas. A especificação de novembro de 2025 permite expor ferramentas que consultam dados e chamam APIs. Ela recomenda manter uma pessoa capaz de negar a execução e tornar as chamadas visíveis ao usuário. A presença do protocolo, por si, não decide se um agente pode cancelar uma compra ou movimentar dinheiro. (MCP, 2025)

A escolha entre REST e GraphQL começa pelo consumidor

REST organiza a interação em recursos, como pedidos e clientes, usando as convenções do HTTP, o protocolo da web. GraphQL oferece uma linguagem de consulta na qual o consumidor escolhe os campos desejados dentro de um esquema definido pelo serviço. O esquema é o catálogo de dados e operações permitidas. A documentação oficial do GraphQL apresenta essa seleção de campos como parte central do funcionamento da linguagem. (GraphQL, consulta em outubro de 2026)

Exemplo hipotético: um aplicativo precisa mostrar o nome do cliente, os pedidos recentes e o endereço de entrega na mesma tela. GraphQL pode reunir essa seleção em uma consulta. Já um parceiro que envia pedidos padronizados pode trabalhar bem com operações REST previsíveis. A escolha depende de quem consome, das consultas necessárias e da capacidade da equipe de operar a solução.

Critério	REST	GraphQL
Forma de pedir dados	Recursos e operações definidos pela API	Campos selecionados pelo consumidor dentro do esquema
Contrato	OpenAPI pode descrever a interface HTTP	Esquema tipado define campos e operações
Reutilização de respostas	Pode aproveitar cache HTTP conforme a configuração	Também permite cache, com estratégia adequada às consultas
Controle de consumo	Limites por operação, cliente e volume	Limites de consulta, volume e complexidade
Pergunta antes de adotar	As operações atendem aos consumidores sem consultas excessivas?	A flexibilidade compensa o esforço de controle e operação?

Cache é a reutilização temporária de uma resposta para evitar processamento repetido, como guardar uma consulta recente de catálogo. A documentação do GraphQL explica que a tecnologia permite cache no cliente, no servidor e na camada de transporte. Também descreve o problema de uma consulta disparar várias leituras no banco. Portanto, reduzir chamadas vistas pelo aplicativo não prova que o servidor trabalhou menos. (GraphQL, consulta em outubro de 2026)

O teste útil acompanha o pedido até a fonte dos dados. Compare tempo de resposta, leituras no banco e consumo de recursos para a mesma necessidade de negócio. Escolher uma tecnologia porque a demonstração parece curta pode esconder o custo de operação que aparecerá depois.

As tendências deixam o custo da chamada mais visível

Três movimentos documentados ajudam a organizar a decisão em 2026. São mudanças de atenção e de prática; nenhum deles obriga a empresa a reescrever uma integração que já funciona.

Contratos legíveis por ferramentas. A OpenAPI descreve a interface de forma padronizada. A aplicação prática é manter essa descrição junto das mudanças do serviço e testar se exemplos e respostas continuam compatíveis.
Consultas flexíveis com limites explícitos. O guia de segurança do GraphQL orienta paginação, limites de profundidade, controle de frequência e análise de complexidade. Esses mecanismos tratam de quanto trabalho uma consulta pode provocar. (GraphQL, 2026)
Agentes com operações delimitadas. O MCP descreve ferramentas que o modelo pode descobrir e chamar. Na implantação, a empresa precisa separar consulta de alteração e definir quem autoriza ações com consequência comercial.

O tamanho de uma chamada não revela sozinho sua conta. Uma consulta pequena pode percorrer muitos registros; uma sequência automática pode repetir a mesma operação enquanto espera uma resposta. Por isso, a proposta do fornecedor deve explicar a unidade cobrada e o comportamento quando o limite é atingido. O teto precisa existir na operação, com bloqueio ou tratamento definido, para que um aviso de consumo tenha consequência prática.

A falha de conexão exige outra decisão. A Stripe documenta chaves de idempotência, identificadores que permitem repetir uma solicitação sem executar indevidamente a operação novamente. As regras variam entre versões da API e incluem condições de retenção e processamento. O princípio interessa a qualquer integração que cria pedidos ou cobranças: uma nova tentativa precisa distinguir recuperação de falha de uma nova compra. (Stripe, consulta em outubro de 2026)

O que precisa estar resolvido antes de contratar

O contrato comercial deve encontrar correspondência no comportamento técnico. Uma promessa de disponibilidade pouco ajuda se ninguém sabe identificar o pedido que falhou ou recuperar uma operação parcialmente concluída. A pauta da contratação pode ser curta, desde que cada resposta tenha um responsável e uma forma de conferência:

Escopo: lista de operações disponíveis e exemplo de entrada, sucesso e erro para cada operação relevante.
Acesso: permissões de leitura e alteração separadas, com procedimento para revogar uma credencial.
Consumo: unidade de cobrança, limite de chamadas e tratamento de consultas caras ou repetidas.
Falha: regra de nova tentativa, identificador para rastrear o pedido e proteção contra duplicação.
Mudança: aviso de incompatibilidade, período de transição e responsável pela adaptação.
Operação: canal de suporte, acordo de disponibilidade e evidência que acompanha a abertura de um chamado.

O curso de API Design: REST e GraphQL desenvolve esse olhar sobre contrato, acesso e limites. A discussão se conecta à análise sobre engenharia de software com IA e fundamentos de entrega: automatizar uma operação exige compreender como testar, acompanhar e corrigir seu resultado.

Na próxima integração, a decisão pode começar por uma demonstração de falha. Peça que o fornecedor interrompa uma chamada em ambiente de teste e mostre a recuperação, o registro do pedido e o efeito na cobrança. Essa evidência permite avaliar o contrato quando a operação sai do roteiro ensaiado.