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