Redirecionamentos 301, 302, 307 e 308: quais preservam o método da requisição

O que é

A RFC 9110 define quatro códigos que significam "o recurso está no URI indicado em Location" e um que aponta para outro recurso:

• 301 Moved Permanently: por razões históricas, um user agent PODE (MAY) trocar POST por GET na requisição seguinte. Cacheável por heurística.
• 302 Found: temporário; vale a mesma observação sobre a troca de POST por GET. Não é cacheável por heurística.
• 303 See Other: o cliente faz uma recuperação (GET ou HEAD) de um recurso diferente; é o padrão post-redirect-get usado em formulários.
• 307 Temporary Redirect: o user agent NÃO PODE (MUST NOT) mudar o método; não é cacheável por heurística.
• 308 Permanent Redirect: NÃO PODE (MUST NOT) mudar o método; cacheável por heurística. A RFC 9110 observa que ele é bem mais recente que os demais e pode não ser reconhecido em todos os lugares.

A RFC 9110 também descreve o que o cliente faz ao seguir o redirecionamento: substitui o URI de destino, descarta os campos gerados automaticamente e os específicos da conexão, considera descartar Authorization e Cookie, muda o método apenas quando o código de status assim determina e remove os cabeçalhos de conteúdo se o método passou a ser GET. Os clientes devem detectar loops; uma especificação anterior sugeria um limite de cinco saltos.

Por que importa

Uma API que responde a um POST com 301 ou 302 não tem como saber se o cliente vai reenviar o corpo com POST ou fazer um GET; a página do MDN sobre o 302 recomenda usar 307 para evitar que os user agents modifiquem a requisição. Caches podem reutilizar códigos permanentes sem consultar a origem, de modo que um 301 ou 308 equivocado continua enviando os clientes ao lugar errado mesmo depois da correção.

Como aplicar

• Recurso movido definitivamente e qualquer método pode chegar: 308. Só importa tráfego GET e HEAD e clientes antigos: 301.
• Desvio temporário em que método e corpo precisam ser mantidos (manutenção, canary): 307.
• Depois de um POST de formulário bem-sucedido no navegador: 303 para a página de resultado, para que um recarregamento não reenvie o formulário.
• Recurso desativado e sem sucessor: 410, não um redirecionamento para a página inicial.
• Defina um Cache-Control explícito nos redirecionamentos permanentes para limitar a duração de um erro.
• Teste com curl -v -L -d '' URL e observe o método em cada salto: o curl passa para GET após 301, 302 e 303, a menos que --post301, --post302 ou --post303 seja informado. -X POST -L não permite ver a mudança, pois a documentação do curl diz que um método definido com -X é usado em todas as requisições.

Armadilhas

Redirecionar para HTTPS, com 301, um endpoint POST em http:// faz com que o corpo seja perdido ou reenviado, dependendo do cliente. Cadeias de redirecionamento multiplicam as idas e voltas de rede e os comportamentos de cache. Os clientes costumam descartar Authorization quando o redirecionamento leva a outro host, como a RFC 9110 manda considerar; a documentação do curl diz que ele não envia credenciais a outros nomes de host, a menos que --location-trusted seja usado, de modo que uma requisição autenticada e redirecionada pode chegar sem o token.