Weiterleitungen 301, 302, 307 und 308: Welche die Anfragemethode beibehalten

Worum es geht

RFC 9110 definiert vier Codes mit der Bedeutung „die Ressource befindet sich an der URI in Location" sowie einen, der auf etwas anderes verweist:

• 301 Moved Permanently: Aus historischen Gründen DARF ein User-Agent bei der Folgeanfrage POST in GET ändern. Heuristisch cachebar.
• 302 Found: vorübergehend; derselbe Hinweis zu POST-zu-GET gilt. Nicht heuristisch cachebar.
• 303 See Other: Der Client führt einen Abruf (GET oder HEAD) einer anderen Ressource aus; das Post-Redirect-Get-Muster für Formulare.
• 307 Temporary Redirect: Der User-Agent DARF die Methode NICHT ändern; nicht heuristisch cachebar.
• 308 Permanent Redirect: DARF die Methode NICHT ändern; heuristisch cachebar. RFC 9110 merkt an, dass er deutlich jünger ist als seine Geschwister und möglicherweise nicht überall erkannt wird.

RFC 9110 beschreibt zudem, was ein Client beim Folgen tut: die Ziel-URI ersetzen, automatisch generierte und verbindungsspezifische Felder verwerfen, das Verwerfen von Authorization und Cookie in Betracht ziehen, die Methode nur dort ändern, wo der Statuscode es vorschreibt, und Content-Header entfernen, falls die Methode zu GET wurde. Clients sollten Schleifen erkennen; eine frühere Spezifikation schlug eine Obergrenze von fünf Sprüngen vor.

Warum es wichtig ist

Eine API, die ein POST mit 301 oder 302 beantwortet, kann nicht wissen, ob der Client den Body erneut per POST sendet oder ein GET ausführt; MDN rät auf der Seite zu 302, stattdessen 307 zu verwenden, damit User-Agents die Anfrage nicht verändern. Permanente Codes dürfen von Caches wiederverwendet werden, ohne den Ursprungsserver zu fragen, sodass ein falsches 301 oder 308 Clients auch nach der Korrektur weiter an die falsche Stelle schickt.

So wird es angewendet

• Ressource dauerhaft verschoben, beliebige Methoden können eintreffen: 308. Nur GET- und HEAD-Verkehr sowie alte Clients spielen eine Rolle: 301.
• Vorübergehende Umleitung, bei der Methode und Body erhalten bleiben müssen (Wartung, Canary): 307.
• Nach einem erfolgreichen Formular-POST im Browser: 303 zur Ergebnisseite, damit ein Neuladen nicht erneut sendet.
• Stillgelegte Ressource ohne Nachfolger: 410, keine Weiterleitung zur Startseite.
• Ein explizites Cache-Control auf permanenten Weiterleitungen setzen, um die Lebensdauer eines Fehlers zu begrenzen.
• Mit curl -v -L -d '' URL testen und die Methode je Sprung beobachten: curl wechselt nach 301, 302 und 303 zu GET, sofern nicht --post301, --post302 oder --post303 angegeben wird. -X POST -L kann diesen Wechsel nicht zeigen, da curl dokumentiert, dass eine mit -X gesetzte Methode für alle Anfragen verwendet wird.

Stolpersteine

Wird ein POST-Endpunkt unter http:// mit 301 auf HTTPS umgeleitet, geht der Body verloren oder wird erneut gesendet, je nach Client. Weiterleitungsketten vervielfachen Roundtrips und Cache-Verhalten. Clients verwerfen häufig Authorization, wenn eine Weiterleitung auf einen anderen Host führt, wie RFC 9110 es ihnen nahelegt; curl dokumentiert, dass es Zugangsdaten bei anderen Hostnamen zurückhält, sofern nicht --location-trusted angegeben wird, sodass eine umgeleitete authentifizierte Anfrage ohne ihr Token ankommen kann.