idnits 2.17.1 draft-ietf-httpbis-bcp56bis-03.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 ([2], [3], [1]), 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 (April 2, 2018) is 2214 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) -- Looks like a reference, but probably isn't: '1' on line 1141 -- Looks like a reference, but probably isn't: '2' on line 1143 -- Looks like a reference, but probably isn't: '3' on line 1145 ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7232 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7233 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7320 (Obsoleted by RFC 8820) ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) -- Obsolete informational reference (is this intentional?): RFC 793 (Obsoleted by RFC 9293) -- Obsolete informational reference (is this intentional?): RFC 2821 (Obsoleted by RFC 5321) -- Obsolete informational reference (is this intentional?): RFC 3205 (Obsoleted by RFC 9205) -- Obsolete informational reference (is this intentional?): RFC 5785 (Obsoleted by RFC 8615) -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 7807 (Obsoleted by RFC 9457) Summary: 10 errors (**), 0 flaws (~~), 1 warning (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP M. Nottingham 3 Internet-Draft April 2, 2018 4 Obsoletes: 3205 (if approved) 5 Intended status: Best Current Practice 6 Expires: October 4, 2018 8 On the use of HTTP as a Substrate 9 draft-ietf-httpbis-bcp56bis-03 11 Abstract 13 HTTP is often used as a substrate for other application protocols. 14 This document specifies best practices for these protocols' use of 15 HTTP. 17 This document obsoletes RFC 3205. 19 Note to Readers 21 Discussion of this draft takes place on the HTTP working group 22 mailing list (ietf-http-wg@w3.org), which is archived at 23 https://lists.w3.org/Archives/Public/ietf-http-wg/ [1]. 25 Working Group information can be found at http://httpwg.github.io/ 26 [2]; source code and issues list for this draft can be found at 27 https://github.com/httpwg/http-extensions/labels/bcp56bis [3]. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on October 4, 2018. 46 Copyright Notice 48 Copyright (c) 2018 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (https://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 65 2. Is HTTP Being Used? . . . . . . . . . . . . . . . . . . . . . 4 66 3. What's Important About HTTP . . . . . . . . . . . . . . . . . 5 67 3.1. Generic Semantics . . . . . . . . . . . . . . . . . . . . 5 68 3.2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 6 69 3.3. Rich Functionality . . . . . . . . . . . . . . . . . . . 7 70 4. Best Practices for Using HTTP . . . . . . . . . . . . . . . . 7 71 4.1. Specifying the Use of HTTP . . . . . . . . . . . . . . . 8 72 4.2. Defining HTTP Resources . . . . . . . . . . . . . . . . . 8 73 4.3. Specifying Client Behaviours . . . . . . . . . . . . . . 9 74 4.4. HTTP URLs . . . . . . . . . . . . . . . . . . . . . . . . 10 75 4.4.1. Initial URL Discovery . . . . . . . . . . . . . . . . 11 76 4.4.2. URL Schemes . . . . . . . . . . . . . . . . . . . . . 11 77 4.4.3. Transport Ports . . . . . . . . . . . . . . . . . . . 12 78 4.5. HTTP Methods . . . . . . . . . . . . . . . . . . . . . . 12 79 4.5.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 13 80 4.6. HTTP Status Codes . . . . . . . . . . . . . . . . . . . . 14 81 4.7. HTTP Header Fields . . . . . . . . . . . . . . . . . . . 15 82 4.8. Defining Message Payloads . . . . . . . . . . . . . . . . 16 83 4.9. HTTP Caching . . . . . . . . . . . . . . . . . . . . . . 16 84 4.10. Application State . . . . . . . . . . . . . . . . . . . . 17 85 4.11. Client Authentication . . . . . . . . . . . . . . . . . . 17 86 4.12. Co-Existing with Web Browsing . . . . . . . . . . . . . . 18 87 4.13. Application Boundaries . . . . . . . . . . . . . . . . . 19 88 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 89 6. Security Considerations . . . . . . . . . . . . . . . . . . . 20 90 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 91 7.1. Normative References . . . . . . . . . . . . . . . . . . 20 92 7.2. Informative References . . . . . . . . . . . . . . . . . 22 93 7.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 25 95 Appendix A. Changes from RFC 3205 . . . . . . . . . . . . . . . 25 96 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 25 98 1. Introduction 100 HTTP [RFC7230] is often used as a substrate for other application 101 protocols. This is done for a variety of reasons, including: 103 o familiarity by implementers, specifiers, administrators, 104 developers and users, 106 o availability of a variety of client, server and proxy 107 implementations, 109 o ease of use, 111 o ubiquity of Web browsers, 113 o reuse of existing mechanisms like authentication and encryption, 115 o presence of HTTP servers and clients in target deployments, and 117 o its ability to traverse firewalls. 119 In many cases, these protocols are ad hoc; they are intended for only 120 deployment on the server side, and consumption by a limited set of 121 clients. A body of practices and tools has arisen around defining 122 such "HTTP APIs" that favours these conditions. 124 However, when such a protocol is standarised, it is typically 125 deployed on multiple servers, implemented a number of times, and 126 might be consumed by a broader variety of clients. Such diversity 127 brings a different set of concerns, and tools and practices intended 128 for a single-server deployment might not be suitable. 130 In particular, standards-defined HTTP APIs need to more carefully 131 consider how extensibility and evolution will be handled, how 132 different deployment requirements will be accommodated, and how 133 clients will evolve with the API. 135 At the same time, the Internet community has a tradition of protocol 136 reuse (e.g., Telnet [RFC0854] as a substrate for FTP [RFC0959] and 137 SMTP [RFC2821]), but less experience using HTTP as a substrate. 138 Because HTTP is extensible in many ways, a number of questions arise, 139 such as: 141 o Should an application using HTTP define a new URL scheme? Use new 142 ports? 144 o Should it use standard HTTP methods and status codes, or define 145 new ones? 147 o How can the maximum value be extracted from the use of HTTP? 149 o How does it coexist with other uses of HTTP - especially Web 150 browsing? 152 o How can interoperability problems and "protocol dead ends" be 153 avoided? 155 This document contains best current practices regarding the use of 156 HTTP by applications other than Web browsing. Section 2 defines what 157 applications it applies to; Section 3 surveys the properties of HTTP 158 that are important to preserve, and Section 4 conveys best practices 159 for those applications that do use HTTP. 161 It is written primarily to guide IETF efforts to define application 162 protocols using HTTP for deployment on the Internet, but might be 163 applicable in other situations. Note that the requirements herein do 164 not necessarily apply to the development of generic HTTP extensions. 166 1.1. Notational Conventions 168 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 169 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 170 "OPTIONAL" in this document are to be interpreted as described in BCP 171 14 [RFC2119] [RFC8174] when, and only when, they appear in all 172 capitals, as shown here. 174 2. Is HTTP Being Used? 176 Different applications have different goals when using HTTP. In this 177 document, we say an application is _using HTTP_ when any of the 178 following conditions are true: 180 o The transport port in use is 80 or 443, 182 o The URL scheme "http" or "https" is used, 184 o The ALPN protocol ID [RFC7301] generically identifies HTTP (e.g., 185 "http/1.1", "h2", "h2c"), or 187 o The IANA registries defined for HTTP are updated or modified. 189 When an application is using HTTP, all of the requirements of the 190 HTTP protocol suite (including but not limited to [RFC7230], 192 [RFC7231], [RFC7232], [RFC7233], [RFC7234], [RFC7235] and [RFC7540]) 193 are in force. 195 An application might not be _using HTTP_ according to this 196 definition, but still relying upon the HTTP specifications in some 197 manner. For example, an application might wish to avoid re- 198 specifying parts of the message format, but change others; or, it 199 might want to use a different set of methods. 201 Such applications are referred to as _protocols based upon HTTP_ in 202 this document. These have more freedom to modify protocol operation, 203 but are also likely to lose at least a portion of the benefits 204 outlined above, as most HTTP implementations won't be easily 205 adaptable to these changes, and as the protocol diverges from HTTP, 206 the benefit of mindshare will be lost. 208 Protocols that are based upon HTTP MUST NOT reuse HTTP's URL schemes, 209 transport ports, ALPN protocol IDs or IANA registries; rather, they 210 are encouraged to establish their own. 212 3. What's Important About HTTP 214 There are many ways that applications using HTTP are defined and 215 deployed, and sometimes they are brought to the IETF for 216 standardisation. In that process, what might be workable for 217 deployment in a limited fashion isn't appropriate for standardisation 218 and the corresponding broader deployment. 220 This section examines the facets of the protocol that are important 221 to preserve in these situations. 223 3.1. Generic Semantics 225 When writing an application's specification, it's often tempting to 226 specify exactly how HTTP is to be implemented, supported and used. 228 However, this can easily lead to an unintended profile of HTTP's 229 behaviour. For example, it's common to see specifications with 230 language like this: 232 A `200 OK` response means that the widget has successfully been 233 updated. 235 This sort of specification is bad practice, because it is adding new 236 semantics to HTTP's status codes and methods, respectively; a 237 recipient - whether it's an origin server, client library, 238 intermediary or cache - now has to know these extra semantics to 239 understand the message. 241 Some applications even require specific behaviours, such as: 243 A `POST` request MUST result in a `201 Created` response. 245 This forms an expectation in the client that the response will always 246 be "201 Created", when in fact there are a number of reasons why the 247 status code might differ in a real deployment. If the client does 248 not anticipate this, the application's deployment is brittle. 250 Much of the value of HTTP is in its _generic semantics_ - that is, 251 the protocol elements defined by HTTP are potentially applicable to 252 every resource, not specific to a particular context. Application- 253 specific semantics are expressed in the payload; mostly, in the body, 254 but also in header fields. 256 This allows a HTTP message to be examined by generic HTTP software 257 (e.g., HTTP servers, intermediaries, client implementations), and its 258 handling to be correctly determined. It also allows people to 259 leverage their knowledge of HTTP semantics without special-casing 260 them for a particular application. 262 Therefore, applications that use HTTP MUST NOT re-define, refine or 263 overlay the semantics of defined protocol elements. Instead, they 264 should focus their specifications on protocol elements that are 265 specific to that application; namely their HTTP resources. 267 See Section 4.2 for details. 269 3.2. Links 271 Another common practice is assuming that the HTTP server's name space 272 (or a portion thereof) is exclusively for the use of a single 273 application. This effectively overlays special, application-specific 274 semantics onto that space, precludes other applications from using 275 it. 277 As explained in [RFC7320], such "squatting" on a part of the URL 278 space by a standard usurps the server's authority over its own 279 resources, can cause deployment issues, and is therefore bad practice 280 in standards. 282 Instead of statically defining URL components like paths, it is 283 RECOMMENDED that applications using HTTP define links in payloads, to 284 allow flexibility in deployment. 286 Using runtime links in this fashion has a number of other benefits. 287 For example, navigating with a link allows a request to be routed to 288 a different server without the overhead of a redirection, thereby 289 supporting deployment across machines well. It becomes possible to 290 "mix" different applications on the same server, and offers a natural 291 path for extensibility, versioning and capability management. 293 3.3. Rich Functionality 295 The simplest possible use of HTTP is to POST data to a single URL, 296 thereby effectively tunnelling through the protocol. 298 This "RPC" style of communication does get some benefit from using 299 HTTP - namely, message framing and the availability of 300 implementations - but fails to realise many others when used 301 exclusively: 303 o Caching for server scalability, latency and bandwidth reduction, 304 and reliability; 306 o Granularity of access control (through use of a rich space of 307 URLs); 309 o Partial content to selectively request part of a response; 311 o Definition of an information space using URLs; and 313 o The ability to interact with the application easily using a Web 314 browser. 316 Using such a high-level protocol to tunnel simple semantics has 317 downsides too; because of its more advanced capabilities, breadth of 318 deployment and age, HTTP's complexity can cause interoperability 319 problems that could be avoided by using a simpler substrate (e.g., 320 WebSockets [RFC6455], if browser support is necessary, or TCP 321 [RFC0793] if not), or making the application be _based upon HTTP_, 322 instead of using it (as defined in Section 2). 324 Applications that use HTTP are encouraged to accommodate the various 325 features that the protocol offers, so that their users receive the 326 maximum benefit from it. This document does not require specific 327 features to be used, since the appropriate design tradeoffs are 328 highly specific to a given situation. However, following the 329 practices in Section 4 will help make them available. 331 4. Best Practices for Using HTTP 333 This section contains best practices regarding the use of HTTP by 334 applications, including practices for specific HTTP protocol 335 elements. 337 4.1. Specifying the Use of HTTP 339 When specifying the use of HTTP, an application SHOULD use [RFC7230] 340 as the primary reference; it is not necessary to reference all of the 341 specifications in the HTTP suite unless there are specific reasons to 342 do so (e.g., a particular feature is called out). 344 Applications using HTTP MAY specify a minimum version to be supported 345 (HTTP/1.1 is suggested), and MUST NOT specify a maximum version, to 346 preserve the protocol's ability to evolve. 348 Likewise, applications need not specify what HTTP mechanisms - such 349 as redirection, caching, authentication, proxy authentication, and so 350 on - are to be supported. For example, an application can specify 351 that it uses HTTP like this: 353 Foo Application uses HTTP [RFC7230]. Implementations MUST support 354 HTTP/1.1, and MAY support later versions. 356 When specifying examples of protocol interactions, applications 357 SHOULD document both the request and response messages, with full 358 headers, preferably in HTTP/1.1 format. For example: 360 GET /thing HTTP/1.1 361 Host: example.com 362 Accept: application/things+json 363 User-Agent: Foo/1.0 365 HTTP/1.1 200 OK 366 Content-Type: application/things+json 367 Content-Length: 500 368 Server: Bar/2.2 370 [payload here] 372 4.2. Defining HTTP Resources 374 Applications that use HTTP should focus on defining the following 375 application-specific protocol elements: 377 o Media types [RFC6838], often based upon a format convention such 378 as JSON [RFC8259], 380 o HTTP header fields, as per Section 4.7, and 382 o The behaviour of resources, as identified by link relations 383 [RFC8288]. 385 By composing these protocol elements, an application can define a set 386 of resources, identified by link relations, that implement specified 387 behaviours, including: 389 o Retrieval of their state using GET, in one or more formats 390 identified by media type; 392 o Resource creation or update using POST or PUT, with an 393 appropriately identified request body format; 395 o Data processing using POST and identified request and response 396 body format(s); and 398 o Resource deletion using DELETE. 400 For example, an application might specify: 402 Resources linked to with the "example-widget" link relation type are 403 Widgets. The state of a Widget can be fetched in the 404 "application/example-widget+json" format, and can be updated by PUT 405 to the same link. Widget resources can be deleted. 407 The "Example-Count" response header field on Widget representations 408 indicates how many Widgets are held by the sender. 410 The "application/example-widget+json" format is a JSON [RFC8259] 411 format representing the state of a Widget. It contains links to 412 related information in the link indicated by the Link header field 413 value with the "example-other-info" link relation type. 415 4.3. Specifying Client Behaviours 417 HTTP does not mandate some behaviours that have nevertheless become 418 very common; if these are not explicitly specified by applications 419 using HTTP, there may be confusion and interoperability problems. 420 This section recommends default handling for these mechanisms. 422 o Redirect handling - applications using HTTP SHOULD specify that 423 3xx redirect status codes be followed automatically. See 424 [RFC7231], Section 6.4. 426 o Redirect methods - applications using HTTP SHOULD specify that 301 427 and 302 redirect status codes rewrite the POST method to GET. See 428 [RFC7231], Section 6.4. 430 o Cookies - Applications using HTTP MUST explicitly reference the 431 Cookie specification [RFC6265] if they are required. 433 o Certificates - Applications using HTTP MUST specify that TLS 434 certificates are to be checked according to [RFC2818] when HTTPS 435 is used. 437 In general, applications using HTTP ought to align their usage as 438 closely as possible with Web browsers, to avoid interoperability 439 issues when they are used. See Section 4.12. 441 If an application using HTTP has browser compatibility as a goal, 442 client interaction ought to be defined in terms of [FETCH], since 443 that is the abstraction that browsers use for HTTP; it enforces many 444 of these best practices. 446 Applications using HTTP MUST NOT require HTTP features that are 447 usually negotiated to be supported. For example, requiring that 448 clients support responses with a certain content-encoding ([RFC7231], 449 Section 3.1.2.2) instead of negotiating for it ([RFC7231], 450 Section 5.3.4) means that otherwise conformant clients cannot 451 interoperate with the application. Applications MAY encourage the 452 implementation of such features, though. 454 4.4. HTTP URLs 456 In HTTP, URLs are opaque identifiers under the control of the server. 457 As outlined in [RFC7320], standards cannot usurp this space, since it 458 might conflict with existing resources, and constrain implementation 459 and deployment. 461 In other words, applications that use HTTP shouldn't associate 462 application semantics with specific URL paths on arbitrary servers. 463 Doing so inappropriately conflates the identity of the resource (its 464 URL) with the capabilities that resource supports, bringing about 465 many of the same interoperability problems that [RFC4367] warns of. 467 For example, specifying that a "GET to the URL /foo retrieves a bar 468 document" is bad practice. Likewise, specifying "The widget API is 469 at the path /bar" violates [RFC7320]. 471 Instead, applications that use HTTP are encouraged to ensure that 472 URLs are discovered at runtime, allowing HTTP-based services to 473 describe their own capabilities. One way to do this is to use typed 474 links [RFC8288] to convey the URIs that are in use, as well as the 475 semantics of the resources that they identify. See Section 4.2 for 476 details. 478 4.4.1. Initial URL Discovery 480 Generally, a client will begin interacting with a given application 481 server by requesting an initial document that contains information 482 about that particular deployment, potentially including links to 483 other relevant resources. 485 Applications that use HTTP are encouraged to allow an arbitrary URL 486 to be used as that entry point. For example, rather than specifying 487 "the initial document is at "/foo/v1", they should allow a deployment 488 to use any URL as the entry point for the application. 490 In cases where doing so is impractical (e.g., it is not possible to 491 convey a whole URL, but only a hostname) standard applications that 492 use HTTP can request a well-known URL [RFC5785] as an entry point. 494 4.4.2. URL Schemes 496 Applications that use HTTP will typically employ the "http" and/or 497 "https" URL schemes. "https" is preferred to provide authentication, 498 integrity and confidentiality, as well as mitigate pervasive 499 monitoring attacks [RFC7258]. 501 However, application-specific schemes can be defined as well. 503 When defining an URL scheme for an application using HTTP, there are 504 a number of tradeoffs and caveats to keep in mind: 506 o Unmodified Web browsers will not support the new scheme. While it 507 is possible to register new URL schemes with Web browsers (e.g. 508 registerProtocolHandler() in [HTML5], as well as several 509 proprietary approaches), support for these mechanisms is not 510 shared by all browsers, and their capabilities vary. 512 o Existing non-browser clients, intermediaries, servers and 513 associated software will not recognise the new scheme. For 514 example, a client library might fail to dispatch the request; a 515 cache might refuse to store the response, and a proxy might fail 516 to forward the request. 518 o Because URLs occur in and are generated in HTTP artefacts 519 commonly, often without human intervention (e.g., in the 520 "Location" response header), it can be difficult to assure that 521 the new scheme is used consistently. 523 o The resources identified by the new scheme will still be available 524 using "http" and/or "https" URLs. Those URLs can "leak" into use, 525 which can present security and operability issues. For example, 526 using a new scheme to assure that requests don't get sent to a 527 "normal" Web site is likely to fail. 529 o Features that rely upon the URL's origin [RFC6454], such as the 530 Web's same-origin policy, will be impacted by a change of scheme. 532 o HTTP-specific features such as cookies [RFC6265], authentication 533 [RFC7235], caching [RFC7234], and CORS [FETCH] might or might not 534 work correctly, depending on how they are defined and implemented. 535 Generally, they are designed and implemented with an assumption 536 that the URL will always be "http" or "https". 538 o Web features that require a secure context [SECCTXT] will likely 539 treat a new scheme as insecure. 541 See [RFC7595] for more information about minting new URL schemes. 543 4.4.3. Transport Ports 545 Applications that use HTTP can use the applicable default port (80 546 for HTTP, 443 for HTTPS), or they can be deployed upon other ports. 547 This decision can be made at deployment time, or might be encouraged 548 by the application's specification (e.g., by registering a port for 549 that application). 551 In either case, non-default ports will need to be reflected in the 552 authority of all URLs for that resource; the only mechanism for 553 changing a default port is changing the scheme (see Section 4.4.2). 555 Using a port other than the default has privacy implications (i.e., 556 the protocol can now be distinguished from other traffic), as well as 557 operability concerns (as some networks might block or otherwise 558 interfere with it). Privacy implications should be documented in 559 Security Considerations. 561 See [RFC7605] for further guidance. 563 4.5. HTTP Methods 565 Applications that use HTTP MUST confine themselves to using 566 registered HTTP methods such as GET, POST, PUT, DELETE, and PATCH. 568 New HTTP methods are rare; they are required to be registered with 569 IETF Review (see [RFC7232]), and are also required to be _generic_. 570 That means that they need to be potentially applicable to all 571 resources, not just those of one application. 573 While historically some applications (e.g., [RFC4791]) have defined 574 non-generic methods, [RFC7231] now forbids this. 576 When authors believe that a new method is required, they are 577 encouraged to engage with the HTTP community early, and document 578 their proposal as a separate HTTP extension, rather than as part of 579 an application's specification. 581 4.5.1. GET 583 GET is one of the most common and useful HTTP methods; its retrieval 584 semantics allow caching, side-effect free linking and forms the basis 585 of many of the benefits of using HTTP. 587 A common use of GET is to perform queries, often using the query 588 component of the URL; this is this a familiar pattern from Web 589 browsing, and the results can be cached, improving efficiency of an 590 often expensive process. 592 In some cases, however, GET might be unwieldy for expressing queries, 593 because of the limited syntax of the URL; in particular, if binary 594 data forms part of the query terms, it needs to be encoded to conform 595 to URL syntax. 597 While this is not an issue for short queries, it can become one for 598 larger query terms, or ones which need to sustain a high rate of 599 requests. Additionally, some HTTP implementations limit the size of 600 URLs they support - although modern HTTP software has much more 601 generous limits than previously (typically, considerably more than 602 8000 octets, as required by [RFC7230] Section 3.1.1). 604 In these cases, an application using HTTP might consider using POST 605 to express queries in the request body; doing so avoids encoding 606 overhead and URL length limits in implementations. However, in doing 607 so it should be noted that the benefits of GET such as caching and 608 linking to query results are lost. Therefore, applications using 609 HTTP that feel a need to allow POST queries ought consider allowing 610 both methods. 612 Applications that use HTTP SHOULD NOT define GET requests to have 613 side effects, since implementations can and do retry HTTP GET 614 requests that fail. 616 Finally, note that while HTTP allows GET requests to have a body 617 syntactically, this is done only to allow parsers to be generic; as 618 per [RFC7231], Section 4.3.1, a body on a GET has no meaning, and 619 will be either ignored or rejected by generic HTTP software. As a 620 result, applications that use HTTP SHOULD NOT define GET to have any 621 sde effects upon their resources. 623 4.6. HTTP Status Codes 625 Applications that use HTTP MUST only use registered HTTP status 626 codes. 628 As with methods, new HTTP status codes are rare, and required (by 629 [RFC7231]) to be registered with IETF review. Similarly, HTTP status 630 codes are generic; they are required (by [RFC7231]) to be potentially 631 applicable to all resources, not just to those of one application. 633 When authors believe that a new status code is required, they are 634 encouraged to engage with the HTTP community early, and document 635 their proposal as a separate HTTP extension, rather than as part of 636 an application's specification. 638 The primary function of status codes is to convey HTTP semantics for 639 the benefit of generic HTTP software, not application-specific 640 semantics. Therefore, applications MUST NOT specify additional 641 semantics or refine existing semantics for status codes. 643 In particular, specifying that a particular status code has a 644 specific meaning in the context of an application is harmful, as 645 these are not generic semantics, since the consumer needs to be in 646 the context of the application to understand them. 648 Furthermore, applications using HTTP MUST NOT re-specify the 649 semantics of HTTP status codes, even if it is only by copying their 650 definition. They MUST NOT require specific reason phrases to be 651 used; the reason phrase has no function in HTTP, and is not 652 guaranteed to be preserved by implementations. The reason phrase is 653 not carried in the [RFC7540] message format. 655 Typically, applications using HTTP will convey application-specific 656 information in the message body and/or HTTP header fields, not the 657 status code. [RFC7807] provides one way for applications using HTTP 658 to do this. 660 Specifications sometimes also create a "laundry list" of potential 661 status codes, in an effort to be helpful. The problem with doing so 662 is that such a list is never complete; for example, if a network 663 proxy is interposed, the client might encounter a "407 Proxy 664 Authentication Required" response; or, if the server is rate limiting 665 the client, it might receive a "429 Too Many Requests" response. 667 Since the list of HTTP status codes can be added to, it's safer to 668 specify behaviours in terms of general response classes (e.g., 669 "successful response" for 2xx; "client error" for 4xx and "server 670 error" for 5xx), pointing out that clients SHOULD be able to handle 671 all applicable protocol elements gracefully (i.e., falling back to 672 the generic "n00" semantics of a given status code; e.g., "499" can 673 be safely handled as "400" by clients that don't recognise it). 675 4.7. HTTP Header Fields 677 Applications that use HTTP MAY define new HTTP header fields, 678 following the advice in [RFC7231], Section 8.3.1. 680 Typically, using HTTP header fields is appropriate in a few different 681 situations: 683 o Their content is useful to intermediaries (who often wish to avoid 684 parsing the body), and/or 686 o Their content is useful to generic HTTP software (e.g., clients, 687 servers), and/or 689 o It is not possible to include their content in the message body 690 (usually because a format does not allow it). 692 New header fields MUST be registered, as per [RFC7231] and [RFC3864]. 694 It is RECOMMENDED that header field names be short (even when HTTP/2 695 header compression is in effect, there is an overhead) but 696 appropriately specific. In particular, if a header field is specific 697 to an application, an identifier for that application SHOULD form a 698 prefix to the header field name, separated by a "-". 700 For example, if the "example" application needs to create three 701 headers, they might be called "example-foo", "example-bar" and 702 "example-baz". Note that the primary motivation here is to avoid 703 consuming more generic header names, not to reserve a portion of the 704 namespace for the application; see [RFC6648] for related 705 considerations. 707 The semantics of existing HTTP header fields MUST NOT be re-defined 708 without updating their registration or defining an extension to them 709 (if allowed). For example, an application using HTTP cannot specify 710 that the "Location" header has a special meaning in a certain 711 context. 713 See Section 4.9 for the interaction between headers and HTTP caching; 714 in particular, request headers that are used to "select" a response 715 have impact there, and need to be carefully considered. 717 See Section 4.10 for considerations regarding header fields that 718 carry application state (e.g,. Cookie). 720 4.8. Defining Message Payloads 722 There are many potential formats for payloads; for example, JSON 723 [RFC8259], XML [XML], and CBOR [RFC7049]. Best practices for their 724 use are out of scope for this document. 726 Applications SHOULD register distinct media types for each format 727 they define; this makes it possible to identify them unambiguously 728 and negotiate for their use. See [RFC6838] for more information. 730 4.9. HTTP Caching 732 HTTP caching [RFC7234] is one of the primary benefits of using HTTP 733 for applications; it provides scalability, reduces latency and 734 improves reliability. Furthermore, HTTP caches are readily available 735 in browsers and other clients, networks as forward and reverse 736 proxies, Content Delivery Networks and as part of server software. 738 Assigning even a short freshness lifetime ([RFC7234], Section 4.2) - 739 e.g., 5 seconds - allows a response to be reused to satisfy multiple 740 clients, and/or a single client making the same request repeatedly. 741 In general, if it is safe to reuse something, consider assigning a 742 freshness lifetime; cache implementations take active measures to 743 expire content intelligently when they are out of space, so "it will 744 fill up the cache" is not a valid concern. 746 Understand that stale responses (e.g., one with "Cache-Control: max- 747 age=0") can be reused when the cache is disconnected from the origin 748 server; this can be useful for handling network issues. See 749 [RFC7234], Section 4.2.4, and also [RFC5861] for additional controls 750 over stale content. 752 Stale responses can be refreshed by assigning a validator, saving 753 both transfer bandwidth and latency for large responses; see 754 [RFC7232]. 756 In some situations, responses without explicit cache directives 757 (e.g., Cache-Control or Expires) will be stored and served using a 758 heuristic freshness lifetime; see [RFC7234], Section 4.2.2. As the 759 heuristic is not under control of the application, it is generally 760 preferable to set an explicit freshness lifetime. 762 If caching of a response is not desired, the appropriate response 763 directive is "Cache-Control: no-store". This only need be sent in 764 situations where the response might be cached; see [RFC7234], 765 Section 3. 767 If an application defines a request header field that might be used 768 by a server to change the response's headers or body, authors should 769 point out that this has implications for caching; in general, such 770 resources need to either make their responses uncacheable (e.g., with 771 the "no-store" cache-control directive defined in [RFC7234], 772 Section 5.2.2.3) or consistently send the Vary response header 773 ([RFC7231], Section 7.1.4). 775 When an application has a need to express a lifetime that's separate 776 from the freshness lifetime, this should be expressed separately, 777 either in the response's body or in a separate header field. When 778 this happens, the relationship between HTTP caching and that lifetime 779 need to be carefully considered, since the response will be used as 780 long as it is considered fresh. 782 Like other functions, HTTP caching is generic; it does not have 783 knowledge of the application in use. Therefore, caching extensions 784 need to be backwards-compatible, as per [RFC7234], Section 5.2.3. 786 4.10. Application State 788 Applications that use HTTP MAY use stateful cookies [RFC6265] to 789 identify a client and/or store client-specific data to contextualise 790 requests. 792 When used, it is important to carefully specify the scoping and use 793 of cookies; if the application exposes sensitive data or capabilities 794 (e.g., by acting as an ambient authority), exploits are possible. 795 Mitigations include using a request-specific token to assure the 796 intent of the client. 798 Applications MUST NOT make assumptions about the relationship between 799 separate requests on a single transport connection; doing so breaks 800 many of the assumptions of HTTP as a stateless protocol, and will 801 cause problems in interoperability, security, operability and 802 evolution. 804 4.11. Client Authentication 806 Applications that use HTTP MAY use HTTP authentication [RFC7235] to 807 identify clients. The Basic authentication scheme [RFC7617] MUST NOT 808 be used unless the underlying transport is authenticated, integrity- 809 protected and confidential (e.g., as provided the "HTTPS" URL scheme, 810 or another using TLS). The Digest scheme [RFC7616] MUST NOT be used 811 unless the underlying transport is similarly secure, or the chosen 812 hash algorithm is not "MD5". 814 When used, it is important to carefully specify the scoping and use 815 of authentication; if the application exposes sensitive data or 816 capabilities (e.g., by acting as an ambient authority), exploits are 817 possible. Mitigations include using a request-specific token to 818 assure the intent of the client. 820 4.12. Co-Existing with Web Browsing 822 Even if there is not an intent for an application that uses HTTP to 823 be used with a Web browser, its resources will remain available to 824 browsers and other HTTP clients. 826 This means that all such applications need to consider how browsers 827 will interact with them, particularly regarding security. 829 For example, if an application's state can be changed using a POST 830 request, a Web browser can easily be coaxed into making that request 831 by a HTML form on an arbitrary Web site. 833 Or, if a resource reflects data from the request into a response, 834 that can be used to perform a Cross-Site Scripting attack on Web 835 browsers directed to it. 837 This is only a small sample of the kinds of issues that applications 838 using HTTP must consider. Generally, the best approach is to 839 consider the application _as_ a Web application, and to follow best 840 practices for their secure development. 842 A complete enumeration of such practices is out of scope for this 843 document, but some considerations include: 845 o Using Strict Transport Security [RFC6797] to assure that HTTPS is 846 used 848 o Using Content-Security-Policy [W3C.WD-CSP3-20160913] to constrain 849 the capabilities of content, thereby mitigating Cross-Site 850 Scripting attacks (which are possible if client-provided data is 851 exposed in any part of a response in the application) 853 o Using X-Frame-Options [RFC7034] to prevent content from being 854 included in a HTML frame from another origin, thereby enabling 855 "clickjacking" 857 o Using Referrer-Policy [W3C.CR-referrer-policy-20170126] to prevent 858 sensitive data in URLs from being leaked in the Referer request 859 header 861 o Using the 'HttpOnly' flag on Cookies to assure that cookies are 862 not exposed to browser scripting languages [RFC6265] 864 Depending on how they are intended to be deployed, specifications for 865 applications using HTTP might require the use of these mechanisms in 866 specific ways, or might merely point them out in Security 867 Considerations. 869 If an application using HTTP has browser compatibility as a goal, 870 client interaction ought to be defined in terms of [FETCH], since 871 that is the abstraction that browsers use for HTTP; it enforces many 872 of these best practices. 874 4.13. Application Boundaries 876 Because the origin [RFC6454] is how many HTTP capabilities are 877 scoped, applications also need to consider how deployments might 878 interact with other applications (including Web browsing) on the same 879 origin. 881 For example, if Cookies [RFC6265] are used to carry application 882 state, they will be sent with all requests to the origin by default, 883 unless scoped by path, and the application might receive cookies from 884 other applications on the origin. This can lead to security issues, 885 as well as collision in cookie names. 887 One solution to these issues is to require a dedicated hostname for 888 the application, so that it has a unique origin. However, it is 889 often desirable to allow multiple applications to be deployed on a 890 single hostname; doing so provides the most deployment flexibility 891 and enables them to be "mixed" together (See [RFC7320] for details). 892 Therefore, applications using HTTP should strive to allow multiple 893 applications on an origin. 895 To enable this, when specifying the use of Cookies, HTTP 896 authentication realms [RFC7235], or other origin-wide HTTP 897 mechanisms, applications using HTTP SHOULD NOT mandate the use of a 898 particular identifier, but instead let deployments configure them. 899 Consideration SHOULD be given to scoping them to part of the origin, 900 using their specified mechanisms for doing so. 902 Modern Web browsers constrain the ability of content from one origin 903 to access resources from another, to avoid leaking private 904 information. As a result, applications that wish to expose cross- 905 origin data to browsers will need to implement the CORS protocol; see 906 [FETCH]. 908 5. IANA Considerations 910 This document has no requirements for IANA. 912 6. Security Considerations 914 Section 4.10 discusses the impact of using stateful mechanisms in the 915 protocol as ambient authority, and suggests a mitigation. 917 Section 4.4.2 requires support for 'https' URLs, and discourages the 918 use of 'http' URLs, to provide authentication, integrity and 919 confidentiality, as well as mitigate pervasive monitoring attacks. 921 Section 4.12 highlights the implications of Web browsers' 922 capabilities on applications that use HTTP. 924 Section 4.13 discusses the issues that arise when applications are 925 deployed on the same origin as Web sites (and other applications). 927 Applications that use HTTP in a manner that involves modification of 928 implementations - for example, requiring support for a new URL 929 scheme, or a non-standard method - risk having those implementations 930 "fork" from their parent HTTP implementations, with the possible 931 result that they do not benefit from patches and other security 932 improvements incorporated upstream. 934 7. References 936 7.1. Normative References 938 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 939 Requirement Levels", BCP 14, RFC 2119, 940 DOI 10.17487/RFC2119, March 1997, 941 . 943 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 944 DOI 10.17487/RFC2818, May 2000, 945 . 947 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 948 Procedures for Message Header Fields", BCP 90, RFC 3864, 949 DOI 10.17487/RFC3864, September 2004, 950 . 952 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 953 DOI 10.17487/RFC6454, December 2011, 954 . 956 [RFC6648] Saint-Andre, P., Crocker, D., and M. Nottingham, 957 "Deprecating the "X-" Prefix and Similar Constructs in 958 Application Protocols", BCP 178, RFC 6648, 959 DOI 10.17487/RFC6648, June 2012, 960 . 962 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 963 Specifications and Registration Procedures", BCP 13, 964 RFC 6838, DOI 10.17487/RFC6838, January 2013, 965 . 967 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 968 Protocol (HTTP/1.1): Message Syntax and Routing", 969 RFC 7230, DOI 10.17487/RFC7230, June 2014, 970 . 972 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 973 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 974 DOI 10.17487/RFC7231, June 2014, 975 . 977 [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 978 Protocol (HTTP/1.1): Conditional Requests", RFC 7232, 979 DOI 10.17487/RFC7232, June 2014, 980 . 982 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 983 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 984 RFC 7233, DOI 10.17487/RFC7233, June 2014, 985 . 987 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 988 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 989 RFC 7234, DOI 10.17487/RFC7234, June 2014, 990 . 992 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 993 Protocol (HTTP/1.1): Authentication", RFC 7235, 994 DOI 10.17487/RFC7235, June 2014, 995 . 997 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 998 "Transport Layer Security (TLS) Application-Layer Protocol 999 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 1000 July 2014, . 1002 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, 1003 RFC 7320, DOI 10.17487/RFC7320, July 2014, 1004 . 1006 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1007 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1008 DOI 10.17487/RFC7540, May 2015, 1009 . 1011 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1012 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1013 May 2017, . 1015 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1016 DOI 10.17487/RFC8288, October 2017, 1017 . 1019 7.2. Informative References 1021 [FETCH] WHATWG, "Fetch - Living Standard", n.d., 1022 . 1024 [HTML5] WHATWG, "HTML - Living Standard", n.d., 1025 . 1027 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 1028 RFC 793, DOI 10.17487/RFC0793, September 1981, 1029 . 1031 [RFC0854] Postel, J. and J. Reynolds, "Telnet Protocol 1032 Specification", STD 8, RFC 854, DOI 10.17487/RFC0854, May 1033 1983, . 1035 [RFC0959] Postel, J. and J. Reynolds, "File Transfer Protocol", 1036 STD 9, RFC 959, DOI 10.17487/RFC0959, October 1985, 1037 . 1039 [RFC2821] Klensin, J., Ed., "Simple Mail Transfer Protocol", 1040 RFC 2821, DOI 10.17487/RFC2821, April 2001, 1041 . 1043 [RFC3205] Moore, K., "On the use of HTTP as a Substrate", BCP 56, 1044 RFC 3205, DOI 10.17487/RFC3205, February 2002, 1045 . 1047 [RFC4367] Rosenberg, J., Ed. and IAB, "What's in a Name: False 1048 Assumptions about DNS Names", RFC 4367, 1049 DOI 10.17487/RFC4367, February 2006, 1050 . 1052 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 1053 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 1054 DOI 10.17487/RFC4791, March 2007, 1055 . 1057 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 1058 Uniform Resource Identifiers (URIs)", RFC 5785, 1059 DOI 10.17487/RFC5785, April 2010, 1060 . 1062 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 1063 Content", RFC 5861, DOI 10.17487/RFC5861, May 2010, 1064 . 1066 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1067 DOI 10.17487/RFC6265, April 2011, 1068 . 1070 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 1071 RFC 6455, DOI 10.17487/RFC6455, December 2011, 1072 . 1074 [RFC6797] Hodges, J., Jackson, C., and A. Barth, "HTTP Strict 1075 Transport Security (HSTS)", RFC 6797, 1076 DOI 10.17487/RFC6797, November 2012, 1077 . 1079 [RFC7034] Ross, D. and T. Gondrom, "HTTP Header Field X-Frame- 1080 Options", RFC 7034, DOI 10.17487/RFC7034, October 2013, 1081 . 1083 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1084 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1085 October 2013, . 1087 [RFC7258] Farrell, S. and H. Tschofenig, "Pervasive Monitoring Is an 1088 Attack", BCP 188, RFC 7258, DOI 10.17487/RFC7258, May 1089 2014, . 1091 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 1092 and Registration Procedures for URI Schemes", BCP 35, 1093 RFC 7595, DOI 10.17487/RFC7595, June 2015, 1094 . 1096 [RFC7605] Touch, J., "Recommendations on Using Assigned Transport 1097 Port Numbers", BCP 165, RFC 7605, DOI 10.17487/RFC7605, 1098 August 2015, . 1100 [RFC7616] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP 1101 Digest Access Authentication", RFC 7616, 1102 DOI 10.17487/RFC7616, September 2015, 1103 . 1105 [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", 1106 RFC 7617, DOI 10.17487/RFC7617, September 2015, 1107 . 1109 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 1110 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 1111 . 1113 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1114 Interchange Format", STD 90, RFC 8259, 1115 DOI 10.17487/RFC8259, December 2017, 1116 . 1118 [SECCTXT] West, M., "Secure Contexts", World Wide Web Consortium CR 1119 CR-secure-contexts-20160915, September 2016, 1120 . 1122 [W3C.CR-referrer-policy-20170126] 1123 Eisinger, J. and E. Stark, "Referrer Policy", World Wide 1124 Web Consortium CR CR-referrer-policy-20170126, January 1125 2017, 1126 . 1128 [W3C.WD-CSP3-20160913] 1129 West, M., "Content Security Policy Level 3", World Wide 1130 Web Consortium WD WD-CSP3-20160913, September 2016, 1131 . 1133 [XML] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 1134 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 1135 Edition)", World Wide Web Consortium Recommendation REC- 1136 xml-20081126, November 2008, 1137 . 1139 7.3. URIs 1141 [1] https://lists.w3.org/Archives/Public/ietf-http-wg/ 1143 [2] http://httpwg.github.io/ 1145 [3] https://github.com/httpwg/http-extensions/labels/bcp56bis 1147 Appendix A. Changes from RFC 3205 1149 [RFC3205] captured the Best Current Practice in the early 2000's, 1150 based on the concerns facing protocol designers at the time. Use of 1151 HTTP has changed considerably since then, and as a result this 1152 document is substantially different. As a result, the changes are 1153 too numerous to list individually. 1155 Author's Address 1157 Mark Nottingham 1159 Email: mnot@mnot.net 1160 URI: https://www.mnot.net/