draft-ietf-httpbis-bcp56bis-09.txt   draft-ietf-httpbis-bcp56bis-latest.txt 
HTTP Working Group M. Nottingham HTTP Working Group M. Nottingham
Internet-Draft October 31, 2019 Internet-Draft September 17, 2020
Obsoletes: 3205 (if approved) Obsoletes: 3205 (if approved)
Intended status: Best Current Practice Intended status: Best Current Practice
Expires: May 3, 2020 Expires: March 21, 2021
Building Protocols with HTTP Building Protocols with HTTP
draft-ietf-httpbis-bcp56bis-09 draft-ietf-httpbis-bcp56bis-latest
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 writing specifications that use HTTP to define new application for writing specifications that use HTTP to define new application
protocols, especially when they are defined for diverse protocols, especially when they are defined for diverse
implementation and broad deployment (e.g., in standards efforts). implementation and broad deployment (e.g., in standards efforts).
Note to Readers Note to Readers
skipping to change at page 1, line 45 skipping to change at page 1, line 45
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 May 3, 2020. This Internet-Draft will expire on March 21, 2021.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2020 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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
skipping to change at page 4, line 11 skipping to change at page 4, line 11
is consumed by diverse clients - as is often the case for HTTP APIs is consumed by diverse clients - as is often the case for HTTP APIs
defined by standards efforts - tools and practices intended for defined by standards efforts - tools and practices intended for
limited deployment can become unsuitable. limited deployment can become unsuitable.
This is largely because implementations (both client and server) will This is largely because implementations (both client and server) will
implement and evolve at different paces. As a result, such an HTTP- implement and evolve at different paces. As a result, such an HTTP-
based API will need to more carefully consider how extensibility of based API will need to more carefully consider how extensibility of
the service will be handled and how different deployment requirements the service will be handled and how different deployment requirements
will be accommodated. will be accommodated.
More generally, application protocols using HTTP face a number of More generally, an application protocol using HTTP faces a number of
design decisions, including: design decisions, including:
o Should it define a new URI scheme? Use new ports? o Should it define a new URI 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
skipping to change at page 6, line 20 skipping to change at page 6, line 20
application. It also allows people to leverage their knowledge of application. It also allows people to leverage their knowledge of
HTTP semantics without special-casing them for a particular HTTP semantics without special-casing them for a particular
application. application.
Therefore, applications that use HTTP MUST NOT re-define, refine or Therefore, applications that use HTTP MUST NOT re-define, refine or
overlay the semantics of generic protocol elements such as methods, overlay the semantics of generic protocol elements such as methods,
status codes or existing header fields. Instead, they should focus status codes or existing header fields. Instead, they should focus
their specifications on protocol elements that are specific to that their specifications on protocol elements that are specific to that
application; namely their HTTP resources. application; namely their HTTP resources.
For example, when writing a specification, it's often tempting to When writing a specification, it's often tempting to specify exactly
specify exactly how HTTP is to be implemented, supported and used. how HTTP is to be implemented, supported and used. However, this can
easily lead to an unintended profile of HTTP's behaviour. For
However, this can easily lead to an unintended profile of HTTP's example, it's common to see specifications with language like this:
behaviour. For example, it's common to see specifications with
language like this:
A `POST` request MUST result in a `201 Created` response. A `POST` request MUST result in a `201 Created` response.
This forms an expectation in the client that the response will always This forms an expectation in the client that the response will always
be "201 Created", when in fact there are a number of reasons why the be "201 Created", when in fact there are a number of reasons why the
status code might differ in a real deployment; for example, there status code might differ in a real deployment; for example, there
might be a proxy that requires authentication, or a server-side might be a proxy that requires authentication, or a server-side
error, or a redirection. If the client does not anticipate this, the error, or a redirection. If the client does not anticipate this, the
application's deployment is brittle. application's deployment is brittle.
skipping to change at page 11, line 40 skipping to change at page 11, line 40
about that particular deployment, potentially including links to about that particular deployment, potentially including links to
other relevant resources. Doing so assures that the deployment is as other relevant resources. Doing so assures that the deployment is as
flexible as possible (potentially spanning multiple servers), allows flexible as possible (potentially spanning multiple servers), allows
evolution, and also gives the application the opportunity to tailor evolution, and also gives the application the opportunity to tailor
the 'discovery document' to the client. the 'discovery document' to the client.
There are a few common patterns for discovering that initial URL. There are a few common patterns for discovering that initial URL.
The most straightforward mechanism for URL discovery is to configure The most straightforward mechanism for URL discovery is to configure
the client with (or otherwise convey to it) a full URL. This might the client with (or otherwise convey to it) a full URL. This might
be done in a configuration document, in DNS or mDNS, or through be done in a configuration document, or through another discovery
another discovery mechanism. mechanism.
However, if the client only knows the server's hostname and the 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 identity of the application, there needs to be some way to derive the
initial URL from that information. initial URL from that information.
Applications MUST NOT define a fixed prefix for its URL paths; for An application cannot define a fixed prefix for its URL paths; see
reasons explained in [RFC7320], this is bad practice. [I-D.nottingham-rfc7320bis]. Instead, a specification for such an
application can use one of the following strategies:
Instead, a specification for such an application can use one of the
following strategies:
o Register a Well-Known URI [I-D.nottingham-rfc5785bis] as an entry o Register a Well-Known URI [I-D.nottingham-rfc5785bis] as an entry
point for that application. This provides a fixed path on every point for that application. This provides a fixed path on every
potential server that will not collide with other applications. potential server that will not collide with other applications.
o Enable the server authority to convey a URL Template [RFC6570] or o Enable the server authority to convey a URL Template [RFC6570] or
similar mechanism for generating a URL for an entry point. For similar mechanism for generating a URL for an entry point. For
example, this might be done in a DNS RR, a configuration document, example, this might be done in a configuration document or other
or other artefact. artefact.
Once the discovery document is located, it can be fetched, cached for Once the discovery document is located, it can be fetched, cached for
later reuse (if allowed by its metadata), and used to locate other later reuse (if allowed by its metadata), and used to locate other
resources that are relevant to the application, using full URIs or resources that are relevant to the application, using full URIs or
URL Templates. URL Templates.
In some cases, an application may not wish to use such a discovery In some cases, an application may not wish to use such a discovery
document; for example, when communication is very brief, or when the document; for example, when communication is very brief, or when the
latency concerns of doing so precludes the use of a discovery latency concerns of doing so precludes the use of a discovery
document. These situations can be addressed by placing all of the document. These situations can be addressed by placing all of the
skipping to change at page 28, line 7 skipping to change at page 28, line 7
avoid allowing the use of mobile code where possible; when it cannot avoid allowing the use of mobile code where possible; when it cannot
be avoided, the resulting system's security properties need be be avoided, the resulting system's security properties need be
carefully scrutinised. carefully scrutinised.
7. References 7. References
7.1. Normative References 7.1. Normative References
[I-D.ietf-httpbis-cache] [I-D.ietf-httpbis-cache]
Fielding, R., Nottingham, M., and J. Reschke, "HTTP Fielding, R., Nottingham, M., and J. Reschke, "HTTP
Caching", draft-ietf-httpbis-cache-05 (work in progress), Caching", draft-ietf-httpbis-cache-11 (work in progress),
July 2019. August 2020.
[I-D.ietf-httpbis-messaging] [I-D.ietf-httpbis-messaging]
Fielding, R., Nottingham, M., and J. Reschke, "HTTP/1.1 Fielding, R., Nottingham, M., and J. Reschke, "HTTP/1.1
Messaging", draft-ietf-httpbis-messaging-05 (work in Messaging", draft-ietf-httpbis-messaging-11 (work in
progress), July 2019. progress), August 2020.
[I-D.ietf-httpbis-semantics] [I-D.ietf-httpbis-semantics]
Fielding, R., Nottingham, M., and J. Reschke, "HTTP Fielding, R., Nottingham, M., and J. Reschke, "HTTP
Semantics", draft-ietf-httpbis-semantics-05 (work in Semantics", draft-ietf-httpbis-semantics-11 (work in
progress), July 2019. progress), August 2020.
[I-D.nottingham-rfc5785bis] [I-D.nottingham-rfc5785bis]
Nottingham, M., "Well-Known Uniform Resource Identifiers Nottingham, M., "Well-Known Uniform Resource Identifiers
(URIs)", draft-nottingham-rfc5785bis-11 (work in (URIs)", draft-nottingham-rfc5785bis-11 (work in
progress), April 2019. progress), April 2019.
[I-D.nottingham-rfc7320bis]
Nottingham, M., "URI Design and Ownership", draft-
nottingham-rfc7320bis-03 (work in progress), January 2020.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818,
DOI 10.17487/RFC2818, May 2000, DOI 10.17487/RFC2818, May 2000,
<https://www.rfc-editor.org/info/rfc2818>. <https://www.rfc-editor.org/info/rfc2818>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
skipping to change at page 29, line 10 skipping to change at page 29, line 15
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13, Specifications and Registration Procedures", BCP 13,
RFC 6838, DOI 10.17487/RFC6838, January 2013, RFC 6838, DOI 10.17487/RFC6838, January 2013,
<https://www.rfc-editor.org/info/rfc6838>. <https://www.rfc-editor.org/info/rfc6838>.
[RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan,
"Transport Layer Security (TLS) Application-Layer Protocol "Transport Layer Security (TLS) Application-Layer Protocol
Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301,
July 2014, <https://www.rfc-editor.org/info/rfc7301>. July 2014, <https://www.rfc-editor.org/info/rfc7301>.
[RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, [RFC7320] Nottingham, M., "URI Design and Ownership", RFC 7320,
RFC 7320, DOI 10.17487/RFC7320, July 2014, DOI 10.17487/RFC7320, July 2014,
<https://www.rfc-editor.org/info/rfc7320>. <https://www.rfc-editor.org/info/rfc7320>.
[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
Transfer Protocol Version 2 (HTTP/2)", RFC 7540, Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
DOI 10.17487/RFC7540, May 2015, DOI 10.17487/RFC7540, May 2015,
<https://www.rfc-editor.org/info/rfc7540>. <https://www.rfc-editor.org/info/rfc7540>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
skipping to change at page 29, line 40 skipping to change at page 29, line 45
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>.
[HTML] WHATWG, "HTML - Living Standard", n.d., [HTML] 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 Field Values for
draft-ietf-httpbis-header-structure-13 (work in progress), HTTP", draft-ietf-httpbis-header-structure-19 (work in
August 2019. progress), June 2020.
[I-D.ietf-httpbis-rfc6265bis] [I-D.ietf-httpbis-rfc6265bis]
Barth, A. and M. West, "Cookies: HTTP State Management West, M. and J. Wilander, "Cookies: HTTP State Management
Mechanism", draft-ietf-httpbis-rfc6265bis-03 (work in Mechanism", draft-ietf-httpbis-rfc6265bis-06 (work in
progress), April 2019. progress), April 2020.
[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>.
skipping to change at page 31, line 48 skipping to change at page 31, line 48
<https://www.rfc-editor.org/info/rfc8297>. <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>.
[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>. <https://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/
[2] http://httpwg.github.io/ [2] http://httpwg.github.io/
[3] https://github.com/httpwg/http-extensions/labels/bcp56bis [3] https://github.com/httpwg/http-extensions/labels/bcp56bis
Appendix A. Changes from RFC 3205 Appendix A. Changes from RFC 3205
[RFC3205] captured the Best Current Practice in the early 2000's, [RFC3205] captured the Best Current Practice in the early 2000's,
based on the concerns facing protocol designers at the time. Use of based on the concerns facing protocol designers at the time. Use of
HTTP has changed considerably since then, and as a result this HTTP has changed considerably since then, and as a result this
document is substantially different. As a result, the changes are document is substantially different. As a result, the changes are
too numerous to list individually. too numerous to list individually.
Author's Address Author's Address
Mark Nottingham Mark Nottingham
made in
Prahran, VIC
Australia
Email: mnot@mnot.net Email: mnot@mnot.net
URI: https://www.mnot.net/ URI: https://www.mnot.net/
 End of changes. 19 change blocks. 
36 lines changed or deleted 39 lines changed or added

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