< draft-ietf-httpbis-bcp56bis-04.txt   draft-ietf-httpbis-bcp56bis-05.txt >
HTTP M. Nottingham HTTP M. Nottingham
Internet-Draft April 11, 2018 Internet-Draft May 1, 2018
Obsoletes: 3205 (if approved) Obsoletes: 3205 (if approved)
Intended status: Best Current Practice Intended status: Best Current Practice
Expires: October 13, 2018 Expires: November 2, 2018
On the use of HTTP as a Substrate On the use of HTTP as a Substrate
draft-ietf-httpbis-bcp56bis-04 draft-ietf-httpbis-bcp56bis-05
Abstract Abstract
HTTP is often used as a substrate for other application protocols HTTP is often used as a substrate for other application protocols
(a.k.a. HTTP-based APIs). This document specifies best practices (a.k.a. HTTP-based APIs). This document specifies best practices
for these protocols' use of HTTP. for these protocols' use of HTTP.
This document obsoletes RFC 3205.
Note to Readers Note to Readers
Discussion of this draft takes place on the HTTP working group Discussion of this draft takes place on the HTTP working group
mailing list (ietf-http-wg@w3.org), which is archived at mailing list (ietf-http-wg@w3.org), which is archived at
https://lists.w3.org/Archives/Public/ietf-http-wg/ [1]. https://lists.w3.org/Archives/Public/ietf-http-wg/ [1].
Working Group information can be found at http://httpwg.github.io/ Working Group information can be found at http://httpwg.github.io/
[2]; source code and issues list for this draft can be found at [2]; source code and issues list for this draft can be found at
https://github.com/httpwg/http-extensions/labels/bcp56bis [3]. https://github.com/httpwg/http-extensions/labels/bcp56bis [3].
skipping to change at page 1, line 45 skipping to change at page 1, line 43
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on October 13, 2018. This Internet-Draft will expire on November 2, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 41 skipping to change at page 2, line 36
4.2. Defining HTTP Resources . . . . . . . . . . . . . . . . . 8 4.2. Defining HTTP Resources . . . . . . . . . . . . . . . . . 8
4.3. Specifying Client Behaviours . . . . . . . . . . . . . . 9 4.3. Specifying Client Behaviours . . . . . . . . . . . . . . 9
4.4. HTTP URLs . . . . . . . . . . . . . . . . . . . . . . . . 10 4.4. HTTP URLs . . . . . . . . . . . . . . . . . . . . . . . . 10
4.4.1. Initial URL Discovery . . . . . . . . . . . . . . . . 11 4.4.1. Initial URL Discovery . . . . . . . . . . . . . . . . 11
4.4.2. URL Schemes . . . . . . . . . . . . . . . . . . . . . 11 4.4.2. URL Schemes . . . . . . . . . . . . . . . . . . . . . 11
4.4.3. Transport Ports . . . . . . . . . . . . . . . . . . . 12 4.4.3. Transport Ports . . . . . . . . . . . . . . . . . . . 12
4.5. HTTP Methods . . . . . . . . . . . . . . . . . . . . . . 12 4.5. HTTP Methods . . . . . . . . . . . . . . . . . . . . . . 12
4.5.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.5.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.5.2. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . 14 4.5.2. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . 14
4.6. HTTP Status Codes . . . . . . . . . . . . . . . . . . . . 14 4.6. HTTP Status Codes . . . . . . . . . . . . . . . . . . . . 14
4.7. HTTP Header Fields . . . . . . . . . . . . . . . . . . . 16 4.6.1. Redirection . . . . . . . . . . . . . . . . . . . . . 16
4.8. Defining Message Payloads . . . . . . . . . . . . . . . . 17 4.7. HTTP Header Fields . . . . . . . . . . . . . . . . . . . 17
4.9. HTTP Caching . . . . . . . . . . . . . . . . . . . . . . 17 4.8. Defining Message Payloads . . . . . . . . . . . . . . . . 18
4.10. Application State . . . . . . . . . . . . . . . . . . . . 19 4.9. HTTP Caching . . . . . . . . . . . . . . . . . . . . . . 18
4.11. Client Authentication . . . . . . . . . . . . . . . . . . 19 4.10. Application State . . . . . . . . . . . . . . . . . . . . 20
4.12. Co-Existing with Web Browsing . . . . . . . . . . . . . . 19 4.11. Client Authentication . . . . . . . . . . . . . . . . . . 20
4.13. Application Boundaries . . . . . . . . . . . . . . . . . 21 4.12. Co-Existing with Web Browsing . . . . . . . . . . . . . . 21
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 4.13. Application Boundaries . . . . . . . . . . . . . . . . . 22
6. Security Considerations . . . . . . . . . . . . . . . . . . . 22 4.14. Server Push . . . . . . . . . . . . . . . . . . . . . . . 23
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
7.1. Normative References . . . . . . . . . . . . . . . . . . 22 6. Security Considerations . . . . . . . . . . . . . . . . . . . 24
7.2. Informative References . . . . . . . . . . . . . . . . . 24 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 24
7.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 27 7.1. Normative References . . . . . . . . . . . . . . . . . . 24
Appendix A. Changes from RFC 3205 . . . . . . . . . . . . . . . 27 7.2. Informative References . . . . . . . . . . . . . . . . . 26
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 27 7.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Appendix A. Changes from RFC 3205 . . . . . . . . . . . . . . . 29
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 29
1. Introduction 1. Introduction
HTTP [RFC7230] is often used as a substrate for other application HTTP [RFC7230] is often used as a substrate for applications other
protocols; this is sometimes referred to as creating "HTTP-based than Web browsing; this is sometimes referred to as creating "HTTP-
APIs", or just "HTTP APIs", although the latter is ambiguous. This based APIs", or just "HTTP APIs". This is done for a variety of
is done for a variety of reasons, including: reasons, including:
o familiarity by implementers, specifiers, administrators, o familiarity by implementers, specifiers, administrators,
developers and users, developers and users,
o availability of a variety of client, server and proxy o availability of a variety of client, server and proxy
implementations, implementations,
o ease of use, o ease of use,
o ubiquity of Web browsers, o availability of Web browsers,
o reuse of existing mechanisms like authentication and encryption, o reuse of existing mechanisms like authentication and encryption,
o presence of HTTP servers and clients in target deployments, and o presence of HTTP servers and clients in target deployments, and
o its ability to traverse firewalls. o its ability to traverse firewalls.
In many cases, these protocols are ad hoc; they are intended for only These protocols are often ad hoc; they are intended for only
deployment on the server side, and consumption by a limited set of deployment by one or a few servers, and consumption by a limited set
clients. A body of practices and tools has arisen around defining of clients. As a result, a body of practices and tools has arisen
HTTP-based APIs that favours these conditions. around defining HTTP-based APIs that favours these conditions.
However, when such a protocol is standarised, it is typically However, when such a protocol is standarised, it is typically
deployed on multiple servers, implemented a number of times, and deployed on multiple uncoordinated servers, implemented a number of
might be consumed by a broader variety of clients. Such diversity times, and consumed by a broader variety of clients. Such diversity
brings a different set of concerns, and tools and practices intended brings a different set of concerns, and tools and practices intended
for a single-server deployment might not be suitable. for a single-server deployment might not be suitable.
In particular, standards-defined HTTP-based APIs need to more For example, HTTP-based APIs deployed in these circumstances need to
carefully consider how extensibility and evolution will be handled, more carefully consider how extensibility and evolution of the
how different deployment requirements will be accommodated, and how service will be handled, how different deployment requirements will
clients will evolve with the API. be accommodated, and how clients will evolve with the API.
At the same time, the IETF has a tradition of protocol reuse (e.g., More generally, application protocols using HTTP face a number of
[TELNET] as a substrate for [FTP] and [SMTP]; HTTP as a substrate for design decisions, including:
[IPP] and [RESTCONF]). Because HTTP is extensible in many ways, a
number of questions arise, such as:
o Should an application using HTTP define a new URL scheme? Use new o Should it define a new URL scheme? Use new ports?
ports?
o Should it use standard HTTP methods and status codes, or define o Should it use standard HTTP methods and status codes, or define
new ones? new ones?
o How can the maximum value be extracted from the use of HTTP? o How can the maximum value be extracted from the use of HTTP?
o How does it coexist with other uses of HTTP - especially Web o How does it coexist with other uses of HTTP - especially Web
browsing? browsing?
o How can interoperability problems and "protocol dead ends" be o How can interoperability problems and "protocol dead ends" be
avoided? avoided?
This document contains best current practices regarding the use of This document contains best current practices regarding the use of
HTTP by applications other than Web browsing. Section 2 defines what HTTP by applications other than Web browsing. Section 2 defines what
applications it applies to; Section 3 surveys the properties of HTTP applications it applies to; Section 3 surveys the properties of HTTP
that are important to preserve, and Section 4 conveys best practices that are important to preserve, and Section 4 conveys best practices
skipping to change at page 5, line 17 skipping to change at page 5, line 8
[RFC7230], [RFC7231], [RFC7232], [RFC7233], [RFC7234], [RFC7235] and [RFC7230], [RFC7231], [RFC7232], [RFC7233], [RFC7234], [RFC7235] and
[RFC7540]). [RFC7540]).
An application might not be using HTTP according to this definition, An application might not be using HTTP according to this definition,
but still relying upon the HTTP specifications in some manner. For but still relying upon the HTTP specifications in some manner. For
example, an application might wish to avoid re-specifying parts of example, an application might wish to avoid re-specifying parts of
the message format, but change others; or, it might want to use a the message format, but change others; or, it might want to use a
different set of methods. different set of methods.
Such applications are referred to as "protocols based upon HTTP" in Such applications are referred to as "protocols based upon HTTP" in
this document. These have more freedom to modify protocol operation, this document. These have more freedom to modify protocol
but are also likely to lose at least a portion of the benefits operations, but are also likely to lose at least a portion of the
outlined above, as most HTTP implementations won't be easily benefits outlined above, as most HTTP implementations won't be easily
adaptable to these changes, and as the protocol diverges from HTTP, adaptable to these changes, and as the protocol diverges from HTTP,
the benefit of mindshare will be lost. the benefit of mindshare will be lost.
Protocols that are based upon HTTP MUST NOT reuse HTTP's URL schemes, Protocols that are based upon HTTP MUST NOT reuse HTTP's URL schemes,
transport ports, ALPN protocol IDs or IANA registries; rather, they transport ports, ALPN protocol IDs or IANA registries; rather, they
are encouraged to establish their own. are encouraged to establish their own.
3. What's Important About HTTP 3. What's Important About HTTP
There are many ways that applications using HTTP are defined and There are many ways that applications using HTTP are defined and
skipping to change at page 6, line 41 skipping to change at page 6, line 35
As explained in [RFC7320], such "squatting" on a part of the URL As explained in [RFC7320], such "squatting" on a part of the URL
space by a standard usurps the server's authority over its own space by a standard usurps the server's authority over its own
resources, can cause deployment issues, and is therefore bad practice resources, can cause deployment issues, and is therefore bad practice
in standards. in standards.
Instead of statically defining URL components like paths, it is Instead of statically defining URL components like paths, it is
RECOMMENDED that applications using HTTP define links in payloads, to RECOMMENDED that applications using HTTP define links in payloads, to
allow flexibility in deployment. allow flexibility in deployment.
Using runtime links in this fashion has a number of other benefits. Using runtime links in this fashion has a number of other benefits -
especially when an application is to have multiple implementations
and/or deployments (as is often the case for those that are
standardised).
For example, navigating with a link allows a request to be routed to For example, navigating with a link allows a request to be routed to
a different server without the overhead of a redirection, thereby a different server without the overhead of a redirection, thereby
supporting deployment across machines well. supporting deployment across machines well.
It also becomes possible to "mix" different applications on the same It also becomes possible to "mix and match" different applications on
server, and offers a natural mechanism for extensibility, versioning the same server, and offers a natural mechanism for extensibility,
and capability management. versioning and capability management, since the document containing
the links can also contain information about their targets.
Using links also offers a form of cache invalidation that's seen on
the Web; when a resource's state changes, the application can change
its link to it so that a fresh copy is always fetched.
3.3. Rich Functionality 3.3. Rich Functionality
The simplest possible use of HTTP is to POST data to a single URL, The simplest possible use of HTTP is to POST data to a single URL,
thereby effectively tunnelling through the protocol. thereby effectively tunnelling through the protocol.
This "RPC" style of communication does get some benefit from using This "RPC" style of communication does get some benefit from using
HTTP - namely, message framing and the availability of HTTP - namely, message framing and the availability of
implementations - but fails to realise many others when used implementations - but fails to realise many others when used
exclusively: exclusively:
skipping to change at page 8, line 12 skipping to change at page 8, line 12
applications, including practices for specific HTTP protocol applications, including practices for specific HTTP protocol
elements. elements.
4.1. Specifying the Use of HTTP 4.1. Specifying the Use of HTTP
When specifying the use of HTTP, an application SHOULD use [RFC7230] When specifying the use of HTTP, an application SHOULD use [RFC7230]
as the primary reference; it is not necessary to reference all of the as the primary reference; it is not necessary to reference all of the
specifications in the HTTP suite unless there are specific reasons to specifications in the HTTP suite unless there are specific reasons to
do so (e.g., a particular feature is called out). do so (e.g., a particular feature is called out).
Applications using HTTP MAY specify a minimum version to be supported Applications using HTTP SHOULD NOT specify a minimum version of HTTP
(HTTP/1.1 is suggested), and MUST NOT specify a maximum version, to to be used; because it is a hop-by-hop protocol, a HTTP connection
preserve the protocol's ability to evolve. can be handled by implementations that are not controlled by the
application; for example, proxies, CDNs, firewalls and so on.
Requiring a particular version of HTTP makes it difficult to use in
these situations, and harms interoperability for little reason (since
HTTP's semantics are stable between protocol versions).
Likewise, applications need not specify what HTTP mechanisms - such However, if an application's deployment would benefit from the use of
as redirection, caching, authentication, proxy authentication, and so a particular version of HTTP (for example, HTTP/2's multiplexing),
on - are to be supported. For example, an application can specify this SHOULD be noted.
that it uses HTTP like this:
Foo Application uses HTTP [RFC7230]. Implementations MUST support Applications using HTTP MUST NOT specify a maximum version, to
HTTP/1.1, and MAY support later versions. preserve the protocol's ability to evolve.
When specifying examples of protocol interactions, applications When specifying examples of protocol interactions, applications
SHOULD document both the request and response messages, with full SHOULD document both the request and response messages, with full
headers, preferably in HTTP/1.1 format. For example: headers, preferably in HTTP/1.1 format. For example:
GET /thing HTTP/1.1 GET /thing HTTP/1.1
Host: example.com Host: example.com
Accept: application/things+json Accept: application/things+json
User-Agent: Foo/1.0 User-Agent: Foo/1.0
skipping to change at page 9, line 42 skipping to change at page 9, line 44
related information in the link indicated by the Link header field related information in the link indicated by the Link header field
value with the "example-other-info" link relation type. value with the "example-other-info" link relation type.
4.3. Specifying Client Behaviours 4.3. Specifying Client Behaviours
HTTP does not mandate some behaviours that have nevertheless become HTTP does not mandate some behaviours that have nevertheless become
very common; if these are not explicitly specified by applications very common; if these are not explicitly specified by applications
using HTTP, there may be confusion and interoperability problems. using HTTP, there may be confusion and interoperability problems.
This section recommends default handling for these mechanisms. This section recommends default handling for these mechanisms.
o Redirect handling - Applications using HTTP SHOULD specify that o Redirect handling - Applications need to specify how redirects are
3xx redirect status codes be followed automatically. See expected to be handled; see Section 4.6.1.
[RFC7231], Section 6.4.
o Redirect methods - Applications using HTTP SHOULD specify that 301
and 302 redirect status codes rewrite the POST method to GET, in
order to be compatible with browsers. See [RFC7231], Section 6.4.
o Cookies - Applications using HTTP MUST explicitly reference the o Cookies - Applications using HTTP MUST explicitly reference the
Cookie specification [RFC6265] if they are required. Cookie specification [RFC6265] if they are required.
o Certificates - Applications using HTTP MUST specify that TLS o Certificates - Applications using HTTP MUST specify that TLS
certificates are to be checked according to [RFC2818] when HTTPS certificates are to be checked according to [RFC2818] when HTTPS
is used. is used.
In general, applications using HTTP ought to align their usage as In general, applications using HTTP ought to align their usage as
closely as possible with Web browsers, to avoid interoperability closely as possible with Web browsers, to avoid interoperability
skipping to change at page 11, line 45 skipping to change at page 11, line 45
registerProtocolHandler() in [HTML5], as well as several registerProtocolHandler() in [HTML5], as well as several
proprietary approaches), support for these mechanisms is not proprietary approaches), support for these mechanisms is not
shared by all browsers, and their capabilities vary. shared by all browsers, and their capabilities vary.
o Existing non-browser clients, intermediaries, servers and o Existing non-browser clients, intermediaries, servers and
associated software will not recognise the new scheme. For associated software will not recognise the new scheme. For
example, a client library might fail to dispatch the request; a example, a client library might fail to dispatch the request; a
cache might refuse to store the response, and a proxy might fail cache might refuse to store the response, and a proxy might fail
to forward the request. to forward the request.
o Because URLs occur in and are generated in HTTP artefacts o Because URLs occur in HTTP artefacts commonly, often being
commonly, often without human intervention (e.g., in the generated automatically (e.g., in the "Location" response header),
"Location" response header), it can be difficult to assure that it can be difficult to assure that the new scheme is used
the new scheme is used consistently. consistently.
o The resources identified by the new scheme will still be available o The resources identified by the new scheme will still be available
using "http" and/or "https" URLs. Those URLs can "leak" into use, using "http" and/or "https" URLs. Those URLs can "leak" into use,
which can present security and operability issues. For example, which can present security and operability issues. For example,
using a new scheme to assure that requests don't get sent to a using a new scheme to assure that requests don't get sent to a
"normal" Web site is likely to fail. "normal" Web site is likely to fail.
o Features that rely upon the URL's origin [RFC6454], such as the o Features that rely upon the URL's origin [RFC6454], such as the
Web's same-origin policy, will be impacted by a change of scheme. Web's same-origin policy, will be impacted by a change of scheme.
skipping to change at page 12, line 29 skipping to change at page 12, line 29
See [RFC7595] for more information about minting new URL schemes. See [RFC7595] for more information about minting new URL schemes.
4.4.3. Transport Ports 4.4.3. Transport Ports
Applications that use HTTP can use the applicable default port (80 Applications that use HTTP can use the applicable default port (80
for HTTP, 443 for HTTPS), or they can be deployed upon other ports. for HTTP, 443 for HTTPS), or they can be deployed upon other ports.
This decision can be made at deployment time, or might be encouraged This decision can be made at deployment time, or might be encouraged
by the application's specification (e.g., by registering a port for by the application's specification (e.g., by registering a port for
that application). that application).
In either case, non-default ports will need to be reflected in the If a non-default port is used, it needs to be reflected in the
authority of all URLs for that resource; the only mechanism for authority of all URLs for that resource; the only mechanism for
changing a default port is changing the scheme (see Section 4.4.2). changing a default port is changing the scheme (see Section 4.4.2).
Using a port other than the default has privacy implications (i.e., Using a port other than the default has privacy implications (i.e.,
the protocol can now be distinguished from other traffic), as well as the protocol can now be distinguished from other traffic), as well as
operability concerns (as some networks might block or otherwise operability concerns (as some networks might block or otherwise
interfere with it). Privacy implications should be documented in interfere with it). Privacy implications should be documented in
Security Considerations. Security Considerations.
See [RFC7605] for further guidance. See [RFC7605] for further guidance.
4.5. HTTP Methods 4.5. HTTP Methods
Applications that use HTTP MUST confine themselves to using Applications that use HTTP MUST confine themselves to using
registered HTTP methods such as GET, POST, PUT, DELETE, and PATCH. registered HTTP methods such as GET, POST, PUT, DELETE, and PATCH.
New HTTP methods are rare; they are required to be registered with New HTTP methods are rare; they are required to be registered with
IETF Review (see [RFC7232]), and are also required to be _generic_. IETF Review (see [RFC7232]), and are also required to be generic.
That means that they need to be potentially applicable to all That means that they need to be potentially applicable to all
resources, not just those of one application. resources, not just those of one application.
While historically some applications (e.g., [RFC4791]) have defined While historically some applications (e.g., [RFC4791]) have defined
non-generic methods, [RFC7231] now forbids this. non-generic methods, [RFC7231] now forbids this.
When authors believe that a new method is required, they are When authors believe that a new method is required, they are
encouraged to engage with the HTTP community early, and document encouraged to engage with the HTTP community early, and document
their proposal as a separate HTTP extension, rather than as part of their proposal as a separate HTTP extension, rather than as part of
an application's specification. an application's specification.
skipping to change at page 16, line 10 skipping to change at page 16, line 10
(by [RFC7231]) to be registered with IETF review. Similarly, HTTP (by [RFC7231]) to be registered with IETF review. Similarly, HTTP
status codes are generic; they are required (by [RFC7231]) to be status codes are generic; they are required (by [RFC7231]) to be
potentially applicable to all resources, not just to those of one potentially applicable to all resources, not just to those of one
application. application.
When authors believe that a new status code is required, they are When authors believe that a new status code is required, they are
encouraged to engage with the HTTP community early, and document encouraged to engage with the HTTP community early, and document
their proposal as a separate HTTP extension, rather than as part of their proposal as a separate HTTP extension, rather than as part of
an application's specification. an application's specification.
4.6.1. Redirection
The 3xx series of status codes specified in [RFC7231], Section 6.4
are used to direct the user agent to another resource to satisfy the
request. The most common of these are 301, 302, 307 and 308
([RFC7538]), all of which use the Location response header field to
indicate where the client should send the request to.
There are two ways that this group of status codes differ:
o Whether they are permanent or temporary. Permanent redirects can
be used to update links stored in the client (e.g., bookmarks),
whereas temporary ones can not. Note that this has no effect on
HTTP caching; it is completely separate.
o Whether they allow the redirected request to change the request
method from POST to GET. Web browsers generally do change POST to
GET for 301 and 302; therefore, 308 and 307 were created to allow
redirection without changing the method.
This table summarises their relationships:
+-------------------------------------------+-----------+-----------+
| | Permanent | Temporary |
+-------------------------------------------+-----------+-----------+
| Allows changing the request method from | 301 | 302 |
| POST to GET | | |
| Does not allow changing the request | 308 | 307 |
| method | | |
+-------------------------------------------+-----------+-----------+
As noted in [RFC7231], a user agent is allowed to automatically
follow a 3xx redirect that has a Location response header field, even
if they don't understand the semantics of the specific status code.
However, they aren't required to do so; therefore, if an application
using HTTP desires redirects to be automatically followed, it needs
to explicitly specify the circumstances when this is required.
Applications using HTTP SHOULD specify that 301 and 302 responses
change the subsequent request method from POST (but no other method)
to GET, to be compatible with browsers.
Generally, when a redirected request is made, its header fields are
copied from the original request's. However, they can be modified by
various mechanisms; e.g., sent Authorization ([RFC7235]) and Cookie
([RFC6265]) headers will change if the origin (and sometimes path) of
the request changes. Applications using HTTP SHOULD specify if any
request headers 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. HTTP Header Fields 4.7. HTTP Header Fields
Applications that use HTTP MAY define new HTTP header fields. Applications that use HTTP MAY define new HTTP header fields.
Typically, using HTTP header fields is appropriate in a few different Typically, using HTTP header fields is appropriate in a few different
situations: situations:
o Their content is useful to intermediaries (who often wish to avoid o Their content is useful to intermediaries (who often wish to avoid
parsing the body), and/or parsing the body), and/or
o Their content is useful to generic HTTP software (e.g., clients, o Their content is useful to generic HTTP software (e.g., clients,
skipping to change at page 17, line 38 skipping to change at page 18, line 40
proxies, Content Delivery Networks and as part of server software. proxies, Content Delivery Networks and as part of server software.
Assigning even a short freshness lifetime ([RFC7234], Section 4.2) - Assigning even a short freshness lifetime ([RFC7234], Section 4.2) -
e.g., 5 seconds - allows a response to be reused to satisfy multiple e.g., 5 seconds - allows a response to be reused to satisfy multiple
clients, and/or a single client making the same request repeatedly. clients, and/or a single client making the same request repeatedly.
In general, if it is safe to reuse something, consider assigning a In general, if it is safe to reuse something, consider assigning a
freshness lifetime; cache implementations take active measures to freshness lifetime; cache implementations take active measures to
remove content intelligently when they are out of space, so "it will remove content intelligently when they are out of space, so "it will
fill up the cache" is not a valid concern. fill up the cache" is not a valid concern.
The most common method for specifying freshness is the max-age
response directive ([RFC7234], Section 5.2.2.8). The Expires header
([RFC7234], Section 5.3) can also be used, but it is not necessary to
specify it; all modern cache implementations support Cache-Control,
and specifying freshness as a delta is both more convenient in most
cases, and less error-prone.
Understand that stale responses (e.g., one with "Cache-Control: max- Understand that stale responses (e.g., one with "Cache-Control: max-
age=0") can be reused when the cache is disconnected from the origin age=0") can be reused when the cache is disconnected from the origin
server; this can be useful for handling network issues. See server; this can be useful for handling network issues. See
[RFC7234], Section 4.2.4, and also [RFC5861] for additional controls [RFC7234], Section 4.2.4, and also [RFC5861] for additional controls
over stale content. over stale content.
Stale responses can be refreshed by assigning a validator, saving Stale responses can be refreshed by assigning a validator, saving
both transfer bandwidth and latency for large responses; see both transfer bandwidth and latency for large responses; see
[RFC7232]. [RFC7232].
skipping to change at page 20, line 14 skipping to change at page 21, line 27
Or, If content returned from the application's resources is under Or, If content returned from the application's resources is under
control of an attacker (for example, part of the request is reflected control of an attacker (for example, part of the request is reflected
in the response, or the response contains external information that in the response, or the response contains external information that
might be under the control of the attacker), a cross-site scripting might be under the control of the attacker), a cross-site scripting
attack is possible, whereby an attacker can inject code into the attack is possible, whereby an attacker can inject code into the
browser and access data and capabilities on that origin. browser and access data and capabilities on that origin.
This is only a small sample of the kinds of issues that applications This is only a small sample of the kinds of issues that applications
using HTTP must consider. Generally, the best approach is to using HTTP must consider. Generally, the best approach is to
consider the application _as_ a Web application, and to follow best consider the application actually as a Web application, and to follow
practices for their secure development. best practices for their secure development.
A complete enumeration of such practices is out of scope for this A complete enumeration of such practices is out of scope for this
document, but some considerations include: document, but some considerations include:
o Using an application-specific media type in the Content-Type o Using an application-specific media type in the Content-Type
header, and requiring clients to fail if it is not used header, and requiring clients to fail if it is not used
o Using X-Content-Type-Options: nosniff [FETCH]} to assure that o Using X-Content-Type-Options: nosniff [FETCH]} to assure that
content under attacker control can't be coaxed into a form that is content under attacker control can't be coaxed into a form that is
interpreted as active content by a Web browser interpreted as active content by a Web browser
skipping to change at page 22, line 5 skipping to change at page 23, line 18
particular identifier, but instead let deployments configure them. particular identifier, but instead let deployments configure them.
Consideration SHOULD be given to scoping them to part of the origin, Consideration SHOULD be given to scoping them to part of the origin,
using their specified mechanisms for doing so. using their specified mechanisms for doing so.
Modern Web browsers constrain the ability of content from one origin Modern Web browsers constrain the ability of content from one origin
to access resources from another, to avoid leaking private to access resources from another, to avoid leaking private
information. As a result, applications that wish to expose cross- information. As a result, applications that wish to expose cross-
origin data to browsers will need to implement the CORS protocol; see origin data to browsers will need to implement the CORS protocol; see
[FETCH]. [FETCH].
4.14. Server Push
HTTP/2 adds the ability for servers to "push" request/response pairs
to clients in [RFC7540], Section 8.2. While server push seems like a
natural fit for many common application semantics (e.g., "fanout" and
publish/subscribe), a few caveats should be noted:
o Server push is hop-by-hop; that is, it is not automatically
forwarded by intermediaries. As a result, it might not work
easily (or at all) with proxies, reverse proxies, and Content
Delivery Networks.
o Server push can have negative performance impact on HTTP when used
incorrectly; in particular, if there is contention with resources
that have actually been requested by the client.
o Server push is implemented differently in different clients,
especially regarding interaction with HTTP caching, and
capabilities might vary.
o 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.
o Server push is not supported in HTTP/1.1 or HTTP/1.0.
o Server push does not form part of the "core" semantics of HTTP,
and therefore might not be supported by future versions of the
protocol.
Applications wishing to optimise cases where the client can perform
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 [RFC7540], Section 8.2, to avoid
cross-origin push attacks.
5. IANA Considerations 5. IANA Considerations
This document has no requirements for IANA. This document has no requirements for IANA.
6. Security Considerations 6. Security Considerations
Section 4.10 discusses the impact of using stateful mechanisms in the Section 4.10 discusses the impact of using stateful mechanisms in the
protocol as ambient authority, and suggests a mitigation. protocol as ambient authority, and suggests a mitigation.
Section 4.4.2 requires support for 'https' URLs, and discourages the Section 4.4.2 requires support for 'https' URLs, and discourages the
use of 'http' URLs, to provide authentication, integrity and use of 'http' URLs, to provide authentication, integrity and
confidentiality, as well as mitigate pervasive monitoring attacks. confidentiality, as well as mitigate pervasive monitoring attacks.
Section 4.12 highlights the implications of Web browsers' Section 4.12 highlights the implications of Web browsers'
capabilities on applications that use HTTP. capabilities on applications that use HTTP.
Section 4.13 discusses the issues that arise when applications are Section 4.13 discusses the issues that arise when applications are
deployed on the same origin as Web sites (and other applications). deployed on the same origin as Web sites (and other applications).
Section 4.14 highlights risks of using HTTP/2 server push in a manner
other than specified.
Applications that use HTTP in a manner that involves modification of Applications that use HTTP in a manner that involves modification of
implementations - for example, requiring support for a new URL implementations - for example, requiring support for a new URL
scheme, or a non-standard method - risk having those implementations scheme, or a non-standard method - risk having those implementations
"fork" from their parent HTTP implementations, with the possible "fork" from their parent HTTP implementations, with the possible
result that they do not benefit from patches and other security result that they do not benefit from patches and other security
improvements incorporated upstream. improvements incorporated upstream.
7. References 7. References
7.1. Normative References 7.1. Normative References
skipping to change at page 24, line 31 skipping to change at page 26, line 41
7.2. Informative References 7.2. Informative References
[CSP] West, M., "Content Security Policy Level 3", World Wide [CSP] West, M., "Content Security Policy Level 3", World Wide
Web Consortium WD WD-CSP3-20160913, September 2016, Web Consortium WD WD-CSP3-20160913, September 2016,
<https://www.w3.org/TR/2016/WD-CSP3-20160913>. <https://www.w3.org/TR/2016/WD-CSP3-20160913>.
[FETCH] WHATWG, "Fetch - Living Standard", n.d., [FETCH] WHATWG, "Fetch - Living Standard", n.d.,
<https://fetch.spec.whatwg.org>. <https://fetch.spec.whatwg.org>.
[FTP] Postel, J. and J. Reynolds, "File Transfer Protocol",
STD 9, RFC 959, DOI 10.17487/RFC0959, October 1985,
<https://www.rfc-editor.org/info/rfc959>.
[HTML5] WHATWG, "HTML - Living Standard", n.d., [HTML5] WHATWG, "HTML - Living Standard", n.d.,
<https://html.spec.whatwg.org>. <https://html.spec.whatwg.org>.
[I-D.ietf-httpbis-header-structure] [I-D.ietf-httpbis-header-structure]
Nottingham, M. and P. Kamp, "Structured Headers for HTTP", Nottingham, M. and P. Kamp, "Structured Headers for HTTP",
draft-ietf-httpbis-header-structure-04 (work in progress), draft-ietf-httpbis-header-structure-04 (work in progress),
March 2018. March 2018.
[IPP] Sweet, M. and I. McDonald, "Internet Printing
Protocol/1.1: Model and Semantics", RFC 8011,
DOI 10.17487/RFC8011, January 2017,
<https://www.rfc-editor.org/info/rfc8011>.
[REFERRER-POLICY] [REFERRER-POLICY]
Eisinger, J. and E. Stark, "Referrer Policy", World Wide Eisinger, J. and E. Stark, "Referrer Policy", World Wide
Web Consortium CR CR-referrer-policy-20170126, January Web Consortium CR CR-referrer-policy-20170126, January
2017, 2017,
<https://www.w3.org/TR/2017/CR-referrer-policy-20170126>. <https://www.w3.org/TR/2017/CR-referrer-policy-20170126>.
[RESTCONF]
Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
<https://www.rfc-editor.org/info/rfc8040>.
[RFC0793] Postel, J., "Transmission Control Protocol", STD 7, [RFC0793] Postel, J., "Transmission Control Protocol", STD 7,
RFC 793, DOI 10.17487/RFC0793, September 1981, RFC 793, DOI 10.17487/RFC0793, September 1981,
<https://www.rfc-editor.org/info/rfc793>. <https://www.rfc-editor.org/info/rfc793>.
[RFC3205] Moore, K., "On the use of HTTP as a Substrate", BCP 56, [RFC3205] Moore, K., "On the use of HTTP as a Substrate", BCP 56,
RFC 3205, DOI 10.17487/RFC3205, February 2002, RFC 3205, DOI 10.17487/RFC3205, February 2002,
<https://www.rfc-editor.org/info/rfc3205>. <https://www.rfc-editor.org/info/rfc3205>.
[RFC4367] Rosenberg, J., Ed. and IAB, "What's in a Name: False [RFC4367] Rosenberg, J., Ed. and IAB, "What's in a Name: False
Assumptions about DNS Names", RFC 4367, Assumptions about DNS Names", RFC 4367,
skipping to change at page 26, line 13 skipping to change at page 28, line 17
<https://www.rfc-editor.org/info/rfc6455>. <https://www.rfc-editor.org/info/rfc6455>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
October 2013, <https://www.rfc-editor.org/info/rfc7049>. October 2013, <https://www.rfc-editor.org/info/rfc7049>.
[RFC7258] Farrell, S. and H. Tschofenig, "Pervasive Monitoring Is an [RFC7258] Farrell, S. and H. Tschofenig, "Pervasive Monitoring Is an
Attack", BCP 188, RFC 7258, DOI 10.17487/RFC7258, May Attack", BCP 188, RFC 7258, DOI 10.17487/RFC7258, May
2014, <https://www.rfc-editor.org/info/rfc7258>. 2014, <https://www.rfc-editor.org/info/rfc7258>.
[RFC7538] Reschke, J., "The Hypertext Transfer Protocol Status Code
308 (Permanent Redirect)", RFC 7538, DOI 10.17487/RFC7538,
April 2015, <https://www.rfc-editor.org/info/rfc7538>.
[RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines
and Registration Procedures for URI Schemes", BCP 35, and Registration Procedures for URI Schemes", BCP 35,
RFC 7595, DOI 10.17487/RFC7595, June 2015, RFC 7595, DOI 10.17487/RFC7595, June 2015,
<https://www.rfc-editor.org/info/rfc7595>. <https://www.rfc-editor.org/info/rfc7595>.
[RFC7605] Touch, J., "Recommendations on Using Assigned Transport [RFC7605] Touch, J., "Recommendations on Using Assigned Transport
Port Numbers", BCP 165, RFC 7605, DOI 10.17487/RFC7605, Port Numbers", BCP 165, RFC 7605, DOI 10.17487/RFC7605,
August 2015, <https://www.rfc-editor.org/info/rfc7605>. August 2015, <https://www.rfc-editor.org/info/rfc7605>.
[RFC7616] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP [RFC7616] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP
skipping to change at page 26, line 40 skipping to change at page 28, line 48
[RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP
APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016,
<https://www.rfc-editor.org/info/rfc7807>. <https://www.rfc-editor.org/info/rfc7807>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259, Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017, DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>. <https://www.rfc-editor.org/info/rfc8259>.
[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>.
[SECCTXT] West, M., "Secure Contexts", World Wide Web Consortium CR [SECCTXT] West, M., "Secure Contexts", World Wide Web Consortium CR
CR-secure-contexts-20160915, September 2016, CR-secure-contexts-20160915, September 2016,
<https://www.w3.org/TR/2016/CR-secure-contexts-20160915>. <https://www.w3.org/TR/2016/CR-secure-contexts-20160915>.
[SMTP] Klensin, J., Ed., "Simple Mail Transfer Protocol",
RFC 2821, DOI 10.17487/RFC2821, April 2001,
<https://www.rfc-editor.org/info/rfc2821>.
[TELNET] Postel, J. and J. Reynolds, "Telnet Protocol
Specification", STD 8, RFC 854, DOI 10.17487/RFC0854, May
1983, <https://www.rfc-editor.org/info/rfc854>.
[XML] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and [XML] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and
F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth
Edition)", World Wide Web Consortium Recommendation REC- Edition)", World Wide Web Consortium Recommendation REC-
xml-20081126, November 2008, xml-20081126, November 2008,
<http://www.w3.org/TR/2008/REC-xml-20081126>. <http://www.w3.org/TR/2008/REC-xml-20081126>.
7.3. URIs 7.3. URIs
[1] https://lists.w3.org/Archives/Public/ietf-http-wg/ [1] https://lists.w3.org/Archives/Public/ietf-http-wg/
 End of changes. 35 change blocks. 
96 lines changed or deleted 185 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/