< draft-ietf-httpbis-bcp56bis-06.txt   draft-ietf-httpbis-bcp56bis-07.txt >
HTTP M. Nottingham HTTP M. Nottingham
Internet-Draft July 1, 2018 Internet-Draft October 21, 2018
Obsoletes: 3205 (if approved) Obsoletes: 3205 (if approved)
Intended status: Best Current Practice Intended status: Best Current Practice
Expires: January 2, 2019 Expires: April 24, 2019
Building Protocols with HTTP Building Protocols with HTTP
draft-ietf-httpbis-bcp56bis-06 draft-ietf-httpbis-bcp56bis-07
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 such protocols' use of HTTP when they are defined for diverse
implementation and broad deployment (e.g., in standards efforts).
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 43 skipping to change at page 1, line 44
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 January 2, 2019. This Internet-Draft will expire on April 24, 2019.
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 24 skipping to change at page 2, line 29
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4
2. Is HTTP Being Used? . . . . . . . . . . . . . . . . . . . . . 4 2. Is HTTP Being Used? . . . . . . . . . . . . . . . . . . . . . 4
3. What's Important About HTTP . . . . . . . . . . . . . . . . . 5 3. What's Important About HTTP . . . . . . . . . . . . . . . . . 5
3.1. Generic Semantics . . . . . . . . . . . . . . . . . . . . 5 3.1. Generic Semantics . . . . . . . . . . . . . . . . . . . . 5
3.2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.3. Rich Functionality . . . . . . . . . . . . . . . . . . . 7 3.3. Rich Functionality . . . . . . . . . . . . . . . . . . . 7
4. Best Practices for Using HTTP . . . . . . . . . . . . . . . . 7 4. Best Practices for Using HTTP . . . . . . . . . . . . . . . . 8
4.1. Specifying the Use of HTTP . . . . . . . . . . . . . . . 8 4.1. Specifying the Use of HTTP . . . . . . . . . . . . . . . 8
4.2. Defining HTTP Resources . . . . . . . . . . . . . . . . . 8 4.2. Defining HTTP Resources . . . . . . . . . . . . . . . . . 9
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 . . . . . . . . . . . . . . . . . . . . . . 13
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 . . . . . . . . . . . . . . . . . . . . 15
4.6.1. Redirection . . . . . . . . . . . . . . . . . . . . . 16 4.6.1. Redirection . . . . . . . . . . . . . . . . . . . . . 16
4.7. HTTP Header Fields . . . . . . . . . . . . . . . . . . . 17 4.7. HTTP Header Fields . . . . . . . . . . . . . . . . . . . 17
4.8. Defining Message Payloads . . . . . . . . . . . . . . . . 18 4.8. Defining Message Payloads . . . . . . . . . . . . . . . . 18
4.9. HTTP Caching . . . . . . . . . . . . . . . . . . . . . . 18 4.9. HTTP Caching . . . . . . . . . . . . . . . . . . . . . . 18
4.10. Application State . . . . . . . . . . . . . . . . . . . . 20 4.10. Application State . . . . . . . . . . . . . . . . . . . . 20
4.11. Client Authentication . . . . . . . . . . . . . . . . . . 20 4.11. Client Authentication . . . . . . . . . . . . . . . . . . 20
4.12. Co-Existing with Web Browsing . . . . . . . . . . . . . . 21 4.12. Co-Existing with Web Browsing . . . . . . . . . . . . . . 21
4.13. Application Boundaries . . . . . . . . . . . . . . . . . 22 4.13. Application Boundaries . . . . . . . . . . . . . . . . . 22
4.14. Server Push . . . . . . . . . . . . . . . . . . . . . . . 23 4.14. Server Push . . . . . . . . . . . . . . . . . . . . . . . 23
4.15. Versioning and Evolution . . . . . . . . . . . . . . . . 24 4.15. Versioning and Evolution . . . . . . . . . . . . . . . . 24
skipping to change at page 3, line 33 skipping to change at page 3, line 37
o availability 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.
These protocols are often ad hoc; they are intended for only These protocols are often ad hoc; they are intended for only
deployment by one or a few servers, and consumption by a limited set deployment by one or a few servers, and consumption by a limited set
of clients. As a result, a body of practices and tools has arisen of clients. Perhaps because of the factors cited above, a body of
around defining HTTP-based APIs that favours these conditions. practices and tools has arisen around defining HTTP-based APIs that
favours these conditions.
However, when such a protocol is standarised, it is typically However, when such an application has multiple, separate
deployed on multiple uncoordinated servers, implemented a number of implementations of the server component, is deployed on multiple
times, and consumed by a broader variety of clients. Such diversity uncoordinated servers, and is consumed by diverse clients - as is
brings a different set of concerns, and tools and practices intended often the case for standards efforts to define new HTTP APIs - tools
for a single-server deployment might not be suitable. and practices intended for limited deployment can become unsuitable.
For example, HTTP-based APIs deployed in these circumstances need to For example, because implementations (both client and server) will
more carefully consider how extensibility and evolution of the implement and evolve at different paces, a HTTP-based API might need
service will be handled, how different deployment requirements will to more carefully consider how extensibility of the service will be
be accommodated, and how clients will evolve with the API. handled, and how different deployment requirements will be
accommodated.
More generally, application protocols using HTTP face a number of More generally, application protocols using HTTP face a number of
design decisions, including: design decisions, including:
o Should it define a new URL scheme? Use new ports? o Should it define a new URL scheme? Use new 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?
skipping to change at page 12, line 47 skipping to change at page 13, line 10
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 in the
IETF Review (see [RFC7232]), and are also required to be generic. HTTP Method Registry with IETF Review (see [RFC7231]), and are also
That means that they need to be potentially applicable to all required to be generic. That means that they need to be potentially
resources, not just those of one application. applicable to all 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.
4.5.1. GET 4.5.1. GET
skipping to change at page 14, line 38 skipping to change at page 14, line 47
do not expose the ability to respond to OPTIONS requests without do not expose the ability to respond to OPTIONS requests without
significant effort. significant effort.
Instead of OPTIONS, one of these alternative approaches might be more Instead of OPTIONS, one of these alternative approaches might be more
appropriate: appropriate:
o For server-wide metadata, create a well-known URI [RFC5785], or o For server-wide metadata, create a well-known URI [RFC5785], or
using an already existing one if it's appropriate (e.g., HostMeta using an already existing one if it's appropriate (e.g., HostMeta
[RFC6415]). [RFC6415]).
o For metadata about a specific resource, use a Link response o For metadata about a specific resource, create a separate resource
header, or a link in the representation format for that resource. and link to it using a Link response header or a link serialised
See [RFC8288]. Note that the Link header is available on HEAD into the representation's body. See [RFC8288]. Note that the
responses, which is useful if the client wants to discover a Link header is available on HEAD responses, which is useful if the
resource's capabilities before they interact with it. client wants to discover a resource's capabilities before they
interact with it.
4.6. HTTP Status Codes 4.6. HTTP Status Codes
The primary function of a HTTP status code is to convey semantics for The primary function of a HTTP status code is to convey semantics for
the benefit of generic HTTP software, not to convey application- the benefit of generic HTTP software, not to convey application-
specific semantics. specific semantics.
In particular, status codes are often generated or overwritten by In particular, status codes are often generated or overwritten by
intermediaries, as well as server and client implementations; for intermediaries, as well as server and client implementations; for
example, when network errors are encountered, a captive portal is example, when network errors are encountered, a captive portal is
skipping to change at page 21, line 15 skipping to change at page 21, line 24
4.12. Co-Existing with Web Browsing 4.12. Co-Existing with Web Browsing
Even if there is not an intent for an application that uses HTTP to Even if there is not an intent for an application that uses HTTP to
be used with a Web browser, its resources will remain available to be used with a Web browser, its resources will remain available to
browsers and other HTTP clients. browsers and other HTTP clients.
This means that all such applications need to consider how browsers This means that all such applications need to consider how browsers
will interact with them, particularly regarding security. will interact with them, particularly regarding security.
For example, if an application's state can be changed using a POST For example, if an application's state can be changed using a POST
request, a Web browser can easily be coaxed into making that request request, a Web browser can easily be coaxed into cross-site request
by a HTML form on an arbitrary Web site. forgery (CSRF) from arbitrary Web sites.
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 (XSS) attack is possible, whereby an attacker can inject code into
browser and access data and capabilities on that origin. the 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 actually as a Web application, and to follow consider the application actually as a Web application, and to follow
best 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
skipping to change at page 23, line 8 skipping to change at page 23, line 16
the application, so that it has a unique origin. However, it is the application, so that it has a unique origin. However, it is
often desirable to allow multiple applications to be deployed on a often desirable to allow multiple applications to be deployed on a
single hostname; doing so provides the most deployment flexibility single hostname; doing so provides the most deployment flexibility
and enables them to be "mixed" together (See [RFC7320] for details). and enables them to be "mixed" together (See [RFC7320] for details).
Therefore, applications using HTTP should strive to allow multiple Therefore, applications using HTTP should strive to allow multiple
applications on an origin. applications on an origin.
To enable this, when specifying the use of Cookies, HTTP To enable this, when specifying the use of Cookies, HTTP
authentication realms [RFC7235], or other origin-wide HTTP authentication realms [RFC7235], or other origin-wide HTTP
mechanisms, applications using HTTP SHOULD NOT mandate the use of a mechanisms, applications using HTTP SHOULD NOT mandate the use of a
particular identifier, but instead let deployments configure them. particular name, 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 4.14. Server Push
skipping to change at page 28, line 7 skipping to change at page 28, line 13
<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>.
[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-06 (work in progress), draft-ietf-httpbis-header-structure-07 (work in progress),
June 2018. July 2018.
[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>.
[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>.
 End of changes. 19 change blocks. 
36 lines changed or deleted 41 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/