Documentação de API desatualizada: teste ações de agentes com segurança

Uma documentação de API desatualizada é um problema de segurança para agentes, não um simples incômodo editorial. Uma pessoa pode ler um exemplo antigo, hesitar e perguntar a um colega. Um agente autônomo de programação costuma transformar esse mesmo exemplo em uma requisição e depois usar a resposta como prova de que agiu corretamente.

Essa diferença muda o padrão de qualidade. Se a documentação ensina um agente a chamar uma API, alternar um token, excluir um registro ou acessar um host de produção, trate o texto como entrada executável. Teste-o junto com a própria ferramenta. Uma página que estava correta quando foi publicada, mas já não corresponde ao serviço ativo, pode conduzir um agente a uma ação insegura mesmo quando a API funciona exatamente como seus responsáveis atuais pretendem.

A deriva mais perigosa raramente produz uma falha evidente. Um 404 chama atenção. Já uma requisição que continua retornando 200 enquanto seleciona mais recursos, usa um padrão alterado ou ignora uma confirmação esperada não chama. Esse é o tipo de divergência que gera um registro de atividade impecável e uma tarde desastrosa.

A documentação passa a fazer parte do plano de controle do agente

Um agente usa a documentação para escolher operações, preencher parâmetros, interpretar respostas e decidir se deve tentar novamente. Isso transforma exemplos, tabelas de referência, guias de autenticação e notas de migração em parte do seu plano de controle. O código do serviço pode estar correto enquanto esse plano instrui o agente a usá-lo de maneira errada.

As equipes costumam traçar uma divisão artificial entre a definição de uma ferramenta e um guia. A definição diz deleteProject(project_id). O guia diz qual identificador de projeto obter, se existe uma simulação, se a exclusão se propaga e o que fazer depois de uma falha de autorização. O agente precisa dos dois. Se qualquer um deles estiver errado, a ação resultante poderá ser incorreta.

Por isso, um exemplo desatualizado é diferente de um parágrafo com erro de digitação. Imagine uma instrução antiga dizendo que a ausência do parâmetro scope significa «projeto atual». Mais tarde, uma alteração no backend faz com que a mesma omissão passe a significar «todos os projetos disponíveis para esta credencial». O endpoint continua funcionando. O exemplo continua sendo analisado sem erro. Um agente que siga o guia antigo pode aplicar uma mudança supostamente local a toda a conta.

A documentação também define o grau de confiança do agente. Trechos concretos pesam mais que um aviso vago no texto ao redor. Se uma página diz «use o menor privilégio» e outra fornece um exemplo de bearer token com acesso à conta inteira, o trecho concreto vence na prática. Os agentes otimizam o caminho que produz um resultado.

Considere como documentação capaz de disparar ações:

• Exemplos de requisições e comandos
• Tabelas de parâmetros que descrevem padrões e valores permitidos
• Instruções de autenticação, credenciais e configuração do ambiente
• Orientações sobre tentativas, paginação, idempotência e tratamento de erros
• Instruções de migração e descontinuação que informam qual operação substitui outra

Uma distinção útil é entre deriva de sintaxe e deriva de significado. A deriva de sintaxe faz um exemplo falhar porque um campo ou caminho mudou. A deriva de significado mantém o exemplo válido, mas altera o que ele afeta. A primeira constrange quem escreveu. A segunda pode danificar dados, gastar dinheiro, expor registros ou ampliar o acesso. Sua suíte precisa detectar as duas.

Uma requisição aprovada ainda pode provar que o exemplo está errado

Um teste de documentação que verifica apenas códigos de status captura as falhas fáceis e deixa passar as inseguras. Um sucesso HTTP diz que o servidor aceitou a requisição. Não diz se ela atingiu o objeto pretendido, produziu o efeito descrito ou respeitou o limite indicado.

Suponha que uma página de referência publique esta requisição:

curl -sS -X POST "$API_URL/v1/exports" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project":"demo","include_archived":false}'

Um teste básico verifica 202 Accepted e declara vitória. Ele não detecta várias mudanças relevantes:

• O serviço renomeou silenciosamente project para project_id e trata o campo antigo como ausente.
• include_archived mudou de uma opção de exclusão para um campo de compatibilidade ignorado.
• A credencial ganhou visibilidade para toda a conta, então demo resolve para o projeto de outro tenant.
• O endpoint ainda enfileira o trabalho, mas agora exporta anexos que o guia diz excluir.

