idnits 2.17.00 (12 Aug 2021) /tmp/idnits64084/draft-ietf-httpbis-bcp56bis-11.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document obsoletes RFC3205, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (17 March 2021) is 429 days in the past. Is this intentional? Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-14 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-httpbis-semantics' == Outdated reference: A later version (-10) exists of draft-ietf-httpbis-rfc6265bis-07 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-cache-14 -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-12) exists of draft-ietf-httpbis-priority-03 -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP M. Nottingham 3 Internet-Draft 17 March 2021 4 Obsoletes: 3205 (if approved) 5 Intended status: Best Current Practice 6 Expires: 18 September 2021 8 Building Protocols with HTTP 9 draft-ietf-httpbis-bcp56bis-11 11 Abstract 13 HTTP is often used as a substrate for other application protocols to 14 create HTTP-based APIs. This document specifies best practices for 15 writing specifications that use HTTP to define new application 16 protocols, especially when they are defined for diverse 17 implementation and broad deployment (e.g., in standards efforts). 19 Note to Readers 21 _RFC EDITOR: please remove this section before publication_ 23 Discussion of this draft takes place on the HTTP working group 24 mailing list (ietf-http-wg@w3.org), which is archived at 25 https://lists.w3.org/Archives/Public/ietf-http-wg/ 26 (https://lists.w3.org/Archives/Public/ietf-http-wg/). 28 Working Group information can be found at http://httpwg.github.io/ 29 (http://httpwg.github.io/); source code and issues list for this 30 draft can be found at https://github.com/httpwg/http- 31 extensions/labels/bcp56bis (https://github.com/httpwg/http- 32 extensions/labels/bcp56bis). 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at https://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on 18 September 2021. 50 Copyright Notice 52 Copyright (c) 2021 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 57 license-info) in effect on the date of publication of this document. 58 Please review these documents carefully, as they describe your rights 59 and restrictions with respect to this document. Code Components 60 extracted from this document must include Simplified BSD License text 61 as described in Section 4.e of the Trust Legal Provisions and are 62 provided without warranty as described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 67 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 68 2. Is HTTP Being Used? . . . . . . . . . . . . . . . . . . . . . 4 69 2.1. Non-HTTP Protocols . . . . . . . . . . . . . . . . . . . 5 70 3. What's Important About HTTP . . . . . . . . . . . . . . . . . 5 71 3.1. Generic Semantics . . . . . . . . . . . . . . . . . . . . 6 72 3.2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 6 73 3.3. Rich Functionality . . . . . . . . . . . . . . . . . . . 7 74 4. Best Practices for Specifying the Use of HTTP . . . . . . . . 8 75 4.1. Specifying the Use of HTTP . . . . . . . . . . . . . . . 8 76 4.2. Specifying Server Behaviour . . . . . . . . . . . . . . . 9 77 4.3. Specifying Client Behaviour . . . . . . . . . . . . . . . 10 78 4.4. Specifying URLs . . . . . . . . . . . . . . . . . . . . . 11 79 4.4.1. Discovering an Application's URLs . . . . . . . . . . 11 80 4.4.2. Considering URI Schemes . . . . . . . . . . . . . . . 12 81 4.4.3. Transport Ports . . . . . . . . . . . . . . . . . . . 13 82 4.5. Using HTTP Methods . . . . . . . . . . . . . . . . . . . 14 83 4.5.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 14 84 4.5.2. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . 15 85 4.6. Using HTTP Status Codes . . . . . . . . . . . . . . . . . 16 86 4.6.1. Redirection . . . . . . . . . . . . . . . . . . . . . 17 87 4.7. Specifying HTTP Header Fields . . . . . . . . . . . . . . 18 88 4.8. Defining Message Content . . . . . . . . . . . . . . . . 20 89 4.9. Leveraging HTTP Caching . . . . . . . . . . . . . . . . . 20 90 4.9.1. Freshness . . . . . . . . . . . . . . . . . . . . . . 20 91 4.9.2. Stale Responses . . . . . . . . . . . . . . . . . . . 21 92 4.9.3. Caching and Application Semantics . . . . . . . . . . 21 93 4.9.4. Varying Content Based Upon the Request . . . . . . . 22 94 4.10. Handling Application State . . . . . . . . . . . . . . . 22 95 4.11. Making Multiple Requests . . . . . . . . . . . . . . . . 23 96 4.12. Client Authentication . . . . . . . . . . . . . . . . . . 23 97 4.13. Co-Existing with Web Browsing . . . . . . . . . . . . . . 24 98 4.14. Maintaining Application Boundaries . . . . . . . . . . . 25 99 4.15. Using Server Push . . . . . . . . . . . . . . . . . . . . 26 100 4.16. Allowing Versioning and Evolution . . . . . . . . . . . . 27 101 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 102 6. Security Considerations . . . . . . . . . . . . . . . . . . . 27 103 6.1. Privacy Considerations . . . . . . . . . . . . . . . . . 28 104 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 105 7.1. Normative References . . . . . . . . . . . . . . . . . . 29 106 7.2. Informative References . . . . . . . . . . . . . . . . . 30 107 Appendix A. Changes from RFC 3205 . . . . . . . . . . . . . . . 33 108 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 33 110 1. Introduction 112 HTTP [I-D.ietf-httpbis-semantics] is often used as a substrate for 113 applications other than Web browsing; this is sometimes referred to 114 as creating "HTTP-based APIs", "REST APIs" or just "HTTP APIs". This 115 is done for a variety of reasons, including: 117 * familiarity by implementers, specifiers, administrators, 118 developers and users, 120 * availability of a variety of client, server and proxy 121 implementations, 123 * ease of use, 125 * availability of Web browsers, 127 * reuse of existing mechanisms like authentication and encryption, 129 * presence of HTTP servers and clients in target deployments, and 131 * its ability to traverse firewalls. 133 These protocols are often ad hoc; they are intended for only 134 deployment by one or a few servers, and consumption by a limited set 135 of clients. As a result, a body of practices and tools has arisen 136 around defining HTTP-based APIs that favours these conditions. 138 However, when such an application has multiple, separate 139 implementations, is deployed on multiple uncoordinated servers, and 140 is consumed by diverse clients -- as is often the case for HTTP APIs 141 defined by standards efforts -- tools and practices intended for 142 limited deployment can become unsuitable. 144 This is largely because implementations (both client and server) will 145 implement and evolve at different paces, and because deployments will 146 often have different features and versions available. As a result, 147 the designers of such an HTTP-based API will need to more carefully 148 consider how extensibility of the service will be handled and how 149 different deployment requirements will be accommodated. 151 More generally, an application protocol using HTTP faces a number of 152 design decisions, including: 154 * Should it define a new URI scheme? Use new ports? 156 * Should it use standard HTTP methods and status codes, or define 157 new ones? 159 * How can the maximum value be extracted from the use of HTTP? 161 * How does it coexist with other uses of HTTP -- especially Web 162 browsing? 164 * How can interoperability problems and "protocol dead ends" be 165 avoided? 167 This document contains best current practices for the specification 168 of such applications. Section 2 defines when it applies; Section 3 169 surveys the properties of HTTP that are important to preserve, and 170 Section 4 conveys best practices for the specifying them. 172 It is written primarily to guide IETF efforts to define application 173 protocols using HTTP for deployment on the Internet, but might be 174 applicable in other situations. Note that the requirements herein do 175 not necessarily apply to the development of generic HTTP extensions. 177 1.1. Notational Conventions 179 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 180 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 181 "OPTIONAL" in this document are to be interpreted as described in BCP 182 14 [RFC2119] [RFC8174] when, and only when, they appear in all 183 capitals, as shown here. 185 2. Is HTTP Being Used? 187 Different applications have different goals when using HTTP. The 188 requirements in this document apply when a specification defines an 189 application that: 191 * uses the transport port 80 or 443, or 192 * uses the URI scheme "http" or "https", or 194 * uses an ALPN protocol ID [RFC7301] that generically identifies 195 HTTP (e.g., "http/1.1", "h2", "h2c"), or 197 * updates or modifies the IANA registries defined for HTTP. 199 Additionally, when a specification is using HTTP, all of the 200 requirements of the HTTP protocol suite are in force (in particular, 201 [I-D.ietf-httpbis-semantics], but also other specifications as 202 appropriate). 204 Note that this document is intended to apply to applications, not 205 generic extensions to HTTP, which follow the requirements in the 206 relevant specification. Furthermore, it is intended for applications 207 defined by IETF specifications, although other standards 208 organisations are encouraged to adhere to its requirements. 210 2.1. Non-HTTP Protocols 212 A specification might not use HTTP according to the criteria above 213 and still define an application that relies upon HTTP in some manner. 214 For example, an application might wish to avoid re-specifying parts 215 of the message format, but change other aspects of the protocol's 216 operation; or, it might want to use a different set of methods. 218 Doing so brings more freedom to modify protocol operations, but loses 219 at least a portion of the benefits outlined above, as most HTTP 220 implementations won't be easily adaptable to these changes, and as 221 the protocol diverges from HTTP, the benefit of mindshare will be 222 lost. 224 Such specifications MUST NOT use HTTP's URI schemes, transport ports, 225 ALPN protocol IDs or IANA registries; rather, they are encouraged to 226 establish their own. 228 3. What's Important About HTTP 230 This section examines the characteristics of the HTTP protocol that 231 are important to consider when using HTTP to define an application 232 protocol. 234 3.1. Generic Semantics 236 Much of the value of HTTP is in its generic semantics -- that is, the 237 protocol elements defined by HTTP are potentially applicable to every 238 resource, not specific to a particular context. Application-specific 239 semantics are best expressed in message content and in header fields, 240 not status codes or methods -- although the latter do have generic 241 semantics that relate to application state. 243 This generic/application-specific split allows a HTTP message to be 244 handled by software (e.g., HTTP servers, intermediaries, client 245 implementations, and caches) without understanding the specific 246 application. It also allows people to leverage their knowledge of 247 HTTP semantics without special-casing them for a particular 248 application. 250 Therefore, applications that use HTTP MUST NOT re-define, refine or 251 overlay the semantics of generic protocol elements such as methods, 252 status codes or existing header fields. Instead, they should focus 253 their specifications on protocol elements that are specific to that 254 application; namely their HTTP resources. 256 When writing a specification, it's often tempting to specify exactly 257 how HTTP is to be implemented, supported and used. However, this can 258 easily lead to an unintended profile of HTTP's behaviour. For 259 example, it's common to see specifications with language like this: 261 A `POST` request MUST result in a `201 Created` response. 263 This forms an expectation in the client that the response will always 264 be "201 Created", when in fact there are a number of reasons why the 265 status code might differ in a real deployment; for example, there 266 might be a proxy that requires authentication, or a server-side 267 error, or a redirection. If the client does not anticipate this, the 268 application's deployment is brittle. 270 See Section 4.2 for more details. 272 3.2. Links 274 Another common practice is assuming that the HTTP server's name space 275 (or a portion thereof) is exclusively for the use of a single 276 application. This effectively overlays special, application-specific 277 semantics onto that space, precludes other applications from using 278 it. 280 As explained in [RFC8820], such "squatting" on a part of the URL 281 space by a standard usurps the server's authority over its own 282 resources, can cause deployment issues, and is therefore bad practice 283 in standards. 285 Instead of statically defining URI components like paths, it is 286 RECOMMENDED that applications using HTTP define and use links, to 287 allow flexibility in deployment. 289 Using runtime links in this fashion has a number of other benefits -- 290 especially when an application is to have multiple implementations 291 and/or deployments (as is often the case for those that are 292 standardised). 294 For example, navigating with a link allows a request to be routed to 295 a different server without the overhead of a redirection, thereby 296 supporting deployment across machines well. 298 It also becomes possible to "mix and match" different applications on 299 the same server, and offers a natural mechanism for extensibility, 300 versioning and capability management, since the document containing 301 the links can also contain information about their targets. 303 Using links also offers a form of cache invalidation that's seen on 304 the Web; when a resource's state changes, the application can change 305 its link to it so that a fresh copy is always fetched. 307 3.3. Rich Functionality 309 HTTP offers a number of features to applications, such as: 311 * Message framing 313 * Multiplexing (in HTTP/2) 315 * Integration with TLS 317 * Support for intermediaries (proxies, gateways, Content Delivery 318 Networks) 320 * Client authentication 322 * Content negotiation for format, language, and other features 324 * Caching for server scalability, latency and bandwidth reduction, 325 and reliability 327 * Granularity of access control (through use of a rich space of 328 URLs) 330 * Partial content to selectively request part of a response 332 * The ability to interact with the application easily using a Web 333 browser 335 Applications that use HTTP are encouraged to utilise the various 336 features that the protocol offers, so that their users receive the 337 maximum benefit from it, and to allow it to be deployed in a variety 338 of situations. This document does not require specific features to 339 be used, since the appropriate design tradeoffs are highly specific 340 to a given situation. However, following the practices in Section 4 341 is a good starting point. 343 4. Best Practices for Specifying the Use of HTTP 345 This section contains best practices for specifying the use of HTTP 346 by applications, including practices for specific HTTP protocol 347 elements. 349 4.1. Specifying the Use of HTTP 351 When specifying the use of HTTP, an application should use 352 [I-D.ietf-httpbis-semantics] as the primary reference; it is not 353 necessary to reference all of the specifications in the HTTP suite 354 unless there are specific reasons to do so (e.g., a particular 355 feature is called out). 357 Because it is a hop-by-hop protocol, a HTTP connection can be handled 358 by implementations that are not controlled by the application; for 359 example, proxies, CDNs, firewalls and so on. Requiring a particular 360 version of HTTP makes it difficult to use in these situations, and 361 harms interoperability. Therefore, it is RECOMMENDED that 362 applications using HTTP not specify a minimum version of HTTP to be 363 used. 365 However, if an application's deployment would benefit from the use of 366 a particular version of HTTP (for example, HTTP/2's multiplexing), 367 this ought be noted. 369 Applications using HTTP MUST NOT specify a maximum version, to 370 preserve the protocol's ability to evolve. 372 When specifying examples of protocol interactions, applications 373 should document both the request and response messages, with complete 374 header sections, preferably in HTTP/1.1 format. For example: 376 GET /thing HTTP/1.1 377 Host: example.com 378 Accept: application/things+json 379 User-Agent: Foo/1.0 381 HTTP/1.1 200 OK 382 Content-Type: application/things+json 383 Content-Length: 500 384 Server: Bar/2.2 386 [content here] 388 4.2. Specifying Server Behaviour 390 The most effective way to specify an application's server-side HTTP 391 behaviours is in terms of the following protocol elements: 393 * Media types [RFC6838], often based upon a format convention such 394 as JSON [RFC8259], 396 * HTTP header fields, as per Section 4.7, and 398 * The behaviour of resources, as identified by link relations 399 [RFC8288]. 401 By composing these protocol elements, an application can define a set 402 of resources, identified by link relations, that implement specified 403 behaviours, including: 405 * retrieval of their state using GET, in one or more formats 406 identified by media type; 408 * resource creation or update using POST or PUT, with an 409 appropriately identified request content format; 411 * data processing using POST and identified request and response 412 content format(s); and 414 * Resource deletion using DELETE. 416 For example, an application might specify: 418 Resources linked to with the "example-widget" link relation type are 419 Widgets. The state of a Widget can be fetched in the 420 "application/example-widget+json" format, and can be updated by PUT 421 to the same link. Widget resources can be deleted. 423 The "Example-Count" response header field on Widget representations 424 indicates how many Widgets are held by the sender. 426 The "application/example-widget+json" format is a JSON [RFC8259] 427 format representing the state of a Widget. It contains links to 428 related information in the link indicated by the Link header field 429 value with the "example-other-info" link relation type. 431 Applications can also specify the use of URI Templates [RFC6570] to 432 allow clients to generate URLs based upon runtime data. 434 4.3. Specifying Client Behaviour 436 In general, applications using HTTP ought to align their expectations 437 for client behaviour as closely as possible with that of Web 438 browsers, to avoid interoperability issues when they are used. 440 One way to do this is to define it in terms of [FETCH], since that is 441 the abstraction that browsers use for HTTP. 443 Some client behaviours (e.g., automatic redirect handling) and 444 extensions (e.g., Cookies) are not required by HTTP, but nevertheless 445 have become very common. If their use is not explicitly specified by 446 applications using HTTP, there may be confusion and interoperability 447 problems. In particular: 449 * Redirect handling - Applications need to specify how redirects are 450 expected to be handled; see Section 4.6.1. 452 * Cookies - Applications using HTTP should explicitly reference the 453 Cookie specification [I-D.ietf-httpbis-rfc6265bis] if they are 454 required. 456 * Certificates - Applications using HTTP should specify that TLS 457 certificates are to be checked according to 458 [I-D.ietf-httpbis-semantics], Section 4.3.4 when HTTPS is used. 460 Applications using HTTP should not statically require HTTP features 461 that are usually negotiated to be supported by clients. For example, 462 requiring that clients support responses with a certain content- 463 coding ([I-D.ietf-httpbis-semantics], Section 8.4.1) instead of 464 negotiating for it ([I-D.ietf-httpbis-semantics], Section 12.5.3) 465 means that otherwise conformant clients cannot interoperate with the 466 application. Applications can encourage the implementation of such 467 features, though. 469 4.4. Specifying URLs 471 In HTTP, the server resources that clients interact with are 472 identified with URLs [RFC3986]. As [RFC8820] explains, parts of the 473 URL are designed to be under the control of the owner (also known as 474 the "authority") of that server, to give them the flexibility in 475 deployment. 477 This means that in most cases, specifications for applications that 478 use HTTP won't contain its URLs; while it is common practice for a 479 specification of a single-deployment API to specify the path prefix 480 "/app/v1" (for example), doing so in an IETF specification is 481 inappropriate. 483 Therefore, the specification writer needs some mechanism to allow 484 clients to discovery an application's URLs. Additionally, they need 485 to specify what URL scheme(s) the application should be used with, 486 and whether to use a dedicated port, or reuse HTTP's port(s). 488 4.4.1. Discovering an Application's URLs 490 Generally, a client will begin interacting with a given application 491 server by requesting an initial document that contains information 492 about that particular deployment, potentially including links to 493 other relevant resources. Doing so assures that the deployment is as 494 flexible as possible (potentially spanning multiple servers), allows 495 evolution, and also gives the application the opportunity to tailor 496 the 'discovery document' to the client. 498 There are a few common patterns for discovering that initial URL. 500 The most straightforward mechanism for URL discovery is to configure 501 the client with (or otherwise convey to it) a full URL. This might 502 be done in a configuration document, or through another discovery 503 mechanism. 505 However, if the client only knows the server's hostname and the 506 identity of the application, there needs to be some way to derive the 507 initial URL from that information. 509 An application cannot define a fixed prefix for its URL paths; see 510 [RFC8820]. Instead, a specification for such an application can use 511 one of the following strategies: 513 * Register a Well-Known URI [RFC8615] as an entry point for that 514 application. This provides a fixed path on every potential server 515 that will not collide with other applications. 517 * Enable the server authority to convey a URL Template [RFC6570] or 518 similar mechanism for generating a URL for an entry point. For 519 example, this might be done in a configuration document or other 520 artefact. 522 Once the discovery document is located, it can be fetched, cached for 523 later reuse (if allowed by its metadata), and used to locate other 524 resources that are relevant to the application, using full URIs or 525 URL Templates. 527 In some cases, an application may not wish to use such a discovery 528 document; for example, when communication is very brief, or when the 529 latency concerns of doing so precludes the use of a discovery 530 document. These situations can be addressed by placing all of the 531 application's resources under a well-known location. 533 4.4.2. Considering URI Schemes 535 Applications that use HTTP will typically employ the "http" and/or 536 "https" URI schemes. "https" is RECOMMENDED to provide 537 authentication, integrity and confidentiality, as well as mitigate 538 pervasive monitoring attacks [RFC7258]. 540 However, application-specific schemes can also be defined. When 541 defining an URI scheme for an application using HTTP, there are a 542 number of tradeoffs and caveats to keep in mind: 544 * Unmodified Web browsers will not support the new scheme. While it 545 is possible to register new URI schemes with Web browsers (e.g. 546 registerProtocolHandler() in [HTML], as well as several 547 proprietary approaches), support for these mechanisms is not 548 shared by all browsers, and their capabilities vary. 550 * Existing non-browser clients, intermediaries, servers and 551 associated software will not recognise the new scheme. For 552 example, a client library might fail to dispatch the request; a 553 cache might refuse to store the response, and a proxy might fail 554 to forward the request. 556 * Because URLs occur in HTTP artefacts commonly, often being 557 generated automatically (e.g., in the "Location" response header 558 field), it can be difficult to assure that the new scheme is used 559 consistently. 561 * The resources identified by the new scheme will still be available 562 using "http" and/or "https" URLs. Those URLs can "leak" into use, 563 which can present security and operability issues. For example, 564 using a new scheme to assure that requests don't get sent to a 565 "normal" Web site is likely to fail. 567 * Features that rely upon the URL's origin [RFC6454], such as the 568 Web's same-origin policy, will be impacted by a change of scheme. 570 * HTTP-specific features such as cookies 571 [I-D.ietf-httpbis-rfc6265bis], authentication 572 [I-D.ietf-httpbis-semantics], caching [I-D.ietf-httpbis-cache], 573 HSTS [RFC6797], and CORS [FETCH] might or might not work 574 correctly, depending on how they are defined and implemented. 575 Generally, they are designed and implemented with an assumption 576 that the URL will always be "http" or "https". 578 * Web features that require a secure context [SECCTXT] will likely 579 treat a new scheme as insecure. 581 See [RFC7595] for more information about minting new URI schemes. 583 4.4.3. Transport Ports 585 Applications can use the applicable default port (80 for HTTP, 443 586 for HTTPS), or they can be deployed upon other ports. This decision 587 can be made at deployment time, or might be encouraged by the 588 application's specification (e.g., by registering a port for that 589 application). 591 If a non-default port is used, it needs to be reflected in the 592 authority of all URLs for that resource; the only mechanism for 593 changing a default port is changing the URI scheme (see 594 Section 4.4.2). 596 Using a port other than the default has privacy implications (i.e., 597 the protocol can now be distinguished from other traffic), as well as 598 operability concerns (as some networks might block or otherwise 599 interfere with it). Privacy implications should be documented in 600 Security Considerations. 602 See [RFC7605] for further guidance. 604 4.5. Using HTTP Methods 606 Applications that use HTTP MUST confine themselves to using 607 registered HTTP methods such as GET, POST, PUT, DELETE, and PATCH. 609 New HTTP methods are rare; they are required to be registered in the 610 HTTP Method Registry with IETF Review (see 611 [I-D.ietf-httpbis-semantics]), and are also required to be generic. 612 That means that they need to be potentially applicable to all 613 resources, not just those of one application. 615 While historically some applications (e.g., [RFC4791]) have defined 616 non-generic methods, [I-D.ietf-httpbis-semantics] now forbids this. 618 When authors believe that a new method is required, they are 619 encouraged to engage with the HTTP community early, and document 620 their proposal as a separate HTTP extension, rather than as part of 621 an application's specification. 623 4.5.1. GET 625 GET is the most common and useful HTTP method; its retrieval 626 semantics allow caching, side-effect free linking and underlies many 627 of the benefits of using HTTP. 629 A common use of GET is to perform queries, often using the query 630 component of the URL; this is a familiar pattern from Web browsing, 631 and the results can be cached, improving efficiency of an often 632 expensive process. 634 In some cases, however, GET might be unwieldy for expressing queries, 635 because of the limited syntax of the URI; in particular, if binary 636 data forms part of the query terms, it needs to be encoded to conform 637 to URI syntax. 639 While this is not an issue for short queries, it can become one for 640 larger query terms, or ones which need to sustain a high rate of 641 requests. Additionally, some HTTP implementations limit the size of 642 URLs they support -- although modern HTTP software has much more 643 generous limits than previously (typically, considerably more than 644 8000 octets, as required by [I-D.ietf-httpbis-semantics]. 646 In these cases, an application using HTTP might consider using POST 647 to express queries in the request's content; doing so avoids encoding 648 overhead and URL length limits in implementations. However, in doing 649 so it should be noted that the benefits of GET such as caching and 650 linking to query results are lost. Therefore, applications using 651 HTTP that feel a need to allow POST queries ought consider allowing 652 both methods. 654 Applications should not change their state or have other side effects 655 that might be significant to the client, since implementations can 656 and do retry HTTP GET requests that fail. Note that this does not 657 include logging and similar functions; see 658 [I-D.ietf-httpbis-semantics], Section 9.2.1. 660 Finally, note that while HTTP allows GET requests to have content 661 syntactically, this is done only to allow parsers to be generic; as 662 per [I-D.ietf-httpbis-semantics], Section 9.3.1, content on a GET has 663 no meaning, and will be either ignored or rejected by generic HTTP 664 software. 666 4.5.2. OPTIONS 668 The OPTIONS method was defined for metadata retrieval, and is used 669 both by WebDAV [RFC4918] and CORS [FETCH]. Because HTTP-based APIs 670 often need to retrieve metadata about resources, it is often 671 considered for their use. 673 However, OPTIONS does have significant limitations: 675 * It isn't possible to link to the metadata with a simple URL, 676 because OPTIONS is not the default GET method. 678 * OPTIONS responses are not cacheable, because HTTP caches operate 679 on representations of the resource (i.e., GET and HEAD). If 680 OPTIONS responses are cached separately, their interaction with 681 HTTP cache expiry, secondary keys and other mechanisms needs to be 682 considered. 684 * OPTIONS is "chatty" - always separating metadata out into a 685 separate request increases the number of requests needed to 686 interact with the application. 688 * Implementation support for OPTIONS is not universal; some servers 689 do not expose the ability to respond to OPTIONS requests without 690 significant effort. 692 Instead of OPTIONS, one of these alternative approaches might be more 693 appropriate: 695 * For server-wide metadata, create a well-known URI [RFC8615], or 696 using an already existing one if it's appropriate (e.g., HostMeta 697 [RFC6415]). 699 * For metadata about a specific resource, create a separate resource 700 and link to it using a Link response header field or a link 701 serialised into the response's content. See [RFC8288]. Note that 702 the Link header field is available on HEAD responses, which is 703 useful if the client wants to discover a resource's capabilities 704 before they interact with it. 706 4.6. Using HTTP Status Codes 708 HTTP status codes convey semantics both for the benefit of generic 709 HTTP components -- such as caches, intermediaries, and clients -- and 710 applications themselves. However, applications can encounter a 711 number of pitfalls in their use. 713 First, status codes are often generated by components other the the 714 application itself. This can happen, for example, when network 715 errors are encountered, a captive portal, proxy or Content Delivery 716 Network is present, when a server is overloaded, or it thinks it is 717 under attack. They can even be generated by generic client software 718 when certain error conditions are encountered. As a result, if an 719 application assigns specific semantics to one of these status codes, 720 a client can be misled about its state, because the status code was 721 generated by a generic component, not the application itself. 723 Furthermore, mapping application errors to individual HTTP status 724 codes one-to-one often leads to a situation where the finite space of 725 applicable HTTP status codes is exhausted. This, in turn, leads to a 726 number of bad practices -- including minting new, application- 727 specific status codes, or using existing status codes even though the 728 link between their semantics and the application's is tenuous at 729 best. 731 Instead, applications using HTTP should define their errors to use 732 the most applicable status code, making generous use of the general 733 status codes (200, 400 and 500) when in doubt. Importantly, they 734 should not specify a one-to-one relationship between status codes and 735 application errors, thereby avoiding the exhaustion issue outlined 736 above. 738 To distinguish between multiple error conditions that are mapped to 739 the same status code, and to avoid the misattribution issue outlined 740 above, applications using HTTP should convey finer-grained error 741 information in the response's message content and/or header fields. 742 [RFC7807] provides one way to do so. 744 Because the set of registered HTTP status codes can expand, 745 applications using HTTP should explicitly point out that clients 746 ought to be able to handle all applicable status codes gracefully 747 (i.e., falling back to the generic "n00" semantics of a given status 748 code; e.g., "499" can be safely handled as "400" by clients that 749 don't recognise it). This is preferable to creating a "laundry list" 750 of potential status codes, since such a list won't be complete in the 751 foreseeable future. 753 Applications using HTTP MUST NOT re-specify the semantics of HTTP 754 status codes, even if it is only by copying their definition. It is 755 RECOMMENDED they require specific reason phrases to be used; the 756 reason phrase has no function in HTTP, is not guaranteed to be 757 preserved by implementations, and is not carried at all in the HTTP/2 758 [RFC7540] message format. 760 Applications MUST only use registered HTTP status codes. As with 761 methods, new HTTP status codes are rare, and required (by 762 [I-D.ietf-httpbis-semantics]) to be registered with IETF Review. 763 Similarly, HTTP status codes are generic; they are required (by 764 [I-D.ietf-httpbis-semantics]) to be potentially applicable to all 765 resources, not just to those of one application. 767 When authors believe that a new status code is required, they are 768 encouraged to engage with the HTTP community early, and document 769 their proposal as a separate HTTP extension, rather than as part of 770 an application's specification. 772 4.6.1. Redirection 774 The 3xx series of status codes specified in 775 [I-D.ietf-httpbis-semantics], Section 15.4 direct the user agent to 776 another resource to satisfy the request. The most common of these 777 are 301, 302, 307 and 308, all of which use the Location response 778 header field to indicate where the client should send the request to. 780 There are two ways that this group of status codes differ: 782 * Whether they are permanent or temporary. Permanent redirects can 783 be used to update links stored in the client (e.g., bookmarks), 784 whereas temporary ones can not. Note that this has no effect on 785 HTTP caching; it is completely separate. 787 * Whether they allow the redirected request to change the request 788 method from POST to GET. Web browsers generally do change POST to 789 GET for 301 and 302; therefore, 308 and 307 were created to allow 790 redirection without changing the method. 792 This table summarises their relationships: 794 +=============================+===========+===========+ 795 | | Permanent | Temporary | 796 +=============================+===========+===========+ 797 | Allows changing the request | 301 | 302 | 798 | method from POST to GET | | | 799 +-----------------------------+-----------+-----------+ 800 | Does not allow changing the | 308 | 307 | 801 | request method | | | 802 +-----------------------------+-----------+-----------+ 804 Table 1 806 As noted in [I-D.ietf-httpbis-semantics], a user agent is allowed to 807 automatically follow a 3xx redirect that has a Location response 808 header field, even if they don't understand the semantics of the 809 specific status code. However, they aren't required to do so; 810 therefore, if an application using HTTP desires redirects to be 811 automatically followed, it needs to explicitly specify the 812 circumstances when this is required. 814 Redirects can be cached (when appropriate cache directives are 815 present), but beyond that they are not 'sticky' -- i.e., redirection 816 of a URI will not result in the client assuming that similar URIs 817 (e.g., with different query parameters) will also be redirected. 819 Applications using HTTP are encouraged to specify that 301 and 302 820 responses change the subsequent request method from POST (but no 821 other method) to GET, to be compatible with browsers. Generally, 822 when a redirected request is made, its header fields are copied from 823 the original request's. However, they can be modified by various 824 mechanisms; e.g., sent Authorization ([I-D.ietf-httpbis-semantics]) 825 and Cookie ([I-D.ietf-httpbis-rfc6265bis]) header fields will change 826 if the origin (and sometimes path) of the request changes. An 827 application using HTTP should specify if any request header fields 828 that it defines need to be modified or removed upon a redirect; 829 however, this behaviour cannot be relied upon, since a generic client 830 (like a browser) will be unaware of such requirements. 832 4.7. Specifying HTTP Header Fields 834 Applications often define new HTTP header fields. Typically, using 835 HTTP header fields is appropriate in a few different situations: 837 * The field is useful to intermediaries (who often wish to avoid 838 parsing message content), and/or 840 * The field is useful to generic HTTP software (e.g., clients, 841 servers), and/or 843 * It is not possible to include their values in the message content 844 (usually because a format does not allow it). 846 When the conditions above are not met, it is usually better to convey 847 application-specific information in other places; e.g., the message 848 content or the URL query string. 850 New header fields MUST be registered, as per 851 [I-D.ietf-httpbis-semantics]. 853 See [I-D.ietf-httpbis-semantics], Section 16.3.2 for guidelines to 854 consider when minting new header fields. [RFC8941] provides a common 855 structure for new header fields, and avoids many issues in their 856 parsing and handling; it is RECOMMENDED that new header fields use 857 it. 859 It is RECOMMENDED that header field names be short (even when field 860 compression is used, there is an overhead) but appropriately 861 specific. In particular, if a header field is specific to an 862 application, an identifier for that application can form a prefix to 863 the header field name, separated by a "-". 865 For example, if the "example" application needs to create three 866 header fields, they might be called "example-foo", "example-bar" and 867 "example-baz". Note that the primary motivation here is to avoid 868 consuming more generic field names, not to reserve a portion of the 869 namespace for the application; see [RFC6648] for related 870 considerations. 872 The semantics of existing HTTP header fields MUST NOT be re-defined 873 without updating their registration or defining an extension to them 874 (if allowed). For example, an application using HTTP cannot specify 875 that the "Location" header field has a special meaning in a certain 876 context. 878 See Section 4.9 for the interaction between header fields and HTTP 879 caching; in particular, request header fields that are used to 880 "select" a response have impact there, and need to be carefully 881 considered. 883 See Section 4.10 for considerations regarding header fields that 884 carry application state (e.g., Cookie). 886 4.8. Defining Message Content 888 Common syntactic conventions for message contents include JSON 889 [RFC8259], XML [XML], and CBOR [RFC7049]. Best practices for their 890 use are out of scope for this document. 892 Applications should register distinct media types for each format 893 they define; this makes it possible to identify them unambiguously 894 and negotiate for their use. See [RFC6838] for more information. 896 4.9. Leveraging HTTP Caching 898 HTTP caching [I-D.ietf-httpbis-cache] is one of the primary benefits 899 of using HTTP for applications; it provides scalability, reduces 900 latency and improves reliability. Furthermore, HTTP caches are 901 readily available in browsers and other clients, networks as forward 902 and reverse proxies, Content Delivery Networks and as part of server 903 software. 905 Even when an application using HTTP isn't designed to take advantage 906 of caching, it needs to consider how caches will handle its 907 responses, to preserve correct behaviour when one is interposed 908 (whether in the network, server, client, or intervening 909 infrastructure). 911 4.9.1. Freshness 913 Assigning even a short freshness lifetime ([I-D.ietf-httpbis-cache], 914 Section 4.2) -- e.g., 5 seconds -- allows a response to be reused to 915 satisfy multiple clients, and/or a single client making the same 916 request repeatedly. In general, if it is safe to reuse something, 917 consider assigning a freshness lifetime. 919 The most common method for specifying freshness is the max-age 920 response directive ([I-D.ietf-httpbis-cache], Section 5.2.2.1). The 921 Expires header field ([I-D.ietf-httpbis-cache], Section 5.3) can also 922 be used, but it is not necessary; all modern cache implementations 923 support Cache-Control, and specifying freshness as a delta is usually 924 more convenient and less error-prone. 926 It is not necessary to add the public response directive 927 ([I-D.ietf-httpbis-cache], Section 5.2.2.9) to cache most responses; 928 it is only necessary when it's desirable to store an authenticated 929 response. 931 In some situations, responses without explicit cache freshness 932 directives will be stored and served using a heuristic freshness 933 lifetime; see [I-D.ietf-httpbis-cache], Section 4.2.2. As the 934 heuristic is not under control of the application, it is generally 935 preferable to set an explicit freshness lifetime, or make the 936 response explicitly uncacheable. 938 If caching of a response is not desired, the appropriate response 939 directive is "Cache-Control: no-store". Other directives are not 940 necessary, and no-store only need be sent in situations where the 941 response might be cached; see [I-D.ietf-httpbis-cache], Section 3. 942 Note that "Cache-Control: no-cache" allows a response to be stored, 943 just not reused by a cache without validation; it does not prevent 944 caching (despite its name). 946 For example, this response cannot be stored or reused by a cache: 948 HTTP/1.1 200 OK 949 Content-Type: application/example+xml 950 Cache-Control: no-store 952 [content] 954 4.9.2. Stale Responses 956 Authors should understand that stale responses (e.g., with "Cache- 957 Control: max-age=0") can be reused by caches when disconnected from 958 the origin server; this can be useful for handling network issues. 960 If doing so is not suitable for a given response, the origin should 961 use "Cache-Control: must-revalidate". See [I-D.ietf-httpbis-cache], 962 Section 4.2.4, and also [RFC5861] for additional controls over stale 963 content. 965 Stale responses can be refreshed by assigning a validator, saving 966 both transfer bandwidth and latency for large responses; see 967 [I-D.ietf-httpbis-semantics]. 969 4.9.3. Caching and Application Semantics 971 When an application has a need to express a lifetime that's separate 972 from the freshness lifetime, this should be conveyed separately, 973 either in the response's content or in a separate header field. When 974 this happens, the relationship between HTTP caching and that lifetime 975 need to be carefully considered, since the response will be used as 976 long as it is considered fresh. 978 In particular, application authors need to consider how responses 979 that are not freshly obtained from the origin server should be 980 handled; if they have a concept like a validity period, this will 981 need to be calculated considering the age of the response (see 982 [I-D.ietf-httpbis-cache], Section 4.2.3). 984 One way to address this is to explicitly specify that all responses 985 be fresh upon use. 987 4.9.4. Varying Content Based Upon the Request 989 If an application uses a request header field to change the 990 response's header fields or content, authors should point out that 991 this has implications for caching; in general, such resources need to 992 either make their responses uncacheable (e.g., with the "no-store" 993 cache-control directive defined in [I-D.ietf-httpbis-cache], 994 Section 5.2.2.3) or send the Vary response header field 995 ([I-D.ietf-httpbis-semantics], Section 12.5.5) on all responses from 996 that resource (including the "default" response). 998 For example, this response: 1000 HTTP/1.1 200 OK 1001 Content-Type: application/example+xml 1002 Cache-Control: max-age=60 1003 ETag: "sa0f8wf20fs0f" 1004 Vary: Accept-Encoding 1006 [content] 1008 can be stored for 60 seconds by both private and shared caches, can 1009 be revalidated with If-None-Match, and varies on the Accept-Encoding 1010 request header field. 1012 4.10. Handling Application State 1014 Applications can use stateful cookies [I-D.ietf-httpbis-rfc6265bis] 1015 to identify a client and/or store client-specific data to 1016 contextualise requests. 1018 When used, it is important to carefully specify the scoping and use 1019 of cookies; if the application exposes sensitive data or capabilities 1020 (e.g., by acting as an ambient authority), exploits are possible. 1021 Mitigations include using a request-specific token to assure the 1022 intent of the client. 1024 4.11. Making Multiple Requests 1026 Clients often need to send multiple requests to perform a task. 1028 In HTTP/1, parallel requests are most often supported by opening 1029 multiple connections. Application performance can be impacted when 1030 too many simultaneous connections are used, because connections' 1031 congestion control will not be coordinated. Furthermore, it can be 1032 difficult for applications to decide when and to select which 1033 connection to use to issue a given request, further impacting 1034 performance. 1036 HTTP/2 and HTTP/3 offer multiplexing to applications, removing the 1037 need to use multiple connections. However, application performance 1038 can still be significantly affected by how the server chooses to 1039 prioritize responses. Depending on the application, it might be best 1040 for the server to determine the priority of responses, or for the 1041 client to hint its priorities to the server (see, e.g., 1042 [I-D.ietf-httpbis-priority]). 1044 In all versions of HTTP, requests are made independently -- you can't 1045 rely on the relative order of two requests to guarantee processing 1046 order. This is because they might be sent over a multiplexed 1047 protocol by an intermediary, sent to different origin servers, or the 1048 server might even perform processing in a different order. If two 1049 requests need strict ordering, the only reliable way to assure the 1050 outcome is to issue the second request when the final response to the 1051 first has begun. 1053 Applications MUST NOT make assumptions about the relationship between 1054 separate requests on a single transport connection; doing so breaks 1055 many of the assumptions of HTTP as a stateless protocol, and will 1056 cause problems in interoperability, security, operability and 1057 evolution. 1059 4.12. Client Authentication 1061 Applications can use HTTP authentication [I-D.ietf-httpbis-semantics] 1062 to identify clients. The Basic authentication scheme [RFC7617] MUST 1063 NOT be used unless the underlying transport is authenticated, 1064 integrity-protected and confidential (e.g., as provided the "HTTPS" 1065 URI scheme, or another using TLS). The Digest scheme [RFC7616] MUST 1066 NOT be used unless the underlying transport is similarly secure, or 1067 the chosen hash algorithm is not "MD5". 1069 With HTTPS, clients might also be authenticated using certificates 1070 [RFC5246]. 1072 When used, it is important to carefully specify the scoping and use 1073 of authentication; if the application exposes sensitive data or 1074 capabilities (e.g., by acting as an ambient authority), exploits are 1075 possible. Mitigations include using a request-specific token to 1076 assure the intent of the client. 1078 4.13. Co-Existing with Web Browsing 1080 Even if there is not an intent for an application to be used with a 1081 Web browser, its resources will remain available to browsers and 1082 other HTTP clients. 1084 This means that all such applications that use HTTP need to consider 1085 how browsers will interact with them, particularly regarding 1086 security. 1088 For example, if an application's state can be changed using a POST 1089 request, a Web browser can easily be coaxed into cross-site request 1090 forgery (CSRF) from arbitrary Web sites. 1092 Or, if content returned from the application's resources is under 1093 control of an attacker (for example, part of the request is reflected 1094 in the response, or the response contains external information that 1095 might be under the control of the attacker), a cross-site scripting 1096 (XSS) attack is possible, whereby an attacker can inject code into 1097 the browser and access data and capabilities on that origin. 1099 This is only a small sample of the kinds of issues that applications 1100 using HTTP must consider. Generally, the best approach is to 1101 consider the application actually as a Web application, and to follow 1102 best practices for their secure development. 1104 A complete enumeration of such practices is out of scope for this 1105 document, but some considerations include: 1107 * Using an application-specific media type in the Content-Type 1108 header field, and requiring clients to fail if it is not used. 1110 * Using X-Content-Type-Options: nosniff [FETCH] to assure that 1111 content under attacker control can't be coaxed into a form that is 1112 interpreted as active content by a Web browser. 1114 * Using Content-Security-Policy [CSP] to constrain the capabilities 1115 of active content (such as HTML [HTML]), thereby mitigating Cross- 1116 Site Scripting attacks. 1118 * Using Referrer-Policy [REFERRER-POLICY] to prevent sensitive data 1119 in URLs from being leaked in the Referer request header field. 1121 * Using the 'HttpOnly' flag on Cookies to assure that cookies are 1122 not exposed to browser scripting languages 1123 [I-D.ietf-httpbis-rfc6265bis]. 1125 * Avoiding use of compression on any sensitive information (e.g., 1126 authentication tokens, passwords), as the scripting environment 1127 offered by Web browsers allows an attacker to repeatedly probe the 1128 compression space; if the attacker has access to the path of the 1129 communication, they can use this capability to recover that 1130 information. 1132 Depending on how they are intended to be deployed, specifications for 1133 applications using HTTP might require the use of these mechanisms in 1134 specific ways, or might merely point them out in Security 1135 Considerations. 1137 An example of a HTTP response from an application that does not 1138 intend for its content to be treated as active by browsers might look 1139 like this: 1141 HTTP/1.1 200 OK 1142 Content-Type: application/example+json 1143 X-Content-Type-Options: nosniff 1144 Content-Security-Policy: default-src 'none' 1145 Cache-Control: max-age=3600 1146 Referrer-Policy: no-referrer 1148 [content] 1150 If an application has browser compatibility as a goal, client 1151 interaction ought to be defined in terms of [FETCH], since that is 1152 the abstraction that browsers use for HTTP; it enforces many of these 1153 best practices. 1155 4.14. Maintaining Application Boundaries 1157 Because the origin [RFC6454] is how many HTTP capabilities are 1158 scoped, applications also need to consider how deployments might 1159 interact with other applications (including Web browsing) on the same 1160 origin. 1162 For example, if Cookies [I-D.ietf-httpbis-rfc6265bis] are used to 1163 carry application state, they will be sent with all requests to the 1164 origin by default, unless scoped by path, and the application might 1165 receive cookies from other applications on the origin. This can lead 1166 to security issues, as well as collision in cookie names. 1168 One solution to these issues is to require a dedicated hostname for 1169 the application, so that it has a unique origin. However, it is 1170 often desirable to allow multiple applications to be deployed on a 1171 single hostname; doing so provides the most deployment flexibility 1172 and enables them to be "mixed" together (See [RFC8820] for details). 1173 Therefore, applications using HTTP should strive to allow multiple 1174 applications on an origin. 1176 To enable this, when specifying the use of Cookies, HTTP 1177 authentication realms [I-D.ietf-httpbis-semantics], or other origin- 1178 wide HTTP mechanisms, applications using HTTP should not mandate the 1179 use of a particular name, but instead let deployments configure them. 1180 Consideration should be given to scoping them to part of the origin, 1181 using their specified mechanisms for doing so. 1183 Modern Web browsers constrain the ability of content from one origin 1184 to access resources from another, to avoid leaking private 1185 information. As a result, applications that wish to expose cross- 1186 origin data to browsers will need to implement the CORS protocol; see 1187 [FETCH]. 1189 4.15. Using Server Push 1191 HTTP/2 adds the ability for servers to "push" request/response pairs 1192 to clients in [RFC7540], Section 8.2. While server push seems like a 1193 natural fit for many common application semantics (e.g., "fanout" and 1194 publish/subscribe), a few caveats should be noted: 1196 * Server push is hop-by-hop; that is, it is not automatically 1197 forwarded by intermediaries. As a result, it might not work 1198 easily (or at all) with proxies, reverse proxies, and Content 1199 Delivery Networks. 1201 * Server push can have negative performance impact on HTTP when used 1202 incorrectly; in particular, if there is contention with resources 1203 that have actually been requested by the client. 1205 * Server push is implemented differently in different clients, 1206 especially regarding interaction with HTTP caching, and 1207 capabilities might vary. 1209 * APIs for server push are currently unavailable in some 1210 implementations, and vary widely in others. In particular, there 1211 is no current browser API for it. 1213 * Server push is not supported in HTTP/1.1 or HTTP/1.0. 1215 * Server push does not form part of the "core" semantics of HTTP, 1216 and therefore might not be supported by future versions of the 1217 protocol. 1219 Applications wishing to optimise cases where the client can perform 1220 work related to requests before the full response is available (e.g., 1221 fetching links for things likely to be contained within) might 1222 benefit from using the 103 (Early Hints) status code; see [RFC8297]. 1224 Applications using server push directly need to enforce the 1225 requirements regarding authority in [RFC7540], Section 8.2, to avoid 1226 cross-origin push attacks. 1228 4.16. Allowing Versioning and Evolution 1230 It's often necessary to introduce new features into application 1231 protocols, and change existing ones. 1233 In HTTP, backwards-incompatible changes are possible using a number 1234 of mechanisms: 1236 * Using a distinct link relation type [RFC8288] to identify a URL 1237 for a resource that implements the new functionality. 1239 * Using a distinct media type [RFC6838] to identify formats that 1240 enable the new functionality. 1242 * Using a distinct HTTP header field to implement new functionality 1243 outside the message content. 1245 5. IANA Considerations 1247 This document has no requirements for IANA. 1249 6. Security Considerations 1251 Section 4.10 discusses the impact of using stateful mechanisms in the 1252 protocol as ambient authority, and suggests a mitigation. 1254 Section 4.4.2 requires support for 'https' URLs, and discourages the 1255 use of 'http' URLs, to provide authentication, integrity and 1256 confidentiality, as well as mitigate pervasive monitoring attacks. 1258 Section 4.13 highlights the implications of Web browsers' 1259 capabilities on applications that use HTTP. 1261 Section 4.14 discusses the issues that arise when applications are 1262 deployed on the same origin as Web sites (and other applications). 1264 Section 4.15 highlights risks of using HTTP/2 server push in a manner 1265 other than specified. 1267 Applications that use HTTP in a manner that involves modification of 1268 implementations -- for example, requiring support for a new URI 1269 scheme, or a non-standard method -- risk having those implementations 1270 "fork" from their parent HTTP implementations, with the possible 1271 result that they do not benefit from patches and other security 1272 improvements incorporated upstream. 1274 6.1. Privacy Considerations 1276 HTTP clients can expose a variety of information to servers. Besides 1277 information that's explicitly sent as part of an application's 1278 operation (for example, names and other user-entered data), and "on 1279 the wire" (which is one of the reasons https is recommended in 1280 Section 4.4.2), other information can be gathered through less 1281 obvious means -- often by connecting activities of a user over time. 1283 This includes session information, tracking the client through 1284 fingerprinting, and mobile code. 1286 Session information includes things like the IP address of the 1287 client, TLS session tickets, Cookies, ETags stored in the client's 1288 cache, and other stateful mechanisms. Applications are advised to 1289 avoid using session mechanisms unless they are unavoidable or 1290 necessary for operation, in which case these risks needs to be 1291 documented. When they are used, implementations should be encouraged 1292 to allow clearing such state. 1294 Fingerprinting uses unique aspects of a client's messages and 1295 behaviours to connect disparate requests and connections. For 1296 example, the User-Agent request header field conveys specific 1297 information about the implementation; the Accept-Language request 1298 header field conveys the users' preferred language. In combination, 1299 a number of these markers can be used to uniquely identify a client, 1300 impacting its control over its data. As a result, applications are 1301 advised to specify that clients should only emit the information they 1302 need to function in requests. 1304 Finally, if an application exposes the ability to run mobile code, 1305 great care needs to be taken, since any ability to observe its 1306 environment can be used as an opportunity to both fingerprint the 1307 client and to obtain and manipulate private data (including session 1308 information). For example, access to high-resolution timers (even 1309 indirectly) can be used to profile the underlying hardware, creating 1310 a unique identifier for the system. Applications are advised to 1311 avoid allowing the use of mobile code where possible; when it cannot 1312 be avoided, the resulting system's security properties need be 1313 carefully scrutinised. 1315 7. References 1317 7.1. Normative References 1319 [I-D.ietf-httpbis-semantics] 1320 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 1321 Semantics", Work in Progress, Internet-Draft, draft-ietf- 1322 httpbis-semantics-14, 12 January 2021, 1323 . 1326 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1327 Requirement Levels", BCP 14, RFC 2119, 1328 DOI 10.17487/RFC2119, March 1997, 1329 . 1331 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1332 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1333 May 2017, . 1335 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 1336 "Transport Layer Security (TLS) Application-Layer Protocol 1337 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 1338 July 2014, . 1340 [RFC8820] Nottingham, M., "URI Design and Ownership", BCP 190, 1341 RFC 8820, DOI 10.17487/RFC8820, June 2020, 1342 . 1344 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1345 Specifications and Registration Procedures", BCP 13, 1346 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1347 . 1349 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1350 DOI 10.17487/RFC8288, October 2017, 1351 . 1353 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1354 Resource Identifier (URI): Generic Syntax", STD 66, 1355 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1356 . 1358 [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers 1359 (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, 1360 . 1362 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 1363 DOI 10.17487/RFC6454, December 2011, 1364 . 1366 [RFC6648] Saint-Andre, P., Crocker, D., and M. Nottingham, 1367 "Deprecating the "X-" Prefix and Similar Constructs in 1368 Application Protocols", BCP 178, RFC 6648, 1369 DOI 10.17487/RFC6648, June 2012, 1370 . 1372 7.2. Informative References 1374 [HTML] WHATWG, "HTML - Living Standard", n.d., 1375 . 1377 [FETCH] WHATWG, "Fetch - Living Standard", n.d., 1378 . 1380 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1381 Interchange Format", STD 90, RFC 8259, 1382 DOI 10.17487/RFC8259, December 2017, 1383 . 1385 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1386 and D. Orchard, "URI Template", RFC 6570, 1387 DOI 10.17487/RFC6570, March 2012, 1388 . 1390 [I-D.ietf-httpbis-rfc6265bis] 1391 West, M. and J. Wilander, "Cookies: HTTP State Management 1392 Mechanism", Work in Progress, Internet-Draft, draft-ietf- 1393 httpbis-rfc6265bis-07, 7 December 2020, 1394 . 1397 [RFC7258] Farrell, S. and H. Tschofenig, "Pervasive Monitoring Is an 1398 Attack", BCP 188, RFC 7258, DOI 10.17487/RFC7258, May 1399 2014, . 1401 [I-D.ietf-httpbis-cache] 1402 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 1403 Caching", Work in Progress, Internet-Draft, draft-ietf- 1404 httpbis-cache-14, 12 January 2021, 1405 . 1407 [RFC6797] Hodges, J., Jackson, C., and A. Barth, "HTTP Strict 1408 Transport Security (HSTS)", RFC 6797, 1409 DOI 10.17487/RFC6797, November 2012, 1410 . 1412 [SECCTXT] West, M., "Secure Contexts", World Wide Web Consortium CR 1413 CR-secure-contexts-20160915, 15 September 2016, 1414 . 1416 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 1417 and Registration Procedures for URI Schemes", BCP 35, 1418 RFC 7595, DOI 10.17487/RFC7595, June 2015, 1419 . 1421 [RFC7605] Touch, J., "Recommendations on Using Assigned Transport 1422 Port Numbers", BCP 165, RFC 7605, DOI 10.17487/RFC7605, 1423 August 2015, . 1425 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 1426 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 1427 DOI 10.17487/RFC4791, March 2007, 1428 . 1430 [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed 1431 Authoring and Versioning (WebDAV)", RFC 4918, 1432 DOI 10.17487/RFC4918, June 2007, 1433 . 1435 [RFC6415] Hammer-Lahav, E., Ed. and B. Cook, "Web Host Metadata", 1436 RFC 6415, DOI 10.17487/RFC6415, October 2011, 1437 . 1439 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 1440 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 1441 . 1443 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1444 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1445 DOI 10.17487/RFC7540, May 2015, 1446 . 1448 [RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for 1449 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 1450 . 1452 [XML] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 1453 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 1454 Edition)", World Wide Web Consortium Recommendation REC- 1455 xml-20081126, 26 November 2008, 1456 . 1458 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1459 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1460 October 2013, . 1462 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 1463 Content", RFC 5861, DOI 10.17487/RFC5861, May 2010, 1464 . 1466 [I-D.ietf-httpbis-priority] 1467 Oku, K. and L. Pardue, "Extensible Prioritization Scheme 1468 for HTTP", Work in Progress, Internet-Draft, draft-ietf- 1469 httpbis-priority-03, 11 January 2021, 1470 . 1473 [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", 1474 RFC 7617, DOI 10.17487/RFC7617, September 2015, 1475 . 1477 [RFC7616] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP 1478 Digest Access Authentication", RFC 7616, 1479 DOI 10.17487/RFC7616, September 2015, 1480 . 1482 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1483 (TLS) Protocol Version 1.2", RFC 5246, 1484 DOI 10.17487/RFC5246, August 2008, 1485 . 1487 [CSP] West, M., "Content Security Policy Level 3", World Wide 1488 Web Consortium WD WD-CSP3-20160913, 13 September 2016, 1489 . 1491 [REFERRER-POLICY] 1492 Eisinger, J. and E. Stark, "Referrer Policy", World Wide 1493 Web Consortium CR CR-referrer-policy-20170126, 26 January 1494 2017, 1495 . 1497 [RFC8297] Oku, K., "An HTTP Status Code for Indicating Hints", 1498 RFC 8297, DOI 10.17487/RFC8297, December 2017, 1499 . 1501 [RFC3205] Moore, K., "On the use of HTTP as a Substrate", BCP 56, 1502 RFC 3205, DOI 10.17487/RFC3205, February 2002, 1503 . 1505 Appendix A. Changes from RFC 3205 1507 [RFC3205] captured the Best Current Practice in the early 2000's, 1508 based on the concerns facing protocol designers at the time. Use of 1509 HTTP has changed considerably since then, and as a result this 1510 document is substantially different. As a result, the changes are 1511 too numerous to list individually. 1513 Author's Address 1515 Mark Nottingham 1516 Prahran VIC 1517 Australia 1519 Email: mnot@mnot.net 1520 URI: https://www.mnot.net/