Como registrar uma observação HTTP delimitada

Objetivo

Registrar uma observação HTTP de modo que outro colaborador possa repetir a verificação sem depender de nenhum estado oculto.

Pré-requisitos

Use um endpoint de teste ou um endpoint público que você tenha permissão para consultar. Registre o horário em UTC, a versão do cliente ou da ferramenta, a família de rede e as configurações não secretas que possam afetar o resultado. Nunca inclua bearer tokens, cookies, URLs privadas nem dados pessoais.

Passos

1. Escreva o método e a URL exatos, incluindo os parâmetros de consulta, mas oculte os segredos.
2. Registre os cabeçalhos da requisição que influenciam de forma relevante o comportamento, como Accept e Content-Type; anote quais cabeçalhos sensíveis foram omitidos.
3. Envie uma única requisição delimitada, com timeout e limite de tamanho da resposta.
4. Registre o código de status, os cabeçalhos de resposta selecionados, uma observação curta e sanitizada e, quando for apropriado reter esse dado, um digest criptográfico dos bytes da resposta.
5. Repita uma vez, nas mesmas condições. Indique se as observações coincidem; se forem diferentes, registre a diferença em vez de escolher o resultado preferido.
6. Declare o que a verificação não estabelece, como a correção do serviço, a disponibilidade a longo prazo ou a veracidade da fonte.

Resultado esperado

O registro contém informação suficiente para reproduzir a requisição e para distinguir uma observação atual de uma afirmação geral. Um revisor consegue identificar o endpoint, a janela de tempo, as condições, o resultado e as limitações sem receber credenciais.

Limites e base de verificação

Uma única resposta HTTP não prova que os dados subjacentes estejam corretos nem que o serviço continuará disponível. Um digest prova apenas a igualdade dos bytes; não prova o significado nem a autenticidade. Os endpoints podem variar conforme o horário, a região, a autenticação ou a carga, portanto repita a observação ou use pontos de observação independentes quando isso for relevante.

Este é um método de documentação original. A terminologia HTTP segue a RFC 9110, o registro de URIs segue a RFC 3986 e o formato de timestamp segue a RFC 3339. Não se alega nenhum experimento, medição ou resultado de campo.