O teste precisa inspecionar o resultado e o estado do serviço, não apenas o status. Em uma conta descartável, crie um registro ativo e um arquivado. Envie a requisição documentada. Consulte o job resultante. Verifique se o artefato contém o registro ativo, omite o arquivado e registra o identificador de projeto esperado. Se o serviço não expõe evidências suficientes para essa verificação, a documentação também não pode prometer esse comportamento com segurança.

A RFC 9110 define códigos de status HTTP como o resultado do tratamento de uma requisição. Ela não afirma que um status bem-sucedido prova a intenção de negócio do chamador. Parece óbvio, mas as equipes continuam criando verificações que reduzem o protocolo a curl mais grep 200. Use a semântica HTTP para asserções de protocolo e acrescente asserções para o resultado real.

Um bom teste nomeia a afirmação que verifica. export_excludes_archived_records é útil. docs_example_returns_success apenas informa que alguém enviou uma requisição.

Exemplos precisam de testes de contrato, não de revisões de capturas de tela

Copiar um exemplo da documentação para um terminal durante a revisão de lançamento é melhor que nada. Não escala, não deixa evidências confiáveis e favorece o caminho feliz. As pessoas também costumam corrigir o comando localmente e esquecer de corrigir a página.

Coloque os exemplos executáveis em um arquivo-fonte estruturado, gere o trecho exibido a partir dele e execute o mesmo arquivo na CI. Você pode usar exemplos OpenAPI, extração de código Markdown ou um diretório separado de fixtures. O mecanismo importa menos que uma propriedade: o comando visto pelo leitor deve ser o mesmo executado pelo teste.

Não mantenha silenciosamente uma «versão de teste» com URLs mais seguras, escopos menores ou cabeçalhos mais completos que os do exemplo publicado. Essa divisão cria uma compilação verde reconfortante enquanto as instruções públicas apodrecem. Parametrize apenas os valores que precisam variar por ambiente, como URL base, credenciais de teste e identificadores de fixtures. Mantenha idênticos o método, o caminho, o formato do corpo e os sinalizadores relevantes de segurança.

Um pequeno teste de shell estabelece o padrão:

set -euo pipefail

project_id="docs-check-$RANDOM"
response=$(curl -sS -X POST "$API_URL/v1/projects" \
  -H "Authorization: Bearer $DOCS_TEST_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"id\":\"$project_id\",\"name\":\"Documentation check\"}")

printf '%s' "$response" | jq -e \
  --arg id "$project_id" \
  '.id == $id and .name == "Documentation check" and .archived == false'

A saída esperada de jq -e é o valor JSON true; em caso de divergência, o processo termina com código diferente de zero. O ponto importante não é a sintaxe do shell. A asserção registra o que a prosa promete: a API cria um projeto com o identificador fornecido, preserva o nome fornecido e não o arquiva por padrão.

Crie uma verificação separada para a documentação renderizada. Se um extrator Markdown retirar da página um bloco marcado como bash, o teste deve executar esse bloco depois de substituir as variáveis de ambiente aprovadas. Se a documentação for gerada a partir de uma descrição OpenAPI, teste o exemplo gerado, não um equivalente copiado à mão.

A revisão por captura de tela ainda ajuda na legibilidade. Ela não prova o comportamento. Um revisor frequentemente não percebe um cabeçalho omitido, sobretudo quando a página contém vários exemplos parecidos. Máquinas não se cansam de comparar um campo com uma fixture.

As verificações do serviço ativo precisam cobrir padrões e caminhos de falha

A maioria das mudanças perigosas de API aparece em padrões, limites de autorização e tratamento de falhas. Os testes do caminho feliz evitam os três porque são fáceis de escrever e manter verdes.

Teste os casos de omissão que um agente pode produzir. Agentes frequentemente montam payloads de forma condicional, então um campo opcional pode desaparecer quando uma busca anterior não retorna valor. Para cada parâmetro opcional documentado, decida se a omissão é segura, rejeitada ou produz uma diferença relevante. Depois, teste diretamente o comportamento documentado.

Para uma operação com o campo dry_run, execute pelo menos estes casos em um ambiente isolado:

