HATEOAS: APIs amigáveis para agentes de IA generativa

O que era uma curiosidade acadêmica agora pode virar a chave da importância de uma API.

Durante muitos anos, HATEOAS foi tratado como uma curiosidade acadêmica do REST. Apesar de fazer parte das restrições definidas por Roy Fielding em sua tese de doutorado, a maioria das APIs REST produzidas pela indústria acabou adotando um modelo muito mais simples: endpoints documentados via OpenAPI/Swagger, clientes fortemente acoplados e URLs conhecidas previamente.

Na prática, isso sempre foi suficiente para aplicações web e mobile, mas a chegada dos agentes de IA mudou completamente quem consome APIs.

Hoje, cada vez mais sistemas são utilizados por LLMs capazes de tomar decisões, executar múltiplas chamadas e navegar por fluxos complexos sem intervenção humana. Nesse cenário, APIs que conseguem “explicar” quais ações são possíveis em determinado estado passam a oferecer uma vantagem significativa.

É justamente aqui que HATEOAS volta à discussão.

Afinal, o que é HATEOAS?

HATEOAS (Hypermedia As The Engine Of Application State) é uma restrição da arquitetura REST onde o servidor não devolve apenas dados, mas também informa quais ações podem ser realizadas em seguida.

Em vez de o cliente conhecer previamente todos os endpoints disponíveis, ele descobre dinamicamente as próximas operações através da própria resposta da API.

Uma API tradicional pode retornar algo como:

{
  "id": 123,
  "status": "pending"
}

Já uma API seguindo HATEOAS poderia responder:

{
  "id": 123,
  "status": "pending",
  "_links": {
    "self": {
      "href": "/orders/123"
    },
    "cancel": {
      "href": "/orders/123/cancel",
      "method": "POST"
    },
    "payment": {
      "href": "/orders/123/payment",
      "method": "POST"
    }
  }
}

Observe que o cliente não precisa conhecer previamente quais operações existem, o próprio recurso informa quais transições de estado são válidas.

Esse conceito é muito semelhante ao funcionamento da Web. Ao acessar uma página, o navegador não possui uma lista completa de URLs do site. Ele simplesmente segue os links apresentados pelo servidor.

HATEOAS aplica exatamente essa ideia às APIs.

Por que quase ninguém adotou HATEOAS?

Apesar de elegante do ponto de vista arquitetural, HATEOAS nunca se tornou dominante.

Existem alguns motivos bastante práticos.

O primeiro é que a maioria dos clientes modernos é fortemente tipada.

Aplicações em React, Angular, Swift, Kotlin ou Flutter normalmente geram SDKs a partir de um contrato OpenAPI. Os endpoints já são conhecidos em tempo de compilação, tornando os links dinâmicos menos úteis.

Outro fator é a documentação.

Ferramentas como Swagger e OpenAPI facilitaram muito o desenvolvimento baseado em contratos estáticos. Para equipes humanas, isso resolve grande parte do problema.

Além disso, implementar HATEOAS corretamente exige modelar cuidadosamente os estados da aplicação e suas transições, aumentando a complexidade da API.

Para muitos times, o custo simplesmente nunca compensou.

O cenário mudou com os agentes de IA

Grande parte dos consumidores de APIs deixou de ser exclusivamente aplicações desenvolvidas por pessoas.

Hoje temos:

  • agentes baseados em LLM;
  • sistemas que utilizam MCP;
  • ferramentas de automação inteligentes;
  • workflows autônomos;
  • orquestradores capazes de executar centenas de chamadas de API.

Esses consumidores apresentam características muito diferentes de um aplicativo mobile tradicional, eles precisam descobrir capacidades em tempo de execução. Precisam entender contexto, decidir qual operação executar a seguir, adaptar seu comportamento conforme o estado atual do recurso.

É exatamente o problema que HATEOAS tenta resolver desde o início.

Enquanto uma aplicação convencional já “sabe” que existe um endpoint /cancel, um agente de IA pode simplesmente observar que aquele link existe — ou não existe — e decidir seu próximo passo sem depender de lógica previamente codificada.

Essa característica reduz o acoplamento entre cliente e servidor e transforma a API em uma interface muito mais autodocumentada.

HATEOAS como mecanismo de descoberta

Imagine um agente responsável por gerenciar pedidos.

Ele consulta um pedido e recebe:

{
  "status": "paid",
  "_links": {
    "refund": {
      "href": "/orders/123/refund"
    },
    "invoice": {
      "href": "/orders/123/invoice"
    }
  }
}

Sem qualquer conhecimento prévio, o agente já consegue inferir:

  • o pedido foi pago;
  • cancelamento não é mais permitido;
  • existe possibilidade de reembolso;
  • é possível emitir nota fiscal.

O próprio recurso descreve seu comportamento. Isso reduz ambiguidades e elimina diversas regras que normalmente ficam espalhadas na documentação ou no código cliente.

Menos endpoints “mágicos”

Outro benefício é evitar que clientes dependam de convenções implícitas.

Em APIs tradicionais é comum assumir coisas como:

GET /users/1

PUT /users/1

DELETE /users/1

Mas será que todos os usuários podem ser removidos? Talvez apenas usuários inativos… a exclusão pode serfeita apenas por administradores… pode ser necessário um processo de aprovação.

Com HATEOAS, a existência — ou ausência — do link de remoção já comunica essa informação.

A API deixa de apenas fornecer dados. Ela também comunica regras de negócio.

Impacto para agentes de IA

Esse talvez seja o aspecto mais interessante. Modelos de linguagem trabalham muito melhor quando recebem contexto explícito, em vez de tentar deduzir qual endpoint chamar entre centenas disponíveis, o agente recebe apenas as ações válidas naquele momento.

Isso melhora:

  • seleção de ferramentas (tool selection);
  • manutenção de contexto durante fluxos longos;
  • navegação entre estados;
  • redução de chamadas inválidas;
  • adaptação automática a mudanças da API.

Em outras palavras, a API passa a guiar o agente durante sua execução.

Alguns especialistas têm chamado esse conceito de APIs AI-friendly, nas quais o servidor não apenas expõe funcionalidades, mas também orienta como elas devem ser utilizadas em tempo de execução. Essa visão vem ganhando força conforme agentes autônomos passam a consumir APIs de maneira cada vez mais intensa.

As vantagens

Menor acoplamento

Clientes deixam de depender de URLs fixas. Mudanças internas tornam-se menos impactantes.

Evolução mais segura

Novas funcionalidades podem surgir apenas adicionando novos links. Clientes antigos continuam funcionando.

APIs mais autodocumentadas

As próprias respostas descrevem o fluxo possível da aplicação.

Melhor experiência para agentes

LLMs conseguem descobrir capacidades dinamicamente, isso reduz a necessidade de instruções externas.

Regras de negócio explícitas

A ausência de um link também comunica informação, nem toda operação está sempre disponível.

Os desafios

Nem tudo são vantagens.

Implementação mais complexa

Gerar links corretamente exige que a API conheça profundamente os estados possíveis do domínio.

Payloads maiores

Cada recurso passa a transportar metadados adicionais. Embora normalmente pequeno, existe um aumento no volume de dados.

Curva de aprendizado

Grande parte dos desenvolvedores nunca trabalhou com HATEOAS, isso aumenta o custo inicial da adoção.

Ecossistema limitado

Poucos frameworks incentivam HATEOAS como padrão. Na maioria dos projetos, ele precisa ser implementado manualmente.

Benefício pequeno para clientes tradicionais

Aplicações web e mobile normalmente já conhecem toda a estrutura da API. Nesses casos, o ganho pode não justificar a complexidade adicional.

Vale a pena adotar?

Como quase toda decisão arquitetural, depende do problema.

Se sua API atende apenas um frontend próprio e um aplicativo mobile desenvolvido pela mesma equipe, provavelmente OpenAPI continua sendo suficiente. Mas se a API precisa ser consumida por múltiplos clientes independentes, parceiros externos ou agentes de IA capazes de executar workflows complexos, HATEOAS passa a oferecer benefícios bastante concretos.

Conclusão

A implementação do HATEOAS já não é apenas uma questão de purismo arquitetural; tornou-se uma vantagem estratégica. Num mundo onde “Hackear a Tarefa” significa construir sistemas que sobrevivam ao teste do tempo e às inovações tecnológicas, preparar as nossas APIs REST para serem facilmente interpretáveis por agentes de IA é um passo essencial.

Seja projetando novas API ou refatorando um monólito, sabendo que essa interface será consumida por ferramentas de IA generativa, integrar padrões hipermedia pode ser a chave para integrações mais fluídas, seguras e verdadeiramente dinâmicas.

Referências Utilizadas e Recomendadas

0 Comentário