draft-ietf-httpbis-bcp56bis-15.txt   draft-ietf-httpbis-bcp56bis-latest.txt 
HTTP Working Group M. Nottingham HTTP Working Group M. Nottingham
Internet-Draft August 27, 2021 Internet-Draft October 16, 2021
Obsoletes: 3205 (if approved) Obsoletes: 3205 (if approved)
Intended status: Best Current Practice Intended status: Best Current Practice
Expires: February 28, 2022 Expires: April 19, 2022
Building Protocols with HTTP Building Protocols with HTTP
draft-ietf-httpbis-bcp56bis-15 draft-ietf-httpbis-bcp56bis-latest
Abstract Abstract
Applications often use HTTP as a substrate to create HTTP-based APIs. Applications often use HTTP as a substrate to create HTTP-based APIs.
This document specifies best practices for writing specifications This document specifies best practices for writing specifications
that use HTTP to define new application protocols. It is written that use HTTP to define new application protocols. It is written
primarily to guide IETF efforts to define application protocols using primarily to guide IETF efforts to define application protocols using
HTTP for deployment on the Internet, but might be applicable in other HTTP for deployment on the Internet, but might be applicable in other
situations. situations.
skipping to change at page 2, line 4 skipping to change at page 2, line 4
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 February 28, 2022. This Internet-Draft will expire on April 19, 2022.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2021 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 5, line 51 skipping to change at page 5, line 51
See Section 4.2 for more details. See Section 4.2 for more details.
3.2. Links 3.2. Links
Another common practice is assuming that the HTTP server's name space Another common practice is assuming that the HTTP server's name space
(or a portion thereof) is exclusively for the use of a single (or a portion thereof) is exclusively for the use of a single
application. This effectively overlays special, application-specific application. This effectively overlays special, application-specific
semantics onto that space, precludes other applications from using semantics onto that space, precludes other applications from using
it. it.
As explained in [RFC8820], such "squatting" on a part of the URL As explained in [BCP190], such "squatting" on a part of the URL space
space by a standard usurps the server's authority over its own by a standard usurps the server's authority over its own resources,
resources, can cause deployment issues, and is therefore bad practice can cause deployment issues, and is therefore bad practice in
in standards. standards.
Instead of statically defining URI components like paths, it is Instead of statically defining URI components like paths, it is
RECOMMENDED that applications using HTTP define and use links RECOMMENDED that applications using HTTP define and use links
[WEB-LINKING] to allow flexibility in deployment. [WEB-LINKING] to 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 especially when an application is to have multiple implementations
and/or deployments (as is often the case for those that are and/or deployments (as is often the case for those that are
standardised). standardised).
skipping to change at page 10, line 8 skipping to change at page 10, line 8
that are usually negotiated to be supported by clients. For example, that are usually negotiated to be supported by clients. For example,
requiring that clients support responses with a certain content- requiring that clients support responses with a certain content-
coding ([HTTP], Section 8.4.1) instead of negotiating for it ([HTTP], coding ([HTTP], Section 8.4.1) instead of negotiating for it ([HTTP],
Section 12.5.3) means that otherwise conformant clients cannot Section 12.5.3) means that otherwise conformant clients cannot
interoperate with the application. Applications can encourage the interoperate with the application. Applications can encourage the
implementation of such features, though. implementation of such features, though.
4.4. Specifying URLs 4.4. Specifying URLs
In HTTP, the resources that clients interact with are identified with In HTTP, the resources that clients interact with are identified with
URLs [URL]. As [RFC8820] explains, parts of the URL are designed to URLs [URL]. As [BCP190] explains, parts of the URL are designed to
be under the control of the owner (also known as the "authority") of be under the control of the owner (also known as the "authority") of
that server, to give them the flexibility in deployment. that server, to give them the flexibility in deployment.
This means that in most cases, specifications for applications that This means that in most cases, specifications for applications that
use HTTP won't contain fixed application URLs or paths; while it is use HTTP won't contain fixed application URLs or paths; while it is
common practice for a specification of a single-deployment API to common practice for a specification of a single-deployment API to
specify the path prefix "/app/v1" (for example), doing so in an IETF specify the path prefix "/app/v1" (for example), doing so in an IETF
specification is inappropriate. specification is inappropriate.
Therefore, the specification writer needs some mechanism to allow Therefore, the specification writer needs some mechanism to allow
skipping to change at page 10, line 45 skipping to change at page 10, line 45
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, or through another discovery be done in a configuration document, or through 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.
An application cannot define a fixed prefix for its URL paths; see An application cannot define a fixed prefix for its URL paths; see
[RFC8820]. Instead, a specification for such an application can use [BCP190]. Instead, a specification for such an application can use
one of the following strategies: one of the following strategies:
o Register a Well-Known URI [WELL-KNOWN-URI] as an entry point for o Register a Well-Known URI [WELL-KNOWN-URI] as an entry point for
that application. This provides a fixed path on every potential that application. This provides a fixed path on every potential
server that will not collide with other applications. server that will not collide with other applications.
o Enable the server authority to convey a URI Template o Enable the server authority to convey a URI Template
[URI-TEMPLATE] or similar mechanism for generating a URL for an [URI-TEMPLATE] or similar mechanism for generating a URL for an
entry point. For example, this might be done in a configuration entry point. For example, this might be done in a configuration
document or other artefact. document or other artefact.
skipping to change at page 18, line 42 skipping to change at page 18, line 42
namespace for the application; see [RFC6648] for related namespace for the application; see [RFC6648] for related
considerations. considerations.
The semantics of existing HTTP header fields MUST NOT be re-defined The semantics of existing HTTP header fields MUST NOT be re-defined
without updating their registration or defining an extension to them without updating their registration or defining an extension to them
(if allowed). For example, an application using HTTP cannot specify (if allowed). For example, an application using HTTP cannot specify
that the "Location" header field has a special meaning in a certain that the "Location" header field has a special meaning in a certain
context. context.
See Section 4.9 for the interaction between header fields and HTTP See Section 4.9 for the interaction between header fields and HTTP
caching; in particular, request header fields that are used to caching; in particular, request header fields that are used to choose
"select" a response have impact there, and need to be carefully (as per Section 4.1 of [HTTP-CACHING]) a response have impact there,
considered. and need to be carefully considered.
See Section 4.10 for considerations regarding header fields that See Section 4.10 for considerations regarding header fields that
carry application state (e.g., Cookie). carry application state (e.g., Cookie).
4.8. Defining Message Content 4.8. Defining Message Content
Common syntactic conventions for message contents include JSON Common syntactic conventions for message contents include JSON
[JSON], XML [XML], and CBOR [RFC8949]. Best practices for their use [JSON], XML [XML], and CBOR [RFC8949]. Best practices for their use
are out of scope for this document. are out of scope for this document.
skipping to change at page 24, line 51 skipping to change at page 24, line 51
For example, if Cookies [COOKIES] are used to carry application For example, if Cookies [COOKIES] are used to carry application
state, they will be sent with all requests to the origin by default state, they will be sent with all requests to the origin by default
(unless scoped by path), and the application might receive cookies (unless scoped by path), and the application might receive cookies
from other applications on the origin. This can lead to security from other applications on the origin. This can lead to security
issues, as well as collision in cookie names. issues, as well as collision in cookie names.
One solution to these issues is to require a dedicated hostname for One solution to these issues is to require a dedicated hostname for
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 [RFC8820] for details). and enables them to be "mixed" together (See [BCP190] 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 [HTTP], or other origin-wide HTTP mechanisms, authentication realms [HTTP], or other origin-wide HTTP mechanisms,
applications using HTTP should not mandate the use of a particular applications using HTTP should not mandate the use of a particular
name, but instead let deployments configure them. Consideration name, but instead let deployments configure them. Consideration
should be given to scoping them to part of the origin, using their should be given to scoping them to part of the origin, using their
specified mechanisms for doing so. specified mechanisms for doing so.
skipping to change at page 28, line 20 skipping to change at page 28, line 20
be used to profile the underlying hardware, creating a unique be used to profile the underlying hardware, creating a unique
identifier for the system. Applications are advised to avoid identifier for the system. Applications are advised to avoid
allowing the use of mobile code where possible; when it cannot be allowing the use of mobile code where possible; when it cannot be
avoided, the resulting system's security properties need be carefully avoided, the resulting system's security properties need be carefully
scrutinised. scrutinised.
7. References 7. References
7.1. Normative References 7.1. Normative References
[BCP190] Consisting of: [RFC8820],
<https://www.rfc-editor.org/info/bcp190>.
[HTTP] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP [HTTP] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP
Semantics", draft-ietf-httpbis-semantics-18 (work in Semantics", draft-ietf-httpbis-semantics-19 (work in
progress), August 2021. progress), September 2021.
[HTTP-CACHING] [HTTP-CACHING]
Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP
Caching", draft-ietf-httpbis-cache-18 (work in progress), Caching", draft-ietf-httpbis-cache-19 (work in progress),
August 2021. September 2021.
[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>.
[RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454,
DOI 10.17487/RFC6454, December 2011, DOI 10.17487/RFC6454, December 2011,
<https://www.rfc-editor.org/info/rfc6454>. <https://www.rfc-editor.org/info/rfc6454>.
skipping to change at page 29, line 42 skipping to change at page 29, line 46
<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>.
[HTTP-PRIORITY] [HTTP-PRIORITY]
Oku, K. and L. Pardue, "Extensible Prioritization Scheme Oku, K. and L. Pardue, "Extensible Prioritization Scheme
for HTTP", draft-ietf-httpbis-priority-04 (work in for HTTP", draft-ietf-httpbis-priority-06 (work in
progress), July 2021. progress), September 2021.
[HTTP11] Fielding, R. T., Nottingham, M., and J. Reschke, [HTTP11] Fielding, R. T., Nottingham, M., and J. Reschke,
"HTTP/1.1", draft-ietf-httpbis-messaging-18 (work in "HTTP/1.1", draft-ietf-httpbis-messaging-19 (work in
progress), August 2021. progress), September 2021.
[HTTP2] Thomson, M. and C. Benfield, "Hypertext Transfer Protocol [HTTP2] Thomson, M. and C. Benfield, "Hypertext Transfer Protocol
Version 2 (HTTP/2)", draft-ietf-httpbis-http2bis-03 (work Version 2 (HTTP/2)", draft-ietf-httpbis-http2bis-05 (work
in progress), July 2021. in progress), September 2021.
[HTTP3] Bishop, M., "Hypertext Transfer Protocol Version 3 [HTTP3] Bishop, M., "Hypertext Transfer Protocol Version 3
(HTTP/3)", draft-ietf-quic-http-34 (work in progress), (HTTP/3)", draft-ietf-quic-http-34 (work in progress),
February 2021. February 2021.
[JSON] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data [JSON] 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>.
 End of changes. 15 change blocks. 
24 lines changed or deleted 27 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/