16. Extending HTTP
HTTP defines a number of generic extension points that can be used to introduce capabilities to the protocol without introducing a new version, including methods, status codes, field names, and further extensibility points within defined fields, such as authentication schemes and cache directives (see Cache-Control extensions in Section 5.2.3 of [CACHING]). Because the semantics of HTTP are not versioned, these extension points are persistent; the version of the protocol in use does not affect their semantics.
Version-independent extensions are discouraged from depending on or interacting with the specific version of the protocol in use. When this is unavoidable, careful consideration needs to be given to how the extension can interoperate across versions.
Additionally, specific versions of HTTP might have their own extensibility points, such as transfer codings in HTTP/1.1 (Section 6.1 of [HTTP/1.1]) and HTTP/2 SETTINGS or frame types ([HTTP/2]). These extension points are specific to the version of the protocol they occur within.
Version-specific extensions cannot override or modify the semantics of a version-independent mechanism or extension point (like a method or header field) without explicitly being allowed by that protocol element. For example, the CONNECT method (Section 9.3.6) allows this.
These guidelines assure that the protocol operates correctly and predictably, even when parts of the path implement different versions of HTTP.
16.1. Method Extensibility
16.1.1. Method Registry
The "Hypertext Transfer Protocol (HTTP) Method Registry", maintained
by IANA at
HTTP method registrations MUST include the following fields:
* Method Name (see Section 9)
* Safe ("yes" or "no", see Section 9.2.1)
* Idempotent ("yes" or "no", see Section 9.2.2)
* Pointer to specification text
Values to be added to this namespace require IETF Review (see [RFC8126], Section 4.8).
16.1.2. Considerations for New Methods
Standardized methods are generic; that is, they are potentially applicable to any resource, not just one particular media type, kind of resource, or application. As such, it is preferred that new methods be registered in a document that isn't specific to a single application or data format, since orthogonal technologies deserve orthogonal specification.
Since message parsing (Section 6) needs to be independent of method semantics (aside from responses to HEAD), definitions of new methods cannot change the parsing algorithm or prohibit the presence of content on either the request or the response message. Definitions of new methods can specify that only a zero-length content is allowed by requiring a Content-Length header field with a value of "0".
Likewise, new methods cannot use the special host:port and asterisk forms of request target that are allowed for CONNECT and OPTIONS, respectively (Section 7.1). A full URI in absolute form is needed for the target URI, which means either the request target needs to be sent in absolute form or the target URI will be reconstructed from the request context in the same way it is for other methods.
A new method definition needs to indicate whether it is safe (Section 9.2.1), idempotent (Section 9.2.2), cacheable (Section 9.2.3), what semantics are to be associated with the request content (if any), and what refinements the method makes to header field or status code semantics. If the new method is cacheable, its definition ought to describe how, and under what conditions, a cache can store a response and use it to satisfy a subsequent request. The new method ought to describe whether it can be made conditional (Section 13.1) and, if so, how a server responds when the condition is false. Likewise, if the new method might have some use for partial response semantics (Section 14.2), it ought to document this, too.
| *Note:* Avoid defining a method name that starts with "M-", | since that prefix might be misinterpreted as having the | semantics assigned to it by [RFC2774].
16.2. Status Code Extensibility
16.2.1. Status Code Registry
The "Hypertext Transfer Protocol (HTTP) Status Code Registry",
maintained by IANA at
A registration MUST include the following fields:
* Status Code (3 digits)
* Short Description
* Pointer to specification text
Values to be added to the HTTP status code namespace require IETF Review (see [RFC8126], Section 4.8).
16.2.2. Considerations for New Status Codes
When it is necessary to express semantics for a response that are not defined by current status codes, a new status code can be registered. Status codes are generic; they are potentially applicable to any resource, not just one particular media type, kind of resource, or application of HTTP. As such, it is preferred that new status codes be registered in a document that isn't specific to a single application.
New status codes are required to fall under one of the categories defined in Section 15. To allow existing parsers to process the response message, new status codes cannot disallow content, although they can mandate a zero-length content.
Proposals for new status codes that are not yet widely deployed ought to avoid allocating a specific number for the code until there is clear consensus that it will be registered; instead, early drafts can use a notation such as "4NN", or "3N0" .. "3N9", to indicate the class of the proposed status code(s) without consuming a number prematurely.
The definition of a new status code ought to explain the request conditions that would cause a response containing that status code (e.g., combinations of request header fields and/or method(s)) along with any dependencies on response header fields (e.g., what fields are required, what fields can modify the semantics, and what field semantics are further refined when used with the new status code).
By default, a status code applies only to the request corresponding to the response it occurs within. If a status code applies to a larger scope of applicability -- for example, all requests to the resource in question or all requests to a server -- this must be explicitly specified. When doing so, it should be noted that not all clients can be expected to consistently apply a larger scope because they might not understand the new status code.
The definition of a new final status code ought to specify whether or not it is heuristically cacheable. Note that any response with a final status code can be cached if the response has explicit freshness information. A status code defined as heuristically cacheable is allowed to be cached without explicit freshness information. Likewise, the definition of a status code can place constraints upon cache behavior if the must-understand cache directive is used. See [CACHING] for more information.
Finally, the definition of a new status code ought to indicate whether the content has any implied association with an identified resource (Section 6.4.2).
16.3. Field Extensibility
HTTP's most widely used extensibility point is the definition of new header and trailer fields.
New fields can be defined such that, when they are understood by a recipient, they override or enhance the interpretation of previously defined fields, define preconditions on request evaluation, or refine the meaning of responses.
However, defining a field doesn't guarantee its deployment or recognition by recipients. Most fields are designed with the expectation that a recipient can safely ignore (but forward downstream) any field not recognized. In other cases, the sender's ability to understand a given field might be indicated by its prior communication, perhaps in the protocol version or fields that it sent in prior messages, or its use of a specific media type. Likewise, direct inspection of support might be possible through an OPTIONS request or by interacting with a defined well-known URI [RFC8615] if such inspection is defined along with the field being introduced.
16.3.1. Field Name Registry
The "Hypertext Transfer Protocol (HTTP) Field Name Registry" defines the namespace for HTTP field names.
Any party can request registration of an HTTP field. See Section 16.3.2 for considerations to take into account when creating a new HTTP field.
The "Hypertext Transfer Protocol (HTTP) Field Name Registry" is
located at
Field names are registered on the advice of a designated expert (appointed by the IESG or their delegate). Fields with the status 'permanent' are Specification Required ([RFC8126], Section 4.6).
Registration requests consist of the following information:
Field name: The requested field name. It MUST conform to the field-name syntax defined in Section 5.1, and it SHOULD be restricted to just letters, digits, and hyphen ('-') characters, with the first character being a letter.
Status: "permanent", "provisional", "deprecated", or "obsoleted".
Specification document(s): Reference to the document that specifies the field, preferably including a URI that can be used to retrieve a copy of the document. Optional but encouraged for provisional registrations. An indication of the relevant section(s) can also be included, but is not required.
And optionally:
Comments: Additional information, such as about reserved entries.
The expert(s) can define additional fields to be collected in the registry, in consultation with the community.
Standards-defined names have a status of "permanent". Other names can also be registered as permanent if the expert(s) finds that they are in use, in consultation with the community. Other names should be registered as "provisional".
Provisional entries can be removed by the expert(s) if -- in consultation with the community -- the expert(s) find that they are not in use. The expert(s) can change a provisional entry's status to permanent at any time.
Note that names can be registered by third parties (including the expert(s)) if the expert(s) determines that an unregistered name is widely deployed and not likely to be registered in a timely manner otherwise.
16.3.2. Considerations for New Fields
HTTP header and trailer fields are a widely used extension point for the protocol. While they can be used in an ad hoc fashion, fields that are intended for wider use need to be carefully documented to ensure interoperability.
In particular, authors of specifications defining new fields are advised to consider and, where appropriate, document the following aspects:
* Under what conditions the field can be used; e.g., only in responses or requests, in all messages, only on responses to a particular request method, etc.
* Whether the field semantics are further refined by their context, such as their use with certain request methods or status codes.
* The scope of applicability for the information conveyed. By default, fields apply only to the message they are associated with, but some response fields are designed to apply to all representations of a resource, the resource itself, or an even broader scope. Specifications that expand the scope of a response field will need to carefully consider issues such as content negotiation, the time period of applicability, and (in some cases) multi-tenant server deployments.
* Under what conditions intermediaries are allowed to insert, delete, or modify the field's value.
* If the field is allowable in trailers; by default, it will not be (see Section 6.5.1).
* Whether it is appropriate or even required to list the field name in the Connection header field (i.e., if the field is to be hop- by-hop; see Section 7.6.1).
* Whether the field introduces any additional security considerations, such as disclosure of privacy-related data.
Request header fields have additional considerations that need to be documented if the default behavior is not appropriate:
* If it is appropriate to list the field name in a Vary response header field (e.g., when the request header field is used by an origin server's content selection algorithm; see Section 12.5.5).
* If the field is intended to be stored when received in a PUT request (see Section 9.3.4).
* If the field ought to be removed when automatically redirecting a request due to security concerns (see Section 15.4).
16.3.2.1. Considerations for New Field Names
Authors of specifications defining new fields are advised to choose a short but descriptive field name. Short names avoid needless data transmission; descriptive names avoid confusion and "squatting" on names that might have broader uses.
To that end, limited-use fields (such as a header confined to a single application or use case) are encouraged to use a name that includes that use (or an abbreviation) as a prefix; for example, if the Foo Application needs a Description field, it might use "Foo- Desc"; "Description" is too generic, and "Foo-Description" is needlessly long.
While the field-name syntax is defined to allow any token character, in practice some implementations place limits on the characters they accept in field-names. To be interoperable, new field names SHOULD constrain themselves to alphanumeric characters, "-", and ".", and SHOULD begin with a letter. For example, the underscore ("_") character can be problematic when passed through non-HTTP gateway interfaces (see Section 17.10).
Field names ought not be prefixed with "X-"; see [BCP178] for further information.
Other prefixes are sometimes used in HTTP field names; for example, "Accept-" is used in many content negotiation headers, and "Content-" is used as explained in Section 6.4. These prefixes are only an aid to recognizing the purpose of a field and do not trigger automatic processing.
16.3.2.2. Considerations for New Field Values
A major task in the definition of a new HTTP field is the specification of the field value syntax: what senders should generate, and how recipients should infer semantics from what is received.
Authors are encouraged (but not required) to use either the ABNF rules in this specification or those in [RFC8941] to define the syntax of new field values.
Authors are advised to carefully consider how the combination of multiple field lines will impact them (see Section 5.3). Because senders might erroneously send multiple values, and both intermediaries and HTTP libraries can perform combination automatically, this applies to all field values -- even when only a single value is anticipated.
Therefore, authors are advised to delimit or encode values that contain commas (e.g., with the quoted-string rule of Section 5.6.4, the String data type of [RFC8941], or a field-specific encoding). This ensures that commas within field data are not confused with the commas that delimit a list value.
For example, the Content-Type field value only allows commas inside quoted strings, which can be reliably parsed even when multiple values are present. The Location field value provides a counter- example that should not be emulated: because URIs can include commas, it is not possible to reliably distinguish between a single value that includes a comma from two values.
Authors of fields with a singleton value (see Section 5.5) are additionally advised to document how to treat messages where the multiple members are present (a sensible default would be to ignore the field, but this might not always be the right choice).
16.4. Authentication Scheme Extensibility
16.4.1. Authentication Scheme Registry
The "Hypertext Transfer Protocol (HTTP) Authentication Scheme
Registry" defines the namespace for the authentication schemes in
challenges and credentials. It is maintained at
Registrations MUST include the following fields:
* Authentication Scheme Name
* Pointer to specification text
* Notes (optional)
Values to be added to this namespace require IETF Review (see [RFC8126], Section 4.8).
16.4.2. Considerations for New Authentication Schemes
There are certain aspects of the HTTP Authentication framework that put constraints on how new authentication schemes can work:
* HTTP authentication is presumed to be stateless: all of the information necessary to authenticate a request MUST be provided in the request, rather than be dependent on the server remembering prior requests. Authentication based on, or bound to, the underlying connection is outside the scope of this specification and inherently flawed unless steps are taken to ensure that the connection cannot be used by any party other than the authenticated user (see Section 3.3).
* The authentication parameter "realm" is reserved for defining protection spaces as described in Section 11.5. New schemes MUST NOT use it in a way incompatible with that definition.
* The "token68" notation was introduced for compatibility with existing authentication schemes and can only be used once per challenge or credential. Thus, new schemes ought to use the auth- param syntax instead, because otherwise future extensions will be impossible.
* The parsing of challenges and credentials is defined by this specification and cannot be modified by new authentication schemes. When the auth-param syntax is used, all parameters ought to support both token and quoted-string syntax, and syntactical constraints ought to be defined on the field value after parsing (i.e., quoted-string processing). This is necessary so that recipients can use a generic parser that applies to all authentication schemes.
*Note:* The fact that the value syntax for the "realm" parameter is restricted to quoted-string was a bad design choice not to be repeated for new parameters.
* Definitions of new schemes ought to define the treatment of unknown extension parameters. In general, a "must-ignore" rule is preferable to a "must-understand" rule, because otherwise it will be hard to introduce new parameters in the presence of legacy recipients. Furthermore, it's good to describe the policy for defining new parameters (such as "update the specification" or "use this registry").
* Authentication schemes need to document whether they are usable in origin-server authentication (i.e., using WWW-Authenticate), and/ or proxy authentication (i.e., using Proxy-Authenticate).
* The credentials carried in an Authorization header field are specific to the user agent and, therefore, have the same effect on HTTP caches as the "private" cache response directive (Section 5.2.2.7 of [CACHING]), within the scope of the request in which they appear.
Therefore, new authentication schemes that choose not to carry credentials in the Authorization header field (e.g., using a newly defined header field) will need to explicitly disallow caching, by mandating the use of cache response directives (e.g., "private").
* Schemes using Authentication-Info, Proxy-Authentication-Info, or any other authentication related response header field need to consider and document the related security considerations (see Section 17.16.4).
16.5. Range Unit Extensibility
16.5.1. Range Unit Registry
The "HTTP Range Unit Registry" defines the namespace for the range
unit names and refers to their corresponding specifications. It is
maintained at
Registration of an HTTP Range Unit MUST include the following fields:
* Name
* Description
* Pointer to specification text
Values to be added to this namespace require IETF Review (see [RFC8126], Section 4.8).
16.5.2. Considerations for New Range Units
Other range units, such as format-specific boundaries like pages, sections, records, rows, or time, are potentially usable in HTTP for application-specific purposes, but are not commonly used in practice. Implementors of alternative range units ought to consider how they would work with content codings and general-purpose intermediaries.
16.6. Content Coding Extensibility
16.6.1. Content Coding Registry
The "HTTP Content Coding Registry", maintained by IANA at
Content coding registrations MUST include the following fields:
* Name
* Description
* Pointer to specification text
Names of content codings MUST NOT overlap with names of transfer
codings (per the "HTTP Transfer Coding Registry" located at
Values to be added to this namespace require IETF Review (see Section 4.8 of [RFC8126]) and MUST conform to the purpose of content coding defined in Section 8.4.1.
16.6.2. Considerations for New Content Codings
New content codings ought to be self-descriptive whenever possible, with optional parameters discoverable within the coding format itself, rather than rely on external metadata that might be lost during transit.
16.7. Upgrade Token Registry
The "Hypertext Transfer Protocol (HTTP) Upgrade Token Registry"
defines the namespace for protocol-name tokens used to identify
protocols in the Upgrade header field. The registry is maintained at
Each registered protocol name is associated with contact information and an optional set of specifications that details how the connection will be processed after it has been upgraded.
Registrations happen on a "First Come First Served" basis (see Section 4.4 of [RFC8126]) and are subject to the following rules:
1. A protocol-name token, once registered, stays registered forever.
2. A protocol-name token is case-insensitive and registered with the preferred case to be generated by senders.
3. The registration MUST name a responsible party for the registration.
4. The registration MUST name a point of contact.
5. The registration MAY name a set of specifications associated with that token. Such specifications need not be publicly available.
6. The registration SHOULD name a set of expected "protocol-version" tokens associated with that token at the time of registration.
7. The responsible party MAY change the registration at any time. The IANA will keep a record of all such changes, and make them available upon request.
8. The IESG MAY reassign responsibility for a protocol token. This will normally only be used in the case when a responsible party cannot be contacted.