idnits 2.17.1 draft-ietf-httpbis-bcp56bis-12.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 (27 April 2021) is 1095 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-15 -- 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-15 == Outdated reference: A later version (-12) exists of draft-ietf-httpbis-priority-03 -- Obsolete informational reference (is this intentional?): RFC 3205 (Obsoleted by RFC 9205) -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) -- Obsolete informational reference (is this intentional?): RFC 7807 (Obsoleted by RFC 9457) Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP M. Nottingham 3 Internet-Draft 27 April 2021 4 Obsoletes: 3205 (if approved) 5 Intended status: Best Current Practice 6 Expires: 29 October 2021 8 Building Protocols with HTTP 9 draft-ietf-httpbis-bcp56bis-12 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 Note to Readers 22 _RFC EDITOR: please remove this section before publication_ 24 Discussion of this draft takes place on the HTTP working group 25 mailing list (ietf-http-wg@w3.org), which is archived at 26 https://lists.w3.org/Archives/Public/ietf-http-wg/ 27 (https://lists.w3.org/Archives/Public/ietf-http-wg/). 29 Working Group information can be found at http://httpwg.github.io/ 30 (http://httpwg.github.io/); source code and issues list for this 31 draft can be found at https://github.com/httpwg/http- 32 extensions/labels/bcp56bis (https://github.com/httpwg/http- 33 extensions/labels/bcp56bis). 35 Status of This Memo 37 This Internet-Draft is submitted in full conformance with the 38 provisions of BCP 78 and BCP 79. 40 Internet-Drafts are working documents of the Internet Engineering 41 Task Force (IETF). Note that other groups may also distribute 42 working documents as Internet-Drafts. The list of current Internet- 43 Drafts is at https://datatracker.ietf.org/drafts/current/. 45 Internet-Drafts are draft documents valid for a maximum of six months 46 and may be updated, replaced, or obsoleted by other documents at any 47 time. It is inappropriate to use Internet-Drafts as reference 48 material or to cite them other than as "work in progress." 49 This Internet-Draft will expire on 29 October 2021. 51 Copyright Notice 53 Copyright (c) 2021 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 58 license-info) in effect on the date of publication of this document. 59 Please review these documents carefully, as they describe your rights 60 and restrictions with respect to this document. Code Components 61 extracted from this document must include Simplified BSD License text 62 as described in Section 4.e of the Trust Legal Provisions and are 63 provided without warranty as described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 68 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 69 2. Is HTTP Being Used? . . . . . . . . . . . . . . . . . . . . . 4 70 2.1. Non-HTTP Protocols . . . . . . . . . . . . . . . . . . . 5 71 3. What's Important About HTTP . . . . . . . . . . . . . . . . . 5 72 3.1. Generic Semantics . . . . . . . . . . . . . . . . . . . . 6 73 3.2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 6 74 3.3. Rich Functionality . . . . . . . . . . . . . . . . . . . 7 75 4. Best Practices for Specifying the Use of HTTP . . . . . . . . 8 76 4.1. Specifying the Use of HTTP . . . . . . . . . . . . . . . 8 77 4.2. Specifying Server Behaviour . . . . . . . . . . . . . . . 9 78 4.3. Specifying Client Behaviour . . . . . . . . . . . . . . . 10 79 4.4. Specifying URLs . . . . . . . . . . . . . . . . . . . . . 11 80 4.4.1. Discovering an Application's URLs . . . . . . . . . . 11 81 4.4.2. Considering URI Schemes . . . . . . . . . . . . . . . 12 82 4.4.3. Transport Ports . . . . . . . . . . . . . . . . . . . 13 83 4.5. Using HTTP Methods . . . . . . . . . . . . . . . . . . . 14 84 4.5.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 14 85 4.5.2. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . 15 86 4.6. Using HTTP Status Codes . . . . . . . . . . . . . . . . . 16 87 4.6.1. Redirection . . . . . . . . . . . . . . . . . . . . . 17 88 4.7. Specifying HTTP Header Fields . . . . . . . . . . . . . . 18 89 4.8. Defining Message Content . . . . . . . . . . . . . . . . 20 90 4.9. Leveraging HTTP Caching . . . . . . . . . . . . . . . . . 20 91 4.9.1. Freshness . . . . . . . . . . . . . . . . . . . . . . 20 92 4.9.2. Stale Responses . . . . . . . . . . . . . . . . . . . 21 93 4.9.3. Caching and Application Semantics . . . . . . . . . . 21 94 4.9.4. Varying Content Based Upon the Request . . . . . . . 22 95 4.10. Handling Application State . . . . . . . . . . . . . . . 22 96 4.11. Making Multiple Requests . . . . . . . . . . . . . . . . 23 97 4.12. Client Authentication . . . . . . . . . . . . . . . . . . 23 98 4.13. Co-Existing with Web Browsing . . . . . . . . . . . . . . 24 99 4.14. Maintaining Application Boundaries . . . . . . . . . . . 25 100 4.15. Using Server Push . . . . . . . . . . . . . . . . . . . . 26 101 4.16. Allowing Versioning and Evolution . . . . . . . . . . . . 27 102 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 103 6. Security Considerations . . . . . . . . . . . . . . . . . . . 27 104 6.1. Privacy Considerations . . . . . . . . . . . . . . . . . 28 105 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 106 7.1. Normative References . . . . . . . . . . . . . . . . . . 29 107 7.2. Informative References . . . . . . . . . . . . . . . . . 30 108 Appendix A. Changes from RFC 3205 . . . . . . . . . . . . . . . 33 109 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 33 111 1. Introduction 113 Applications other than Web browsing often use HTTP 114 [I-D.ietf-httpbis-semantics] as a substrate, a practice sometimes 115 referred to as creating "HTTP-based APIs", "REST APIs" or just "HTTP 116 APIs". This is done for a variety of reasons, including: 118 * familiarity by implementers, specifiers, administrators, 119 developers and users, 121 * availability of a variety of client, server and proxy 122 implementations, 124 * ease of use, 126 * availability of Web browsers, 128 * reuse of existing mechanisms like authentication and encryption, 130 * presence of HTTP servers and clients in target deployments, and 132 * its ability to traverse firewalls. 134 These protocols are often ad hoc; they are intended for only 135 deployment by one or a few servers, and consumption by a limited set 136 of clients. As a result, a body of practices and tools has arisen 137 around defining HTTP-based APIs that favours these conditions. 139 However, when such an application has multiple, separate 140 implementations, is deployed on multiple uncoordinated servers, and 141 is consumed by diverse clients -- as is often the case for HTTP APIs 142 defined by standards efforts -- tools and practices intended for 143 limited deployment can become unsuitable. 145 This mismatch is largely because the API's clients and servers will 146 implement and evolve at different paces, leading to a need for 147 deployments with different features and versions to co-exist. As a 148 result, the designers of HTTP-based APIs intended for such 149 deployments need to more carefully consider how extensibility of the 150 service will be handled and how different deployment requirements 151 will be accommodated. 153 More generally, an application protocol using HTTP faces a number of 154 design decisions, including: 156 * Should it define a new URI scheme? Use new ports? 158 * Should it use standard HTTP methods and status codes, or define 159 new ones? 161 * How can the maximum value be extracted from the use of HTTP? 163 * How does it coexist with other uses of HTTP -- especially Web 164 browsing? 166 * How can interoperability problems and "protocol dead ends" be 167 avoided? 169 This document contains best current practices for the specification 170 of such applications. Section 2 defines when it applies; Section 3 171 surveys the properties of HTTP that are important to preserve, and 172 Section 4 conveys best practices for specifying them. 174 It is written primarily to guide IETF efforts to define application 175 protocols using HTTP for deployment on the Internet, but might be 176 applicable in other situations. Note that the requirements herein do 177 not necessarily apply to the development of generic HTTP extensions. 179 1.1. Notational Conventions 181 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 182 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 183 "OPTIONAL" in this document are to be interpreted as described in BCP 184 14 [RFC2119] [RFC8174] when, and only when, they appear in all 185 capitals, as shown here. 187 2. Is HTTP Being Used? 189 Different applications have different goals when using HTTP. The 190 requirements in this document apply when a specification defines an 191 application that: 193 * uses the transport port 80 or 443, or 195 * uses the URI scheme "http" or "https", or 197 * uses an ALPN protocol ID [RFC7301] that generically identifies 198 HTTP (e.g., "http/1.1", "h2", "h2c"), or 200 * updates or modifies the IANA registries defined for HTTP. 202 Additionally, when a specification is using HTTP, all of the 203 requirements of the HTTP protocol suite are in force (in particular, 204 [I-D.ietf-httpbis-semantics], but also other specifications as 205 appropriate). 207 Note that this document is intended to apply to applications, not 208 generic extensions to HTTP. Furthermore, while it is intended for 209 IETF-specified applications, other standards organisations are 210 encouraged to adhere to its requirements. 212 2.1. Non-HTTP Protocols 214 An application can rely upon HTTP without meeting the criteria for 215 using it defined above. For example, an application might wish to 216 avoid re-specifying parts of the message format, but change other 217 aspects of the protocol's operation; or, it might want to use a 218 different set of methods. 220 Doing so brings more freedom to modify protocol operations, but loses 221 at least a portion of the benefits outlined above, as most HTTP 222 implementations won't be easily adaptable to these changes, and the 223 benefit of mindshare will be lost. 225 Such specifications MUST NOT use HTTP's URI schemes, transport ports, 226 ALPN protocol IDs or IANA registries; rather, they are encouraged to 227 establish their own. 229 3. What's Important About HTTP 231 This section examines the characteristics of HTTP that are important 232 to consider when using HTTP to define an application 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 common software (e.g., HTTP servers, intermediaries, 245 client implementations, and caches) without understanding the 246 specific application. It also allows people to leverage their 247 knowledge of HTTP semantics without special-casing them for a 248 particular 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 Specifications should use [I-D.ietf-httpbis-semantics] as the primary 352 reference for HTTP; it is not necessary to reference all of the 353 specifications in the HTTP suite unless there are specific reasons to 354 do so (e.g., a particular feature is called out). 356 Because HTTP is a hop-by-hop protocol, a connection can be handled by 357 implementations that are not controlled by the application; for 358 example, proxies, CDNs, firewalls and so on. Requiring a particular 359 version of HTTP makes it difficult to use in these situations, and 360 harms interoperability. Therefore, it is NOT RECOMMENDED that 361 applications using HTTP specify a minimum version of HTTP to be used. 363 However, if an application's deployment would benefit from the use of 364 a particular version of HTTP (for example, HTTP/2's multiplexing), 365 this ought be noted. 367 Applications using HTTP MUST NOT specify a maximum version, to 368 preserve the protocol's ability to evolve. 370 When specifying examples of protocol interactions, applications 371 should document both the request and response messages, with complete 372 header sections, preferably in HTTP/1.1 format. For example: 374 GET /thing HTTP/1.1 375 Host: example.com 376 Accept: application/things+json 377 User-Agent: Foo/1.0 379 HTTP/1.1 200 OK 380 Content-Type: application/things+json 381 Content-Length: 500 382 Server: Bar/2.2 384 [content here] 386 4.2. Specifying Server Behaviour 388 The server-side behaviours of an application are most effectively 389 specified by defining the following protocol elements: 391 * Media types [RFC6838], often based upon a format convention such 392 as JSON [RFC8259], 394 * HTTP header fields, as per Section 4.7, and 396 * The behaviour of resources, as identified by link relations 397 [RFC8288]. 399 An application can define its operation by composing these protocol 400 elements to define a set of resources that are identified by link 401 relations and that implement specified behaviours, including: 403 * retrieval of their state using GET, in one or more formats 404 identified by media type; 406 * resource creation or update using POST or PUT, with an 407 appropriately identified request content format; 409 * data processing using POST and identified request and response 410 content format(s); and 412 * Resource deletion using DELETE. 414 For example, an application might specify: 416 Resources linked to with the "example-widget" link relation type are 417 Widgets. The state of a Widget can be fetched in the 418 "application/example-widget+json" format, and can be updated by PUT 419 to the same link. Widget resources can be deleted. 421 The "Example-Count" response header field on Widget representations 422 indicates how many Widgets are held by the sender. 424 The "application/example-widget+json" format is a JSON [RFC8259] 425 format representing the state of a Widget. It contains links to 426 related information in the link indicated by the Link header field 427 value with the "example-other-info" link relation type. 429 Applications can also specify the use of URI Templates [RFC6570] to 430 allow clients to generate URLs based upon runtime data. 432 4.3. Specifying Client Behaviour 434 An application's expectations for client behaviour ought to be 435 closely aligned with those of Web browsers, to avoid interoperability 436 issues when they are used. 438 One way to do this is to define it in terms of [FETCH], since that is 439 the abstraction that browsers use for HTTP. 441 Some client behaviours (e.g., automatic redirect handling) and 442 extensions (e.g., Cookies) are not required by HTTP, but nevertheless 443 have become very common. If their use is not explicitly specified by 444 applications using HTTP, there may be confusion and interoperability 445 problems. In particular: 447 * Redirect handling - Applications need to specify how redirects are 448 expected to be handled; see Section 4.6.1. 450 * Cookies - Applications using HTTP should explicitly reference the 451 Cookie specification [RFC6265] if they are required. 453 * Certificates - Applications using HTTP should specify that TLS 454 certificates are to be checked according to Section 4.3.4 of 455 [I-D.ietf-httpbis-semantics] when HTTPS is used. 457 Applications using HTTP should not statically require HTTP features 458 that are usually negotiated to be supported by clients. For example, 459 requiring that clients support responses with a certain content- 460 coding ([I-D.ietf-httpbis-semantics], Section 8.4.1) instead of 461 negotiating for it ([I-D.ietf-httpbis-semantics], Section 12.5.3) 462 means that otherwise conformant clients cannot interoperate with the 463 application. Applications can encourage the implementation of such 464 features, though. 466 4.4. Specifying URLs 468 In HTTP, the resources that clients interact with are identified with 469 URLs [RFC3986]. As [RFC8820] explains, parts of the URL are designed 470 to be under the control of the owner (also known as the "authority") 471 of that server, to give them the flexibility in deployment. 473 This means that in most cases, specifications for applications that 474 use HTTP won't contain its URLs; while it is common practice for a 475 specification of a single-deployment API to specify the path prefix 476 "/app/v1" (for example), doing so in an IETF specification is 477 inappropriate. 479 Therefore, the specification writer needs some mechanism to allow 480 clients to discovery an application's URLs. Additionally, they need 481 to specify what URL scheme(s) the application should be used with, 482 and whether to use a dedicated port, or reuse HTTP's port(s). 484 4.4.1. Discovering an Application's URLs 486 Generally, a client will begin interacting with a given application 487 server by requesting an initial document that contains information 488 about that particular deployment, potentially including links to 489 other relevant resources. Doing so assures that the deployment is as 490 flexible as possible (potentially spanning multiple servers), allows 491 evolution, and also gives the application the opportunity to tailor 492 the 'discovery document' to the client. 494 There are a few common patterns for discovering that initial URL. 496 The most straightforward mechanism for URL discovery is to configure 497 the client with (or otherwise convey to it) a full URL. This might 498 be done in a configuration document, or through another discovery 499 mechanism. 501 However, if the client only knows the server's hostname and the 502 identity of the application, there needs to be some way to derive the 503 initial URL from that information. 505 An application cannot define a fixed prefix for its URL paths; see 506 [RFC8820]. Instead, a specification for such an application can use 507 one of the following strategies: 509 * Register a Well-Known URI [RFC8615] as an entry point for that 510 application. This provides a fixed path on every potential server 511 that will not collide with other applications. 513 * Enable the server authority to convey a URL Template [RFC6570] or 514 similar mechanism for generating a URL for an entry point. For 515 example, this might be done in a configuration document or other 516 artefact. 518 Once the discovery document is located, it can be fetched, cached for 519 later reuse (if allowed by its metadata), and used to locate other 520 resources that are relevant to the application, using full URIs or 521 URL Templates. 523 In some cases, an application may not wish to use such a discovery 524 document; for example, when communication is very brief, or when the 525 latency concerns of doing so precludes the use of a discovery 526 document. These situations can be addressed by placing all of the 527 application's resources under a well-known location. 529 4.4.2. Considering URI Schemes 531 Applications that use HTTP will typically employ the "http" and/or 532 "https" URI schemes. "https" is RECOMMENDED to provide 533 authentication, integrity and confidentiality, as well as mitigate 534 pervasive monitoring attacks [RFC7258]. 536 However, application-specific schemes can also be defined. When 537 defining an URI scheme for an application using HTTP, there are a 538 number of tradeoffs and caveats to keep in mind: 540 * Unmodified Web browsers will not support the new scheme. While it 541 is possible to register new URI schemes with Web browsers (e.g. 542 registerProtocolHandler() in [HTML], as well as several 543 proprietary approaches), support for these mechanisms is not 544 shared by all browsers, and their capabilities vary. 546 * Existing non-browser clients, intermediaries, servers and 547 associated software will not recognise the new scheme. For 548 example, a client library might fail to dispatch the request; a 549 cache might refuse to store the response, and a proxy might fail 550 to forward the request. 552 * Because URLs occur in HTTP artefacts commonly, often being 553 generated automatically (e.g., in the "Location" response header 554 field), it can be difficult to assure that the new scheme is used 555 consistently. 557 * The resources identified by the new scheme will still be available 558 using "http" and/or "https" URLs. Those URLs can "leak" into use, 559 which can present security and operability issues. For example, 560 using a new scheme to assure that requests don't get sent to a 561 "normal" Web site is likely to fail. 563 * Features that rely upon the URL's origin [RFC6454], such as the 564 Web's same-origin policy, will be impacted by a change of scheme. 566 * HTTP-specific features such as cookies [RFC6265], authentication 567 [I-D.ietf-httpbis-semantics], caching [I-D.ietf-httpbis-cache], 568 HSTS [RFC6797], and CORS [FETCH] might or might not work 569 correctly, depending on how they are defined and implemented. 570 Generally, they are designed and implemented with an assumption 571 that the URL will always be "http" or "https". 573 * Web features that require a secure context [SECCTXT] will likely 574 treat a new scheme as insecure. 576 See [RFC7595] for more information about minting new URI schemes. 578 4.4.3. Transport Ports 580 Applications can use the applicable default port (80 for HTTP, 443 581 for HTTPS), or they can be deployed upon other ports. This decision 582 can be made at deployment time, or might be encouraged by the 583 application's specification (e.g., by registering a port for that 584 application). 586 If a non-default port is used, it needs to be reflected in the 587 authority of all URLs for that resource; the only mechanism for 588 changing a default port is changing the URI scheme (see 589 Section 4.4.2). 591 Using a port other than the default has privacy implications (i.e., 592 the protocol can now be distinguished from other traffic), as well as 593 operability concerns (as some networks might block or otherwise 594 interfere with it). Privacy implications should be documented in 595 Security Considerations. 597 See [RFC7605] for further guidance. 599 4.5. Using HTTP Methods 601 Applications that use HTTP MUST confine themselves to using 602 registered HTTP methods such as GET, POST, PUT, DELETE, and PATCH. 604 New HTTP methods are rare; they are required to be registered in the 605 HTTP Method Registry with IETF Review (see 606 [I-D.ietf-httpbis-semantics]), and are also required to be generic. 607 That means that they need to be potentially applicable to all 608 resources, not just those of one application. 610 While historically some applications (e.g., [RFC4791]) have defined 611 non-generic methods, [I-D.ietf-httpbis-semantics] now forbids this. 613 When authors believe that a new method is required, they are 614 encouraged to engage with the HTTP community early, and document 615 their proposal as a separate HTTP extension, rather than as part of 616 an application's specification. 618 4.5.1. GET 620 GET is the most common and useful HTTP method; its retrieval 621 semantics allow caching, side-effect free linking and underlies many 622 of the benefits of using HTTP. 624 Queries can be performed with GET, often using the query component of 625 the URL; this is a familiar pattern from Web browsing, and the 626 results can be cached, improving efficiency of an often expensive 627 process. In some cases, however, GET might be unwieldy for 628 expressing queries, because of the limited syntax of the URI; in 629 particular, if binary data forms part of the query terms, it needs to 630 be encoded to conform to URI syntax. 632 While this is not an issue for short queries, it can become one for 633 larger query terms, or ones which need to sustain a high rate of 634 requests. Additionally, some HTTP implementations limit the size of 635 URLs they support -- although modern HTTP software has much more 636 generous limits than previously (typically, considerably more than 637 8000 octets, as required by [I-D.ietf-httpbis-semantics]). 639 In these cases, an application using HTTP might consider using POST 640 to express queries in the request's content; doing so avoids encoding 641 overhead and URL length limits in implementations. However, in doing 642 so it should be noted that the benefits of GET such as caching and 643 linking to query results are lost. Therefore, applications using 644 HTTP that feel a need to allow POST queries ought consider allowing 645 both methods. 647 Applications should not change their state or have other side effects 648 that might be significant to the client, since implementations can 649 and do retry HTTP GET requests that fail. Note that this does not 650 include logging and similar functions; see 651 [I-D.ietf-httpbis-semantics], Section 9.2.1. 653 Finally, note that while HTTP allows GET requests to have content 654 syntactically, this is done only to allow parsers to be generic; as 655 per [I-D.ietf-httpbis-semantics], Section 9.3.1, content on a GET has 656 no meaning, and will be either ignored or rejected by generic HTTP 657 software. 659 4.5.2. OPTIONS 661 The OPTIONS method was defined for metadata retrieval, and is used 662 both by WebDAV [RFC4918] and CORS [FETCH]. Because HTTP-based APIs 663 often need to retrieve metadata about resources, it is often 664 considered for their use. 666 However, OPTIONS does have significant limitations: 668 * It isn't possible to link to the metadata with a simple URL, 669 because OPTIONS is not the default GET method. 671 * OPTIONS responses are not cacheable, because HTTP caches operate 672 on representations of the resource (i.e., GET and HEAD). If 673 OPTIONS responses are cached separately, their interaction with 674 HTTP cache expiry, secondary keys and other mechanisms needs to be 675 considered. 677 * OPTIONS is "chatty" - always separating metadata out into a 678 separate request increases the number of requests needed to 679 interact with the application. 681 * Implementation support for OPTIONS is not universal; some servers 682 do not expose the ability to respond to OPTIONS requests without 683 significant effort. 685 Instead of OPTIONS, one of these alternative approaches might be more 686 appropriate: 688 * For server-wide metadata, create a well-known URI [RFC8615], or 689 using an already existing one if it's appropriate (e.g., HostMeta 690 [RFC6415]). 692 * For metadata about a specific resource, create a separate resource 693 and link to it using a Link response header field or a link 694 serialised into the response's content. See [RFC8288]. Note that 695 the Link header field is available on HEAD responses, which is 696 useful if the client wants to discover a resource's capabilities 697 before they interact with it. 699 4.6. Using HTTP Status Codes 701 HTTP status codes convey semantics both for the benefit of generic 702 HTTP components -- such as caches, intermediaries, and clients -- and 703 applications themselves. However, applications can encounter a 704 number of pitfalls in their use. 706 First, status codes are often generated by components other the the 707 application itself. This can happen, for example, when network 708 errors are encountered, a captive portal, proxy or Content Delivery 709 Network is present, when a server is overloaded, or it thinks it is 710 under attack. They can even be generated by generic client software 711 when certain error conditions are encountered. As a result, if an 712 application assigns specific semantics to one of these status codes, 713 a client can be misled about its state, because the status code was 714 generated by a generic component, not the application itself. 716 Furthermore, mapping application errors to individual HTTP status 717 codes one-to-one often leads to a situation where the finite space of 718 applicable HTTP status codes is exhausted. This, in turn, leads to a 719 number of bad practices -- including minting new, application- 720 specific status codes, or using existing status codes even though the 721 link between their semantics and the application's is tenuous at 722 best. 724 Instead, applications using HTTP should define their errors to use 725 the most applicable status code, making generous use of the general 726 status codes (200, 400 and 500) when in doubt. Importantly, they 727 should not specify a one-to-one relationship between status codes and 728 application errors, thereby avoiding the exhaustion issue outlined 729 above. 731 To distinguish between multiple error conditions that are mapped to 732 the same status code, and to avoid the misattribution issue outlined 733 above, applications using HTTP should convey finer-grained error 734 information in the response's message content and/or header fields. 735 [RFC7807] provides one way to do so. 737 Because the set of registered HTTP status codes can expand, 738 applications using HTTP should explicitly point out that clients 739 ought to be able to handle all applicable status codes gracefully 740 (i.e., falling back to the generic "n00" semantics of a given status 741 code; e.g., "499" can be safely handled as "400" by clients that 742 don't recognise it). This is preferable to creating a "laundry list" 743 of potential status codes, since such a list won't be complete in the 744 foreseeable future. 746 Applications using HTTP MUST NOT re-specify the semantics of HTTP 747 status codes, even if it is only by copying their definition. It is 748 NOT RECOMMENDED they require specific reason phrases to be used; the 749 reason phrase has no function in HTTP, is not guaranteed to be 750 preserved by implementations, and is not carried at all in the HTTP/2 751 [RFC7540] message format. 753 Applications MUST only use registered HTTP status codes. As with 754 methods, new HTTP status codes are rare, and required (by 755 [I-D.ietf-httpbis-semantics]) to be registered with IETF Review. 756 Similarly, HTTP status codes are generic; they are required (by 757 [I-D.ietf-httpbis-semantics]) to be potentially applicable to all 758 resources, not just to those of one application. 760 When authors believe that a new status code is required, they are 761 encouraged to engage with the HTTP community early, and document 762 their proposal as a separate HTTP extension, rather than as part of 763 an application's specification. 765 4.6.1. Redirection 767 The 3xx series of status codes specified in Section 15.4 of 768 [I-D.ietf-httpbis-semantics] direct the user agent to another 769 resource to satisfy the request. The most common of these are 301, 770 302, 307 and 308, all of which use the Location response header field 771 to indicate where the client should resend the request. 773 There are two ways that the members of this group of status codes 774 differ: 776 * Whether they are permanent or temporary. Permanent redirects can 777 be used to update links stored in the client (e.g., bookmarks), 778 whereas temporary ones can not. Note that this has no effect on 779 HTTP caching; it is completely separate. 781 * Whether they allow the redirected request to change the request 782 method from POST to GET. Web browsers generally do change POST to 783 GET for 301 and 302; therefore, 308 and 307 were created to allow 784 redirection without changing the method. 786 This table summarises their relationships: 788 +=============================+===========+===========+ 789 | | Permanent | Temporary | 790 +=============================+===========+===========+ 791 | Allows changing the request | 301 | 302 | 792 | method from POST to GET | | | 793 +-----------------------------+-----------+-----------+ 794 | Does not allow changing the | 308 | 307 | 795 | request method | | | 796 +-----------------------------+-----------+-----------+ 798 Table 1 800 The 303 See Other status code can be used to inform the client that 801 the result of an operation is available at a different location using 802 GET. 804 As noted in [I-D.ietf-httpbis-semantics], a user agent is allowed to 805 automatically follow a 3xx redirect that has a Location response 806 header field, even if they don't understand the semantics of the 807 specific status code. However, they aren't required to do so; 808 therefore, if an application using HTTP desires redirects to be 809 automatically followed, it needs to explicitly specify the 810 circumstances when this is required. 812 Redirects can be cached (when appropriate cache directives are 813 present), but beyond that they are not 'sticky' -- i.e., redirection 814 of a URI will not result in the client assuming that similar URIs 815 (e.g., with different query parameters) will also be redirected. 817 Applications using HTTP are encouraged to specify that 301 and 302 818 responses change the subsequent request method from POST (but no 819 other method) to GET, to be compatible with browsers. Generally, 820 when a redirected request is made, its header fields are copied from 821 the original request's. However, they can be modified by various 822 mechanisms; e.g., sent Authorization ([I-D.ietf-httpbis-semantics], 823 Section 11) and Cookie ([RFC6265]) header fields will change if the 824 origin (and sometimes path) of the request changes. An application 825 using HTTP should specify if any request header fields that it 826 defines need to be modified or removed upon a redirect; however, this 827 behaviour cannot be relied upon, since a generic client (like a 828 browser) will be unaware of such requirements. 830 4.7. Specifying HTTP Header Fields 832 Applications often define new HTTP header fields. Typically, using 833 HTTP header fields is appropriate in a few different situations: 835 * The field is useful to intermediaries (who often wish to avoid 836 parsing message content), and/or 838 * The field is useful to generic HTTP software (e.g., clients, 839 servers), and/or 841 * It is not possible to include their values in the message content 842 (usually because a format does not allow it). 844 When the conditions above are not met, it is usually better to convey 845 application-specific information in other places; e.g., the message 846 content or the URL query string. 848 New header fields MUST be registered, as per Section 16.3 of 849 [I-D.ietf-httpbis-semantics]. 851 See Section 16.3.2 of [I-D.ietf-httpbis-semantics] for guidelines to 852 consider when minting new header fields. [RFC8941] provides a common 853 structure for new header fields, and avoids many issues in their 854 parsing and handling; it is RECOMMENDED that new header fields use 855 it. 857 It is RECOMMENDED that header field names be short (even when field 858 compression is used, there is an overhead) but appropriately 859 specific. In particular, if a header field is specific to an 860 application, an identifier for that application can form a prefix to 861 the header field name, separated by a "-". 863 For example, if the "example" application needs to create three 864 header fields, they might be called "example-foo", "example-bar" and 865 "example-baz". Note that the primary motivation here is to avoid 866 consuming more generic field names, not to reserve a portion of the 867 namespace for the application; see [RFC6648] for related 868 considerations. 870 The semantics of existing HTTP header fields MUST NOT be re-defined 871 without updating their registration or defining an extension to them 872 (if allowed). For example, an application using HTTP cannot specify 873 that the "Location" header field has a special meaning in a certain 874 context. 876 See Section 4.9 for the interaction between header fields and HTTP 877 caching; in particular, request header fields that are used to 878 "select" a response have impact there, and need to be carefully 879 considered. 881 See Section 4.10 for considerations regarding header fields that 882 carry application state (e.g., Cookie). 884 4.8. Defining Message Content 886 Common syntactic conventions for message contents include JSON 887 [RFC8259], XML [XML], and CBOR [RFC7049]. Best practices for their 888 use are out of scope for this document. 890 Applications should register distinct media types for each format 891 they define; this makes it possible to identify them unambiguously 892 and negotiate for their use. See [RFC6838] for more information. 894 4.9. Leveraging HTTP Caching 896 HTTP caching [I-D.ietf-httpbis-cache] is one of the primary benefits 897 of using HTTP for applications; it provides scalability, reduces 898 latency and improves reliability. Furthermore, HTTP caches are 899 readily available in browsers and other clients, networks as forward 900 and reverse proxies, Content Delivery Networks and as part of server 901 software. 903 Even when an application using HTTP isn't designed to take advantage 904 of caching, it needs to consider how caches will handle its 905 responses, to preserve correct behaviour when one is interposed 906 (whether in the network, server, client, or intervening 907 infrastructure). 909 4.9.1. Freshness 911 Assigning even a short freshness lifetime ([I-D.ietf-httpbis-cache], 912 Section 4.2) -- e.g., 5 seconds -- allows a response to be reused to 913 satisfy multiple clients, and/or a single client making the same 914 request repeatedly. In general, if it is safe to reuse something, 915 consider assigning a freshness lifetime. 917 The most common method for specifying freshness is the max-age 918 response directive ([I-D.ietf-httpbis-cache], Section 5.2.2.1). The 919 Expires header field ([I-D.ietf-httpbis-cache], Section 5.3) can also 920 be used, but it is not necessary; all modern cache implementations 921 support Cache-Control, and specifying freshness as a delta is usually 922 more convenient and less error-prone. 924 It is not necessary to add the public response directive 925 ([I-D.ietf-httpbis-cache], Section 5.2.2.9) to cache most responses; 926 it is only necessary when it's desirable to store an authenticated 927 response. 929 In some situations, responses without explicit cache freshness 930 directives will be stored and served using a heuristic freshness 931 lifetime; see [I-D.ietf-httpbis-cache], Section 4.2.2. As the 932 heuristic is not under control of the application, it is generally 933 preferable to set an explicit freshness lifetime, or make the 934 response explicitly uncacheable. 936 If caching of a response is not desired, the appropriate response 937 directive is "Cache-Control: no-store". Other directives are not 938 necessary, and no-store only need be sent in situations where the 939 response might be cached; see [I-D.ietf-httpbis-cache], Section 3. 940 Note that "Cache-Control: no-cache" allows a response to be stored, 941 just not reused by a cache without validation; it does not prevent 942 caching (despite its name). 944 For example, this response cannot be stored or reused by a cache: 946 HTTP/1.1 200 OK 947 Content-Type: application/example+xml 948 Cache-Control: no-store 950 [content] 952 4.9.2. Stale Responses 954 Authors should understand that stale responses (e.g., with "Cache- 955 Control: max-age=0") can be reused by caches when disconnected from 956 the origin server; this can be useful for handling network issues. 958 If doing so is not suitable for a given response, the origin should 959 use "Cache-Control: must-revalidate". See Section 4.2.4 of 960 [I-D.ietf-httpbis-cache], and also [RFC5861] for additional controls 961 over stale content. 963 Stale responses can be refreshed by assigning a validator, saving 964 both transfer bandwidth and latency for large responses; see 965 Section 13 of [I-D.ietf-httpbis-semantics]. 967 4.9.3. Caching and Application Semantics 969 When an application has a need to express a lifetime that's separate 970 from the freshness lifetime, this should be conveyed separately, 971 either in the response's content or in a separate header field. When 972 this happens, the relationship between HTTP caching and that lifetime 973 need to be carefully considered, since the response will be used as 974 long as it is considered fresh. 976 In particular, application authors need to consider how responses 977 that are not freshly obtained from the origin server should be 978 handled; if they have a concept like a validity period, this will 979 need to be calculated considering the age of the response (see 980 [I-D.ietf-httpbis-cache], Section 4.2.3). 982 One way to address this is to explicitly specify that all responses 983 be fresh upon use. 985 4.9.4. Varying Content Based Upon the Request 987 If an application uses a request header field to change the 988 response's header fields or content, authors should point out that 989 this has implications for caching; in general, such resources need to 990 either make their responses uncacheable (e.g., with the "no-store" 991 cache-control directive defined in [I-D.ietf-httpbis-cache], 992 Section 5.2.2.5) or send the Vary response header field 993 ([I-D.ietf-httpbis-semantics], Section 12.5.5) on all responses from 994 that resource (including the "default" response). 996 For example, this response: 998 HTTP/1.1 200 OK 999 Content-Type: application/example+xml 1000 Cache-Control: max-age=60 1001 ETag: "sa0f8wf20fs0f" 1002 Vary: Accept-Encoding 1004 [content] 1006 can be stored for 60 seconds by both private and shared caches, can 1007 be revalidated with If-None-Match, and varies on the Accept-Encoding 1008 request header field. 1010 4.10. Handling Application State 1012 Applications can use stateful cookies [RFC6265] to identify a client 1013 and/or store client-specific data to contextualise requests. 1015 When used, it is important to carefully specify the scoping and use 1016 of cookies; if the application exposes sensitive data or capabilities 1017 (e.g., by acting as an ambient authority), exploits are possible. 1018 Mitigations include using a request-specific token to assure the 1019 intent of the client. 1021 4.11. Making Multiple Requests 1023 Clients often need to send multiple requests to perform a task. 1025 In HTTP/1, parallel requests are most often supported by opening 1026 multiple connections. Application performance can be impacted when 1027 too many simultaneous connections are used, because connections' 1028 congestion control will not be coordinated. Furthermore, it can be 1029 difficult for applications to decide when and to select which 1030 connection to use to issue a given request, further impacting 1031 performance. 1033 HTTP/2 and HTTP/3 offer multiplexing to applications, removing the 1034 need to use multiple connections. However, application performance 1035 can still be significantly affected by how the server chooses to 1036 prioritize responses. Depending on the application, it might be best 1037 for the server to determine the priority of responses, or for the 1038 client to hint its priorities to the server (see, e.g., 1039 [I-D.ietf-httpbis-priority]). 1041 In all versions of HTTP, requests are made independently -- you can't 1042 rely on the relative order of two requests to guarantee processing 1043 order. This is because they might be sent over a multiplexed 1044 protocol by an intermediary, sent to different origin servers, or the 1045 server might even perform processing in a different order. If two 1046 requests need strict ordering, the only reliable way to assure the 1047 outcome is to issue the second request when the final response to the 1048 first has begun. 1050 Applications MUST NOT make assumptions about the relationship between 1051 separate requests on a single transport connection; doing so breaks 1052 many of the assumptions of HTTP as a stateless protocol, and will 1053 cause problems in interoperability, security, operability and 1054 evolution. 1056 4.12. Client Authentication 1058 Applications can use HTTP authentication Section 11 of 1059 [I-D.ietf-httpbis-semantics] to identify clients. The Basic 1060 authentication scheme [RFC7617] MUST NOT be used unless the 1061 underlying transport is authenticated, integrity-protected and 1062 confidential (e.g., as provided the "HTTPS" URI scheme, or another 1063 using TLS). The Digest scheme [RFC7616] MUST NOT be used unless the 1064 underlying transport is similarly secure, or the chosen hash 1065 algorithm is not "MD5". 1067 With HTTPS, clients might also be authenticated using certificates 1068 [RFC5246]. 1070 When used, it is important to carefully specify the scoping and use 1071 of authentication; if the application exposes sensitive data or 1072 capabilities (e.g., by acting as an ambient authority), exploits are 1073 possible. Mitigations include using a request-specific token to 1074 assure the intent of the client. 1076 4.13. Co-Existing with Web Browsing 1078 Even if there is not an intent for an application to be used with a 1079 Web browser, its resources will remain available to browsers and 1080 other HTTP clients. This means that all such applications that use 1081 HTTP need to consider how browsers will interact with them, 1082 particularly regarding security. 1084 For example, if an application's state can be changed using a POST 1085 request, a Web browser can easily be coaxed into cross-site request 1086 forgery (CSRF) from arbitrary Web sites. 1088 Or, if an attacker gains control of content returned from the 1089 application's resources (for example, part of the request is 1090 reflected in the response, or the response contains external 1091 information that the attacker can change), they can inject code into 1092 the browser and access data and capabilities as if they were the 1093 origin -- a technique known as a cross-site scripting (XSS) attack. 1095 This is only a small sample of the kinds of issues that applications 1096 using HTTP must consider. Generally, the best approach is to 1097 consider the application actually as a Web application, and to follow 1098 best practices for their secure development. 1100 A complete enumeration of such practices is out of scope for this 1101 document, but some considerations include: 1103 * Using an application-specific media type in the Content-Type 1104 header field, and requiring clients to fail if it is not used. 1106 * Using X-Content-Type-Options: nosniff [FETCH] to assure that 1107 content under attacker control can't be coaxed into a form that is 1108 interpreted as active content by a Web browser. 1110 * Using Content-Security-Policy [CSP] to constrain the capabilities 1111 of active content (i.e., that which can execute script, such as 1112 HTML [HTML] and PDF), thereby mitigating Cross-Site Scripting 1113 attacks. 1115 * Using Referrer-Policy [REFERRER-POLICY] to prevent sensitive data 1116 in URLs from being leaked in the Referer request header field. 1118 * Using the 'HttpOnly' flag on Cookies to assure that cookies are 1119 not exposed to browser scripting languages [RFC6265]. 1121 * Avoiding use of compression on any sensitive information (e.g., 1122 authentication tokens, passwords), as the scripting environment 1123 offered by Web browsers allows an attacker to repeatedly probe the 1124 compression space; if the attacker has access to the path of the 1125 communication, they can use this capability to recover that 1126 information. 1128 Depending on how they are intended to be deployed, specifications for 1129 applications using HTTP might require the use of these mechanisms in 1130 specific ways, or might merely point them out in Security 1131 Considerations. 1133 An example of a HTTP response from an application that does not 1134 intend for its content to be treated as active by browsers might look 1135 like this: 1137 HTTP/1.1 200 OK 1138 Content-Type: application/example+json 1139 X-Content-Type-Options: nosniff 1140 Content-Security-Policy: default-src 'none' 1141 Cache-Control: max-age=3600 1142 Referrer-Policy: no-referrer 1144 [content] 1146 If an application has browser compatibility as a goal, client 1147 interaction ought to be defined in terms of [FETCH], since that is 1148 the abstraction that browsers use for HTTP; it enforces many of these 1149 best practices. 1151 4.14. Maintaining Application Boundaries 1153 Because many HTTP capabilities are scoped to the origin [RFC6454], 1154 applications also need to consider how deployments might interact 1155 with other applications (including Web browsing) on the same origin. 1157 For example, if Cookies [RFC6265] are used to carry application 1158 state, they will be sent with all requests to the origin by default 1159 (unless scoped by path), and the application might receive cookies 1160 from other applications on the origin. This can lead to security 1161 issues, as well as collision in cookie names. 1163 One solution to these issues is to require a dedicated hostname for 1164 the application, so that it has a unique origin. However, it is 1165 often desirable to allow multiple applications to be deployed on a 1166 single hostname; doing so provides the most deployment flexibility 1167 and enables them to be "mixed" together (See [RFC8820] for details). 1168 Therefore, applications using HTTP should strive to allow multiple 1169 applications on an origin. 1171 To enable this, when specifying the use of Cookies, HTTP 1172 authentication realms [I-D.ietf-httpbis-semantics], or other origin- 1173 wide HTTP mechanisms, applications using HTTP should not mandate the 1174 use of a particular name, but instead let deployments configure them. 1175 Consideration should be given to scoping them to part of the origin, 1176 using their specified mechanisms for doing so. 1178 Modern Web browsers constrain the ability of content from one origin 1179 to access resources from another, to avoid leaking private 1180 information. As a result, applications that wish to expose cross- 1181 origin data to browsers will need to implement the CORS protocol; see 1182 [FETCH]. 1184 4.15. Using Server Push 1186 HTTP/2 adds the ability for servers to "push" request/response pairs 1187 to clients in [RFC7540], Section 8.2. While server push seems like a 1188 natural fit for many common application semantics (e.g., "fanout" and 1189 publish/subscribe), a few caveats should be noted: 1191 * Server push is hop-by-hop; that is, it is not automatically 1192 forwarded by intermediaries. As a result, it might not work 1193 easily (or at all) with proxies, reverse proxies, and Content 1194 Delivery Networks. 1196 * Server push can have negative performance impact on HTTP when used 1197 incorrectly; in particular, if there is contention with resources 1198 that have actually been requested by the client. 1200 * Server push is implemented differently in different clients, 1201 especially regarding interaction with HTTP caching, and 1202 capabilities might vary. 1204 * APIs for server push are currently unavailable in some 1205 implementations, and vary widely in others. In particular, there 1206 is no current browser API for it. 1208 * Server push is not supported in HTTP/1.1 or HTTP/1.0. 1210 * Server push does not form part of the "core" semantics of HTTP, 1211 and therefore might not be supported by future versions of the 1212 protocol. 1214 Applications wishing to optimise cases where the client can perform 1215 work related to requests before the full response is available (e.g., 1216 fetching links for things likely to be contained within) might 1217 benefit from using the 103 (Early Hints) status code; see [RFC8297]. 1219 Applications using server push directly need to enforce the 1220 requirements regarding authority in [RFC7540], Section 8.2, to avoid 1221 cross-origin push attacks. 1223 4.16. Allowing Versioning and Evolution 1225 It's often necessary to introduce new features into application 1226 protocols, and change existing ones. 1228 In HTTP, backwards-incompatible changes are possible using a number 1229 of mechanisms: 1231 * Using a distinct link relation type [RFC8288] to identify a URL 1232 for a resource that implements the new functionality. 1234 * Using a distinct media type [RFC6838] to identify formats that 1235 enable the new functionality. 1237 * Using a distinct HTTP header field to implement new functionality 1238 outside the message content. 1240 5. IANA Considerations 1242 This document has no requirements for IANA. 1244 6. Security Considerations 1246 Section 4.10 discusses the impact of using stateful mechanisms in the 1247 protocol as ambient authority, and suggests a mitigation. 1249 Section 4.4.2 requires support for 'https' URLs, and discourages the 1250 use of 'http' URLs, to provide authentication, integrity and 1251 confidentiality, as well as mitigate pervasive monitoring attacks. 1253 Section 4.13 highlights the implications of Web browsers' 1254 capabilities on applications that use HTTP. 1256 Section 4.14 discusses the issues that arise when applications are 1257 deployed on the same origin as Web sites (and other applications). 1259 Section 4.15 highlights risks of using HTTP/2 server push in a manner 1260 other than specified. 1262 Applications that use HTTP in a manner that involves modification of 1263 implementations -- for example, requiring support for a new URI 1264 scheme, or a non-standard method -- risk having those implementations 1265 "fork" from their parent HTTP implementations, with the possible 1266 result that they do not benefit from patches and other security 1267 improvements incorporated upstream. 1269 6.1. Privacy Considerations 1271 HTTP clients can expose a variety of information to servers. Besides 1272 information that's explicitly sent as part of an application's 1273 operation (for example, names and other user-entered data), and "on 1274 the wire" (which is one of the reasons https is recommended in 1275 Section 4.4.2), other information can be gathered through less 1276 obvious means -- often by connecting activities of a user over time. 1278 This includes session information, tracking the client through 1279 fingerprinting, and mobile code. 1281 Session information includes things like the IP address of the 1282 client, TLS session tickets, Cookies, ETags stored in the client's 1283 cache, and other stateful mechanisms. Applications are advised to 1284 avoid using session mechanisms unless they are unavoidable or 1285 necessary for operation, in which case these risks needs to be 1286 documented. When they are used, implementations should be encouraged 1287 to allow clearing such state. 1289 Fingerprinting uses unique aspects of a client's messages and 1290 behaviours to connect disparate requests and connections. For 1291 example, the User-Agent request header field conveys specific 1292 information about the implementation; the Accept-Language request 1293 header field conveys the users' preferred language. In combination, 1294 a number of these markers can be used to uniquely identify a client, 1295 impacting its control over its data. As a result, applications are 1296 advised to specify that clients should only emit the information they 1297 need to function in requests. 1299 Finally, if an application exposes the ability to run mobile code, 1300 great care needs to be taken, since any ability to observe its 1301 environment can be used as an opportunity to both fingerprint the 1302 client and to obtain and manipulate private data (including session 1303 information). For example, access to high-resolution timers (even 1304 indirectly) can be used to profile the underlying hardware, creating 1305 a unique identifier for the system. Applications are advised to 1306 avoid allowing the use of mobile code where possible; when it cannot 1307 be avoided, the resulting system's security properties need be 1308 carefully scrutinised. 1310 7. References 1312 7.1. Normative References 1314 [I-D.ietf-httpbis-semantics] 1315 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 1316 Semantics", Work in Progress, Internet-Draft, draft-ietf- 1317 httpbis-semantics-15, 30 March 2021, 1318 . 1321 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1322 Requirement Levels", BCP 14, RFC 2119, 1323 DOI 10.17487/RFC2119, March 1997, 1324 . 1326 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1327 Resource Identifier (URI): Generic Syntax", STD 66, 1328 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1329 . 1331 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 1332 DOI 10.17487/RFC6454, December 2011, 1333 . 1335 [RFC6648] Saint-Andre, P., Crocker, D., and M. Nottingham, 1336 "Deprecating the "X-" Prefix and Similar Constructs in 1337 Application Protocols", BCP 178, RFC 6648, 1338 DOI 10.17487/RFC6648, June 2012, 1339 . 1341 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1342 Specifications and Registration Procedures", BCP 13, 1343 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1344 . 1346 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 1347 "Transport Layer Security (TLS) Application-Layer Protocol 1348 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 1349 July 2014, . 1351 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1352 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1353 May 2017, . 1355 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1356 DOI 10.17487/RFC8288, October 2017, 1357 . 1359 [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers 1360 (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, 1361 . 1363 [RFC8820] Nottingham, M., "URI Design and Ownership", BCP 190, 1364 RFC 8820, DOI 10.17487/RFC8820, June 2020, 1365 . 1367 7.2. Informative References 1369 [CSP] West, M., "Content Security Policy Level 3", World Wide 1370 Web Consortium WD WD-CSP3-20160913, 13 September 2016, 1371 . 1373 [FETCH] WHATWG, "Fetch - Living Standard", n.d., 1374 . 1376 [HTML] WHATWG, "HTML - Living Standard", n.d., 1377 . 1379 [I-D.ietf-httpbis-cache] 1380 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 1381 Caching", Work in Progress, Internet-Draft, draft-ietf- 1382 httpbis-cache-15, 30 March 2021, 1383 . 1385 [I-D.ietf-httpbis-priority] 1386 Oku, K. and L. Pardue, "Extensible Prioritization Scheme 1387 for HTTP", Work in Progress, Internet-Draft, draft-ietf- 1388 httpbis-priority-03, 11 January 2021, 1389 . 1392 [REFERRER-POLICY] 1393 Eisinger, J. and E. Stark, "Referrer Policy", World Wide 1394 Web Consortium CR CR-referrer-policy-20170126, 26 January 1395 2017, 1396 . 1398 [RFC3205] Moore, K., "On the use of HTTP as a Substrate", BCP 56, 1399 RFC 3205, DOI 10.17487/RFC3205, February 2002, 1400 . 1402 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 1403 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 1404 DOI 10.17487/RFC4791, March 2007, 1405 . 1407 [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed 1408 Authoring and Versioning (WebDAV)", RFC 4918, 1409 DOI 10.17487/RFC4918, June 2007, 1410 . 1412 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1413 (TLS) Protocol Version 1.2", RFC 5246, 1414 DOI 10.17487/RFC5246, August 2008, 1415 . 1417 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 1418 Content", RFC 5861, DOI 10.17487/RFC5861, May 2010, 1419 . 1421 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1422 DOI 10.17487/RFC6265, April 2011, 1423 . 1425 [RFC6415] Hammer-Lahav, E., Ed. and B. Cook, "Web Host Metadata", 1426 RFC 6415, DOI 10.17487/RFC6415, October 2011, 1427 . 1429 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1430 and D. Orchard, "URI Template", RFC 6570, 1431 DOI 10.17487/RFC6570, March 2012, 1432 . 1434 [RFC6797] Hodges, J., Jackson, C., and A. Barth, "HTTP Strict 1435 Transport Security (HSTS)", RFC 6797, 1436 DOI 10.17487/RFC6797, November 2012, 1437 . 1439 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1440 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1441 October 2013, . 1443 [RFC7258] Farrell, S. and H. Tschofenig, "Pervasive Monitoring Is an 1444 Attack", BCP 188, RFC 7258, DOI 10.17487/RFC7258, May 1445 2014, . 1447 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1448 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1449 DOI 10.17487/RFC7540, May 2015, 1450 . 1452 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 1453 and Registration Procedures for URI Schemes", BCP 35, 1454 RFC 7595, DOI 10.17487/RFC7595, June 2015, 1455 . 1457 [RFC7605] Touch, J., "Recommendations on Using Assigned Transport 1458 Port Numbers", BCP 165, RFC 7605, DOI 10.17487/RFC7605, 1459 August 2015, . 1461 [RFC7616] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP 1462 Digest Access Authentication", RFC 7616, 1463 DOI 10.17487/RFC7616, September 2015, 1464 . 1466 [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", 1467 RFC 7617, DOI 10.17487/RFC7617, September 2015, 1468 . 1470 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 1471 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 1472 . 1474 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1475 Interchange Format", STD 90, RFC 8259, 1476 DOI 10.17487/RFC8259, December 2017, 1477 . 1479 [RFC8297] Oku, K., "An HTTP Status Code for Indicating Hints", 1480 RFC 8297, DOI 10.17487/RFC8297, December 2017, 1481 . 1483 [RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for 1484 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 1485 . 1487 [SECCTXT] West, M., "Secure Contexts", World Wide Web Consortium CR 1488 CR-secure-contexts-20160915, 15 September 2016, 1489 . 1491 [XML] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 1492 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 1493 Edition)", World Wide Web Consortium Recommendation REC- 1494 xml-20081126, 26 November 2008, 1495 . 1497 Appendix A. Changes from RFC 3205 1499 [RFC3205] captured the Best Current Practice in the early 2000's, 1500 based on the concerns facing protocol designers at the time. Use of 1501 HTTP has changed considerably since then, and as a result this 1502 document is substantially different. As a result, the changes are 1503 too numerous to list individually. 1505 Author's Address 1507 Mark Nottingham 1508 Prahran VIC 1509 Australia 1511 Email: mnot@mnot.net 1512 URI: https://www.mnot.net/