RFC 7538

RFC 7538: The Hypertext Transfer Protocol Status Code 308 (Permanent Redirect) 🎀

Okay bestie, this one is RFC 7538 💖. It's a Standards Track doc from April 2015, written by Julian F. Reschke at greenbytes, and it's ISSN 2070-1721. It obsoletes RFC 7238, which was Experimental. The big news is that it adds HTTP status code 308 to the family of redirect codes. ✨

Its IETF stream is the Internet Engineering Task Force, and it's the official protocol spec, so the details matter a lot 🧚

Abstract

This doc specifies the extra HTTP status code 308 (Permanent Redirect) 🦋

Status of This Memo

This is an Internet Standards Track document, so it's the real deal 👑

It's a product of the IETF and reflects the consensus of the IETF community. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check Section 2 of RFC 5741 🌸

Info about the current status of this doc, any errata, and how to give feedback lives at http://www.rfc-editor.org/info/rfc7538 💅

Copyright Notice

Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved. 🌈

This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info), as in effect on the publication date. Read these carefully, because they spell out your rights and restrictions for this doc 📜

Code Components pulled out of this doc must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, per the Simplified BSD License 🫶

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Notational Conventions  . . . . . . . . . . . . . . . . . . .   2
   3.  308 Permanent Redirect  . . . . . . . . . . . . . . . . . . .   3
   4.  Deployment Considerations . . . . . . . . . . . . . . . . . .   3
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .   4
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   5
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   5
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .   5
     7.2.  Informative References  . . . . . . . . . . . . . . . . .   5
   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .   6
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   6

---

1. Introduction ✨

HTTP has a set of status codes for redirecting a request to a different URI ([RFC3986]). The history of these codes is summarized in Section 6.4 of [RFC7231], which also sorts the existing status codes into four categories 🍓

The first of those categories has 301 (Moved Permanently), 302 (Found), and 307 (Temporary Redirect). Here's how they break down:

+-------------------------------------------+-----------+-----------+
|                                           | Permanent | Temporary |
+-------------------------------------------+-----------+-----------+
| Allows changing the request method from   | 301       | 302       |
| POST to GET                               |           |           |
| Does not allow changing the request       | -         | 307       |
| method from POST to GET                   |           |           |
+-------------------------------------------+-----------+-----------+

So 307 is the temporary one that doesn't let you flip POST to GET, and there's no permanent version of it. Section 6.4.7 of [RFC7231] says it doesn't define a permanent variant of status code 307. This spec fills that gap by adding 308, the missing permanent variant (Section 3) 🦋

Also, this spec makes no technical changes from the Experimental RFC 7238, which it obsoletes 🌸

2. Notational Conventions 💜

Okay, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this doc are interpreted as described in [RFC2119]. Those capital words carry the official meaning, so pay attention to them 🔥

3. 308 Permanent Redirect 🌈

The 308 (Permanent Redirect) status code tells you the target resource got a new permanent URI, and any future references ought to use one of the enclosed URIs 🦋 Clients that can edit links ought to automatically re-link references to the effective request URI (Section 5.5 of [RFC7230]) to one or more of the new references the server sends, when that's possible ✨

The server SHOULD generate a Location header field ([RFC7231], Section 7.1.2) in the response, containing a preferred URI reference for the new permanent URI 💅 The user agent MAY use the Location field value for automatic redirection. The server's response payload usually has a short hypertext note with a hyperlink to the new URI(s) 🎀

A 308 response is cacheable by default, i.e., unless the method definition or explicit cache controls say otherwise (see [RFC7234], Section 4.2.2) 🧚

Note: 308 is basically a cousin of 301 (Moved Permanently) ([RFC7231], Section 6.4.2). The only difference is that 308 does NOT let you change the request method from POST to GET.

4. Deployment Considerations 🫶

Section 6 of [RFC7231] requires recipients to treat unknown 3xx status codes the same way they treat status code 300 (Multiple Choices) ([RFC7231], Section 6.4.1). So servers can't count on automatic redirection working like it does for 301, 302, or 307 😭

