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 December 4, 2019
Obsoletes: 3205 (if approved) Obsoletes: 3205 (if approved)
Intended status: Best Current Practice Intended status: Best Current Practice
Expires: May 3, 2020 Expires: June 6, 2020
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 June 6, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 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 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-06 (work in progress),
July 2019. November 2019.
[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-06 (work in
progress), July 2019. progress), November 2019.
[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-06 (work in
progress), July 2019. progress), November 2019.
[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-02 (work in progress), October 2019.
[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 41 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>.
[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-13 (work in progress), draft-ietf-httpbis-header-structure-14 (work in progress),
August 2019. October 2019.
[I-D.ietf-httpbis-rfc6265bis] [I-D.ietf-httpbis-rfc6265bis]
Barth, A. and M. West, "Cookies: HTTP State Management Barth, A. and M. West, "Cookies: HTTP State Management
Mechanism", draft-ietf-httpbis-rfc6265bis-03 (work in Mechanism", draft-ietf-httpbis-rfc6265bis-03 (work in
progress), April 2019. progress), April 2019.
[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,
 End of changes. 12 change blocks. 
21 lines changed or deleted 23 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/