RFC 9205

Building Protocols with HTTP

📅 published June 2022, from ietf

RFC 9205: Building Protocols with HTTP ✨

okay bestie, this one is the BCP for anyone building an app protocol on top of HTTP 🎀 here's the title block tea:

Number: RFC 9205
Title: Building Protocols with HTTP
Author: M. Nottingham
Date: June 2022
Category: Best Current Practice (it's BCP: 56) 💅
Obsoletes: RFC 3205 (so that one is retired, iykyk 💀)
Publisher: IETF, ISSN 2070-1721

Abstract 🦋

so a LOT of apps use HTTP as the base for their APIs (you've heard "REST APIs" and "HTTP APIs" 100 times, same thing 🧚). this doc gives best practices for writing specs that use HTTP to define brand new application protocols. it's written mainly to help IETF folks building app protocols on HTTP for the Internet, but it could be useful in other situations too 🌸

this document obsoletes [RFC3205] 💜

Status of This Memo 📜

this memo documents an Internet Best Current Practice.

this doc is a product of the Internet Engineering Task Force (IETF). it represents the consensus of the IETF community. it got public review and was approved for publication by the Internet Engineering Steering Group (IESG). more info on BCPs is in Section 2 of RFC 7841 ✨

info about the current status, any errata, and how to give feedback is at https://www.rfc-editor.org/info/rfc9205 🔗

Copyright Notice ©️

this doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as in effect on the date of publication. please read these carefully, because they explain your rights and restrictions for this document 🙏 code components pulled out of this document must include Revised BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, as described in the Revised BSD License.

Table of Contents 🗂️

1.  Introduction
  1.1.  Notational Conventions
2.  Is HTTP Being Used?
  2.1.  Non-HTTP Protocols
3.  What's Important About HTTP
  3.1.  Generic Semantics
  3.2.  Links
  3.3.  Rich Functionality
4.  Best Practices for Specifying the Use of HTTP
  4.1.  Specifying the Use of HTTP
  4.2.  Specifying Server Behaviour
  4.3.  Specifying Client Behaviour
  4.4.  Specifying URLs
    4.4.1.  Discovering an Application's URLs
    4.4.2.  Considering URI Schemes
    4.4.3.  Choosing Transport Ports
  4.5.  Using HTTP Methods
    4.5.1.  GET
    4.5.2.  OPTIONS
  4.6.  Using HTTP Status Codes
    4.6.1.  Redirection
  4.7.  Specifying HTTP Header Fields
  4.8.  Defining Message Content
  4.9.  Leveraging HTTP Caching
    4.9.1.  Freshness
    4.9.2.  Stale Responses
    4.9.3.  Caching and Application Semantics
    4.9.4.  Varying Content Based Upon the Request
  4.10. Handling Application State
  4.11. Making Multiple Requests
  4.12. Client Authentication
  4.13. Coexisting with Web Browsing
  4.14. Maintaining Application Boundaries
  4.15. Using Server Push
  4.16. Allowing Versioning and Evolution
5.  IANA Considerations
6.  Security Considerations
  6.1.  Privacy Considerations
7.  References
  7.1.  Normative References
  7.2.  Informative References
Appendix A.  Changes from RFC 3205
Author's Address

1. Introduction 🌷

apps that aren't web browsing use HTTP [HTTP] as a substrate all the time. people call it "HTTP-based APIs", "REST APIs", or just "HTTP APIs" 💅 and folks do it for a bunch of reasons, like:

everyone's already familiar with it (implementers, specifiers, admins, devs, users 🫶)
there's a ton of client, server, and proxy implementations out there
it's easy to use
web browsers already exist
you get to reuse stuff like authentication and encryption
HTTP servers and clients are already in the target deployments
it can get through firewalls ✨

these protocols are usually ad hoc, made for just one or a few servers and a small set of clients. so a whole pile of practices and tools has grown up around defining HTTP-based APIs that work well for those conditions 🧸

BUT, when an app has multiple separate implementations, runs on lots of uncoordinated servers, and gets used by all kinds of clients (which is super common for APIs from standards efforts), those small-deployment tools and practices can stop working 😭

the big reason is that clients and servers implement and evolve at different speeds. so deployments with different features and versions need to coexist. that means designers of HTTP-based APIs for that kind of deployment need to think harder about how the service gets extended and how different deployment needs get handled 🦋

more generally, an app protocol using HTTP has to make a bunch of design decisions, like:

should it define a new URI scheme? use new ports?
should it use standard HTTP methods and status codes, or define new ones?
how do you get the most out of using HTTP?
how does it coexist with other uses of HTTP, especially web browsing?
how do you avoid interoperability problems and "protocol dead ends"? 💀

Section 2 defines when this document applies, Section 3 covers the HTTP properties that are important to keep, and Section 4 has best practices for specifying apps that use HTTP 🎀

it's written mainly to guide IETF efforts to define app protocols using HTTP for Internet deployment, but it might be useful in other situations too. just note that the requirements here don't necessarily apply to developing generic HTTP extensions 🙈

this document obsoletes [RFC3205] to reflect the experience and developments regarding HTTP since then 💜

1.1. Notational Conventions 🔤

the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 🧠

2. Is HTTP Being Used? 🤔

different apps have different goals when they use HTTP. the recommendations in this doc apply when a spec defines an app that:

uses the transport port 80 or 443, or
uses the URI scheme http or https, or
uses an ALPN protocol ID [RFC7301] that generically identifies HTTP (e.g., "http/1.1", "h2", "h3"), or
makes registrations in or overall modifications to the IANA registries defined for HTTP 📋

also, when a spec is using HTTP, all the requirements of the HTTP protocol suite are in force (that's [HTTP] especially, but also other specs like the specific HTTP version in use and any extensions in use) 🫶

note that this doc is meant for apps, not generic extensions to HTTP. and while it's meant for IETF-specified apps, other standards orgs are encouraged to follow its requirements too 🌈

2.1. Non-HTTP Protocols 🙅‍♀️

an app can rely on HTTP without meeting the criteria above. for example, an app might want to avoid re-specifying parts of the message format but change other parts of how the protocol works, or it might want to use app-specific methods 🧩

doing this gives you more freedom to change protocol operations, BUT at least some of the benefits from Section 3 get lost, since most HTTP implementations won't be easy to adapt to those changes. you also lose the benefit of mindshare 😭

Such specifications MUST NOT use HTTP's URI schemes, transport ports,
ALPN protocol IDs, or IANA registries; rather, they are encouraged to
establish their own.

3. What's Important About HTTP 💎

this section looks at the HTTP characteristics that matter when you use HTTP to define an app protocol 🔍

3.1. Generic Semantics 🧁

so much of HTTP's value is in its generic semantics. the protocol elements HTTP defines could potentially apply to every resource, and they aren't tied to any one context ✨ app-specific semantics are best expressed in message content and header fields, NOT in status codes or methods (even though status codes and methods do have generic semantics that relate to app state, so they're not totally off limits 🙃)

this split between generic and app-specific semantics means common software (HTTP servers, intermediaries, client implementations, caches) can handle an HTTP message without understanding the app in use 🙌 it also means people can use what they already know about HTTP without needing special knowledge of one particular app 🧠

so, applications that use HTTP MUST NOT redefine, refine, or overlay the semantics of generic protocol elements like methods, status codes, or existing header fields. instead, they should focus their specs on the protocol elements that are specific to that app, which are their HTTP resources 🎯

ok real talk, when you're writing a spec it's super tempting to nail down exactly how HTTP has to be implemented, supported, and used. but that can easily lead to an unintended profile of HTTP behaviour 😬 for example, it's really common to see specs with language like this:

A POST request MUST result in a 201 (Created) response.

this sets up an expectation in the client that the response will always be 201 (Created). but in real deployments the status code can differ for lots of reasons. for example, a proxy might require authentication, there could be a server-side error, or there could be a redirection. if the client doesn't expect that, the app's deployment gets brittle 💀

see Section 4.2 for more details 🫶

3.2. Links ✨

Okay, next up: links 🦋 Another super common move is treating the HTTP server's whole namespace (or a chunk of it) like it's one app's exclusive playground. That slaps app-specific semantics onto that space and locks every other application out. 🙈

As [BCP190] explains, "squatting" on part of the URL space like this usurps the server's authority over its own resources, can cause deployment issues, and is therefore bad practice in standards. Not it 💀

Instead of hardcoding URI components like paths, it is RECOMMENDED that applications using HTTP define and use links [WEB-LINKING] to allow flexibility in deployment. 💖

Runtime links come with a bunch of other perks, especially when an application is going to have multiple implementations and/or deployments (which is super common for standardised ones) 🌈

For example, navigating with a link lets a request get routed to a different server without the overhead of a redirection, so deployment across machines just works so much better 🧚

Links also make it possible to "mix and match" different applications on the same server. They're a natural mechanism for extensibility, versioning, and capability management too, because the document containing the links can also contain information about their targets 👑

Links also give you a form of cache invalidation that's seen all over the Web. When a resource's state changes, the application can change the affected links so a fresh copy is always fetched 💅

See Section 4.4 for more details. 🫶

3.3. Rich Functionality 🎀

HTTP hands applications a whole buffet of features, such as:

Message framing
Multiplexing (in HTTP/2 [HTTP/2] and HTTP/3 [HTTP/3])
Integration with TLS
Support for intermediaries (proxies, gateways, content delivery networks (CDNs))
Client authentication
Content negotiation for format, language, and other features
Caching for server scalability, latency and bandwidth reduction, and reliability
Granularity of access control (through use of a rich space of URLs)
Partial content to selectively request part of a response
The ability to interact with the application easily using a Web browser

An application that uses HTTP is encouraged to use the various features the protocol offers, so its users get the maximum benefit and the application can be deployed in a variety of situations 🌸 This document does not require specific features to be used, since the right design trade-offs are highly specific to a given situation. However, following the practices in Section 4 is a good starting point 🍓

4. Best Practices for Specifying the Use of HTTP ✨

This section is full of best practices for specifying how applications use HTTP, including practices for specific HTTP protocol elements 📚

4.1. Specifying the Use of HTTP 💜

Specifications should use [HTTP] as the primary reference for HTTP. It's not necessary to reference all of the specifications in the HTTP suite unless there are specific reasons to do so (e.g., a particular feature is called out) 🫶

Because HTTP is a hop-by-hop protocol, a connection can be handled by implementations that aren't controlled by the application. Think proxies, CDNs, firewalls, and so on 🦋 Requiring a particular version of HTTP makes it difficult to use in these situations and harms interoperability. Therefore, it is NOT RECOMMENDED that applications using HTTP specify a minimum version of HTTP to be used. 🙅‍♀️

However, if an application's deployment benefits from a particular version of HTTP (for example, HTTP/2's multiplexing), this ought be noted ✨

Applications using HTTP MUST NOT specify a maximum version, so the protocol can keep evolving. No cap, this one is serious 👑

When specifying examples of protocol interactions, applications should document both the request and response messages with complete header sections, preferably in HTTP/1.1 format [HTTP/1.1]. For example:

GET /thing HTTP/1.1
Host: example.com
Accept: application/things+json
User-Agent: Foo/1.0

HTTP/1.1 200 OK
Content-Type: application/things+json
Content-Length: 500
Server: Bar/2.2

[content here]

4.2. Specifying Server Behaviour 🌈

The server-side behaviours of an application are most effectively specified by defining the following protocol elements:

Media types [RFC6838], often based upon a format convention such as JSON [JSON];
HTTP header fields, per Section 4.7; and
The behaviour of resources, as identified by link relations [WEB-LINKING].

An application can define its operation by composing these protocol elements into a set of resources that are identified by link relations and that implement specified behaviours. That includes:

retrieval of resource state using GET in one or more formats identified by media type;
resource creation or update using POST or PUT, with an appropriately identified request content format;
data processing using POST and identified request and response content format(s); and
Resource deletion using DELETE.

For example, an application might specify:

|  Resources linked to with the "example-widget" link relation type
|  are Widgets.  The state of a Widget can be fetched in the
|  "application/example-widget+json" format, and can be updated by
|  PUT to the same link.  Widget resources can be deleted.
|
|  The Example-Count response header field on Widget representations
|  indicates how many Widgets are held by the sender.
|
|  The "application/example-widget+json" format is a JSON [RFC8259]
|  format representing the state of a Widget.  It contains links to
|  related information in the link indicated by the Link header field
|  value with the "example-other-info" link relation type.

Applications can also specify the use of URI Templates [URI-TEMPLATE] so clients can generate URLs based on runtime data 🧚

4.3. Specifying Client Behaviour 🎀

An application's expectations for client behaviour ought to be closely aligned with those of Web browsers, so things don't get weird when they're used together 💅

One way to do this is to define it in terms of [FETCH], since that's the abstraction browsers use for HTTP 🌸

Some client behaviours (e.g., automatic redirect handling) and extensions (e.g., cookies) aren't required by HTTP, but they've nevertheless become super common. If an application using HTTP doesn't explicitly specify their use, there may be confusion and interoperability problems. In particular:

Redirect handling: Applications need to specify how redirects are expected to be handled; see Section 4.6.1.
Cookies: Applications using HTTP should explicitly reference the Cookie specification [COOKIES] if they are required.
Certificates: Applications using HTTP should specify that TLS certificates are to be checked according to Section 4.3.4 of [HTTP] when HTTPS is used.

Applications using HTTP should not require that clients statically support HTTP features that are usually negotiated. For example, requiring that clients support responses with a certain content coding ([HTTP], Section 8.4.1) instead of negotiating for it ([HTTP], Section 12.5.3) means that otherwise conformant clients can't interoperate with the application 😭 Applications can encourage the implementation of such features, though 🫶

4.4. Specifying URLs 🦋

In HTTP, the resources clients interact with are identified with URLs [URL]. As [BCP190] explains, parts of the URL are designed to be under the control of the server's owner (also known as the "authority"), which gives them flexibility in deployment 🌈

This means that in most cases, specifications for applications using HTTP won't contain fixed application URLs or paths. It's common for a single-deployment API to specify a path prefix like "/app/v1" (for example), but doing so in an IETF specification is inappropriate 🙈

So the specification writer needs some mechanism that lets clients discover an application's URLs. They also need to specify which URL scheme(s) the application should be used with, and whether to use a dedicated port or reuse HTTP's port(s) 👑

4.4.1. Discovering an Application's URLs 💖

Generally, a client starts interacting with an application server by requesting an initial document that contains information about that particular deployment, potentially including links to other relevant resources. Doing this keeps the deployment as flexible as possible (potentially spanning multiple servers), allows evolution, and gives the application a chance to tailor the "discovery document" to the client ✨

There are a few common patterns for discovering that initial URL 🧚

The most straightforward mechanism is to configure the client with (or otherwise convey to it) a full URL. This might be done in a configuration document or through another discovery mechanism 🍓

However, if the client only knows the server's hostname and the identity of the application, there needs to be some way to derive the initial URL from that information 🫶

An application cannot define a fixed prefix for its URL paths; see [BCP190]. Instead, a specification for such an application can use one of the following strategies:

Register a well-known URI [WELL-KNOWN-URI] as an entry point for that application. This provides a fixed path on every potential server that won't collide with other applications.
Enable the server authority to convey a URI Template [URI-TEMPLATE] or similar mechanism for generating a URL for an entry point. For example, this might be done in a configuration document or other artefact.

Once the discovery document is located, it can be fetched, cached for later reuse (if allowed by its metadata), and used to locate other resources relevant to the application using full URIs or URL Templates 💅

In some cases, an application may not want to use a discovery document, like when communication is very brief or when the latency concerns of doing so rule it out. These situations can be addressed by placing all of the application's resources under a well-known location 🌈

4.4.2. Considering URI Schemes ✨

okay so apps that use HTTP usually go with the http and/or https URI schemes 💅. https is RECOMMENDED because it gives you authentication, integrity, and confidentiality, and it helps protect against pervasive monitoring attacks [RFC7258] 🔐.

BUT you can also define your own application-specific scheme 🦋. Just know there are a bunch of trade-offs and caveats when you do:

Unmodified Web browsers won't support your new scheme. You can register new URI schemes with browsers (e.g., registerProtocolHandler() in [HTML], plus a few proprietary options) 🛠️, but not every browser supports those mechanisms, and what they can do varies a lot 😭.
Existing non-browser clients, intermediaries, servers, and related software won't recognise the new scheme. Like, a client library might fail to dispatch the request, a cache might refuse to store the response, and a proxy might fail to forward the request 💀.
URLs show up all over HTTP artefacts and are often generated automatically (e.g., in the Location response header field) 🤖, so it can be hard to make sure your new scheme gets used consistently.
The resources behind your new scheme are still reachable with http and/or https URLs. Those URLs can "leak" into use, which can cause security and operability problems 🚨. For example, using a new scheme to make sure requests don't reach a "normal" Web site is likely to fail 🙈.
Features that rely on the URL's origin [RFC6454] get affected by a scheme change. The Web's same-origin policy is one of these 🧱.
HTTP-specific features might or might not work correctly. That includes cookies [COOKIES], authentication [HTTP], caching [HTTP-CACHING], HTTP Strict Transport Security (HSTS) [RFC6797], and Cross-Origin Resource Sharing (CORS) [FETCH]. It all depends on how they're defined and implemented 🤷‍♀️. Generally, they're designed and built assuming the URL will always be http or https 💜.
Web features that need a secure context [SECCTXT] will likely treat your new scheme as insecure 🙅‍♀️.

See [RFC7595] for more info about minting new URI schemes 🧚.

4.4.3. Choosing Transport Ports 🎀

Apps can use the applicable default port (80 for HTTP, 443 for HTTPS) 🍓, or they can be deployed on other ports. You can decide this at deployment time, or the application's specification might encourage a particular port (e.g., by registering a port for that application) 📝.

If you use a non-default port, it needs to show up in the authority of all URLs for that resource 🌸. The only way to change a default port is to change the URI scheme (see Section 4.4.2) ✨.

Using a port other than the default has privacy implications, because the protocol can now be told apart from other traffic 👀. It also has operability concerns, since some networks might block or otherwise mess with it 🚧. Privacy implications (including the ones that come from being distinguishable) should be documented in Security Considerations 🔒.

See [RFC7605] for further guidance 💖.

4.5. Using HTTP Methods 💌

Apps that use HTTP MUST confine themselves to registered HTTP methods such as GET, POST, PUT, DELETE, and PATCH 🧸.

New HTTP methods are rare 🦄. They're required to be registered in the "HTTP Method Registry" with IETF Review (see [HTTP]), and they're also required to be generic. That means they need to be potentially applicable to all resources, not just the ones belonging to one application 🌍.

Historically, some applications (e.g., [RFC4791]) defined their own application-specific methods, but [HTTP] now forbids this 🙅‍♀️.

If you think you need a new method, you're encouraged to engage with the HTTP community early (e.g., on the <mailto:ietf-http-wg@w3.org> mailing list) 📬. Document your proposal as a separate HTTP extension instead of as part of your application's specification 🫶.

4.5.1. GET 🍰

GET is the most common and useful HTTP method 👑. Its retrieval semantics allow caching and side-effect free linking, and they underlie a lot of the benefits of using HTTP ✨.

You can run queries with GET, often using the query component of the URL. It's a familiar pattern from Web browsing 🌐, and the results can be cached, which makes an often expensive process way more efficient 🚀. In some cases, though, GET might be unwieldy for expressing queries because of the limited syntax of the URI 😩. In particular, if binary data forms part of the query terms, it needs to be encoded so it conforms to the URI syntax 🔢.

This isn't an issue for short queries, but it can become one for larger query terms or for queries that need to sustain a high rate of requests 📈. Also, some HTTP implementations limit the size of URLs they support. Modern HTTP software has way more generous limits than it used to, though (typically, considerably more than 8000 octets, as required by [HTTP]) 💪.

In these cases, an application using HTTP might consider using POST to express queries in the request's content. Doing so avoids encoding overhead and URL length limits in implementations 🙌. But heads up: if you do that, the benefits of GET, like caching and linking to query results, are lost 💔. So applications using HTTP that need to support POST queries ought to consider allowing both methods 💅.

Processing of GET requests should not change the application's state or have other side effects that might be significant to the client, since implementations can and do retry HTTP GET requests that fail 🔁. Also, some GET requests protected by TLS early data might be vulnerable to replay attacks (see [RFC8470]) 🚨. Note that this does not include logging and similar functions; see [HTTP], Section 9.2.1 📝.

Finally, the generic HTTP syntax does allow a GET request message to contain content, but that's only so message parsers can stay generic 🧩. Per [HTTP], Section 9.3.1, content in a GET is not recommended, has no meaning, and will be either ignored or rejected by generic HTTP software (such as intermediaries, caches, servers, and client libraries) 🙅‍♀️.

4.5.2. OPTIONS 🎈

The OPTIONS method was defined for metadata retrieval. It's used by both Web Distributed Authoring and Versioning (WebDAV) [RFC4918] and CORS [FETCH] 🛎️. Because HTTP-based APIs often need to retrieve metadata about resources, people often consider OPTIONS for that 🤔.

BUT OPTIONS has some real limitations 😬:

You can't link to the metadata with a simple URL, because OPTIONS isn't the default method 🔗.
OPTIONS responses aren't cacheable, because HTTP caches operate on representations of the resource (i.e., GET and HEAD) 🗃️. If OPTIONS responses get cached separately, you'll need to think about how they interact with HTTP cache expiry, secondary keys, and other mechanisms 🧠.
OPTIONS is "chatty", because requesting metadata separately increases the number of requests needed to interact with the application 📞.
Implementation support for OPTIONS isn't universal. Some servers don't expose the ability to respond to OPTIONS requests without significant effort 😵.

So instead of OPTIONS, one of these alternatives might be a better fit 💖:

For server-wide metadata, create a well-known URI [WELL-KNOWN-URI], or use an already existing one if it's appropriate (e.g., host-meta [RFC6415]) 🌟.
For metadata about a specific resource, create a separate resource and link to it using a Link response header field, or a link serialised into the response's content. See [WEB-LINKING] 🧵. Note that the Link header field is available on HEAD responses, which is super useful if the client wants to discover a resource's capabilities before interacting with it 🕵️‍♀️.

4.6. Using HTTP Status Codes 🚦

HTTP status codes carry semantics for generic HTTP components (like caches, intermediaries, and clients) and for applications themselves 🎀. But apps can run into a bunch of pitfalls when using them 😭.

First, status codes are often generated by components other than the application itself 🎭. This can happen when network errors pop up, when a captive portal, proxy, or content delivery network is in the mix, or when a server is overloaded or thinks it's under attack 🛑. They can even be generated by generic client software when certain error conditions come up 🤖. So if an application gives one of these status codes specific semantics, a client can get misled about the application's state, because the code was actually generated by a generic component 🫠.

Also, mapping application errors one-to-one onto individual HTTP status codes often means the finite space of applicable status codes runs out 📉. That leads to some bad habits, like minting new application-specific status codes, or reusing existing ones even though the link between their semantics and the application's is tenuous at best 🙈.

Instead, applications using HTTP should define their errors to use the most applicable status code, leaning on the general status codes (200, 400, and 500) when they're not sure ✨. Importantly, they should not specify a one-to-one relationship between status codes and application errors, which avoids the exhaustion issue above 🧘‍♀️.

To tell apart multiple error conditions mapped to the same status code, and to avoid the misattribution issue above, applications using HTTP should convey finer-grained error information in the response's message content and/or header fields 🔍. [PROBLEM-DETAILS] gives one way to do that 🎁.

The set of registered HTTP status codes can expand, so applications using HTTP should explicitly point out that clients ought to handle all applicable status codes gracefully 🦋. That means falling back to the generic n00 semantics of a given status code; e.g., 499 can be safely handled as 400 (Bad Request) by clients that don't recognise it 🫶. This is way better than making a "laundry list" of potential status codes, since that list won't be complete in the foreseeable future 📜.

Applications using HTTP MUST NOT re-specify the semantics of HTTP status codes, even if it's only by copying their definition 🚫. It is NOT RECOMMENDED that they require specific reason phrases to be used. The reason phrase has no function in HTTP, isn't guaranteed to be preserved by implementations, and isn't carried at all in the HTTP/2 [HTTP/2] message format 💀.

Applications MUST only use registered HTTP status codes 📋. As with methods, new HTTP status codes are rare, and [HTTP] requires them to be registered with IETF Review 🗓️. Similarly, HTTP status codes are generic. [HTTP] requires them to be potentially applicable to all resources, not just to those of one application 🌈.

When authors believe a new status code is required, they're encouraged to engage with the HTTP community early (e.g., on the <mailto:ietf-http-wg@w3.org> mailing list) 💌. Document the proposal as a separate HTTP extension, rather than as part of an application's specification 🥹.

4.6.1. Redirection

Okay bestie, redirects are giving "the thing you want lives over there now" 🦋. The 3xx series of status codes specified in Section 15.4 of [HTTP] directs the user agent to another resource to satisfy the request. The most common ones are 301, 302, 307, and 308, and they all use the Location response header field to show where the client should resend the request 💌.

There are two ways this group of status codes differs 👀:

Permanent vs. temporary. Permanent redirects can be used to update links stored in the client (e.g., bookmarks), whereas temporary ones cannot. Note that this has no effect on HTTP caching; it is completely separate 🔖.
Whether they let the redirected request change the request method from POST to GET. Web browsers generally do change POST to GET for 301 and 302, so 308 and 307 were created to allow redirection without changing the method 🙅‍♀️.

Here's the summary table, because we love a visual 💅:

         +==============================+===========+===========+
         |                              | Permanent | Temporary |
         +==============================+===========+===========+
         | Allows change of the request | 301       | 302       |
         | method from POST to GET      |           |           |
         +------------------------------+-----------+-----------+
         | Does not allow change of the | 308       | 307       |
         | request method               |           |           |
         +------------------------------+-----------+-----------+

                                 Table 1

The 303 (See Other) status code can be used to tell the client that the result of an operation is available at a different location, using GET 🧚.

As noted in [HTTP], a user agent is allowed to automatically follow a 3xx redirect that has a Location response header field, even if it doesn't understand the semantics of the specific status code. However, it isn't required to do so, so if an application using HTTP wants redirects to be automatically followed, it needs to explicitly specify the circumstances where that's required 🤓.

Redirects can be cached (when the right cache directives are present), but beyond that they are not "sticky" 🙅‍♀️. In other words, redirecting one URI will not make the client assume that similar URIs (e.g., with different query parameters) will also be redirected ✨.

Applications using HTTP are encouraged to specify that 301 and 302 responses change the subsequent request method from POST (but no other method) to GET, so they play nice with browsers 🌈. Generally, when a redirected request is made, its header fields are copied from the original request. However, they can be modified by various mechanisms; e.g., the sent Authorization ([HTTP], Section 11) and Cookie ([COOKIES]) header fields will change if the origin (and sometimes the path) of the request changes 🍓. An application using HTTP should specify if any request header fields it defines need to be modified or removed upon a redirect. However, this behaviour cannot be relied upon, since a generic client (like a browser) will be unaware of such requirements 😭.

4.7. Specifying HTTP Header Fields

Applications often define new HTTP header fields 🎀. Typically, using HTTP header fields is appropriate in a few different situations:

The field is useful to intermediaries (who often wish to avoid parsing message content), and/or
The field is useful to generic HTTP software (e.g., clients, servers), and/or
It is not possible to include their values in the message content (usually because a format does not allow it).

When the conditions above are not met, it's usually better to convey application-specific information in other places -- e.g., the message content or the URL query string 🫶.

New header fields MUST be registered, per Section 16.3 of [HTTP] 📝.

See Section 16.3.2 of [HTTP] for guidelines to consider when minting new header fields 💖. [STRUCTURED-FIELDS] provides a common structure for new header fields and avoids many issues in their parsing and handling, so it is RECOMMENDED that new header fields use it 🙌.

It is RECOMMENDED that header field names be short (even when field compression is used, there is an overhead) but appropriately specific ✨. In particular, if a header field is specific to an application, an identifier for that application can form a prefix to the header field name, separated by a hyphen 🦋.

For example, if the "example" application needs to create three header fields, they might be called "example-foo", "example-bar", and "example-baz" 🧚. The main motivation here is to avoid consuming more generic field names, not to reserve a portion of the namespace for the application. See [RFC6648] for related considerations 📚.

The semantics of existing HTTP header fields MUST NOT be redefined without updating their registration or defining an extension to them (if allowed) 🚫. For example, an application using HTTP cannot specify that the Location header field has a special meaning in a certain context 💀.

See Section 4.9 for the interaction between header fields and HTTP caching. In particular, request header fields that are used to choose (per Section 4.1 of [HTTP-CACHING]) a response have an impact there and need to be carefully considered 🔥.

See Section 4.10 for considerations regarding header fields that carry application state (e.g., Cookie) 🍪.

4.8. Defining Message Content

Common syntactic conventions for message content include JSON [JSON], XML [XML], and Concise Binary Object Representation (CBOR) [RFC8949] 📦. Best practices for their use are out of scope for this document 🙈.

Applications should register distinct media types for each format they define. This makes it possible to identify them unambiguously and negotiate for their use. See [RFC6838] for more information 🏷️.

4.9. Leveraging HTTP Caching

HTTP caching [HTTP-CACHING] is one of the primary benefits of using HTTP for applications 👑. It provides scalability, reduces latency, and improves reliability. Plus, HTTP caches are readily available in browsers and other clients, in networks as forward and reverse proxies, in content delivery networks, and as part of server software 🌸.

Even when an application using HTTP isn't designed to take advantage of caching, it needs to consider how caches will handle its responses to preserve correct behaviour when one is interposed (whether in the network, server, client, or intervening infrastructure) 🕵️‍♀️.

4.9.1. Freshness

Assigning even a short freshness lifetime ([HTTP-CACHING], Section 4.2) -- e.g., 5 seconds -- allows a response to be reused to satisfy multiple clients and/or a single client making the same request repeatedly 🔁. In general, if it is safe to reuse something, consider assigning a freshness lifetime ⏱️.

The most common method for specifying freshness is the max-age response directive ([HTTP-CACHING], Section 5.2.2.1). The Expires header field ([HTTP-CACHING], Section 5.3) can also be used, but it is not necessary. All modern cache implementations support the Cache-Control header field, and specifying freshness as a delta is usually more convenient and less error-prone 💅.

It is not necessary to add the public response directive ([HTTP-CACHING], Section 5.2.2.9) to cache most responses. It's only necessary when it's desirable to store an authenticated response, or when the status code isn't understood by the cache and there isn't explicit freshness information available 🔐.

In some situations, responses without explicit cache freshness directives will be stored and served using a heuristic freshness lifetime; see [HTTP-CACHING], Section 4.2.2 🤷‍♀️. As the heuristic is not under the control of the application, it is generally preferable to set an explicit freshness lifetime or make the response explicitly uncacheable 🧊.

If caching of a response is not desired, the appropriate cache response directive is no-store. Other directives are not necessary, and no-store only needs to be sent in situations where the response might be cached; see [HTTP-CACHING], Section 3 🚫. Note that the no-cache directive allows a response to be stored, just not reused by a cache without validation. It does not prevent caching (despite its name) 😭.

For example, this response cannot be stored or reused by a cache:

HTTP/1.1 200 OK
Content-Type: application/example+xml
Cache-Control: no-store

[content]

4.9.2. Stale Responses

Authors should understand that stale responses (e.g., with Cache-Control: max-age=0) can be reused by caches when disconnected from the origin server. This can be useful for handling network issues 📡.

If doing so is not suitable for a given response, the origin should send the must-revalidate cache directive. See Section 4.2.4 of [HTTP-CACHING] and also [RFC5861] for additional controls over stale content 🎛️.

Stale responses can be refreshed by assigning a validator, saving both transfer bandwidth and latency for large responses; see Section 13 of [HTTP] 💸.

4.9.3. Caching and Application Semantics

When an application needs to express a lifetime that's separate from the freshness lifetime, this should be conveyed separately, either in the response's content or in a separate header field. When this happens, the relationship between HTTP caching and that lifetime needs to be carefully considered, since the response will be used as long as it is considered fresh 🧠.

In particular, application authors need to consider how responses that are not freshly obtained from the origin server should be handled. If they have a concept like a validity period, this will need to be calculated considering the age of the response (see [HTTP-CACHING], Section 4.2.3) ⏳.

One way to address this is to explicitly specify that responses need to be fresh upon use ✅.

4.9.4. Varying Content Based Upon the Request

If an application uses a request header field to change the response's header fields or content, authors should point out that this has implications for caching. In general, such resources need to either make their responses uncacheable (e.g., with the no-store cache directive defined in [HTTP-CACHING], Section 5.2.2.5) or send the Vary response header field ([HTTP], Section 12.5.5) on all responses from that resource (including the "default" response) 🧁.

For example, this response:

HTTP/1.1 200 OK
Content-Type: application/example+xml
Cache-Control: max-age=60
ETag: "sa0f8wf20fs0f"
Vary: Accept-Encoding

[content]

can be stored for 60 seconds by both private and shared caches, can be revalidated with If-None-Match, and varies on the Accept-Encoding request header field 🥰.

4.10. Handling Application State

Applications can use stateful cookies [COOKIES] to identify a client and/or store client-specific data to contextualise requests 🍪.

When used, it is important to carefully specify the scoping and use of cookies. If the application exposes sensitive data or capabilities (e.g., by acting as an ambient authority), exploits are possible 🚨. Mitigations include using a request-specific token to ensure the intent of the client 🛡️.

4.11. Making Multiple Requests 💌

Okay so clients often need to send multiple requests to get one task done 🙈

In HTTP/1 [HTTP/1.1], parallel requests are mostly handled by opening multiple connections. ngl that can hurt performance when too many connections are running at once, because their congestion control isn't coordinated 💀 It also gets hard for apps to decide when to send a request and which connection to use for it, which hurts performance even more.

HTTP/2 [HTTP/2] and HTTP/3 [HTTP/3] give apps multiplexing, so you don't need multiple connections anymore ✨ Still, performance can get seriously affected by how the server chooses to prioritize responses 😤 Depending on the app, it might be best for the server to decide priority, or for the client to hint its priorities to the server (see, e.g., [HTTP-PRIORITY]).

In all versions of HTTP, requests are made independently. You can't rely on the relative order of two requests to guarantee their processing order 😭 That's because they might be sent over a multiplexed protocol by an intermediary, or sent to different origin servers, or the server might even process things in a different order. If two requests need strict ordering, the only reliable way to make sure of the outcome is to issue the second request when the final response to the first has begun.

Applications MUST NOT make assumptions about the relationship between separate requests on a single transport connection. Doing so breaks many of the assumptions of HTTP as a stateless protocol, and it will cause problems in interoperability, security, operability, and evolution 🚫

4.12. Client Authentication 🪪

Applications can use HTTP authentication (Section 11 of [HTTP]) to identify clients. Per [RFC7617], the Basic authentication scheme isn't suitable for protecting sensitive or valuable information unless the channel is secure (e.g., using the "https" URI scheme). Likewise, [RFC7616] requires the Digest authentication scheme to be used over a secure channel 🔐

With HTTPS, clients might also be authenticated using certificates [RFC8446], but heads up: that authentication is intrinsically scoped to the underlying transport connection 👀 So a client has no way of knowing whether the authenticated status was used in preparing the response (though Vary: * and/or the private cache directive can give a partial indication). The only way to get a specifically unauthenticated response is to open a new connection.

When authentication is used, it's important to carefully specify its scoping and use. If the application exposes sensitive data or capabilities (e.g., by acting as an ambient authority; see Section 8.3 of [RFC6454]), exploits are possible 💀 Mitigations include using a request-specific token to make sure the intent of the client is clear 🛡️

4.13. Coexisting with Web Browsing 🌐

Even if an application isn't meant to be used with a Web browser, its resources will still be available to browsers and other HTTP clients. So every application that uses HTTP needs to think about how browsers will interact with it, especially when it comes to security 👩‍💻

For example, if an application's state can be changed using a POST request, a Web browser can easily be coaxed into cross-site request forgery (CSRF) from arbitrary Web sites 😱

Or, if an attacker gains control of content returned from the application's resources (for example, part of the request is reflected in the response, or the response contains external information the attacker can change), they can inject code into the browser and access data and capabilities as if they were the origin. This is a technique known as a cross-site scripting (XSS) attack 🕷️

This is only a small sample of the issues applications using HTTP have to consider. Generally, the best approach is to actually treat the application as a Web application, and to follow best practices for its secure development 🎀

A complete list of those practices is out of scope for this document, but some considerations include:

Using an application-specific media type in the Content-Type header field, and requiring clients to fail if it isn't used.
Using X-Content-Type-Options: nosniff [FETCH] to make sure content under attacker control can't be coaxed into a form that a Web browser interprets as active content.
Using Content-Security-Policy [CSP] to constrain the capabilities of active content (i.e., content that can execute scripts, such as HTML [HTML] and PDF), which helps mitigate XSS attacks.
Using Referrer-Policy [REFERRER-POLICY] to prevent sensitive data in URLs from being leaked in the Referer request header field.
Using the 'HttpOnly' flag on Cookies so cookies aren't exposed to browser scripting languages [COOKIES].
Avoiding compression on any sensitive information (e.g., authentication tokens, passwords). The scripting environment offered by Web browsers lets an attacker repeatedly probe the compression space, and if the attacker has access to the network path of the communication, they can use that capability to recover the information 🙀

Depending on how they're meant to be deployed, specifications for applications using HTTP might require these mechanisms to be used in specific ways, or might simply point them out in Security Considerations 📝

Here's an example of an HTTP response from an application that doesn't intend for its content to be treated as active by browsers:

HTTP/1.1 200 OK
Content-Type: application/example+json
X-Content-Type-Options: nosniff
Content-Security-Policy: default-src 'none'
Cache-Control: max-age=3600
Referrer-Policy: no-referrer

[content]

If an application has browser compatibility as a goal, client interaction ought to be defined in terms of [FETCH], since that's the abstraction browsers use for HTTP. It enforces many of these best practices ✨

4.14. Maintaining Application Boundaries 🧱

Many HTTP capabilities are scoped to the origin [RFC6454], so applications also need to think about how their deployments might interact with other applications (including Web browsing) that use the same origin server 🏠

For example, if cookies [COOKIES] are used to carry application state, they'll be sent with all requests to the origin by default (unless scoped by path). The application might also receive cookies from other applications on the origin server. This can lead to security issues, as well as collisions in cookie names 😬

One solution is to require a dedicated hostname for the application so it has a unique origin. However, it's often desirable to let multiple applications be deployed on a single hostname, since that provides the most deployment flexibility and lets them be "mixed" together (see [BCP190] for details) 🍹

So, applications using HTTP should strive to allow multiple applications on an origin. Specifically, when specifying the use of cookies, HTTP authentication realms [HTTP], or other origin-wide HTTP mechanisms, applications using HTTP should not mandate the use of a particular name, and should instead let deployments configure them. Consideration should be given to scoping them to part of the origin, using their specified mechanisms for doing so 🧩

Modern Web browsers limit the ability of content from one origin to access resources from another, to avoid leaking private information. So applications that want to expose cross-origin data to browsers will need to implement the CORS protocol; see [FETCH] 🔒

4.15. Using Server Push 📨

HTTP/2 added the ability for servers to "push" request/response pairs to clients in [HTTP/2], Section 8.4. Server push seems like a natural fit for many common application semantics (e.g., "fanout" and publish/subscribe), but a few caveats should be noted 👇

Server push is hop by hop. That is, it isn't automatically forwarded by intermediaries. As a result, it might not work easily (or at all) with proxies, reverse proxies, and content delivery networks.
Server push can have a negative performance impact on HTTP when used incorrectly, particularly if there's contention with resources that the client has actually requested 📉
Server push is implemented differently in different clients, especially when it comes to interaction with HTTP caching, and capabilities might vary 🤷‍♀️
APIs for server push are currently unavailable in some implementations and vary widely in others. In particular, there is no current browser API for it.
Server push isn't supported in HTTP/1.1 or HTTP/1.0.
Server push doesn't form part of the "core" semantics of HTTP, and therefore might not be supported by future versions of the protocol.

Applications that want to optimize cases where the client can do work related to requests before the full response is available (e.g., fetching links for things likely to be contained within) might benefit from using the 103 (Early Hints) status code; see [RFC8297] 🚀

Applications using server push directly need to enforce the requirements regarding authority in [HTTP/2], Section 8.4, to avoid cross-origin push attacks 🛑

4.16. Allowing Versioning and Evolution 🦋

It's often necessary to introduce new features into application protocols and to change existing ones 🌱

In HTTP, backwards-incompatible changes can be made using mechanisms such as:

Using a distinct link relation type [WEB-LINKING] to identify a URL for a resource that implements the new functionality.
Using a distinct media type [RFC6838] to identify formats that enable the new functionality.
Using a distinct HTTP header field to implement new functionality outside the message content.

5. IANA Considerations 🌈

This document has no IANA actions.

6. Security Considerations 🔒✨

okay bestie, listen up because this part is SERIOUS 💀. Apps running on HTTP inherit all the security stuff from HTTP itself plus any extensions they use. [HTTP], [HTTP-CACHING], and [WEB-LINKING] are usually relevant, among others 🫶.

Section 4.4.2 recommends supporting https URLs and discourages using http URLs to get authentication, integrity, and confidentiality, and to dodge pervasive monitoring attacks 🛡️. Lots of HTTP apps do auth with bearer tokens (like in session cookies 🍪). If the transport is unencrypted, someone who can eavesdrop on or mess with the traffic can often level up their privileges and do stuff to resources they shouldn't touch 😭. Not okay!!

Section 4.9.3 points out the chance of a mismatch between HTTP caching and app-specific storage of responses or the info inside them 🗂️. Section 4.10 covers how stateful mechanisms in the protocol act as ambient authority, and it suggests a fix 🔐. Section 4.13 talks about what Web browsers can do and how that affects apps that use HTTP 🌐. Section 4.14 covers the issues when apps are deployed on the same origin as websites (and other apps) 🏠. And Section 4.15 flags the risks of using HTTP/2 server push in a way other than what's specified 🚩.

Also, if an app changes implementations, like needing support for a new URI scheme or a non-standard method, those implementations can "fork" from their parent HTTP implementations 🍴. The result? They might miss out on patches and other security improvements that land upstream. Main character energy for the wrong reasons 💀.

6.1. Privacy Considerations 🕵️‍♀️💜

HTTP clients can expose all kinds of info to servers 👀. There's stuff that's sent on purpose as part of an app's operation (like names and other user-entered data) and stuff that's "on the wire" (one of the reasons https is recommended in Section 4.4.2 🔒). Then there's info gathered through sneakier routes, usually by connecting a user's activities across time ⏳. Lowkey creepy 😭.

This includes session information, tracking the client through fingerprinting, and code execution 🧩.

Session information covers things like the client's IP address, TLS session tickets, Cookies, ETags stored in the client's cache, and other stateful mechanisms 🍪. Apps are advised to avoid session mechanisms unless they're unavoidable or necessary for operation. If they do use them, those risks need to be documented 📝. When they're used, implementations should be encouraged to allow clearing that state 🧹.

Fingerprinting uses the unique bits of a client's messages and behaviours to connect separate requests and connections 🧬. For example, the User-Agent request header field tells you specific info about the implementation, and the Accept-Language request header field tells you the user's preferred language 🌍. Put enough of these markers together and you can uniquely identify a client, which messes with its control over its own data 😤. So apps are advised to specify that clients should only send the info they need to function in requests ✨.

Last but not least, if an app lets code run, be VERY careful 🚨. Any ability to observe the environment can be used to fingerprint the client and to get at and manipulate private data (including session info) 💅. For example, access to high-resolution timers, even indirectly, can be used to profile the underlying hardware, which creates a unique identifier for the system ⏱️. Apps are advised to avoid mobile code where possible. When it can't be avoided, the resulting system's security properties need be carefully scrutinised 🔍. No cap, this is where the drama lives 🎭.

7. References 📚

7.1. Normative References 💖

[BCP190]   Nottingham, M., "URI Design and Ownership", BCP 190,
           RFC 8820, DOI 10.17487/RFC8820, June 2020,
           <https://www.rfc-editor.org/rfc/rfc8820>.

[HTTP]     Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
           Ed., "HTTP Semantics", STD 97, RFC 9110,
           DOI 10.17487/RFC9110, June 2022,
           <https://www.rfc-editor.org/info/rfc9110>.

[HTTP-CACHING]
           Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
           Ed., "HTTP Caching", STD 98, RFC 9111,
           DOI 10.17487/RFC9111, June 2022,
           <https://www.rfc-editor.org/info/rfc9111>.

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

[RFC6454]  Barth, A., "The Web Origin Concept", RFC 6454,
           DOI 10.17487/RFC6454, December 2011,
           <https://www.rfc-editor.org/info/rfc6454>.

[RFC6648]  Saint-Andre, P., Crocker, D., and M. Nottingham,
           "Deprecating the "X-" Prefix and Similar Constructs in
           Application Protocols", BCP 178, RFC 6648,
           DOI 10.17487/RFC6648, June 2012,
           <https://www.rfc-editor.org/info/rfc6648>.

[RFC6838]  Freed, N., Klensin, J., and T. Hansen, "Media Type
           Specifications and Registration Procedures", BCP 13,
           RFC 6838, DOI 10.17487/RFC6838, January 2013,
           <https://www.rfc-editor.org/info/rfc6838>.

[RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
           2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
           May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[STRUCTURED-FIELDS]
           Nottingham, M. and P-H. Kamp, "Structured Field Values for
           HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021,
           <https://www.rfc-editor.org/info/rfc8941>.

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

[WEB-LINKING]
           Nottingham, M., "Web Linking", RFC 8288,
           DOI 10.17487/RFC8288, October 2017,
           <https://www.rfc-editor.org/info/rfc8288>.

[WELL-KNOWN-URI]
           Nottingham, M., "Well-Known Uniform Resource Identifiers
           (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019,
           <https://www.rfc-editor.org/info/rfc8615>.

7.2. Informative References 🎀

Okay bestie, here's the reading list for the extra-credit stuff. These are the docs the spec leans on for background, and I'm keeping every entry exactly as written so nothing gets lost 💅

7.2.  Informative References

   [COOKIES]  Barth, A., "HTTP State Management Mechanism", RFC 6265,
              DOI 10.17487/RFC6265, April 2011,
              <https://www.rfc-editor.org/info/rfc6265>.

   [CSP]      West, M., "Content Security Policy Level 3", W3C Working
              Draft, June 2021,
              <https://www.w3.org/TR/2021/WD-CSP3-20210629>.

   [FETCH]    WHATWG, "Fetch - Living Standard",
              <https://fetch.spec.whatwg.org>.

   [HTML]     WHATWG, "HTML - Living Standard",
              <https://html.spec.whatwg.org>.

   [HTTP-PRIORITY]
              奥 一穂 (Oku, K.) and L. Pardue, "Extensible Prioritization
              Scheme for HTTP", RFC 9218, DOI 10.17487/RFC9218, June
              2022, <https://www.rfc-editor.org/info/rfc9218>.

   [HTTP/1.1] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
              Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112,
              June 2022, <https://www.rfc-editor.org/info/rfc9112>.

   [HTTP/2]   Thomson, M., Ed. and C. Benfield, Ed., "HTTP/2", RFC 9113,
              DOI 10.17487/RFC9113, June 2022,
              <https://www.rfc-editor.org/info/rfc9113>.

   [HTTP/3]   Bishop, M., Ed., "HTTP/3", RFC 9114, DOI 10.17487/RFC9114,
              June 2022, <https://www.rfc-editor.org/info/rfc9114>.

   [JSON]     Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", STD 90, RFC 8259,
              DOI 10.17487/RFC8259, December 2017,
              <https://www.rfc-editor.org/info/rfc8259>.

   [PROBLEM-DETAILS]
              Nottingham, M. and E. Wilde, "Problem Details for HTTP
              APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016,
              <https://www.rfc-editor.org/info/rfc7807>.

   [REFERRER-POLICY]
              Eisinger, J. and E. Stark, "Referrer Policy", W3C
              Candidate Recommendation CR-referrer-policy-20170126,
              January 2017,
              <https://www.w3.org/TR/2017/CR-referrer-policy-20170126>.

   [RFC3205]  Moore, K., "On the use of HTTP as a Substrate", BCP 56,
              RFC 3205, DOI 10.17487/RFC3205, February 2002,
              <https://www.rfc-editor.org/info/rfc3205>.

   [RFC4791]  Daboo, C., Desruisseaux, B., and L. Dusseault,
              "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
              DOI 10.17487/RFC4791, March 2007,
              <https://www.rfc-editor.org/info/rfc4791>.

   [RFC4918]  Dusseault, L., Ed., "HTTP Extensions for Web Distributed
              Authoring and Versioning (WebDAV)", RFC 4918,
              DOI 10.17487/RFC4918, June 2007,
              <https://www.rfc-editor.org/info/rfc4918>.

   [RFC5861]  Nottingham, M., "HTTP Cache-Control Extensions for Stale
              Content", RFC 5861, DOI 10.17487/RFC5861, May 2010,
              <https://www.rfc-editor.org/info/rfc5861>.

   [RFC6415]  Hammer-Lahav, E., Ed. and B. Cook, "Web Host Metadata",
              RFC 6415, DOI 10.17487/RFC6415, October 2011,
              <https://www.rfc-editor.org/info/rfc6415>.

   [RFC6797]  Hodges, J., Jackson, C., and A. Barth, "HTTP Strict
              Transport Security (HSTS)", RFC 6797,
              DOI 10.17487/RFC6797, November 2012,
              <https://www.rfc-editor.org/info/rfc6797>.

   [RFC7258]  Farrell, S. and H. Tschofenig, "Pervasive Monitoring Is an
              Attack", BCP 188, RFC 7258, DOI 10.17487/RFC7258, May
              2014, <https://www.rfc-editor.org/info/rfc7258>.

   [RFC7301]  Friedl, S., Popov, A., Langley, A., and E. Stephan,
              "Transport Layer Security (TLS) Application-Layer Protocol
              Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301,
              July 2014, <https://www.rfc-editor.org/info/rfc7301>.

   [RFC7595]  Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines
              and Registration Procedures for URI Schemes", BCP 35,
              RFC 7595, DOI 10.17487/RFC7595, June 2015,
              <https://www.rfc-editor.org/info/rfc7595>.

   [RFC7605]  Touch, J., "Recommendations on Using Assigned Transport
              Port Numbers", BCP 165, RFC 7605, DOI 10.17487/RFC7605,
              August 2015, <https://www.rfc-editor.org/info/rfc7605>.

   [RFC7616]  Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP
              Digest Access Authentication", RFC 7616,
              DOI 10.17487/RFC7616, September 2015,
              <https://www.rfc-editor.org/info/rfc7616>.

   [RFC7617]  Reschke, J., "The 'Basic' HTTP Authentication Scheme",
              RFC 7617, DOI 10.17487/RFC7617, September 2015,
              <https://www.rfc-editor.org/info/rfc7617>.

   [RFC8297]  Oku, K., "An HTTP Status Code for Indicating Hints",
              RFC 8297, DOI 10.17487/RFC8297, December 2017,
              <https://www.rfc-editor.org/info/rfc8297>.

   [RFC8446]  Rescorla, E., "The Transport Layer Security (TLS) Protocol
              Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
              <https://www.rfc-editor.org/info/rfc8446>.

   [RFC8470]  Thomson, M., Nottingham, M., and W. Tarreau, "Using Early
              Data in HTTP", RFC 8470, DOI 10.17487/RFC8470, September
              2018, <https://www.rfc-editor.org/info/rfc8470>.

   [RFC8949]  Bormann, C. and P. Hoffman, "Concise Binary Object
              Representation (CBOR)", STD 94, RFC 8949,
              DOI 10.17487/RFC8949, December 2020,
              <https://www.rfc-editor.org/info/rfc8949>.

   [SECCTXT]  West, M., "Secure Contexts", W3C Candidate Recommendation,
              September 2021,
              <https://www.w3.org/TR/2021/CRD-secure-contexts-20210918>.

   [URI-TEMPLATE]
              Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
              and D. Orchard, "URI Template", RFC 6570,
              DOI 10.17487/RFC6570, March 2012,
              <https://www.rfc-editor.org/info/rfc6570>.

   [XML]      Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and
              F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth
              Edition)", W3C Recommendation REC-xml-20081126, November
              2008, <https://www.w3.org/TR/2008/REC-xml-20081126>.

Appendix A. Changes from RFC 3205 🦋

Okay so, [RFC3205] was the Best Current Practice from the early 2000s, and it was written around the worries protocol designers had back then. HTTP has had a massive glow-up since, like, a lot has changed 💅 That means this document is substantially different from it. The changes are way too numerous to list one by one, so just know it's a whole new era 🌸

Author's Address 🧚

   Mark Nottingham
   Prahran
   Australia
   Email: mnot@mnot.net
   URI:   https://www.mnot.net/

That's the whole doc, bestie! 💖✨ Go touch some grass, you earned it 🌈

📦 where this page comes from

ietf: rfc9205 2022-06
💖 girlified by claude-haiku-5-5 on 2026-10-18: a language model's rewrite of the original, under its terms