That's why using status code 308 is limited to cases where the server is pretty sure the client understands the new code, or where falling back to the semantics of status code 300 isn't a problem 💀

Server implementers are advised not to vary the status code based on request characteristics, like the User-Agent header field ("User-Agent Sniffing"). Doing that usually leads to code that's hard to maintain and hard to debug, and it would also need extra care around caching (i.e., setting a "Vary" response header field, as defined in Section 7.1.4 of [RFC7231]) 🙈

Also, lots of existing HTML-based user agents will emulate a refresh when they hit an HTML <meta> refresh directive ([HTML], Section 4.2.5.3). That can be used as another fallback. Here's an example:

Client request:

  GET / HTTP/1.1
  Host: example.com

Server response:

  HTTP/1.1 308 Permanent Redirect
  Content-Type: text/html; charset=UTF-8
  Location: http://example.com/new
  Content-Length: 356

  <!DOCTYPE HTML>
  <html>
     <head>
        <title>Permanent Redirect</title>
        <meta http-equiv="refresh"
              content="0; url=http://example.com/new">
     </head>
     <body>
        <p>
           The document has been moved to
           <a href="http://example.com/new"
           >http://example.com/new</a>.
        </p>
     </body>
  </html>

5. Security Considerations 🔐

Every security consideration that applies to HTTP redirects applies to the 308 status code too (see Section 9 of [RFC7231]). This part is serious, so read it carefully 😤

Unsecured communication over the Internet can be hit by man-in-the-middle modification of messages, including changes to status codes or redirect targets. That's a real danger. Using Transport Layer Security (TLS) is one way to mitigate those attacks. See Section 9 of [RFC7230] for related attacks on authority and message integrity 🚨

6. IANA Considerations 📋

The "Hypertext Transfer Protocol (HTTP) Status Code Registry" (defined in Section 8.2 of [RFC7231] and located at http://www.iana.org/assignments/http-status-codes) has been updated to reference this specification ✨

Here's the new entry:

+-------+--------------------+----------------------------------+
| Value | Description        | Reference                        |
+-------+--------------------+----------------------------------+
| 308   | Permanent Redirect | Section 3 of this specification  |
+-------+--------------------+----------------------------------+

7. References 📚

7.1. Normative References

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119, March 1997,
           <http://www.rfc-editor.org/info/rfc2119>.

[RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
           Resource Identifier (URI): Generic Syntax", STD 66, RFC
           3986, January 2005,
           <http://www.rfc-editor.org/info/rfc3986>.

[RFC7230]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
           Protocol (HTTP/1.1): Message Syntax and Routing", RFC
           7230, June 2014, <http://www.rfc-editor.org/info/rfc7230>.

[RFC7231]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
           Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
           June 2014, <http://www.rfc-editor.org/info/rfc7231>.

[RFC7234]  Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
           Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
           RFC 7234, June 2014,
           <http://www.rfc-editor.org/info/rfc7234>.

7.2. Informative References

[HTML]     Hickson, I., Berjon, R., Faulkner, S., Leithead, T., Doyle
           Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", W3C
           Recommendation REC-html5-20141028, October 2014,
           <http://www.w3.org/TR/2014/REC-html5-20141028/>.

           Latest version available at <http://www.w3.org/TR/html5/>.

Acknowledgements 💖

The definition for the new status code 308 reuses text from the HTTP/1.1 definitions of status codes 301 and 307. Honestly, that's a good sign: it means they didn't reinvent the wheel 🎡

Huge thanks to Ben Campbell, Cyrus Daboo, Adrian Farrell, Eran Hammer-Lahav, Bjoern Hoehrmann, Barry Leiba, Subramanian Moonesamy, Kathleen Moriarty, Peter Saint-Andre, Robert Sparks, and Roy Fielding for feedback on this document 🫶👑

Author's Address 🦋

Julian F. Reschke greenbytes GmbH Hafenweg 16 Muenster, NW 48155 Germany

EMail: julian.reschke@greenbytes.de URI: http://greenbytes.de/tech/webdav/