Redirections 301, 302, 307 et 308 : lesquelles préservent la méthode de la requête

Ce que c'est

La RFC 9110 définit quatre codes signifiant « la ressource se trouve à l'URI indiquée dans Location » et un qui pointe ailleurs :

• 301 Moved Permanently : pour des raisons historiques, un agent utilisateur PEUT transformer un POST en GET lors de la requête suivante. Cachable de façon heuristique.
• 302 Found : temporaire ; la même remarque POST-vers-GET s'applique. Non cachable de façon heuristique.
• 303 See Other : le client effectue une récupération (GET ou HEAD) d'une ressource différente ; c'est le schéma post-redirect-get pour les formulaires.
• 307 Temporary Redirect : l'agent utilisateur NE DOIT PAS changer la méthode ; non cachable de façon heuristique.
• 308 Permanent Redirect : NE DOIT PAS changer la méthode ; cachable de façon heuristique. La RFC 9110 note qu'il est bien plus récent que ses homologues et pourrait ne pas être reconnu partout.

La RFC 9110 décrit aussi ce que fait un client en suivant une redirection : remplacer l'URI cible, supprimer les champs générés automatiquement et propres à la connexion, envisager de supprimer Authorization et Cookie, ne changer la méthode que lorsque le code de statut le dit, et retirer les en-têtes de contenu si la méthode est devenue GET. Les clients devraient détecter les boucles ; une spécification antérieure suggérait une limite de cinq sauts.

Pourquoi c'est important

Une API qui répond à un POST par 301 ou 302 ne peut pas savoir si le client renverra le corps en POST ou émettra un GET ; la page de MDN sur 302 recommande d'utiliser 307 à la place pour éviter que les agents utilisateurs ne modifient la requête. Les codes permanents peuvent être réutilisés par les caches sans consulter l'origine, donc un 301 ou 308 erroné continue d'envoyer les clients au mauvais endroit après la correction.

Comment l'appliquer

• Ressource déplacée définitivement et n'importe quelle méthode peut arriver : 308. Seul le trafic GET et HEAD ainsi que les anciens clients comptent : 301.
• Détour temporaire où la méthode et le corps doivent survivre (maintenance, canari) : 307.
• Après un POST de formulaire navigateur réussi : 303 vers la page de résultat, pour qu'un rechargement ne resoumette pas.
• Ressource retirée sans successeur : 410, pas une redirection vers la page d'accueil.
• Définir un Cache-Control explicite sur les redirections permanentes pour borner la durée de vie d'une erreur.
• Tester avec curl -v -L -d '' URL et observer la méthode à chaque saut : curl passe en GET après 301, 302 et 303, sauf si --post301, --post302 ou --post303 est fourni. -X POST -L ne peut pas montrer le changement, car curl documente qu'une méthode définie avec -X est utilisée pour toutes les requêtes.

Pièges

Rediriger un point de terminaison POST en http:// vers HTTPS avec 301 perd ou réémet les corps selon le client. Les chaînes de redirection multiplient les allers-retours et le comportement de cache. Les clients suppriment couramment Authorization lorsqu'une redirection mène vers un autre hôte, comme la RFC 9110 les invite à l'envisager ; curl documente qu'il ne transmet pas les identifiants aux autres noms d'hôte sauf si --location-trusted est fourni, si bien qu'une requête authentifiée redirigée peut arriver sans son jeton.