1. dry_run: true retorna um plano e deixa a fixture inalterada.
2. dry_run: false realiza a mudança indicada apenas na fixture nomeada.
3. Omitir dry_run rejeita a requisição ou produz o padrão documentado.
4. Um token sem escopo suficiente falha antes que qualquer mudança ocorra.
5. Repetir a requisição documentada se comporta conforme as orientações de idempotência.

O terceiro caso detecta uma fonte comum de danos acidentais. A equipe do serviço altera um padrão para favorecer usuários interativos, enquanto a documentação ainda pressupõe o valor antigo. Uma interface humana pode mostrar uma tela de confirmação. Um cliente de API não tem essa tela.

Exemplos de falha também precisam de testes. A documentação costuma dizer «tente novamente em 429» sem informar se a resposta inclui Retry-After, se é seguro repetir a operação ou se a requisição precisa de um token de idempotência. Esse conselho pode transformar um breve limite de taxa em faturas duplicadas, implantações duplicadas ou revogações repetidas.

Teste a orientação exata para a falha. Force a condição de limitação em um serviço de teste ou ambiente controlado. Confirme que o cliente documentado lê o cabeçalho indicado, espera conforme a orientação e reenvia o mesmo identificador de idempotência quando a API oferece esse recurso. Se o serviço não consegue produzir o erro de forma previsível, documente a incerteza em vez de publicar uma receita confiante.

A palavra-chave default do OpenAPI cria uma armadilha relacionada. Em descrições JSON Schema e OpenAPI, um padrão declarado costuma comunicar o que as ferramentas podem presumir ou exibir. Ele não faz automaticamente com que toda implementação do servidor aplique esse valor. Verifique o serviço implantado com o campo omitido. Um padrão do esquema e um padrão do servidor são afirmações separadas até que um teste as vincule.

Fluxos destrutivos exigem provas descartáveis

Não teste exemplos destrutivos em uma conta de staging compartilhada e chame isso de seguro. Ambientes compartilhados acumulam fixtures antigas, experimentos manuais e credenciais com alcance incerto. Mais cedo ou mais tarde, um teste de documentação corresponderá ao objeto errado ou um comando de limpeza ultrapassará seu limite.

Use um tenant ou conta de teste dedicado, com credenciais que alcancem somente os recursos de teste. Crie cada fixture com um marcador exclusivo da execução. Recupere-a por esse marcador antes de alterá-la. Depois do teste, verifique o estado resultante em vez de presumir que a API fez o que a resposta afirmou.

Um exemplo de exclusão deve demonstrar o ciclo completo:

create fixture: docs-delete-<run-id>
read fixture: confirm owner=test-suite and run_id=<run-id>
delete fixture: send the rendered documentation request
read fixture: expect the documented absence or tombstone state
list nearby fixtures: confirm unrelated fixtures remain

Essa última verificação importa. Um teste de exclusão que apenas confirma o desaparecimento do objeto escolhido não detecta um seletor amplo demais. Já vi equipes aceitarem um endpoint em lote porque sua única fixture desapareceu como esperado, embora o endpoint também tivesse removido todo recurso com prefixo semelhante. O teste precisava de um vizinho deliberadamente parecido que deveria sobreviver.

Não instrua agentes a usar seletores convenientes como latest, all, um filtro vazio ou um nome legível quando existir um identificador imutável. Esses seletores parecem amigáveis em um tutorial, mas tornam-se perigosos quando um agente executa a receita em uma conta movimentada. Se uma operação realmente exige um seletor amplo, coloque o escopo no corpo da requisição ou nos argumentos do comando, onde um revisor possa vê-lo. Não o esconda em um padrão do servidor.

Para operações irreversíveis, publique uma leitura de pré-verificação e faça o exemplo consumir seu resultado. Primeiro busque o objeto, confirme seu ID imutável e seu estado relevante, depois execute a alteração. Isso acrescenta atrito. Esse atrito custa menos que explicar por que um agente excluiu o objeto que por acaso compartilhava um nome de exibição.

Os testes de ferramentas devem comparar significado, não apenas esquemas

A validação do esquema é necessária, mas os esquemas geralmente descrevem a forma com mais fidelidade que as consequências. Um corpo de requisição pode satisfazer todas as restrições de tipo e ainda direcionar a ação ao ambiente errado ou com privilégio inadequado.

Baseie as asserções em quatro perguntas: quem foi afetado pela ação? O que mudou? O que não mudou? Qual identidade a autorizou? Essas perguntas servem para APIs HTTP, comandos SSH e ferramentas internas.

No caso de HTTP, capture um identificador de requisição quando o serviço fornecer um e consulte o recurso ou registro de auditoria resultante no ambiente de teste. Compare o identificador, o ator, o alvo e a alteração. No caso de SSH, execute comandos em um host descartável, capture o status de saída e a saída, e depois inspecione o estado do host com um comando de verificação separado. Não deixe o comando da ação corrigir sua própria prova.

Uma boa fixture oferece contraste. Se você testa um comando que deve reiniciar um serviço, crie outro que precise continuar em execução. Se testa uma consulta limitada a um repositório, inclua um segundo repositório que a mesma credencial possa ver, mas que a requisição não possa tocar. Sem contraste, uma ação ampla pode parecer correta.

É aqui que muitas equipes usam testes de contrato de forma incorreta. Ferramentas de contrato orientadas pelo consumidor podem confirmar que um provedor aceita o formato da requisição e retorna os campos esperados. Elas não determinam se a requisição selecionou a conta de produção correta, se uma opção force ganhou outro significado ou se uma exclusão se propagou além do objeto documentado. Mantenha o teste de contrato. Acrescente um teste de resultado com fixtures capazes de revelar o excesso de alcance.

A descrição da ferramenta também precisa ser testada. Se uma ferramenta expõe environment, não descreva production como valor aceitável sem verificar que ele encaminha para o host documentado e usa o caminho de autorização indicado. Agentes usam descrições para preencher argumentos. Uma descrição desatualizada é apenas a versão em prosa de um exemplo de API desatualizado.

O agente precisa de evidências de atualização e de um caminho seguro para recusar

Um agente não deve concluir que a documentação está atualizada só porque aparece em um repositório ou portal interno. Forneça evidências verificáveis por máquina, vinculadas à operação que ele pretende chamar.

Um manifesto simples pode bastar:

{
  "operation": "POST /v1/exports",
  "documentation_source": "docs/api/exports.md#creating-an-export",
  "verified_in": "isolated-test-tenant",
  "verification_commit": "<commit-id>",
  "assertions": [
    "returns an export job",
    "omits archived fixtures when include_archived is false",
    "rejects a token without export scope"
  ],
  "review_required_when": ["production", "include_archived=true"]
}

O identificador do commit não é, por si só, um selo de confiança. Ele permite que um revisor rastreie a documentação e o código de teste que produziram a evidência. Se o processo de lançamento exigir um limite de idade, armazene o horário da verificação nos registros de compilação. Não finja que uma marca de tempo torna seguro um comportamento antigo. Uma implantação do serviço pode invalidar o teste de ontem.

A regra de decisão do agente deve ser clara. Se a operação solicitada não tiver um registro de verificação aprovado para a interface implantada, ele deve executar uma pré-verificação sem alteração em um contexto de teste aprovado ou pedir a uma pessoa que aprove a ação exata. Não deve improvisar com base em um endpoint vizinho.

Separe «desconhecido» de «seguro». Agentes tendem a preencher lacunas porque concluir uma tarefa recebe retorno positivo. O design da ferramenta precisa fazer da abstenção um resultado aceitável quando faltarem evidências. Retorne um motivo como: documentation example has no verified outcome test for this operation. Essa mensagem oferece ao desenvolvedor um alvo claro para correção, em vez de uma recusa vaga.

Não tente resolver isso com um arquivo extenso de políticas que enumere todas as frases arriscadas em todos os documentos. A redação mudará mais rápido que as regras. Vincule uma operação concreta a um teste concreto e forneça o resultado ao agente.

Gates de lançamento só funcionam quando bloqueiam a página enganosa

Um programa de verificação da documentação falha quando produz relatórios sem uma ação obrigatória. A verificação deve bloquear a publicação, ou pelo menos o acesso do agente ao exemplo afetado, quando o contrato do serviço mudar.

Ligue as verificações às alterações na especificação da API, nos handlers de rotas, no middleware de autenticação, nos construtores de requisições do SDK e nas fontes da documentação. Uma mudança em qualquer uma dessas áreas deve executar os testes relevantes. Se um teste falhar, a equipe tem três escolhas honestas: restaurar o comportamento antigo, atualizar documentação e testes para o novo comportamento ou marcar a operação como indisponível para agentes até a verificação passar.

A revisão manual continua útil para decisões, mas sozinha é uma recomendação inadequada. Ela é popular porque parece barata e preserva um fluxo rápido de publicação. Também pede que o revisor simule mentalmente um serviço, credenciais, padrões e transições de estado a partir de texto. As pessoas não fazem isso de modo confiável em lançamentos rotineiros.

Torne as falhas fáceis de entender. Um bom relatório informa a página, o bloco de código, a operação, a fixture, a resposta observada e a asserção violada. «A integração da documentação falhou» cria uma caça ao tesouro. «exports.md, linha 42, diz que registros arquivados são excluídos; o artefato de exportação incluiu a fixture archived-run-817» dá ao responsável uma correção direta.

Não afrouxe um teste só porque uma mudança no serviço o tornou inconveniente. Primeiro decida se a promessa antiga era útil. Se era, restaure-a ou declare a nova limitação com destaque. Se era insegura, remova o exemplo em vez de preservá-lo com uma frase mais branda. Um agente normalmente seguirá o comando que restar.

A documentação versionada exige a mesma disciplina. Uma página de uma versão antiga da API pode descrever corretamente uma implantação antiga e ainda enganar um agente apontado para a URL base atual. Coloque a versão no caminho do endpoint, na URL do servidor ou nos metadados da ferramenta, onde o agente possa vinculá-la à requisição. Um título dizendo «v1» em algum ponto acima da dobra é uma evidência fraca.

A autorização limita o alcance, mas não corrige instruções erradas

Aprovação e isolamento de credenciais continuam importantes porque os testes de documentação podem deixar passar defeitos. Eles reduzem o dano quando um agente escolhe a operação errada. Não transformam uma instrução antiga em correta.

Mantenha as duas funções separadas. A verificação da documentação pergunta: «Este exemplo descreve o serviço ativo e suas consequências?» A autorização da ação pergunta: «Este agente deve poder fazer esta chamada agora?» Misturá-las gera confusão. Um usuário pode aprovar uma chamada porque o agente diz que exportará um projeto, enquanto o exemplo desatualizado na verdade exporta todos os projetos visíveis para a credencial.

Para ações HTTP e SSH conduzidas por agentes, o Sallyport mantém as credenciais fora do agente e pode exigir que uma pessoa autorize uma sessão ou o uso de uma credencial específica. Esse é um último limite útil quando um teste de documentação não encontra evidências confiáveis ou quando uma ação tem consequências que merecem revisão humana.

A tela de aprovação deve mostrar a operação, o alvo e o escopo em termos que uma pessoa possa avaliar. «POST /v1/exports» é insuficiente quando o corpo da requisição contém include_archived=true ou um seletor para toda a conta. Se sua camada de autorização não consegue revelar o escopo relevante, restrinja a interface da ferramenta até que consiga.

Os registros de auditoria fornecem o material para melhorar os testes. Quando uma pessoa revogar uma execução ou questionar uma ação, examine a requisição exata, a fonte da documentação citada pelo agente e as evidências de verificação disponíveis. Não transforme essa análise em busca de culpados. Use-a para acrescentar a fixture, a asserção ou a condição de recusa que faltava.

Comece testando o exemplo que mais provavelmente causará arrependimento

Não comece pela requisição GET mais simples da referência. Comece pelo exemplo capaz de excluir, publicar, alternar credenciais, conceder acesso, cobrar ou alcançar um host de produção. Dê a ele uma fixture isolada, execute o comando renderizado exato e verifique tanto a mudança pretendida quanto a mudança próxima que não pode acontecer.

Depois, conecte esse teste à fonte da documentação e torne a falha visível antes da publicação ou do uso pelo agente. O trabalho é menos glamoroso que escrever uma nova descrição de ferramenta, mas elimina uma suposição perigosa: a de que uma página é segura porque já passou por uma revisão.

Um serviço ativo muda. Sua documentação mudará mais lentamente, a menos que você force os dois a se encontrarem em um teste. Faça desse encontro parte do lançamento, antes que um agente transforme uma frase antiga em ação.