idnits 2.17.1 draft-ietf-httpbis-p2-semantics-22.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 RFC2616, but the abstract doesn't seem to mention this, which it should. -- The draft header indicates that this document updates RFC2817, 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 (Using the creation date from RFC2817, updated by this document, for RFC5378 checks: 1998-11-18) -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 23, 2013) is 4073 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-22 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-22 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-22 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-22 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-22 ** Downref: Normative reference to an Informational RFC: RFC 1950 ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Downref: Normative reference to an Informational RFC: RFC 1952 -- Obsolete informational reference (is this intentional?): RFC 1305 (Obsoleted by RFC 5905) -- Obsolete informational reference (is this intentional?): RFC 2068 (Obsoleted by RFC 2616) -- Obsolete informational reference (is this intentional?): RFC 2388 (Obsoleted by RFC 7578) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 5987 (Obsoleted by RFC 8187) -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 3 errors (**), 0 flaws (~~), 6 warnings (==), 12 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPbis Working Group R. Fielding, Ed. 3 Internet-Draft Adobe 4 Obsoletes: 2616 (if approved) J. Reschke, Ed. 5 Updates: 2817 (if approved) greenbytes 6 Intended status: Standards Track February 23, 2013 7 Expires: August 27, 2013 9 Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content 10 draft-ietf-httpbis-p2-semantics-22 12 Abstract 14 The Hypertext Transfer Protocol (HTTP) is an application-level 15 protocol for distributed, collaborative, hypertext information 16 systems. This document defines the semantics of HTTP/1.1 messages, 17 as expressed by request methods, request header fields, response 18 status codes, and response header fields, along with the payload of 19 messages (metadata and body content) and mechanisms for content 20 negotiation. 22 Editorial Note (To be removed by RFC Editor) 24 Discussion of this draft takes place on the HTTPBIS working group 25 mailing list (ietf-http-wg@w3.org), which is archived at 26 . 28 The current issues list is at 29 and related 30 documents (including fancy diffs) can be found at 31 . 33 The changes in this draft are summarized in Appendix E.2. 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 http://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 August 27, 2013. 51 Copyright Notice 53 Copyright (c) 2013 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 58 (http://trustee.ietf.org/license-info) in effect on the date of 59 publication of this document. Please review these documents 60 carefully, as they describe your rights and restrictions with respect 61 to this document. Code Components extracted from this document must 62 include Simplified BSD License text as described in Section 4.e of 63 the Trust Legal Provisions and are provided without warranty as 64 described in the Simplified BSD License. 66 This document may contain material from IETF Documents or IETF 67 Contributions published or made publicly available before November 68 10, 2008. The person(s) controlling the copyright in some of this 69 material may not have granted the IETF Trust the right to allow 70 modifications of such material outside the IETF Standards Process. 71 Without obtaining an adequate license from the person(s) controlling 72 the copyright in such materials, this document may not be modified 73 outside the IETF Standards Process, and derivative works of it may 74 not be created outside the IETF Standards Process, except to format 75 it for publication as an RFC or to translate it into languages other 76 than English. 78 Table of Contents 80 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 6 81 1.1. Conformance and Error Handling . . . . . . . . . . . . . . 6 82 1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 6 83 2. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 7 84 3. Representations . . . . . . . . . . . . . . . . . . . . . . . 7 85 3.1. Representation Metadata . . . . . . . . . . . . . . . . . 8 86 3.1.1. Processing the Data . . . . . . . . . . . . . . . . . 8 87 3.1.2. Encoding for Compression or Integrity . . . . . . . . 11 88 3.1.3. Audience Language . . . . . . . . . . . . . . . . . . 13 89 3.1.4. Identification . . . . . . . . . . . . . . . . . . . . 14 90 3.2. Representation Data . . . . . . . . . . . . . . . . . . . 17 91 3.3. Payload Semantics . . . . . . . . . . . . . . . . . . . . 17 92 3.4. Content Negotiation . . . . . . . . . . . . . . . . . . . 18 93 3.4.1. Proactive Negotiation . . . . . . . . . . . . . . . . 18 94 3.4.2. Reactive Negotiation . . . . . . . . . . . . . . . . . 19 95 4. Request Methods . . . . . . . . . . . . . . . . . . . . . . . 20 96 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 20 97 4.2. Common Method Properties . . . . . . . . . . . . . . . . . 22 98 4.2.1. Safe Methods . . . . . . . . . . . . . . . . . . . . . 22 99 4.2.2. Idempotent Methods . . . . . . . . . . . . . . . . . . 23 100 4.2.3. Cacheable Methods . . . . . . . . . . . . . . . . . . 23 101 4.3. Method Definitions . . . . . . . . . . . . . . . . . . . . 23 102 4.3.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 24 103 4.3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . 24 104 4.3.3. POST . . . . . . . . . . . . . . . . . . . . . . . . . 25 105 4.3.4. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 26 106 4.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . . 28 107 4.3.6. CONNECT . . . . . . . . . . . . . . . . . . . . . . . 29 108 4.3.7. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . 31 109 4.3.8. TRACE . . . . . . . . . . . . . . . . . . . . . . . . 32 110 5. Request Header Fields . . . . . . . . . . . . . . . . . . . . 32 111 5.1. Controls . . . . . . . . . . . . . . . . . . . . . . . . . 32 112 5.1.1. Expect . . . . . . . . . . . . . . . . . . . . . . . . 33 113 5.1.2. Max-Forwards . . . . . . . . . . . . . . . . . . . . . 36 114 5.2. Conditionals . . . . . . . . . . . . . . . . . . . . . . . 36 115 5.3. Content Negotiation . . . . . . . . . . . . . . . . . . . 37 116 5.3.1. Quality Values . . . . . . . . . . . . . . . . . . . . 37 117 5.3.2. Accept . . . . . . . . . . . . . . . . . . . . . . . . 38 118 5.3.3. Accept-Charset . . . . . . . . . . . . . . . . . . . . 40 119 5.3.4. Accept-Encoding . . . . . . . . . . . . . . . . . . . 41 120 5.3.5. Accept-Language . . . . . . . . . . . . . . . . . . . 42 121 5.4. Authentication Credentials . . . . . . . . . . . . . . . . 43 122 5.5. Request Context . . . . . . . . . . . . . . . . . . . . . 43 123 5.5.1. From . . . . . . . . . . . . . . . . . . . . . . . . . 44 124 5.5.2. Referer . . . . . . . . . . . . . . . . . . . . . . . 44 125 5.5.3. User-Agent . . . . . . . . . . . . . . . . . . . . . . 45 126 6. Response Status Codes . . . . . . . . . . . . . . . . . . . . 46 127 6.1. Overview of Status Codes . . . . . . . . . . . . . . . . . 47 128 6.2. Informational 1xx . . . . . . . . . . . . . . . . . . . . 49 129 6.2.1. 100 Continue . . . . . . . . . . . . . . . . . . . . . 49 130 6.2.2. 101 Switching Protocols . . . . . . . . . . . . . . . 50 131 6.3. Successful 2xx . . . . . . . . . . . . . . . . . . . . . . 50 132 6.3.1. 200 OK . . . . . . . . . . . . . . . . . . . . . . . . 50 133 6.3.2. 201 Created . . . . . . . . . . . . . . . . . . . . . 51 134 6.3.3. 202 Accepted . . . . . . . . . . . . . . . . . . . . . 51 135 6.3.4. 203 Non-Authoritative Information . . . . . . . . . . 51 136 6.3.5. 204 No Content . . . . . . . . . . . . . . . . . . . . 52 137 6.3.6. 205 Reset Content . . . . . . . . . . . . . . . . . . 52 138 6.4. Redirection 3xx . . . . . . . . . . . . . . . . . . . . . 53 139 6.4.1. 300 Multiple Choices . . . . . . . . . . . . . . . . . 54 140 6.4.2. 301 Moved Permanently . . . . . . . . . . . . . . . . 55 141 6.4.3. 302 Found . . . . . . . . . . . . . . . . . . . . . . 55 142 6.4.4. 303 See Other . . . . . . . . . . . . . . . . . . . . 56 143 6.4.5. 305 Use Proxy . . . . . . . . . . . . . . . . . . . . 56 144 6.4.6. 306 (Unused) . . . . . . . . . . . . . . . . . . . . . 56 145 6.4.7. 307 Temporary Redirect . . . . . . . . . . . . . . . . 57 146 6.5. Client Error 4xx . . . . . . . . . . . . . . . . . . . . . 57 147 6.5.1. 400 Bad Request . . . . . . . . . . . . . . . . . . . 57 148 6.5.2. 402 Payment Required . . . . . . . . . . . . . . . . . 57 149 6.5.3. 403 Forbidden . . . . . . . . . . . . . . . . . . . . 57 150 6.5.4. 404 Not Found . . . . . . . . . . . . . . . . . . . . 58 151 6.5.5. 405 Method Not Allowed . . . . . . . . . . . . . . . . 58 152 6.5.6. 406 Not Acceptable . . . . . . . . . . . . . . . . . . 58 153 6.5.7. 408 Request Timeout . . . . . . . . . . . . . . . . . 59 154 6.5.8. 409 Conflict . . . . . . . . . . . . . . . . . . . . . 59 155 6.5.9. 410 Gone . . . . . . . . . . . . . . . . . . . . . . . 59 156 6.5.10. 411 Length Required . . . . . . . . . . . . . . . . . 60 157 6.5.11. 413 Payload Too Large . . . . . . . . . . . . . . . . 60 158 6.5.12. 414 URI Too Long . . . . . . . . . . . . . . . . . . . 60 159 6.5.13. 415 Unsupported Media Type . . . . . . . . . . . . . . 60 160 6.5.14. 417 Expectation Failed . . . . . . . . . . . . . . . . 61 161 6.5.15. 426 Upgrade Required . . . . . . . . . . . . . . . . . 61 162 6.6. Server Error 5xx . . . . . . . . . . . . . . . . . . . . . 61 163 6.6.1. 500 Internal Server Error . . . . . . . . . . . . . . 61 164 6.6.2. 501 Not Implemented . . . . . . . . . . . . . . . . . 61 165 6.6.3. 502 Bad Gateway . . . . . . . . . . . . . . . . . . . 62 166 6.6.4. 503 Service Unavailable . . . . . . . . . . . . . . . 62 167 6.6.5. 504 Gateway Timeout . . . . . . . . . . . . . . . . . 62 168 6.6.6. 505 HTTP Version Not Supported . . . . . . . . . . . . 62 169 7. Response Header Fields . . . . . . . . . . . . . . . . . . . . 62 170 7.1. Control Data . . . . . . . . . . . . . . . . . . . . . . . 63 171 7.1.1. Origination Date . . . . . . . . . . . . . . . . . . . 63 172 7.1.2. Location . . . . . . . . . . . . . . . . . . . . . . . 66 173 7.1.3. Retry-After . . . . . . . . . . . . . . . . . . . . . 68 174 7.1.4. Vary . . . . . . . . . . . . . . . . . . . . . . . . . 68 175 7.2. Validator Header Fields . . . . . . . . . . . . . . . . . 69 176 7.3. Authentication Challenges . . . . . . . . . . . . . . . . 70 177 7.4. Response Context . . . . . . . . . . . . . . . . . . . . . 70 178 7.4.1. Allow . . . . . . . . . . . . . . . . . . . . . . . . 71 179 7.4.2. Server . . . . . . . . . . . . . . . . . . . . . . . . 71 180 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 72 181 8.1. Method Registry . . . . . . . . . . . . . . . . . . . . . 72 182 8.1.1. Procedure . . . . . . . . . . . . . . . . . . . . . . 72 183 8.1.2. Considerations for New Methods . . . . . . . . . . . . 72 184 8.1.3. Registrations . . . . . . . . . . . . . . . . . . . . 73 185 8.2. Status Code Registry . . . . . . . . . . . . . . . . . . . 73 186 8.2.1. Procedure . . . . . . . . . . . . . . . . . . . . . . 73 187 8.2.2. Considerations for New Status Codes . . . . . . . . . 73 188 8.2.3. Registrations . . . . . . . . . . . . . . . . . . . . 74 189 8.3. Header Field Registry . . . . . . . . . . . . . . . . . . 75 190 8.3.1. Considerations for New Header Fields . . . . . . . . . 76 191 8.3.2. Registrations . . . . . . . . . . . . . . . . . . . . 78 192 8.4. Content Coding Registry . . . . . . . . . . . . . . . . . 78 193 8.4.1. Procedure . . . . . . . . . . . . . . . . . . . . . . 78 194 8.4.2. Registrations . . . . . . . . . . . . . . . . . . . . 79 195 9. Security Considerations . . . . . . . . . . . . . . . . . . . 79 196 9.1. Attacks Based On File and Path Names . . . . . . . . . . . 79 197 9.2. Personal Information . . . . . . . . . . . . . . . . . . . 80 198 9.3. Sensitive Information in URIs . . . . . . . . . . . . . . 80 199 9.4. Product Information . . . . . . . . . . . . . . . . . . . 81 200 9.5. Fragment after Redirects . . . . . . . . . . . . . . . . . 81 201 9.6. Browser Fingerprinting . . . . . . . . . . . . . . . . . . 81 202 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 82 203 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 82 204 11.1. Normative References . . . . . . . . . . . . . . . . . . . 82 205 11.2. Informative References . . . . . . . . . . . . . . . . . . 84 206 Appendix A. Differences between HTTP and MIME . . . . . . . . . . 85 207 A.1. MIME-Version . . . . . . . . . . . . . . . . . . . . . . . 86 208 A.2. Conversion to Canonical Form . . . . . . . . . . . . . . . 86 209 A.3. Conversion of Date Formats . . . . . . . . . . . . . . . . 86 210 A.4. Conversion of Content-Encoding . . . . . . . . . . . . . . 87 211 A.5. Conversion of Content-Transfer-Encoding . . . . . . . . . 87 212 A.6. MHTML and Line Length Limitations . . . . . . . . . . . . 87 213 Appendix B. Changes from RFC 2616 . . . . . . . . . . . . . . . . 87 214 Appendix C. Imported ABNF . . . . . . . . . . . . . . . . . . . . 90 215 Appendix D. Collected ABNF . . . . . . . . . . . . . . . . . . . 90 216 Appendix E. Change Log (to be removed by RFC Editor before 217 publication) . . . . . . . . . . . . . . . . . . . . 93 218 E.1. Since RFC 2616 . . . . . . . . . . . . . . . . . . . . . . 93 219 E.2. Since draft-ietf-httpbis-p2-semantics-21 . . . . . . . . . 94 220 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 222 1. Introduction 224 Each Hypertext Transfer Protocol (HTTP) message is either a request 225 or a response. A server listens on a connection for a request, 226 parses each message received, interprets the message semantics in 227 relation to the identified request target, and responds to that 228 request with one or more response messages. A client constructs 229 request messages to communicate specific intentions, and examines 230 received responses to see if the intentions were carried out and 231 determine how to interpret the results. This document defines 232 HTTP/1.1 request and response semantics in terms of the architecture 233 defined in [Part1]. 235 HTTP provides a uniform interface for interacting with a resource 236 (Section 2), regardless of its type, nature, or implementation, via 237 the manipulation and transfer of representations (Section 3). 239 HTTP semantics include the intentions defined by each request method 240 (Section 4), extensions to those semantics that might be described in 241 request header fields (Section 5), the meaning of status codes to 242 indicate a machine-readable response (Section 6), and the meaning of 243 other control data and resource metadata that might be given in 244 response header fields (Section 7). 246 This document also defines representation metadata that describe how 247 a payload is intended to be interpreted by a recipient, the request 248 header fields that might influence content selection, and the various 249 selection algorithms that are collectively referred to as "content 250 negotiation" (Section 3.4). 252 1.1. Conformance and Error Handling 254 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 255 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 256 document are to be interpreted as described in [RFC2119]. 258 Conformance criteria and considerations regarding error handling are 259 defined in Section 2.5 of [Part1]. 261 1.2. Syntax Notation 263 This specification uses the Augmented Backus-Naur Form (ABNF) 264 notation of [RFC5234] with the list rule extension defined in Section 265 1.2 of [Part1]. Appendix C describes rules imported from other 266 documents. Appendix D shows the collected ABNF with the list rule 267 expanded. 269 This specification uses the terms "character", "character encoding 270 scheme", "charset", and "protocol element" as they are defined in 271 [RFC6365]. 273 2. Resources 275 The target of each HTTP request is called a resource. HTTP does not 276 limit the nature of a resource; it merely defines an interface that 277 might be used to interact with resources. Each resource is 278 identified by a Uniform Resource Identifier (URI), as described in 279 Section 2.7 of [Part1]. 281 When a client constructs an HTTP/1.1 request message, it sends the 282 target URI in one of various forms, as defined in (Section 5.3 of 283 [Part1]). When a request is received, the server reconstructs an 284 effective request URI for the target resource (Section 5.5 of 285 [Part1]). 287 One design goal of HTTP is to separate resource identification from 288 request semantics, which is made possible by vesting the request 289 semantics in the request method (Section 4) and a few request- 290 modifying header fields (Section 5). Resource owners SHOULD NOT 291 include request semantics within a URI, such as by specifying an 292 action to invoke within the path or query components of the effective 293 request URI, unless those semantics are disabled when they are 294 inconsistent with the request method. 296 3. Representations 298 If we consider that a resource could be anything, and that the 299 uniform interface provided by HTTP is similar to a window through 300 which one can observe and act upon such a thing only through the 301 communication of messages to some independent actor on the other 302 side, then we need an abstraction to represent ("take the place of") 303 the current or desired state of that thing in our communications. We 304 call that abstraction a representation [REST]. 306 For the purposes of HTTP, a "representation" is information that is 307 intended to reflect a past, current, or desired state of a given 308 resource, in a format that can be readily communicated via the 309 protocol, and that consists of a set of representation metadata and a 310 potentially unbounded stream of representation data. 312 An origin server might be provided with, or capable of generating, 313 multiple representations that are each intended to reflect the 314 current state of a target resource. In such cases, some algorithm is 315 used by the origin server to select one of those representations as 316 most applicable to a given request, usually based on content 317 negotiation. We refer to that one representation as the "selected 318 representation" and use its particular data and metadata for 319 evaluating conditional requests [Part4] and constructing the payload 320 for 200 (OK) and 304 (Not Modified) responses to GET (Section 4.3.1). 322 3.1. Representation Metadata 324 Representation header fields provide metadata about the 325 representation. When a message includes a payload body, the 326 representation header fields describe how to interpret the 327 representation data enclosed in the payload body. In a response to a 328 HEAD request, the representation header fields describe the 329 representation data that would have been enclosed in the payload body 330 if the same request had been a GET. 332 The following header fields are defined to convey representation 333 metadata: 335 +-------------------+-----------------+ 336 | Header Field Name | Defined in... | 337 +-------------------+-----------------+ 338 | Content-Type | Section 3.1.1.5 | 339 | Content-Encoding | Section 3.1.2.2 | 340 | Content-Language | Section 3.1.3.2 | 341 | Content-Location | Section 3.1.4.2 | 342 +-------------------+-----------------+ 344 3.1.1. Processing the Data 346 3.1.1.1. Media Type 348 HTTP uses Internet Media Types [RFC2046] in the Content-Type 349 (Section 3.1.1.5) and Accept (Section 5.3.2) header fields in order 350 to provide open and extensible data typing and type negotiation. 351 Media types define both a data format and various processing models: 352 how to process that data in accordance with each context in which it 353 is received. 355 media-type = type "/" subtype *( OWS ";" OWS parameter ) 356 type = token 357 subtype = token 359 The type/subtype MAY be followed by parameters in the form of 360 attribute/value pairs. 362 parameter = attribute "=" value 363 attribute = token 364 value = word 366 The type, subtype, and parameter attribute names are case- 367 insensitive. Parameter values might or might not be case-sensitive, 368 depending on the semantics of the parameter name. The presence or 369 absence of a parameter might be significant to the processing of a 370 media-type, depending on its definition within the media type 371 registry. 373 A parameter value that matches the token production can be 374 transmitted as either a token or within a quoted-string. The quoted 375 and unquoted values are equivalent. For example, the following 376 examples are all equivalent, but the first is preferred for 377 consistency: 379 text/html;charset=utf-8 380 text/html;charset=UTF-8 381 Text/HTML;Charset="utf-8" 382 text/html; charset="utf-8" 384 Internet media types ought to be registered with IANA according to 385 the procedures defined in [BCP13]. 387 3.1.1.2. Charset 389 HTTP uses charset names to indicate or negotiate the character 390 encoding scheme of a textual representation [RFC6365]. A charset is 391 identified by a case-insensitive token. 393 charset = token 395 Charset names ought to be registered in IANA Character Set registry 396 () according to the 397 procedures defined in [RFC2978]. 399 3.1.1.3. Canonicalization and Text Defaults 401 Internet media types are registered with a canonical form in order to 402 be interoperable among systems with varying native encoding formats. 403 Representations selected or transferred via HTTP ought to be in 404 canonical form, for many of the same reasons described by the 405 Multipurpose Internet Mail Extensions (MIME) [RFC2045]. However, the 406 performance characteristics of email deployments (i.e., store and 407 forward messages to peers) are significantly different from those 408 common to HTTP and the Web (server-based information services). 409 Furthermore, MIME's constraints for the sake of compatibility with 410 older mail transfer protocols do not apply to HTTP (see Appendix A). 412 MIME's canonical form requires that media subtypes of the "text" type 413 use CRLF as the text line break. HTTP allows the transfer of text 414 media with plain CR or LF alone representing a line break, when such 415 line breaks are consistent for an entire representation. HTTP 416 senders MAY generate, and recipients MUST be able to parse, line 417 breaks in text media that consist of CRLF, bare CR, or bare LF. In 418 addition, text media in HTTP is not limited to charsets that use 419 octets 13 and 10 for CR and LF, respectively. This flexibility 420 regarding line breaks applies only to text within a representation 421 that has been assigned a "text" media type; it does not apply to 422 "multipart" types or HTTP elements outside the payload body (e.g., 423 header fields). 425 If a representation is encoded with a content-coding, the underlying 426 data ought to be in a form defined above prior to being encoded. 428 3.1.1.4. Multipart Types 430 MIME provides for a number of "multipart" types -- encapsulations of 431 one or more representations within a single message body. All 432 multipart types share a common syntax, as defined in Section 5.1.1 of 433 [RFC2046], and include a boundary parameter as part of the media type 434 value. The message body is itself a protocol element; a sender MUST 435 generate only CRLF to represent line breaks between body parts. 437 HTTP message framing does not use the multipart boundary as an 438 indicator of message body length, though it might be used by 439 implementations that generate or process the payload. For example, 440 the "multipart/form-data" type is often used for carrying form data 441 in a request, as described in [RFC2388], and the "multipart/ 442 byteranges" type is defined by this specification for use in some 206 443 (Partial Content) responses [Part5]. 445 3.1.1.5. Content-Type 447 The "Content-Type" header field indicates the media type of the 448 associated representation: either the representation enclosed in the 449 message payload or the selected representation, as determined by the 450 message semantics. The indicated media type defines both the data 451 format and how that data is intended to be processed by a recipient, 452 within the scope of the received message semantics, after any content 453 codings indicated by Content-Encoding are decoded. 455 Content-Type = media-type 457 Media types are defined in Section 3.1.1.1. An example of the field 458 is 460 Content-Type: text/html; charset=ISO-8859-4 462 A sender that generates a message containing a payload body SHOULD 463 generate a Content-Type header field in that message unless the 464 intended media type of the enclosed representation is unknown to the 465 sender. If a Content-Type header field is not present, recipients 466 MAY either assume a media type of "application/octet-stream" 467 ([RFC2046], Section 4.5.1) or examine the data to determine its type. 469 In practice, resource owners do not always properly configure their 470 origin server to provide the correct Content-Type for a given 471 representation, with the result that some clients will examine a 472 payload's content and override the specified type. Clients that do 473 so risk drawing incorrect conclusions, which might expose additional 474 security risks (e.g., "privilege escalation"). Furthermore, it is 475 impossible to determine the sender's intent by examining the data 476 format: many data formats match multiple media types that differ only 477 in processing semantics. Implementers are encouraged to provide a 478 means of disabling such "content sniffing" when it is used. 480 3.1.2. Encoding for Compression or Integrity 482 3.1.2.1. Content Codings 484 Content coding values indicate an encoding transformation that has 485 been or can be applied to a representation. Content codings are 486 primarily used to allow a representation to be compressed or 487 otherwise usefully transformed without losing the identity of its 488 underlying media type and without loss of information. Frequently, 489 the representation is stored in coded form, transmitted directly, and 490 only decoded by the recipient. 492 content-coding = token 494 All content-coding values are case-insensitive and ought to be 495 registered within the HTTP Content Coding registry, as defined in 496 Section 8.4. They are used in the Accept-Encoding (Section 5.3.4) 497 and Content-Encoding (Section 3.1.2.2) header fields. 499 The following content-coding values are defined by this 500 specification: 502 compress (and x-compress): See Section 4.2.1 of [Part1]. 504 deflate: See Section 4.2.2 of [Part1]. 506 gzip (and x-gzip): See Section 4.2.3 of [Part1]. 508 3.1.2.2. Content-Encoding 510 The "Content-Encoding" header field indicates what content codings 511 have been applied to the representation, beyond those inherent in the 512 media type, and thus what decoding mechanisms have to be applied in 513 order to obtain data in the media type referenced by the Content-Type 514 header field. Content-Encoding is primarily used to allow a 515 representation's data to be compressed without losing the identity of 516 its underlying media type. 518 Content-Encoding = 1#content-coding 520 An example of its use is 522 Content-Encoding: gzip 524 If multiple encodings have been applied to a representation, the 525 content codings MUST be listed in the order in which they were 526 applied. Additional information about the encoding parameters MAY be 527 provided by other header fields not defined by this specification. 529 Unlike Transfer-Encoding (Section 3.3.1 of [Part1]), the codings 530 listed in Content-Encoding are a characteristic of the 531 representation; the representation is defined in terms of the coded 532 form, and all other metadata about the representation is about the 533 coded form unless otherwise noted in the metadata definition. 534 Typically, the representation is only decoded just prior to rendering 535 or analogous usage. 537 If the media type includes an inherent encoding, such as a data 538 format that is always compressed, then that encoding would not be 539 restated in Content-Encoding even if it happens to be the same 540 algorithm as one of the content codings. Such a content coding would 541 only be listed if, for some bizarre reason, it is applied a second 542 time to form the representation. Likewise, an origin server might 543 choose to publish the same data as multiple representations that 544 differ only in whether the coding is defined as part of Content-Type 545 or Content-Encoding, since some user agents will behave differently 546 in their handling of each response (e.g., open a "Save as ..." dialog 547 instead of automatic decompression and rendering of content). 549 An origin server MAY respond with a status code of 415 (Unsupported 550 Media Type) if a representation in the request message has a content 551 coding that is not acceptable. 553 3.1.3. Audience Language 555 3.1.3.1. Language Tags 557 A language tag, as defined in [RFC5646], identifies a natural 558 language spoken, written, or otherwise conveyed by human beings for 559 communication of information to other human beings. Computer 560 languages are explicitly excluded. HTTP uses language tags within 561 the Accept-Language and Content-Language fields. 563 language-tag = 565 A language tag is composed of one or more parts: a primary language 566 subtag followed by a possibly empty series of subtags. White space 567 is not allowed within the tag and all tags are case-insensitive. 568 Example tags include: 570 en, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN 572 See [RFC5646] for further information. 574 3.1.3.2. Content-Language 576 The "Content-Language" header field describes the natural language(s) 577 of the intended audience for the representation. Note that this 578 might not be equivalent to all the languages used within the 579 representation. 581 Content-Language = 1#language-tag 583 Language tags are defined in Section 3.1.3.1. The primary purpose of 584 Content-Language is to allow a user to identify and differentiate 585 representations according to the users' own preferred language. 586 Thus, if the content is intended only for a Danish-literate audience, 587 the appropriate field is 589 Content-Language: da 591 If no Content-Language is specified, the default is that the content 592 is intended for all language audiences. This might mean that the 593 sender does not consider it to be specific to any natural language, 594 or that the sender does not know for which language it is intended. 596 Multiple languages MAY be listed for content that is intended for 597 multiple audiences. For example, a rendition of the "Treaty of 598 Waitangi", presented simultaneously in the original Maori and English 599 versions, would call for 600 Content-Language: mi, en 602 However, just because multiple languages are present within a 603 representation does not mean that it is intended for multiple 604 linguistic audiences. An example would be a beginner's language 605 primer, such as "A First Lesson in Latin", which is clearly intended 606 to be used by an English-literate audience. In this case, the 607 Content-Language would properly only include "en". 609 Content-Language MAY be applied to any media type -- it is not 610 limited to textual documents. 612 3.1.4. Identification 614 3.1.4.1. Identifying a Representation 616 When a complete or partial representation is transferred in a message 617 payload, it is often desirable for the sender to supply, or the 618 recipient to determine, an identifier for a resource corresponding to 619 that representation. 621 For a request message: 623 o If the request has a Content-Location header field, then the 624 sender asserts that the payload is a representation of the 625 resource identified by the Content-Location field-value. However, 626 such an assertion cannot be trusted unless it can be verified by 627 other means (not defined by HTTP). The information might still be 628 useful for revision history links. 630 o Otherwise, the payload is unidentified. 632 For a response message, the following rules are applied in order 633 until a match is found: 635 1. If the request is GET or HEAD and the response status code is 200 636 (OK), 204 (No Content), 206 (Partial Content), or 304 (Not 637 Modified), the payload is a representation of the resource 638 identified by the effective request URI (Section 5.5 of [Part1]). 640 2. If the request is GET or HEAD and the response status code is 203 641 (Non-Authoritative Information), the payload is a potentially 642 modified or enhanced representation of the target resource as 643 provided by an intermediary. 645 3. If the response has a Content-Location header field and its 646 field-value is a reference to the same URI as the effective 647 request URI, the payload is a representation of the resource 648 identified by the effective request URI. 650 4. If the response has a Content-Location header field and its 651 field-value is a reference to a URI different from the effective 652 request URI, then the sender asserts that the payload is a 653 representation of the resource identified by the Content-Location 654 field-value. However, such an assertion cannot be trusted unless 655 it can be verified by other means (not defined by HTTP). 657 5. Otherwise, the payload is unidentified. 659 3.1.4.2. Content-Location 661 The "Content-Location" header field references a URI that can be used 662 as an identifier for a specific resource corresponding to the 663 representation in this message's payload. In other words, if one 664 were to perform a GET request on this URI at the time of this 665 message's generation, then a 200 (OK) response would contain the same 666 representation that is enclosed as payload in this message. 668 Content-Location = absolute-URI / partial-URI 670 The Content-Location value is not a replacement for the effective 671 Request URI (Section 5.5 of [Part1]). It is representation metadata. 672 It has the same syntax and semantics as the header field of the same 673 name defined for MIME body parts in Section 4 of [RFC2557]. However, 674 its appearance in an HTTP message has some special implications for 675 HTTP recipients. 677 If Content-Location is included in a 2xx (Successful) response 678 message and its value refers (after conversion to absolute form) to a 679 URI that is the same as the effective request URI, then the recipient 680 MAY consider the payload to be a current representation of that 681 resource at the time indicated by the message origination date. For 682 a GET or HEAD request, this is the same as the default semantics when 683 no Content-Location is provided by the server. For a state-changing 684 request like PUT or POST, it implies that the server's response 685 contains the new representation of that resource, thereby 686 distinguishing it from representations that might only report about 687 the action (e.g., "It worked!"). This allows authoring applications 688 to update their local copies without the need for a subsequent GET 689 request. 691 If Content-Location is included in a 2xx (Successful) response 692 message and its field-value refers to a URI that differs from the 693 effective request URI, then the origin server claims that the URI is 694 an identifier for a different resource corresponding to the enclosed 695 representation. Such a claim can only be trusted if both identifiers 696 share the same resource owner, which cannot be programmatically 697 determined via HTTP. 699 o For a response to a GET or HEAD request, this is an indication 700 that the effective request URI refers to a resource that is 701 subject to content negotiation and the Content-Location field- 702 value is a more specific identifier for the selected 703 representation. 705 o For a 201 (Created) response to a state-changing method, a 706 Content-Location field-value that is identical to the Location 707 field-value indicates that this payload is a current 708 representation of the newly created resource. 710 o Otherwise, such a Content-Location indicates that this payload is 711 a representation reporting on the requested action's status and 712 that the same report is available (for future access with GET) at 713 the given URI. For example, a purchase transaction made via a 714 POST request might include a receipt document as the payload of 715 the 200 (OK) response; the Content-Location field-value provides 716 an identifier for retrieving a copy of that same receipt in the 717 future. 719 A user agent that sends Content-Location in a request message is 720 stating that its value refers to where the user agent originally 721 obtained the content of the enclosed representation (prior to any 722 modifications made by that user agent). In other words, the user 723 agent is providing a back link to the source of the original 724 representation. 726 An origin server that receives a Content-Location field in a request 727 message MUST treat the information as transitory request context 728 rather than as metadata to be saved verbatim as part of the 729 representation. An origin server MAY use that context to guide in 730 processing the request or to save it for other uses, such as within 731 source links or versioning metadata. However, an origin server MUST 732 NOT use such context information to alter the request semantics. 734 For example, if a client makes a PUT request on a negotiated resource 735 and the origin server accepts that PUT (without redirection), then 736 the new state of that resource is expected to be consistent with the 737 one representation supplied in that PUT; the Content-Location cannot 738 be used as a form of reverse content selection identifier to update 739 only one of the negotiated representations. If the user agent had 740 wanted the latter semantics, it would have applied the PUT directly 741 to the Content-Location URI. 743 3.2. Representation Data 745 The representation data associated with an HTTP message is either 746 provided as the payload body of the message or referred to by the 747 message semantics and the effective request URI. The representation 748 data is in a format and encoding defined by the representation 749 metadata header fields. 751 The data type of the representation data is determined via the header 752 fields Content-Type and Content-Encoding. These define a two-layer, 753 ordered encoding model: 755 representation-data := Content-Encoding( Content-Type( bits ) ) 757 3.3. Payload Semantics 759 Some HTTP messages transfer a complete or partial representation as 760 the message "payload". In some cases, a payload might contain only 761 the associated representation's header fields (e.g., responses to 762 HEAD) or only some part(s) of the representation data (e.g., the 206 763 (Partial Content) status code). 765 The purpose of a payload in a request is defined by the method 766 semantics. For example, a representation in the payload of a PUT 767 request (Section 4.3.4) represents the desired state of the target 768 resource if the request is successfully applied, whereas a 769 representation in the payload of a POST request (Section 4.3.3) 770 represents an anonymous resource for providing data to be processed, 771 such as the information that a user entered within an HTML form. 773 In a response, the payload's purpose is defined by both the request 774 method and the response status code. For example, the payload of a 775 200 (OK) response to GET (Section 4.3.1) represents the current state 776 of the target resource, as observed at the time of the message 777 origination date (Section 7.1.1.2), whereas the payload of the same 778 status code in a response to POST might represent either the 779 processing result or the new state of the target resource after 780 applying the processing. Response messages with an error status code 781 usually contain a payload that represents the error condition, such 782 that it describes the error state and what next steps are suggested 783 for resolving it. 785 Header fields that specifically describe the payload, rather than the 786 associated representation, are referred to as "payload header 787 fields". Payload header fields are defined in other parts of this 788 specification, due to their impact on message parsing. 790 +-------------------+--------------------------+ 791 | Header Field Name | Defined in... | 792 +-------------------+--------------------------+ 793 | Content-Length | Section 3.3.2 of [Part1] | 794 | Content-Range | Section 4.2 of [Part5] | 795 | Transfer-Encoding | Section 3.3.1 of [Part1] | 796 +-------------------+--------------------------+ 798 3.4. Content Negotiation 800 When responses convey payload information, whether indicating a 801 success or an error, the origin server often has different ways of 802 representing that information; for example, in different formats, 803 languages, or encodings. Likewise, different users or user agents 804 might have differing capabilities, characteristics, or preferences 805 that could influence which representation, among those available, 806 would be best to deliver. For this reason, HTTP provides mechanisms 807 for content negotiation. 809 This specification defines two patterns of content negotiation that 810 can be made visible within the protocol: "proactive", where the 811 server selects the representation based upon the user agent's stated 812 preferences, and "reactive" negotiation, where the server provides a 813 list of representations for the user agent to choose from. Other 814 patterns of content negotiation include "conditional content", where 815 the representation consists of multiple parts that are selectively 816 rendered based on user agent parameters, "active content", where the 817 representation contains a script that makes additional (more 818 specific) requests based on the user agent characteristics, and 819 "Transparent Content Negotiation" ([RFC2295]), where content 820 selection is performed by an intermediary. These patterns are not 821 mutually exclusive, and each has trade-offs in applicability and 822 practicality. 824 Note that, in all cases, the supplier of representations to the 825 origin server determines which representations might be considered to 826 be the "same information". 828 3.4.1. Proactive Negotiation 830 When content negotiation preferences are sent by the user agent in a 831 request in order to encourage an algorithm located at the server to 832 select the preferred representation, it is called proactive 833 negotiation (a.k.a., server-driven negotiation). Selection is based 834 on the available representations for a response (the dimensions over 835 which it might vary, such as language, content-coding, etc.) compared 836 to various information supplied in the request, including both the 837 explicit negotiation fields of Section 5.3 and implicit 838 characteristics, such as the client's network address or parts of the 839 User-Agent field. 841 Proactive negotiation is advantageous when the algorithm for 842 selecting from among the available representations is difficult to 843 describe to a user agent, or when the server desires to send its 844 "best guess" to the user agent along with the first response (hoping 845 to avoid the round-trip delay of a subsequent request if the "best 846 guess" is good enough for the user). In order to improve the 847 server's guess, a user agent MAY send request header fields that 848 describe its preferences. 850 Proactive negotiation has serious disadvantages: 852 o It is impossible for the server to accurately determine what might 853 be "best" for any given user, since that would require complete 854 knowledge of both the capabilities of the user agent and the 855 intended use for the response (e.g., does the user want to view it 856 on screen or print it on paper?); 858 o Having the user agent describe its capabilities in every request 859 can be both very inefficient (given that only a small percentage 860 of responses have multiple representations) and a potential risk 861 to the user's privacy; 863 o It complicates the implementation of an origin server and the 864 algorithms for generating responses to a request; and, 866 o It limits the reusability of responses for shared caching. 868 A user agent cannot rely on proactive negotiation preferences being 869 consistently honored, since the origin server might not implement 870 proactive negotiation for the requested resource or might decide that 871 sending a response that doesn't conform to the user agent's 872 preferences is better than sending a 406 (Not Acceptable) response. 874 An origin server MAY generate a Vary header field (Section 7.1.4) in 875 responses that are subject to proactive negotiation to indicate what 876 parameters of request information might be used in its selection 877 algorithm, thereby providing a means for recipients to determine the 878 reusability of that same response for user agents with differing 879 request information. 881 3.4.2. Reactive Negotiation 883 With reactive negotiation (a.k.a., agent-driven negotiation), 884 selection of the best representation for a response is performed by 885 the user agent after receiving an initial response from the origin 886 server with a list of alternative resources. If the user agent is 887 not satisfied by the initial response, it can perform a GET request 888 on one or more of the alternative resources, selected based on 889 metadata included in the list, to obtain a different form of 890 representation. Selection of alternatives might be performed 891 automatically by the user agent or manually by the user selecting 892 from a generated (possibly hypertext) menu. 894 A server can send a 300 (Multiple Choices) response to indicate that 895 reactive negotiation by the user agent is desired, or a 406 (Not 896 Acceptable) status code to indicate that proactive negotiation has 897 failed. In both cases, the response ought to include information 898 about the available representations so that the user or user agent 899 can react by making a selection. 901 Reactive negotiation is advantageous when the response would vary 902 over commonly-used dimensions (such as type, language, or encoding), 903 when the origin server is unable to determine a user agent's 904 capabilities from examining the request, and generally when public 905 caches are used to distribute server load and reduce network usage. 907 Reactive negotiation suffers from the disadvantages of transmitting a 908 list of alternatives to the user agent, which degrades user-perceived 909 latency if transmitted in the header section, and needing a second 910 request to obtain an alternate representation. Furthermore, this 911 specification does not define a mechanism for supporting automatic 912 selection, though it does not prevent such a mechanism from being 913 developed as an extension. 915 4. Request Methods 917 4.1. Overview 919 The request method token is the primary source of request semantics; 920 it indicates the purpose for which the client has made this request 921 and what is expected by the client as a successful result. The 922 request semantics might be further specialized by the semantics of 923 some header fields when present in a request (Section 5) if those 924 additional semantics do not conflict with the method. 926 method = token 928 HTTP was originally designed to be usable as an interface to 929 distributed object systems. The request method was envisioned as 930 applying semantics to a target resource in much the same way as 931 invoking a defined method on an identified object would apply 932 semantics. The method token is case-sensitive because it might be 933 used as a gateway to object-based systems with case-sensitive method 934 names. 936 Unlike distributed objects, the standardized request methods in HTTP 937 are not resource-specific, since uniform interfaces provide for 938 better visibility and reuse in network-based systems [REST]. Once 939 defined, a standardized method ought to have the same semantics when 940 applied to any resource, though each resource determines for itself 941 whether those semantics are implemented or allowed. 943 This specification defines a number of standardized methods that are 944 commonly used in HTTP, as outlined by the following table. By 945 convention, standardized methods are defined in all-uppercase ASCII 946 letters. 948 +---------+-------------------------------------------------+-------+ 949 | Method | Description | Sec. | 950 +---------+-------------------------------------------------+-------+ 951 | GET | Transfer a current representation of the target | 4.3.1 | 952 | | resource. | | 953 | HEAD | Same as GET, but only transfer the status line | 4.3.2 | 954 | | and header block. | | 955 | POST | Perform resource-specific processing on the | 4.3.3 | 956 | | request payload. | | 957 | PUT | Replace all current representations of the | 4.3.4 | 958 | | target resource with the request payload. | | 959 | DELETE | Remove all current representations of the | 4.3.5 | 960 | | target resource. | | 961 | CONNECT | Establish a tunnel to the server identified by | 4.3.6 | 962 | | the target resource. | | 963 | OPTIONS | Describe the communication options for the | 4.3.7 | 964 | | target resource. | | 965 | TRACE | Perform a message loop-back test along the path | 4.3.8 | 966 | | to the target resource. | | 967 +---------+-------------------------------------------------+-------+ 969 All general-purpose servers MUST support the methods GET and HEAD. 970 All other methods are OPTIONAL; when implemented, a server MUST 971 implement the above methods according to the semantics defined for 972 them in Section 4.3. 974 Additional methods, outside the scope of this specification, have 975 been standardized for use in HTTP. All such methods ought to be 976 registered within the HTTP Method Registry maintained by IANA, as 977 defined in Section 8.1. 979 The set of methods allowed by a target resource can be listed in an 980 Allow header field (Section 7.4.1). However, the set of allowed 981 methods can change dynamically. When a request method is received 982 that is unrecognized or not implemented by an origin server, the 983 origin server SHOULD respond with the 501 (Not Implemented) status 984 code. When a request method is received that is known by an origin 985 server but not allowed for the target resource, the origin server 986 SHOULD respond with the 405 (Method Not Allowed) status code. 988 A client can send conditional request header fields (Section 5.2) to 989 make the requested action conditional on the current state of the 990 target resource ([Part4]). 992 4.2. Common Method Properties 994 4.2.1. Safe Methods 996 Request methods are considered "safe" if their defined semantics are 997 essentially read-only; i.e., the client does not request, and does 998 not expect, any state change on the origin server as a result of 999 applying a safe method to a target resource. Likewise, reasonable 1000 use of a safe method is not expected to cause any harm, loss of 1001 property, or unusual burden on the origin server. 1003 This definition of safe methods does not prevent an implementation 1004 from including behavior that is potentially harmful, not entirely 1005 read-only, or which causes side-effects while invoking a safe method. 1006 What is important, however, is that the client did not request that 1007 additional behavior and cannot be held accountable for it. For 1008 example, most servers append request information to access log files 1009 at the completion of every response, regardless of the method, and 1010 that is considered safe even though the log storage might become full 1011 and crash the server. Likewise, a safe request initiated by 1012 selecting an advertisement on the Web will often have the side-effect 1013 of charging an advertising account. 1015 Of the request methods defined by this specification, the GET, HEAD, 1016 OPTIONS, and TRACE methods are defined to be safe. 1018 The purpose of distinguishing between safe and unsafe methods is to 1019 allow automated retrieval processes (spiders) and cache performance 1020 optimization (pre-fetching) to work without fear of causing harm. In 1021 addition, it allows a user agent to apply appropriate constraints on 1022 the automated use of unsafe methods when processing potentially 1023 untrusted content. 1025 A user agent SHOULD distinguish between safe and unsafe methods when 1026 presenting potential actions to a user, such that the user can be 1027 made aware of an unsafe action before it is requested. 1029 When a resource is constructed such that parameters within the 1030 effective request URI have the effect of selecting an action, it is 1031 the resource owner's responsibility to ensure that the action is 1032 consistent with the request method semantics. For example, it is 1033 common for Web-based content editing software to use actions within 1034 query parameters, such as "page?do=delete". If the purpose of such a 1035 resource is to perform an unsafe action, then the resource MUST 1036 disable or disallow that action when it is accessed using a safe 1037 request method. Failure to do so will result in unfortunate side- 1038 effects when automated processes perform a GET on every URI reference 1039 for the sake of link maintenance, pre-fetching, building a search 1040 index, etc. 1042 4.2.2. Idempotent Methods 1044 Request methods are considered "idempotent" if the intended effect of 1045 multiple identical requests is the same as for a single request. Of 1046 the request methods defined by this specification, the PUT, DELETE, 1047 and safe request methods are idempotent. 1049 Like the definition of safe, the idempotent property only applies to 1050 what has been requested by the user; a server is free to log each 1051 request separately, retain a revision control history, or implement 1052 other non-idempotent side-effects for each idempotent request. 1054 Idempotent methods are distinguished because the request can be 1055 repeated automatically if a communication failure occurs before the 1056 client is able to read the server's response. For example, if a 1057 client sends a PUT request and the underlying connection is closed 1058 before any response is received, then it can establish a new 1059 connection and retry the idempotent request because it knows that 1060 repeating the request will have the same effect even if the original 1061 request succeeded. Note, however, that repeated failures would 1062 indicate a problem within the server. 1064 4.2.3. Cacheable Methods 1066 Request methods are considered "cacheable" if it is possible and 1067 useful to answer a current client request with a stored response from 1068 a prior request. GET and HEAD are defined to be cacheable. In 1069 general, safe methods that do not depend on a current or 1070 authoritative response are cacheable, though the overwhelming 1071 majority of caches only support GET and HEAD. HTTP requirements for 1072 cache behavior and cacheable responses are defined in [Part6]. 1074 4.3. Method Definitions 1075 4.3.1. GET 1077 The GET method requests transfer of a current selected representation 1078 for the target resource. GET is the primary mechanism of information 1079 retrieval and the focus of almost all performance optimizations. 1080 Hence, when people speak of retrieving some identifiable information 1081 via HTTP, they are generally referring to making a GET request. 1083 It is tempting to think of resource identifiers as remote filesystem 1084 pathnames, and of representations as being a copy of the contents of 1085 such files. In fact, that is how many resources are implemented (see 1086 Section 9.1 for related security considerations). However, there are 1087 no such limitations in practice. The HTTP interface for a resource 1088 is just as likely to be implemented as a tree of content objects, a 1089 programmatic view on various database records, or a gateway to other 1090 information systems. Even when the URI mapping mechanism is tied to 1091 a filesystem, an origin server might be configured to execute the 1092 files with the request as input and send the output as the 1093 representation, rather then transfer the files directly. Regardless, 1094 only the origin server needs to know how each of its resource 1095 identifiers correspond to an implementation, and how each 1096 implementation manages to select and send a current representation of 1097 the target resource in a response to GET. 1099 A client can alter the semantics of GET to be a "range request", 1100 requesting transfer of only some part(s) of the selected 1101 representation, by sending a Range header field in the request 1102 ([Part5]). 1104 A payload within a GET request message has no defined semantics; 1105 sending a payload body on a GET request might cause some existing 1106 implementations to reject the request. 1108 The response to a GET request is cacheable; a cache MAY use it to 1109 satisfy subsequent GET and HEAD requests unless otherwise indicated 1110 by the Cache-Control header field (Section 7.2 of [Part6]). 1112 4.3.2. HEAD 1114 The HEAD method is identical to GET except that the server MUST NOT 1115 send a message body in the response (i.e., the response terminates at 1116 the end of the header block). Aside from the payload header fields 1117 (Section 3.3), the server SHOULD send the same header fields in 1118 response to a HEAD request as it would have sent if the request had 1119 been a GET. This method can be used for obtaining metadata about the 1120 selected representation without transferring the representation data. 1121 This method is often used for testing hypertext links for validity, 1122 accessibility, and recent modification. 1124 A payload within a HEAD request message has no defined semantics; 1125 sending a payload body on a HEAD request might cause some existing 1126 implementations to reject the request. 1128 The response to a HEAD request is cacheable; a cache MAY use it to 1129 satisfy subsequent HEAD requests unless otherwise indicated by the 1130 Cache-Control header field (Section 7.2 of [Part6]). A HEAD response 1131 might also have an effect on previously cached responses to GET; see 1132 Section 5 of [Part6]. 1134 4.3.3. POST 1136 The POST method requests that the target resource process the 1137 representation enclosed in the request according to the resource's 1138 own specific semantics. For example, POST is used for the following 1139 functions (among others): 1141 o Providing a block of data, such as the fields entered into an HTML 1142 form, to a data-handling process; 1144 o Posting a message to a bulletin board, newsgroup, mailing list, 1145 blog, or similar group of articles; 1147 o Creating a new resource that has yet to be identified by the 1148 origin server; and 1150 o Appending data to a resource's existing representation(s). 1152 An origin server indicates response semantics by choosing an 1153 appropriate status code depending on the result of processing the 1154 POST request; almost all of the status codes defined by this 1155 specification might be received in a response to POST (the exceptions 1156 being 206, 304, and 416). 1158 If one or more resources has been created on the origin server as a 1159 result of successfully processing a POST request, the origin server 1160 SHOULD send a 201 (Created) response containing a Location header 1161 field that provides an identifier for the primary resource created 1162 (Section 7.1.2) and a representation that describes the status of the 1163 request while referring to the new resource(s). 1165 Responses to POST requests are only cacheable when they include 1166 explicit freshness information (see Section 4.1.1 of [Part6]). 1167 However, POST caching is not widely implemented. For cases where an 1168 origin server wishes the client to be able to cache the result of a 1169 POST in a way that can be reused by a later GET, the origin server 1170 MAY send a 200 (OK) response containing the result and a Content- 1171 Location header field that has the same value as the POST's effective 1172 request URI (Section 3.1.4.2). 1174 If the result of processing a POST would be equivalent to a 1175 representation of an existing resource, an origin server MAY redirect 1176 the user agent to that resource by sending a 303 (See Other) response 1177 with the existing resource's identifier in the Location field. This 1178 has the benefits of providing the user agent a resource identifier 1179 and transferring the representation via a method more amenable to 1180 shared caching, though at the cost of an extra request if the user 1181 agent does not already have the representation cached. 1183 4.3.4. PUT 1185 The PUT method requests that the state of the target resource be 1186 created or replaced with the state defined by the representation 1187 enclosed in the request message payload. A successful PUT of a given 1188 representation would suggest that a subsequent GET on that same 1189 target resource will result in an equivalent representation being 1190 sent in a 200 (OK) response. However, there is no guarantee that 1191 such a state change will be observable, since the target resource 1192 might be acted upon by other user agents in parallel, or might be 1193 subject to dynamic processing by the origin server, before any 1194 subsequent GET is received. A successful response only implies that 1195 the user agent's intent was achieved at the time of its processing by 1196 the origin server. 1198 If the target resource does not have a current representation and the 1199 PUT successfully creates one, then the origin server MUST inform the 1200 user agent by sending a 201 (Created) response. If the target 1201 resource does have a current representation and that representation 1202 is successfully modified in accordance with the state of the enclosed 1203 representation, then either a 200 (OK) or 204 (No Content) response 1204 SHOULD be sent to indicate successful completion of the request. 1206 An origin server SHOULD ignore unrecognized header fields received in 1207 a PUT request (i.e., do not save them as part of the resource state). 1209 An origin server SHOULD verify that the PUT representation is 1210 consistent with any constraints the server has for the target 1211 resource that cannot or will not be changed by the PUT. This is 1212 particularly important when the origin server uses internal 1213 configuration information related to the URI in order to set the 1214 values for representation metadata on GET responses. When a PUT 1215 representation is inconsistent with the target resource, the origin 1216 server SHOULD either make them consistent, by transforming the 1217 representation or changing the resource configuration, or respond 1218 with an appropriate error message containing sufficient information 1219 to explain why the representation is unsuitable. The 409 (Conflict) 1220 or 415 (Unsupported Media Type) status codes are suggested, with the 1221 latter being specific to constraints on Content-Type values. 1223 For example, if the target resource is configured to always have a 1224 Content-Type of "text/html" and the representation being PUT has a 1225 Content-Type of "image/jpeg", then the origin server SHOULD do one 1226 of: 1228 a. reconfigure the target resource to reflect the new media type; 1230 b. transform the PUT representation to a format consistent with that 1231 of the resource before saving it as the new resource state; or, 1233 c. reject the request with a 415 (Unsupported Media Type) response 1234 indicating that the target resource is limited to "text/html", 1235 perhaps including a link to a different resource that would be a 1236 suitable target for the new representation. 1238 HTTP does not define exactly how a PUT method affects the state of an 1239 origin server beyond what can be expressed by the intent of the user 1240 agent request and the semantics of the origin server response. It 1241 does not define what a resource might be, in any sense of that word, 1242 beyond the interface provided via HTTP. It does not define how 1243 resource state is "stored", nor how such storage might change as a 1244 result of a change in resource state, nor how the origin server 1245 translates resource state into representations. Generally speaking, 1246 all implementation details behind the resource interface are 1247 intentionally hidden by the server. 1249 An origin server MUST NOT send a validator header field 1250 (Section 7.2), such as an ETag or Last-Modified field, in a 1251 successful response to PUT unless the request's representation data 1252 was saved without any transformation applied to the body (i.e., the 1253 resource's new representation data is identical to the representation 1254 data received in the PUT request) and the validator field value 1255 reflects the new representation. This requirement allows a user 1256 agent to know when the representation body it has in memory remains 1257 current as a result of the PUT, thus not in need of retrieving again 1258 from the origin server, and that the new validator(s) received in the 1259 response can be used for future conditional requests in order to 1260 prevent accidental overwrites (Section 5.2). 1262 The fundamental difference between the POST and PUT methods is 1263 highlighted by the different intent for the enclosed representation. 1264 The target resource in a POST request is intended to handle the 1265 enclosed representation according to the resource's own semantics, 1266 whereas the enclosed representation in a PUT request is defined as 1267 replacing the state of the target resource. Hence, the intent of PUT 1268 is idempotent and visible to intermediaries, even though the exact 1269 effect is only known by the origin server. 1271 Proper interpretation of a PUT request presumes that the user agent 1272 knows which target resource is desired. A service that selects a 1273 proper URI on behalf of the client, after receiving a state-changing 1274 request, SHOULD be implemented using the POST method rather than PUT. 1275 If the origin server will not make the requested PUT state change to 1276 the target resource and instead wishes to have it applied to a 1277 different resource, such as when the resource has been moved to a 1278 different URI, then the origin server MUST send an appropriate 3xx 1279 (Redirection) response; the user agent MAY then make its own decision 1280 regarding whether or not to redirect the request. 1282 A PUT request applied to the target resource MAY have side-effects on 1283 other resources. For example, an article might have a URI for 1284 identifying "the current version" (a resource) that is separate from 1285 the URIs identifying each particular version (different resources 1286 that at one point shared the same state as the current version 1287 resource). A successful PUT request on "the current version" URI 1288 might therefore create a new version resource in addition to changing 1289 the state of the target resource, and might also cause links to be 1290 added between the related resources. 1292 An origin server SHOULD reject any PUT request that contains a 1293 Content-Range header field (Section 4.2 of [Part5]), since it might 1294 be misinterpreted as partial content (or might be partial content 1295 that is being mistakenly PUT as a full representation). Partial 1296 content updates are possible by targeting a separately identified 1297 resource with state that overlaps a portion of the larger resource, 1298 or by using a different method that has been specifically defined for 1299 partial updates (for example, the PATCH method defined in [RFC5789]). 1301 Responses to the PUT method are not cacheable. If a PUT request 1302 passes through a cache that has one or more stored responses for the 1303 effective request URI, those stored responses will be invalidated 1304 (see Section 6 of [Part6]). 1306 4.3.5. DELETE 1308 The DELETE method requests that the origin server remove the 1309 association between the target resource and its current 1310 functionality. In effect, this method is similar to the rm command 1311 in UNIX: it expresses a deletion operation on the URI mapping of the 1312 origin server, rather than an expectation that the previously 1313 associated information be deleted. 1315 If the target resource has one or more current representations, they 1316 might or might not be destroyed by the origin server, and the 1317 associated storage might or might not be reclaimed, depending 1318 entirely on the nature of the resource and its implementation by the 1319 origin server (which are beyond the scope of this specification). 1320 Likewise, other implementation aspects of a resource might need to be 1321 deactivated or archived as a result of a DELETE, such as database or 1322 gateway connections. In general, it is assumed that the origin 1323 server will only allow DELETE on resources for which it has a 1324 prescribed mechanism for accomplishing the deletion. 1326 Relatively few resources allow the DELETE method -- its primary use 1327 is for remote authoring environments, where the user has some 1328 direction regarding its effect. For example, a resource that was 1329 previously created using a PUT request, or identified via the 1330 Location header field after a 201 (Created) response to a POST 1331 request, might allow a corresponding DELETE request to undo those 1332 actions. Similarly, custom user agent implementations that implement 1333 an authoring function, such as revision control clients using HTTP 1334 for remote operations, might use DELETE based on an assumption that 1335 the server's URI space has been crafted to correspond to a version 1336 repository. 1338 If a DELETE method is successfully applied, the origin server SHOULD 1339 send a 202 (Accepted) status code if the action seems okay but has 1340 not yet been enacted, a 204 (No Content) status code if the action 1341 has been enacted and no further information is to be supplied, or a 1342 200 (OK) status code if the action has been enacted and the response 1343 message includes a representation describing the status. 1345 A payload within a DELETE request message has no defined semantics; 1346 sending a payload body on a DELETE request might cause some existing 1347 implementations to reject the request. 1349 Responses to the DELETE method are not cacheable. If a DELETE 1350 request passes through a cache that has one or more stored responses 1351 for the effective request URI, those stored responses will be 1352 invalidated (see Section 6 of [Part6]). 1354 4.3.6. CONNECT 1356 The CONNECT method requests that the recipient establish a tunnel to 1357 the destination origin server identified by the request-target and, 1358 if successful, thereafter restrict its behavior to blind forwarding 1359 of packets, in both directions, until the connection is closed. 1361 CONNECT is intended only for use in requests to a proxy. An origin 1362 server that receives a CONNECT request for itself MAY respond with a 1363 2xx status code to indicate that a connection is established. 1365 However, most origin servers do not implement CONNECT. 1367 A client sending a CONNECT request MUST send the authority form of 1368 request-target (Section 5.3 of [Part1]); i.e., the request-target 1369 consists of only the host name and port number of the tunnel 1370 destination, separated by a colon. For example, 1372 CONNECT server.example.com:80 HTTP/1.1 1373 Host: server.example.com:80 1375 The recipient proxy can establish a tunnel either by directly 1376 connecting to the request-target or, if configured to use another 1377 proxy, by forwarding the CONNECT request to the next inbound proxy. 1378 Any 2xx (Successful) response indicates that the sender (and all 1379 inbound proxies) will switch to tunnel mode immediately after the 1380 blank line that concludes the successful response's header block; 1381 data received after that blank line is from the server identified by 1382 the request-target. Any response other than a successful response 1383 indicates that the tunnel has not yet been formed and that the 1384 connection remains governed by HTTP. 1386 A server SHOULD NOT send any Transfer-Encoding or Content-Length 1387 header fields in a successful response. A client MUST ignore any 1388 Content-Length or Transfer-Encoding header fields received in a 1389 successful response. 1391 There are significant risks in establishing a tunnel to arbitrary 1392 servers, particularly when the destination is a well-known or 1393 reserved TCP port that is not intended for Web traffic. For example, 1394 a CONNECT to a request-target of "example.com:25" would suggest that 1395 the proxy connect to the reserved port for SMTP traffic; if allowed, 1396 that could trick the proxy into relaying spam email. Proxies that 1397 support CONNECT SHOULD restrict its use to a limited set of known 1398 ports or a configurable whitelist of safe request targets. 1400 Proxy authentication might be used to establish the authority to 1401 create a tunnel. For example, 1403 CONNECT server.example.com:80 HTTP/1.1 1404 Host: server.example.com:80 1405 Proxy-Authorization: basic aGVsbG86d29ybGQ= 1407 When a tunnel intermediary detects that either side has closed its 1408 connection, any outstanding data that came from that side will first 1409 be sent to the other side and then the intermediary will close both 1410 connections. If there is outstanding data left undelivered, that 1411 data will be discarded. 1413 A payload within a CONNECT request message has no defined semantics; 1414 sending a payload body on a CONNECT request might cause some existing 1415 implementations to reject the request. 1417 Responses to the CONNECT method are not cacheable. 1419 4.3.7. OPTIONS 1421 The OPTIONS method requests information about the communication 1422 options available on the request/response chain identified by the 1423 effective request URI. This method allows a client to determine the 1424 options and/or requirements associated with a resource, or the 1425 capabilities of a server, without implying a resource action. 1427 An OPTIONS request with an asterisk ("*") as the request-target 1428 (Section 5.3 of [Part1]) applies to the server in general rather than 1429 to a specific resource. Since a server's communication options 1430 typically depend on the resource, the "*" request is only useful as a 1431 "ping" or "no-op" type of method; it does nothing beyond allowing the 1432 client to test the capabilities of the server. For example, this can 1433 be used to test a proxy for HTTP/1.1 conformance (or lack thereof). 1435 If the request-target is not an asterisk, the OPTIONS request applies 1436 to the options that are available when communicating with the target 1437 resource. 1439 A server generating a successful response to OPTIONS SHOULD send any 1440 header fields that might indicate optional features implemented by 1441 the server and applicable to the target resource (e.g., Allow), 1442 including potential extensions not defined by this specification. 1443 The response payload, if any, might also describe the communication 1444 options in a machine or human-readable representation. A standard 1445 format for such a representation is not defined by this 1446 specification, but might be defined by future extensions to HTTP. A 1447 server MUST generate a Content-Length field with a value of "0" if no 1448 payload body is to be sent in the response. 1450 A client MAY send a Max-Forwards header field in an OPTIONS request 1451 to target a specific recipient in the request chain (see 1452 Section 5.1.2). A proxy MUST NOT generate a Max-Forwards header 1453 field while forwarding a request unless that request was received 1454 with a Max-Forwards field. 1456 A client that generates an OPTIONS request containing a payload body 1457 MUST send a valid Content-Type header field describing the 1458 representation media type. Although this specification does not 1459 define any use for such a payload, future extensions to HTTP might 1460 use the OPTIONS body to make more detailed queries about the target 1461 resource. 1463 Responses to the OPTIONS method are not cacheable. 1465 4.3.8. TRACE 1467 The TRACE method requests a remote, application-level loop-back of 1468 the request message. The final recipient of the request SHOULD 1469 reflect the message received, excluding some fields described below, 1470 back to the client as the message body of a 200 (OK) response with a 1471 Content-Type of "message/http" (Section 7.3.1 of [Part1]). The final 1472 recipient is either the origin server or the first server to receive 1473 a Max-Forwards value of zero (0) in the request (Section 5.1.2). 1475 A client MUST NOT send header fields in a TRACE request containing 1476 sensitive data that might be disclosed by the response. For example, 1477 it would be foolish for a user agent to send stored user credentials 1478 [Part7] or cookies [RFC6265] in a TRACE request. The final recipient 1479 SHOULD exclude any request header fields from the response body that 1480 are likely to contain sensitive data. 1482 TRACE allows the client to see what is being received at the other 1483 end of the request chain and use that data for testing or diagnostic 1484 information. The value of the Via header field (Section 5.7.1 of 1485 [Part1]) is of particular interest, since it acts as a trace of the 1486 request chain. Use of the Max-Forwards header field allows the 1487 client to limit the length of the request chain, which is useful for 1488 testing a chain of proxies forwarding messages in an infinite loop. 1490 A client MUST NOT send a message body in a TRACE request. 1492 Responses to the TRACE method are not cacheable. 1494 5. Request Header Fields 1496 A client sends request header fields to provide more information 1497 about the request context, make the request conditional based on the 1498 target resource state, suggest preferred formats for the response, 1499 supply authentication credentials, or modify the expected request 1500 processing. These fields act as request modifiers, similar to the 1501 parameters on a programming language method invocation. 1503 5.1. Controls 1505 Controls are request header fields that direct specific handling of 1506 the request. 1508 +-------------------+------------------------+ 1509 | Header Field Name | Defined in... | 1510 +-------------------+------------------------+ 1511 | Cache-Control | Section 7.2 of [Part6] | 1512 | Expect | Section 5.1.1 | 1513 | Host | Section 5.4 of [Part1] | 1514 | Max-Forwards | Section 5.1.2 | 1515 | Pragma | Section 7.4 of [Part6] | 1516 | Range | Section 3.1 of [Part5] | 1517 | TE | Section 4.3 of [Part1] | 1518 +-------------------+------------------------+ 1520 5.1.1. Expect 1522 The "Expect" header field is used to indicate that particular server 1523 behaviors are required by the client. 1525 Expect = 1#expectation 1527 expectation = expect-name [ BWS "=" BWS expect-value ] 1528 *( OWS ";" [ OWS expect-param ] ) 1529 expect-param = expect-name [ BWS "=" BWS expect-value ] 1531 expect-name = token 1532 expect-value = token / quoted-string 1534 If all received Expect header field(s) are syntactically valid but 1535 contain an expectation that the recipient does not understand or 1536 cannot comply with, the recipient MUST respond with a 417 1537 (Expectation Failed) status code. A recipient of a syntactically 1538 invalid Expectation header field MUST respond with a 4xx status code 1539 other than 417. 1541 Comparison is case-insensitive for names (expect-name), and case- 1542 sensitive for values (expect-value). 1544 The Expect header field MUST be forwarded if the request is 1545 forwarded. 1547 Many older HTTP/1.0 and HTTP/1.1 servers do not understand the Expect 1548 header field. 1550 5.1.1.1. Use of the 100 (Continue) Status 1552 The only expectation defined by this specification is: 1554 100-continue 1556 The request includes a payload body and the client will wait for a 1557 100 (Continue) response after sending the request header section 1558 but before sending the payload body. The 100-continue expectation 1559 does not use any expect-params. 1561 The primary purpose of the 100 (Continue) status code (Section 6.2.1) 1562 is to allow a client that is sending a request message with a payload 1563 to determine if the origin server is willing to accept the request 1564 (based on the request header fields) before the client sends the 1565 payload body. In some cases, it might either be inappropriate or 1566 highly inefficient for the client to send the payload body if the 1567 server will reject the message without looking at the body. 1569 Requirements for HTTP/1.1 clients: 1571 o If a client will wait for a 100 (Continue) response before sending 1572 the payload body, it MUST send an Expect header field with the 1573 "100-continue" expectation. 1575 o A client MUST NOT send an Expect header field with the "100- 1576 continue" expectation if it does not intend to send a payload 1577 body. 1579 Because of the presence of older implementations, the protocol allows 1580 ambiguous situations in which a client might send "Expect: 100- 1581 continue" without receiving either a 417 (Expectation Failed) or a 1582 100 (Continue) status code. Therefore, when a client sends this 1583 header field to an origin server (possibly via a proxy) from which it 1584 has never seen a 100 (Continue) status code, the client SHOULD NOT 1585 wait for an indefinite period before sending the payload body. 1587 Requirements for HTTP/1.1 origin servers: 1589 o Upon receiving a request that includes an Expect header field with 1590 the "100-continue" expectation, an origin server MUST either 1591 respond with 100 (Continue) status code and continue to read from 1592 the input stream, or respond with a final status code. The origin 1593 server MUST NOT wait for the payload body before sending the 100 1594 (Continue) response. If the origin server responds with a final 1595 status code, it MUST NOT have performed the request method and MAY 1596 either close the connection or continue to read and discard the 1597 rest of the request. 1599 o An origin server SHOULD NOT send a 100 (Continue) response if the 1600 request message does not include an Expect header field with the 1601 "100-continue" expectation, and MUST NOT send a 100 (Continue) 1602 response if such a request comes from an HTTP/1.0 (or earlier) 1603 client. There is an exception to this rule: for compatibility 1604 with [RFC2068], a server MAY send a 100 (Continue) status code in 1605 response to an HTTP/1.1 PUT or POST request that does not include 1606 an Expect header field with the "100-continue" expectation. This 1607 exception, the purpose of which is to minimize any client 1608 processing delays associated with an undeclared wait for 100 1609 (Continue) status code, applies only to HTTP/1.1 requests, and not 1610 to requests with any other HTTP-version value. 1612 o An origin server MAY omit a 100 (Continue) response if it has 1613 already received some or all of the payload body for the 1614 corresponding request. 1616 o An origin server that sends a 100 (Continue) response MUST 1617 ultimately send a final status code, once the payload body is 1618 received and processed, unless it terminates the transport 1619 connection prematurely. 1621 o If an origin server receives a request that does not include an 1622 Expect header field with the "100-continue" expectation, the 1623 request includes a payload body, and the server responds with a 1624 final status code before reading the entire payload body from the 1625 transport connection, then the server SHOULD NOT close the 1626 transport connection until it has read the entire request, or 1627 until the client closes the connection. Otherwise, the client 1628 might not reliably receive the response message. However, this 1629 requirement ought not be construed as preventing a server from 1630 defending itself against denial-of-service attacks, or from badly 1631 broken client implementations. 1633 Requirements for HTTP/1.1 proxies: 1635 o If a proxy receives a request that includes an Expect header field 1636 with the "100-continue" expectation, and the proxy either knows 1637 that the next-hop server complies with HTTP/1.1 or higher, or does 1638 not know the HTTP version of the next-hop server, it MUST forward 1639 the request, including the Expect header field. 1641 o If the proxy knows that the version of the next-hop server is 1642 HTTP/1.0 or lower, it MUST NOT forward the request, and it MUST 1643 respond with a 417 (Expectation Failed) status code. 1645 o Proxies SHOULD maintain a record of the HTTP version numbers 1646 received from recently-referenced next-hop servers. 1648 o A proxy MUST NOT forward a 100 (Continue) response if the request 1649 message was received from an HTTP/1.0 (or earlier) client and did 1650 not include an Expect header field with the "100-continue" 1651 expectation. This requirement overrides the general rule for 1652 forwarding of 1xx responses (see Section 6.2.1). 1654 5.1.2. Max-Forwards 1656 The "Max-Forwards" header field provides a mechanism with the TRACE 1657 (Section 4.3.8) and OPTIONS (Section 4.3.7) methods to limit the 1658 number of times that the request is forwarded by proxies. This can 1659 be useful when the client is attempting to trace a request that 1660 appears to be failing or looping mid-chain. 1662 Max-Forwards = 1*DIGIT 1664 The Max-Forwards value is a decimal integer indicating the remaining 1665 number of times this request message can be forwarded. 1667 Each recipient of a TRACE or OPTIONS request containing a Max- 1668 Forwards header field MUST check and update its value prior to 1669 forwarding the request. If the received value is zero (0), the 1670 recipient MUST NOT forward the request; instead, it MUST respond as 1671 the final recipient. If the received Max-Forwards value is greater 1672 than zero, then the forwarded message MUST contain an updated Max- 1673 Forwards field with a value decremented by one (1). 1675 The Max-Forwards header field MAY be ignored for all other request 1676 methods. 1678 5.2. Conditionals 1680 The HTTP conditional request header fields [Part4] allow a client to 1681 place a precondition on the state of the target resource, so that the 1682 action corresponding to the method semantics will not be applied if 1683 the precondition evaluates to false. Each precondition defined by 1684 this specification consists of a comparison between a set of 1685 validators obtained from prior representations of the target resource 1686 to the current state of validators for the selected representation 1687 (Section 7.2). Hence, these preconditions evaluate whether the state 1688 of the target resource has changed since a given state known by the 1689 client. The effect of such an evaluation depends on the method 1690 semantics and choice of conditional, as defined in Section 5 of 1691 [Part4]. 1693 +---------------------+------------------------+ 1694 | Header Field Name | Defined in... | 1695 +---------------------+------------------------+ 1696 | If-Match | Section 3.1 of [Part4] | 1697 | If-None-Match | Section 3.2 of [Part4] | 1698 | If-Modified-Since | Section 3.3 of [Part4] | 1699 | If-Unmodified-Since | Section 3.4 of [Part4] | 1700 | If-Range | Section 3.2 of [Part5] | 1701 +---------------------+------------------------+ 1703 5.3. Content Negotiation 1705 The following request header fields are sent by a user agent to 1706 engage in proactive negotiation of the response content, as defined 1707 in Section 3.4.1. The preferences sent in these fields apply to any 1708 content in the response, including representations of the target 1709 resource, representations of error or processing status, and 1710 potentially even the miscellaneous text strings that might appear 1711 within the protocol. 1713 +-------------------+---------------+ 1714 | Header Field Name | Defined in... | 1715 +-------------------+---------------+ 1716 | Accept | Section 5.3.2 | 1717 | Accept-Charset | Section 5.3.3 | 1718 | Accept-Encoding | Section 5.3.4 | 1719 | Accept-Language | Section 5.3.5 | 1720 +-------------------+---------------+ 1722 5.3.1. Quality Values 1724 Many of the request header fields for proactive negotiation use a 1725 common parameter, named "q" (case-insensitive), to assign a relative 1726 "weight" to the preference for that associated kind of content. This 1727 weight is referred to as a "quality value" (or "qvalue") because the 1728 same parameter name is often used within server configurations to 1729 assign a weight to the relative quality of the various 1730 representations that can be selected for a resource. 1732 The weight is normalized to a real number in the range 0 through 1, 1733 where 0.001 is the least preferred and 1 is the most preferred; a 1734 value of 0 means "not acceptable". If no "q" parameter is present, 1735 the default weight is 1. 1737 weight = OWS ";" OWS "q=" qvalue 1738 qvalue = ( "0" [ "." 0*3DIGIT ] ) 1739 / ( "1" [ "." 0*3("0") ] ) 1741 A sender of qvalue MUST NOT generate more than three digits after the 1742 decimal point. User configuration of these values ought to be 1743 limited in the same fashion. 1745 5.3.2. Accept 1747 The "Accept" header field can be used by user agents to specify 1748 response media types that are acceptable. Accept header fields can 1749 be used to indicate that the request is specifically limited to a 1750 small set of desired types, as in the case of a request for an in- 1751 line image. 1753 Accept = #( media-range [ accept-params ] ) 1755 media-range = ( "*/*" 1756 / ( type "/" "*" ) 1757 / ( type "/" subtype ) 1758 ) *( OWS ";" OWS parameter ) 1759 accept-params = weight *( accept-ext ) 1760 accept-ext = OWS ";" OWS token [ "=" word ] 1762 The asterisk "*" character is used to group media types into ranges, 1763 with "*/*" indicating all media types and "type/*" indicating all 1764 subtypes of that type. The media-range can include media type 1765 parameters that are applicable to that range. 1767 Each media-range might be followed by zero or more applicable media 1768 type parameters (e.g., charset), an optional "q" parameter for 1769 indicating a relative weight (Section 5.3.1), and then zero or more 1770 extension parameters. The "q" parameter is necessary if any accept- 1771 ext are present, since it acts as a separator between the two 1772 parameter sets. 1774 Note: Use of the "q" parameter name to separate media type 1775 parameters from Accept extension parameters is due to historical 1776 practice. Although this prevents any media type parameter named 1777 "q" from being used with a media range, such an event is believed 1778 to be unlikely given the lack of any "q" parameters in the IANA 1779 media type registry and the rare usage of any media type 1780 parameters in Accept. Future media types are discouraged from 1781 registering any parameter named "q". 1783 The example 1785 Accept: audio/*; q=0.2, audio/basic 1787 SHOULD be interpreted as "I prefer audio/basic, but send me any audio 1788 type if it is the best available after an 80% mark-down in quality". 1790 A request without any Accept header field implies that the user agent 1791 will accept any media type in response. If an Accept header field is 1792 present in a request and none of the available representations for 1793 the response have a media type that is listed as acceptable, the 1794 origin server MAY either honor the Accept header field by sending a 1795 406 (Not Acceptable) response or disregard the Accept header field by 1796 treating the response as if it is not subject to content negotiation. 1798 A more elaborate example is 1800 Accept: text/plain; q=0.5, text/html, 1801 text/x-dvi; q=0.8, text/x-c 1803 Verbally, this would be interpreted as "text/html and text/x-c are 1804 the equally preferred media types, but if they do not exist, then 1805 send the text/x-dvi representation, and if that does not exist, send 1806 the text/plain representation". 1808 Media ranges can be overridden by more specific media ranges or 1809 specific media types. If more than one media range applies to a 1810 given type, the most specific reference has precedence. For example, 1812 Accept: text/*, text/plain, text/plain;format=flowed, */* 1814 have the following precedence: 1816 1. text/plain;format=flowed 1818 2. text/plain 1820 3. text/* 1822 4. */* 1824 The media type quality factor associated with a given type is 1825 determined by finding the media range with the highest precedence 1826 that matches the type. For example, 1828 Accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1, 1829 text/html;level=2;q=0.4, */*;q=0.5 1831 would cause the following values to be associated: 1833 +-------------------+---------------+ 1834 | Media Type | Quality Value | 1835 +-------------------+---------------+ 1836 | text/html;level=1 | 1 | 1837 | text/html | 0.7 | 1838 | text/plain | 0.3 | 1839 | image/jpeg | 0.5 | 1840 | text/html;level=2 | 0.4 | 1841 | text/html;level=3 | 0.7 | 1842 +-------------------+---------------+ 1844 Note: A user agent might be provided with a default set of quality 1845 values for certain media ranges. However, unless the user agent is a 1846 closed system that cannot interact with other rendering agents, this 1847 default set ought to be configurable by the user. 1849 5.3.3. Accept-Charset 1851 The "Accept-Charset" header field can be sent by a user agent to 1852 indicate what charsets are acceptable in textual response content. 1853 This field allows user agents capable of understanding more 1854 comprehensive or special-purpose charsets to signal that capability 1855 to an origin server that is capable of representing information in 1856 those charsets. 1858 Accept-Charset = 1#( ( charset / "*" ) [ weight ] ) 1860 Charset names are defined in Section 3.1.1.2. A user agent MAY 1861 associate a quality value with each charset to indicate the user's 1862 relative preference for that charset, as defined in Section 5.3.1. 1863 An example is 1865 Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 1867 The special value "*", if present in the Accept-Charset field, 1868 matches every charset that is not mentioned elsewhere in the Accept- 1869 Charset field. If no "*" is present in an Accept-Charset field, then 1870 any charsets not explicitly mentioned in the field are considered 1871 "not acceptable" to the client. 1873 A request without any Accept-Charset header field implies that the 1874 user agent will accept any charset in response. Most general-purpose 1875 user agents do not send Accept-Charset, unless specifically 1876 configured to do so, because a detailed list of supported charsets 1877 makes it easier for a server to identify an individual by virtue of 1878 the user agent's request characteristics (Section 9.6). 1880 If an Accept-Charset header field is present in a request and none of 1881 the available representations for the response has a charset that is 1882 listed as acceptable, the origin server MAY either honor the Accept- 1883 Charset header field, by sending a 406 (Not Acceptable) response, or 1884 disregard the Accept-Charset header field by treating the resource as 1885 if it is not subject to content negotiation. 1887 5.3.4. Accept-Encoding 1889 The "Accept-Encoding" header field can be used by user agents to 1890 indicate what response content-codings (Section 3.1.2.1) are 1891 acceptable in the response. An "identity" token is used as a synonym 1892 for "no encoding" in order to communicate when no encoding is 1893 preferred. 1895 Accept-Encoding = #( codings [ weight ] ) 1896 codings = content-coding / "identity" / "*" 1898 Each codings value MAY be given an associated quality value 1899 representing the preference for that encoding, as defined in 1900 Section 5.3.1. The asterisk "*" symbol in an Accept-Encoding field 1901 matches any available content-coding not explicitly listed in the 1902 header field. 1904 For example, 1906 Accept-Encoding: compress, gzip 1907 Accept-Encoding: 1908 Accept-Encoding: * 1909 Accept-Encoding: compress;q=0.5, gzip;q=1.0 1910 Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0 1912 A request without an Accept-Encoding header field implies that the 1913 user agent has no preferences regarding content-codings. Although 1914 this allows the server to use any content-coding in a response, it 1915 does not imply that the user agent will be able to correctly process 1916 all encodings. 1918 A server tests whether a content-coding for a given representation is 1919 acceptable using these rules: 1921 1. If no Accept-Encoding field is in the request, any content-coding 1922 is considered acceptable by the user agent. 1924 2. If the representation has no content-coding, then it is 1925 acceptable by default unless specifically excluded by the Accept- 1926 Encoding field stating either "identity;q=0" or "*;q=0" without a 1927 more specific entry for "identity". 1929 3. If the representation's content-coding is one of the content- 1930 codings listed in the Accept-Encoding field, then it is 1931 acceptable unless it is accompanied by a qvalue of 0. (As 1932 defined in Section 5.3.1, a qvalue of 0 means "not acceptable".) 1934 4. If multiple content-codings are acceptable, then the acceptable 1935 content-coding with the highest non-zero qvalue is preferred. 1937 An Accept-Encoding header field with a combined field-value that is 1938 empty implies that the user agent does not want any content-coding in 1939 response. If an Accept-Encoding header field is present in a request 1940 and none of the available representations for the response have a 1941 content-coding that is listed as acceptable, the origin server SHOULD 1942 send a response without any content-coding. 1944 Note: Most HTTP/1.0 applications do not recognize or obey qvalues 1945 associated with content-codings. This means that qvalues might 1946 not work and are not permitted with x-gzip or x-compress. 1948 5.3.5. Accept-Language 1950 The "Accept-Language" header field can be used by user agents to 1951 indicate the set of natural languages that are preferred in the 1952 response. Language tags are defined in Section 3.1.3.1. 1954 Accept-Language = 1#( language-range [ weight ] ) 1955 language-range = 1956 1958 Each language-range can be given an associated quality value 1959 representing an estimate of the user's preference for the languages 1960 specified by that range, as defined in Section 5.3.1. For example, 1962 Accept-Language: da, en-gb;q=0.8, en;q=0.7 1964 would mean: "I prefer Danish, but will accept British English and 1965 other types of English". 1967 Note that some recipients treat the order in which language tags are 1968 listed as an indication of descending priority, particularly for tags 1969 that are assigned equal quality values (no value is the same as q=1). 1970 However, this behavior cannot be relied upon. For consistency and to 1971 maximize interoperability, many user agents assign each language tag 1972 a unique quality value while also listing them in order of decreasing 1973 quality. Additional discussion of language priority lists can be 1974 found in Section 2.3 of [RFC4647]. 1976 For matching, Section 3 of [RFC4647] defines several matching 1977 schemes. Implementations can offer the most appropriate matching 1978 scheme for their requirements. The "Basic Filtering" scheme 1979 ([RFC4647], Section 3.3.1) is identical to the matching scheme that 1980 was previously defined for HTTP in Section 14.4 of [RFC2616]. 1982 It might be contrary to the privacy expectations of the user to send 1983 an Accept-Language header field with the complete linguistic 1984 preferences of the user in every request (Section 9.6). 1986 Since intelligibility is highly dependent on the individual user, 1987 user agents need to allow user control over the linguistic 1988 preference. A user agent that does not provide such control to the 1989 user MUST NOT send an Accept-Language header field. 1991 Note: User agents ought to provide guidance to users when setting 1992 a preference, since users are rarely familiar with the details of 1993 language matching as described above. For example, users might 1994 assume that on selecting "en-gb", they will be served any kind of 1995 English document if British English is not available. A user 1996 agent might suggest, in such a case, to add "en" to the list for 1997 better matching behavior. 1999 5.4. Authentication Credentials 2001 Two header fields are used for carrying authentication credentials, 2002 as defined in [Part7]. Note that various custom mechanisms for user 2003 authentication use the Cookie header field for this purpose, as 2004 defined in [RFC6265]. 2006 +---------------------+------------------------+ 2007 | Header Field Name | Defined in... | 2008 +---------------------+------------------------+ 2009 | Authorization | Section 4.1 of [Part7] | 2010 | Proxy-Authorization | Section 4.3 of [Part7] | 2011 +---------------------+------------------------+ 2013 5.5. Request Context 2015 The following request header fields provide additional information 2016 about the request context, including information about the user, user 2017 agent, and resource behind the request. 2019 +-------------------+---------------+ 2020 | Header Field Name | Defined in... | 2021 +-------------------+---------------+ 2022 | From | Section 5.5.1 | 2023 | Referer | Section 5.5.2 | 2024 | User-Agent | Section 5.5.3 | 2025 +-------------------+---------------+ 2027 5.5.1. From 2029 The "From" header field contains an Internet email address for a 2030 human user who controls the requesting user agent. The address ought 2031 to be machine-usable, as defined by "mailbox" in Section 3.4 of 2032 [RFC5322]: 2034 From = mailbox 2036 mailbox = 2038 An example is: 2040 From: webmaster@example.org 2042 The From header field is rarely sent by non-robotic user agents. A 2043 user agent SHOULD NOT send a From header field without explicit 2044 configuration by the user, since that might conflict with the user's 2045 privacy interests or their site's security policy. 2047 Robotic user agents SHOULD send a valid From header field so that the 2048 person responsible for running the robot can be contacted if problems 2049 occur on servers, such as if the robot is sending excessive, 2050 unwanted, or invalid requests. 2052 Servers SHOULD NOT use the From header field for access control or 2053 authentication, since most recipients will assume that the field 2054 value is public information. 2056 5.5.2. Referer 2058 The "Referer" [sic] header field allows the user agent to specify a 2059 URI reference for the resource from which the target URI was obtained 2060 (i.e., the "referrer", though the field name is misspelled). A user 2061 agent MUST exclude any fragment or userinfo components [RFC3986] when 2062 generating the Referer field value. 2064 Referer = absolute-URI / partial-URI 2066 Referer allows servers to generate back-links to other resources for 2067 simple analytics, logging, optimized caching, etc. It also allows 2068 obsolete or mistyped links to be found for maintenance. Some servers 2069 use Referer as a means of denying links from other sites (so-called 2070 "deep linking") or restricting cross-site request forgery (CSRF), but 2071 not all requests contain a Referer header field. 2073 Example: 2075 Referer: http://www.example.org/hypertext/Overview.html 2077 If the target URI was obtained from a source that does not have its 2078 own URI (e.g., input from the user keyboard, or an entry within the 2079 user's bookmarks/favorites), the user agent MUST either exclude 2080 Referer or send it with a value of "about:blank". 2082 The Referer field has the potential to reveal information about the 2083 request context or browsing history of the user, which is a privacy 2084 concern if the referring resource's identifier reveals personal 2085 information (such as an account name) or a resource that is supposed 2086 to be confidential (such as behind a firewall or internal to a 2087 secured service). Most general-purpose user agents do not send the 2088 Referer header field when the referring resource is a local "file" or 2089 "data" URI. A user agent SHOULD NOT send a Referer header field in 2090 an unsecured HTTP request if the referring page was received with a 2091 secure protocol. See Section 9.3 for additional security 2092 considerations. 2094 Some intermediaries have been known to indiscriminately remove 2095 Referer header fields from outgoing requests. This has the 2096 unfortunate side-effect of interfering with protection against CSRF 2097 attacks, which can be far more harmful to their users. 2098 Intermediaries and user agent extensions that wish to limit 2099 information disclosure in Referer ought to restrict their changes to 2100 specific edits, such as replacing internal domain names with 2101 pseudonyms or truncating the query and/or path components. 2102 Intermediaries SHOULD NOT modify or delete the Referer field when the 2103 field value shares the same scheme and host as the request target. 2105 5.5.3. User-Agent 2107 The "User-Agent" header field contains information about the user 2108 agent originating the request, which is often used by servers to help 2109 identify the scope of reported interoperability problems, to work 2110 around or tailor responses to avoid particular user agent 2111 limitations, and for analytics regarding browser or operating system 2112 use. A user agent SHOULD send a User-Agent field in each request 2113 unless specifically configured not to do so. 2115 User-Agent = product *( RWS ( product / comment ) ) 2117 The User-Agent field-value consists of one or more product 2118 identifiers, each followed by zero or more comments (Section 3.2 of 2119 [Part1]), which together identify the user agent software and its 2120 significant subproducts. By convention, the product identifiers are 2121 listed in decreasing order of their significance for identifying the 2122 user agent software. Each product identifier consists of a name and 2123 optional version. 2125 product = token ["/" product-version] 2126 product-version = token 2128 Senders SHOULD limit generated product identifiers to what is 2129 necessary to identify the product; senders MUST NOT generate 2130 advertising or other non-essential information within the product 2131 identifier. Senders SHOULD NOT generate information in product- 2132 version that is not a version identifier (i.e., successive versions 2133 of the same product name ought to only differ in the product-version 2134 portion of the product identifier). 2136 Example: 2138 User-Agent: CERN-LineMode/2.15 libwww/2.17b3 2140 A user agent SHOULD NOT generate a User-Agent field containing 2141 needlessly fine-grained detail and SHOULD limit the addition of 2142 subproducts by third parties. Overly long and detailed User-Agent 2143 field values increase request latency and the risk of a user being 2144 identified against their wishes ("fingerprinting"). 2146 Likewise, implementations are encouraged not to use the product 2147 tokens of other implementations in order to declare compatibility 2148 with them, as this circumvents the purpose of the field. If a user 2149 agent masquerades as a different user agent, recipients can assume 2150 that the user intentionally desires to see responses tailored for 2151 that identified user agent, even if they might not work as well for 2152 the actual user agent being used. 2154 6. Response Status Codes 2156 The status-code element is a 3-digit integer code giving the result 2157 of the attempt to understand and satisfy the request. 2159 HTTP status codes are extensible. HTTP clients are not required to 2160 understand the meaning of all registered status codes, though such 2161 understanding is obviously desirable. However, clients MUST 2162 understand the class of any status code, as indicated by the first 2163 digit, and treat an unrecognized status code as being equivalent to 2164 the x00 status code of that class, with the exception that a response 2165 with an unrecognized status code MUST NOT be cached. 2167 For example, if an unrecognized status code of 471 is received by a 2168 client, the client can assume that there was something wrong with its 2169 request and treat the response as if it had received a 400 status 2170 code. The response message will usually contain a representation 2171 that explains the status. 2173 The first digit of the status-code defines the class of response. 2174 The last two digits do not have any categorization role. There are 5 2175 values for the first digit: 2177 o 1xx (Informational): The request was received, continuing process 2179 o 2xx (Successful): The request was successfully received, 2180 understood, and accepted 2182 o 3xx (Redirection): Further action needs to be taken in order to 2183 complete the request 2185 o 4xx (Client Error): The request contains bad syntax or cannot be 2186 fulfilled 2188 o 5xx (Server Error): The server failed to fulfill an apparently 2189 valid request 2191 6.1. Overview of Status Codes 2193 The status codes listed below are defined in this specification, 2194 Section 4 of [Part4], Section 4 of [Part5], and Section 3 of [Part7]. 2195 The reason phrases listed here are only recommendations -- they can 2196 be replaced by local equivalents without affecting the protocol. 2198 +------+-------------------------------+------------------------+ 2199 | code | reason-phrase | Defined in... | 2200 +------+-------------------------------+------------------------+ 2201 | 100 | Continue | Section 6.2.1 | 2202 | 101 | Switching Protocols | Section 6.2.2 | 2203 | 200 | OK | Section 6.3.1 | 2204 | 201 | Created | Section 6.3.2 | 2205 | 202 | Accepted | Section 6.3.3 | 2206 | 203 | Non-Authoritative Information | Section 6.3.4 | 2207 | 204 | No Content | Section 6.3.5 | 2208 | 205 | Reset Content | Section 6.3.6 | 2209 | 206 | Partial Content | Section 4.1 of [Part5] | 2210 | 300 | Multiple Choices | Section 6.4.1 | 2211 | 301 | Moved Permanently | Section 6.4.2 | 2212 | 302 | Found | Section 6.4.3 | 2213 | 303 | See Other | Section 6.4.4 | 2214 | 304 | Not Modified | Section 4.1 of [Part4] | 2215 | 305 | Use Proxy | Section 6.4.5 | 2216 | 307 | Temporary Redirect | Section 6.4.7 | 2217 | 400 | Bad Request | Section 6.5.1 | 2218 | 401 | Unauthorized | Section 3.1 of [Part7] | 2219 | 402 | Payment Required | Section 6.5.2 | 2220 | 403 | Forbidden | Section 6.5.3 | 2221 | 404 | Not Found | Section 6.5.4 | 2222 | 405 | Method Not Allowed | Section 6.5.5 | 2223 | 406 | Not Acceptable | Section 6.5.6 | 2224 | 407 | Proxy Authentication Required | Section 3.2 of [Part7] | 2225 | 408 | Request Time-out | Section 6.5.7 | 2226 | 409 | Conflict | Section 6.5.8 | 2227 | 410 | Gone | Section 6.5.9 | 2228 | 411 | Length Required | Section 6.5.10 | 2229 | 412 | Precondition Failed | Section 4.2 of [Part4] | 2230 | 413 | Payload Too Large | Section 6.5.11 | 2231 | 414 | URI Too Long | Section 6.5.12 | 2232 | 415 | Unsupported Media Type | Section 6.5.13 | 2233 | 416 | Range Not Satisfiable | Section 4.4 of [Part5] | 2234 | 417 | Expectation Failed | Section 6.5.14 | 2235 | 426 | Upgrade Required | Section 6.5.15 | 2236 | 500 | Internal Server Error | Section 6.6.1 | 2237 | 501 | Not Implemented | Section 6.6.2 | 2238 | 502 | Bad Gateway | Section 6.6.3 | 2239 | 503 | Service Unavailable | Section 6.6.4 | 2240 | 504 | Gateway Time-out | Section 6.6.5 | 2241 | 505 | HTTP Version Not Supported | Section 6.6.6 | 2242 +------+-------------------------------+------------------------+ 2244 Note that this list is not exhaustive -- it does not include 2245 extension status codes defined in other specifications. 2247 Responses with status codes that are defined as cacheable by default 2248 (e.g., 200, 203, 206, 300, 301, and 410 in this specification) can be 2249 reused by a cache with heuristic expiration unless otherwise 2250 indicated by the method definition or explicit cache controls 2251 [Part6]; all other status codes are not cacheable by default. 2253 6.2. Informational 1xx 2255 The 1xx (Informational) class of status code indicates an interim 2256 response for communicating connection status or request progress 2257 prior to completing the requested action and sending a final 2258 response. All 1xx responses consist of only the status-line and 2259 optional header fields, and thus are terminated by the empty line at 2260 the end of the header block. Since HTTP/1.0 did not define any 1xx 2261 status codes, servers MUST NOT send a 1xx response to an HTTP/1.0 2262 client except under experimental conditions. 2264 A client MUST be prepared to accept one or more 1xx status responses 2265 prior to a final response, even if the client does not expect one. A 2266 user agent MAY ignore unexpected 1xx status responses. 2268 Proxies MUST forward 1xx responses, unless the connection between the 2269 proxy and its client has been closed, or unless the proxy itself 2270 requested the generation of the 1xx response. For example, if a 2271 proxy adds an "Expect: 100-continue" field when it forwards a 2272 request, then it need not forward the corresponding 100 (Continue) 2273 response(s). 2275 6.2.1. 100 Continue 2277 The 100 (Continue) status code indicates that the initial part of a 2278 request has been received and has not yet been rejected by the 2279 server. The server intends to send a final response after the 2280 request has been fully received and acted upon. 2282 When the request contains an Expect header field that includes a 100- 2283 continue expectation, the 100 response indicates that the server 2284 wishes to receive the request payload body, as described in 2285 Section 5.1.1.1. The client ought to continue sending the request 2286 and discard the 100 response. 2288 If the request did not contain an Expect header field containing the 2289 100-continue expectation, the client can simply discard this interim 2290 response. 2292 6.2.2. 101 Switching Protocols 2294 The 101 (Switching Protocols) status code indicates that the server 2295 understands and is willing to comply with the client's request, via 2296 the Upgrade header field (Section 6.7 of [Part1]), for a change in 2297 the application protocol being used on this connection. The server 2298 MUST generate an Upgrade header field in the response that indicates 2299 which protocol(s) will be switched to immediately after the empty 2300 line that terminates the 101 response. 2302 It is assumed that the server will only agree to switch protocols 2303 when it is advantageous to do so. For example, switching to a newer 2304 version of HTTP might be advantageous over older versions, and 2305 switching to a real-time, synchronous protocol might be advantageous 2306 when delivering resources that use such features. 2308 6.3. Successful 2xx 2310 The 2xx (Successful) class of status code indicates that the client's 2311 request was successfully received, understood, and accepted. 2313 6.3.1. 200 OK 2315 The 2316 200 (OK) status code indicates that the request has succeeded. The 2317 payload sent in a 200 response depends on the request method. For 2318 the methods defined by this specification, the intended meaning of 2319 the payload can be summarized as: 2321 GET a representation of the target resource; 2323 HEAD the same representation as GET, but without the representation 2324 data; 2326 POST a representation of the status of, or results obtained from, 2327 the action; 2329 PUT, DELETE a representation of the status of the action; 2331 OPTIONS a representation of the communications options; 2333 TRACE a representation of the request message as received by the end 2334 server. 2336 Aside from responses to CONNECT, a 200 response always has a payload, 2337 though an origin server MAY generate a payload body of zero length. 2338 If no payload is desired, an origin server ought to send 204 (No 2339 Content) instead. For CONNECT, no payload is allowed because the 2340 successful result is a tunnel, which begins immediately after the 200 2341 response header block. 2343 A 200 response is cacheable unless otherwise indicated by the method 2344 definition or explicit cache controls (see Section 4.1.2 of [Part6]). 2346 6.3.2. 201 Created 2348 The 201 (Created) status code indicates that the request has been 2349 fulfilled and has resulted in one or more new resources being 2350 created. The primary resource created by the request is identified 2351 by either a Location header field in the response or, if no Location 2352 field is received, by the effective request URI. 2354 The 201 response payload typically describes and links to the 2355 resource(s) created. See Section 7.2 for a discussion of the meaning 2356 and purpose of validator header fields, such as ETag and Last- 2357 Modified, in a 201 response. 2359 6.3.3. 202 Accepted 2361 The 202 (Accepted) status code indicates that the request has been 2362 accepted for processing, but the processing has not been completed. 2363 The request might or might not eventually be acted upon, as it might 2364 be disallowed when processing actually takes place. There is no 2365 facility in HTTP for re-sending a status code from an asynchronous 2366 operation. 2368 The 202 response is intentionally non-committal. Its purpose is to 2369 allow a server to accept a request for some other process (perhaps a 2370 batch-oriented process that is only run once per day) without 2371 requiring that the user agent's connection to the server persist 2372 until the process is completed. The representation sent with this 2373 response ought to describe the request's current status and point to 2374 (or embed) a status monitor that can provide the user with an 2375 estimate of when the request will be fulfilled. 2377 6.3.4. 203 Non-Authoritative Information 2379 The 203 (Non-Authoritative Information) status code indicates that 2380 the request was successful but the enclosed payload has been modified 2381 from that of the origin server's 200 (OK) response by a transforming 2382 proxy (Section 5.7.2 of [Part1]). This status code allows the proxy 2383 to notify recipients when a transformation has been applied, since 2384 that knowledge might impact later decisions regarding the content. 2385 For example, future cache validation requests for the content might 2386 only be applicable along the same request path (through the same 2387 proxies). 2389 The 203 response is similar to the Warning code of 214 Transformation 2390 Applied (Section 7.5 of [Part6]), which has the advantage of being 2391 applicable to responses with any status code. 2393 A 203 response is cacheable unless otherwise indicated by the method 2394 definition or explicit cache controls (see Section 4.1.2 of [Part6]). 2396 6.3.5. 204 No Content 2398 The 204 (No Content) status code indicates that the server has 2399 successfully fulfilled the request and that there is no additional 2400 content to send in the response payload body. Metadata in the 2401 response header fields refer to the target resource and its selected 2402 representation after the requested action was applied. 2404 For example, if a 204 status code is received in response to a PUT 2405 request and the response contains an ETag header field, then the PUT 2406 was successful and the ETag field-value contains the entity-tag for 2407 the new representation of that target resource. 2409 The 204 response allows a server to indicate that the action has been 2410 successfully applied to the target resource, while implying that the 2411 user agent does not need to traverse away from its current "document 2412 view" (if any). The server assumes that the user agent will provide 2413 some indication of the success to its user, in accord with its own 2414 interface, and apply any new or updated metadata in the response to 2415 its active representation. 2417 For example, a 204 status code is commonly used with document editing 2418 interfaces corresponding to a "save" action, such that the document 2419 being saved remains available to the user for editing. It is also 2420 frequently used with interfaces that expect automated data transfers 2421 to be prevalent, such as within distributed version control systems. 2423 A 204 response is terminated by the first empty line after the header 2424 fields because it cannot contain a message body. 2426 A 204 response is cacheable unless otherwise indicated by the method 2427 definition or explicit cache controls (see Section 4.1.2 of [Part6]). 2429 6.3.6. 205 Reset Content 2431 The 205 (Reset Content) status code indicates that the server has 2432 fulfilled the request and desires that the user agent reset the 2433 "document view", which caused the request to be sent, to its original 2434 state as received from the origin server. 2436 This response is intended to support a common data entry use case 2437 where the user receives content that supports data entry (a form, 2438 notepad, canvas, etc.), enters or manipulates data in that space, 2439 causes the entered data to be submitted in a request, and then the 2440 data entry mechanism is reset for the next entry so that the user can 2441 easily initiate another input action. 2443 Since the 205 status code implies that no additional content will be 2444 provided in the payload, the server MUST send a message body of zero 2445 length. In other words, the server MUST send a "Content-Length: 0" 2446 field in a 205 response or close the connection immediately after 2447 sending the blank line terminating the header section. 2449 6.4. Redirection 3xx 2451 The 3xx (Redirection) class of status code indicates that further 2452 action needs to be taken by the user agent in order to fulfill the 2453 request. If a Location header field (Section 7.1.2) is provided, the 2454 user agent MAY automatically redirect its request to the URI 2455 referenced by the Location field value, even if the specific status 2456 code is not understood. Automatic redirection needs to done with 2457 care for methods not known to be safe, as defined in Section 4.2.1, 2458 since the user might not wish to redirect an unsafe request. 2460 There are several types of redirects: 2462 1. Redirects that indicate the resource might be available at a 2463 different URI, as provided by the Location field, as in the 2464 status codes 301 (Moved Permanently), 302 (Found), and 307 2465 (Temporary Redirect). 2467 2. Redirection that offers a choice of matching resources, each 2468 capable of representing the original request target, as in the 2469 300 (Multiple Choices) status code. 2471 3. Redirection to a different resource, identified by the Location 2472 field, that can represent an indirect response to the request, as 2473 in the 303 (See Other) status code. 2475 4. Redirection to a previously cached result, as in the 304 (Not 2476 Modified) status code. 2478 Note: In HTTP/1.0, the status codes 301 (Moved Permanently) and 2479 302 (Found) were defined for the first type of redirect 2480 ([RFC1945], Section 9.3). Early user agents split on whether the 2481 method applied to the redirect target would be the same as the 2482 original request or would be rewritten as GET. Although HTTP 2483 originally defined the former semantics for 301 and 302 (to match 2484 its original implementation at CERN), and defined 303 (See Other) 2485 to match the latter semantics, prevailing practice gradually 2486 converged on the latter semantics for 301 and 302 as well. The 2487 first revision of HTTP/1.1 added 307 (Temporary Redirect) to 2488 indicate the former semantics without being impacted by divergent 2489 practice. Over 10 years later, most user agents still do method 2490 rewriting for 301 and 302; therefore, this specification makes 2491 that behavior conformant when the original request is POST. 2493 Clients SHOULD detect and intervene in cyclical redirections (i.e., 2494 "infinite" redirection loops). 2496 Note: An earlier version of this specification recommended a 2497 maximum of five redirections ([RFC2068], Section 10.3). Content 2498 developers need to be aware that some clients might implement such 2499 a fixed limitation. 2501 6.4.1. 300 Multiple Choices 2503 The 300 (Multiple Choices) status code indicates that the target 2504 resource has more than one representation, each with its own more 2505 specific identifier, and information about the alternatives is being 2506 provided so that the user (or user agent) can select a preferred 2507 representation by redirecting its request to one or more of those 2508 identifiers. In other words, the server desires that the user agent 2509 engage in reactive negotiation to select the most appropriate 2510 representation(s) for its needs (Section 3.4). 2512 If the server has a preferred choice, the server SHOULD generate a 2513 Location header field containing a preferred choice's URI reference. 2514 The user agent MAY use the Location field value for automatic 2515 redirection. 2517 For request methods other than HEAD, the server SHOULD generate a 2518 payload in the 300 response containing a list of representation 2519 metadata and URI reference(s) from which the user or user agent can 2520 choose the one most preferred. The user agent MAY make a selection 2521 from that list automatically, depending upon the list format, but 2522 this specification does not define a standard for such automatic 2523 selection. 2525 A 300 response is cacheable unless otherwise indicated by the method 2526 definition or explicit cache controls (see Section 4.1.2 of [Part6]). 2528 Note: The original proposal for 300 defined the URI header field 2529 as providing a list of alternative representations, such that it 2530 would be usable for 200, 300, and 406 responses and be transferred 2531 in responses to the HEAD method. However, lack of deployment and 2532 disagreement over syntax led to both URI and Alternates (a 2533 subsequent proposal) being dropped from this specification. It is 2534 possible to communicate the list using a set of Link header fields 2535 [RFC5988], each with a relationship of "alternate", though 2536 deployment is a chicken-and-egg problem. 2538 6.4.2. 301 Moved Permanently 2540 The 301 (Moved Permanently) status code indicates that the target 2541 resource has been assigned a new permanent URI and any future 2542 references to this resource ought to use one of the enclosed URIs. 2543 Clients with link editing capabilities ought to automatically re-link 2544 references to the effective request URI to one or more of the new 2545 references sent by the server, where possible. 2547 The server SHOULD generate a Location header field in the response 2548 containing a preferred URI reference for the new permanent URI. The 2549 user agent MAY use the Location field value for automatic 2550 redirection. The server's response payload usually contains a short 2551 hypertext note with a hyperlink to the new URI(s). 2553 Note: For historic reasons, user agents MAY change the request 2554 method from POST to GET for the subsequent request. If this 2555 behavior is undesired, status code 307 (Temporary Redirect) can be 2556 used instead. 2558 A 301 response is cacheable unless otherwise indicated by the method 2559 definition or explicit cache controls (see Section 4.1.2 of [Part6]). 2561 6.4.3. 302 Found 2563 The 302 (Found) status code indicates that the target resource 2564 resides temporarily under a different URI. Since the redirection 2565 might be altered on occasion, the client ought to continue to use the 2566 effective request URI for future requests. 2568 The server SHOULD generate a Location header field in the response 2569 containing a URI reference for the different URI. The user agent MAY 2570 use the Location field value for automatic redirection. The server's 2571 response payload usually contains a short hypertext note with a 2572 hyperlink to the different URI(s). 2574 Note: For historic reasons, user agents MAY change the request 2575 method from POST to GET for the subsequent request. If this 2576 behavior is undesired, status code 307 (Temporary Redirect) can be 2577 used instead. 2579 6.4.4. 303 See Other 2581 The 303 (See Other) status code indicates that the server is 2582 redirecting the user agent to a different resource, as indicated by a 2583 URI in the Location header field, that is intended to provide an 2584 indirect response to the original request. In order to satisfy the 2585 original request, a user agent ought to perform a retrieval request 2586 using the Location URI (a GET or HEAD request if using HTTP), which 2587 can itself be redirected further, and present the eventual result as 2588 an answer to the original request. Note that the new URI in the 2589 Location header field is not considered equivalent to the effective 2590 request URI. 2592 This status code is applicable to any HTTP method. It is primarily 2593 used to allow the output of a POST action to redirect the user agent 2594 to a selected resource, since doing so provides the information 2595 corresponding to the POST response in a form that can be separately 2596 identified, bookmarked, and cached independent of the original 2597 request. 2599 A 303 response to a GET request indicates that the origin server does 2600 not have a representation of the target resource that can be 2601 transferred by the server over HTTP. However, the Location field 2602 value refers to a resource that is descriptive of the target 2603 resource, such that making a retrieval request on that other resource 2604 might result in a representation that is useful to recipients without 2605 implying that it represents the original target resource. Note that 2606 answers to the questions of what can be represented, what 2607 representations are adequate, and what might be a useful description 2608 are outside the scope of HTTP. 2610 Except for responses to a HEAD request, the representation of a 303 2611 response ought to contain a short hypertext note with a hyperlink to 2612 the same URI reference provided in the Location header field. 2614 6.4.5. 305 Use Proxy 2616 The 305 (Use Proxy) status code was defined in a previous version of 2617 this specification and is now deprecated (Appendix B). 2619 6.4.6. 306 (Unused) 2621 The 306 status code was defined in a previous version of this 2622 specification, is no longer used, and the code is reserved. 2624 6.4.7. 307 Temporary Redirect 2626 The 307 (Temporary Redirect) status code indicates that the target 2627 resource resides temporarily under a different URI and the user agent 2628 MUST NOT change the request method if it performs an automatic 2629 redirection to that URI. Since the redirection can change over time, 2630 the client ought to continue using the original effective request URI 2631 for future requests. 2633 The server SHOULD generate a Location header field in the response 2634 containing a URI reference for the different URI. The user agent MAY 2635 use the Location field value for automatic redirection. The server's 2636 response payload usually contains a short hypertext note with a 2637 hyperlink to the different URI(s). 2639 Note: This status code is similar to 302 (Found), except that it 2640 does not allow changing the request method from POST to GET. This 2641 specification defines no equivalent counterpart for 301 (Moved 2642 Permanently) ([status-308], however, defines the status code 308 2643 (Permanent Redirect) for this purpose). 2645 6.5. Client Error 4xx 2647 The 4xx (Client Error) class of status code indicates that the client 2648 seems to have erred. Except when responding to a HEAD request, the 2649 server SHOULD send a representation containing an explanation of the 2650 error situation, and whether it is a temporary or permanent 2651 condition. These status codes are applicable to any request method. 2652 User agents SHOULD display any included representation to the user. 2654 6.5.1. 400 Bad Request 2656 The 400 (Bad Request) status code indicates that the server cannot or 2657 will not process the request because the received syntax is invalid, 2658 nonsensical, or exceeds some limitation on what the server is willing 2659 to process. 2661 6.5.2. 402 Payment Required 2663 The 402 (Payment Required) status code is reserved for future use. 2665 6.5.3. 403 Forbidden 2667 The 403 (Forbidden) status code indicates that the server understood 2668 the request but refuses to authorize it. A server that wishes to 2669 make public why the request has been forbidden can describe that 2670 reason in the response payload (if any). 2672 If authentication credentials were provided in the request, the 2673 server considers them insufficient to grant access. The client 2674 SHOULD NOT repeat the request with the same credentials. The client 2675 MAY repeat the request with new or different credentials. However, a 2676 request might be forbidden for reasons unrelated to the credentials. 2678 An origin server that wishes to "hide" the current existence of a 2679 forbidden target resource MAY instead respond with a status code of 2680 404 (Not Found). 2682 6.5.4. 404 Not Found 2684 The 404 (Not Found) status code indicates that the origin server did 2685 not find a current representation for the target resource or is not 2686 willing to disclose that one exists. A 404 status does not indicate 2687 whether this lack of representation is temporary or permanent; the 2688 410 (Gone) status code is preferred over 404 if the origin server 2689 knows, presumably through some configurable means, that the condition 2690 is likely to be permanent. 2692 A 404 response is cacheable unless otherwise indicated by the method 2693 definition or explicit cache controls (see Section 4.1.2 of [Part6]). 2695 6.5.5. 405 Method Not Allowed 2697 The 405 (Method Not Allowed) status code indicates that the method 2698 specified in the request-line is known by the origin server but not 2699 supported by the target resource. The origin server MUST generate an 2700 Allow header field in a 405 response containing a list of the target 2701 resource's currently supported methods. 2703 A 405 response is cacheable unless otherwise indicated by the method 2704 definition or explicit cache controls (see Section 4.1.2 of [Part6]). 2706 6.5.6. 406 Not Acceptable 2708 The 406 (Not Acceptable) status code indicates that the target 2709 resource does not have a current representation that would be 2710 acceptable to the user agent, according to the proactive negotiation 2711 header fields received in the request (Section 5.3), and the server 2712 is unwilling to supply a default representation. 2714 The server SHOULD generate a payload containing a list of available 2715 representation characteristics and corresponding resource identifiers 2716 from which the user or user agent can choose the one most 2717 appropriate. A user agent MAY automatically select the most 2718 appropriate choice from that list. However, this specification does 2719 not define any standard for such automatic selection, as described in 2720 Section 6.4.1. 2722 6.5.7. 408 Request Timeout 2724 The 408 (Request Timeout) status code indicates that the server did 2725 not receive a complete request message within the time that it was 2726 prepared to wait. A server SHOULD send the close connection option 2727 (Section 6.1 of [Part1]) in the response, since 408 implies that the 2728 server has decided to close the connection rather than continue 2729 waiting. If the client has an outstanding request in transit, the 2730 client MAY repeat that request on a new connection. 2732 6.5.8. 409 Conflict 2734 The 409 (Conflict) status code indicates that the request could not 2735 be completed due to a conflict with the current state of the 2736 resource. This code is used in situations where the user might be 2737 able to resolve the conflict and resubmit the request. The server 2738 SHOULD generate a payload that includes enough information for a user 2739 to recognize the source of the conflict. 2741 Conflicts are most likely to occur in response to a PUT request. For 2742 example, if versioning were being used and the representation being 2743 PUT included changes to a resource that conflict with those made by 2744 an earlier (third-party) request, the origin server might use a 409 2745 response to indicate that it can't complete the request. In this 2746 case, the response representation would likely contain information 2747 useful for merging the differences based on the revision history. 2749 6.5.9. 410 Gone 2751 The 410 (Gone) status code indicates that access to the target 2752 resource is no longer available at the origin server and that this 2753 condition is likely to be permanent. If the origin server does not 2754 know, or has no facility to determine, whether or not the condition 2755 is permanent, the status code 404 (Not Found) ought to be used 2756 instead. 2758 The 410 response is primarily intended to assist the task of web 2759 maintenance by notifying the recipient that the resource is 2760 intentionally unavailable and that the server owners desire that 2761 remote links to that resource be removed. Such an event is common 2762 for limited-time, promotional services and for resources belonging to 2763 individuals no longer associated with the origin server's site. It 2764 is not necessary to mark all permanently unavailable resources as 2765 "gone" or to keep the mark for any length of time -- that is left to 2766 the discretion of the server owner. 2768 A 410 response is cacheable unless otherwise indicated by the method 2769 definition or explicit cache controls (see Section 4.1.2 of [Part6]). 2771 6.5.10. 411 Length Required 2773 The 411 (Length Required) status code indicates that the server 2774 refuses to accept the request without a defined Content-Length 2775 (Section 3.3.2 of [Part1]). The client MAY repeat the request if it 2776 adds a valid Content-Length header field containing the length of the 2777 message body in the request message. 2779 6.5.11. 413 Payload Too Large 2781 The 413 (Payload Too Large) status code indicates that the server is 2782 refusing to process a request because the request payload is larger 2783 than the server is willing or able to process. The server MAY close 2784 the connection to prevent the client from continuing the request. 2786 If the condition is temporary, the server SHOULD generate a Retry- 2787 After header field to indicate that it is temporary and after what 2788 time the client MAY try again. 2790 6.5.12. 414 URI Too Long 2792 The 414 (URI Too Long) status code indicates that the server is 2793 refusing to service the request because the request-target (Section 2794 5.3 of [Part1]) is longer than the server is willing to interpret. 2795 This rare condition is only likely to occur when a client has 2796 improperly converted a POST request to a GET request with long query 2797 information, when the client has descended into a "black hole" of 2798 redirection (e.g., a redirected URI prefix that points to a suffix of 2799 itself), or when the server is under attack by a client attempting to 2800 exploit potential security holes. 2802 A 414 response is cacheable unless otherwise indicated by the method 2803 definition or explicit cache controls (see Section 4.1.2 of [Part6]). 2805 6.5.13. 415 Unsupported Media Type 2807 The 415 (Unsupported Media Type) status code indicates that the 2808 origin server is refusing to service the request because the payload 2809 is in a format not supported by the target resource for this method. 2810 The format problem might be due to the request's indicated Content- 2811 Type or Content-Encoding, or as a result of inspecting the data 2812 directly. 2814 6.5.14. 417 Expectation Failed 2816 The 417 (Expectation Failed) status code indicates that the 2817 expectation given in the request's Expect header field 2818 (Section 5.1.1) could not be met by at least one of the inbound 2819 servers. 2821 6.5.15. 426 Upgrade Required 2823 The 426 (Upgrade Required) status code indicates that the server 2824 refuses to perform the request using the current protocol but might 2825 be willing to do so after the client upgrades to a different 2826 protocol. The server MUST send an Upgrade header field in a 426 2827 response to indicate the required protocol(s) (Section 6.7 of 2828 [Part1]). 2830 Example: 2832 HTTP/1.1 426 Upgrade Required 2833 Upgrade: HTTP/3.0 2834 Connection: Upgrade 2835 Content-Length: 53 2836 Content-Type: text/plain 2838 This service requires use of the HTTP/3.0 protocol. 2840 6.6. Server Error 5xx 2842 The 5xx (Server Error) class of status code indicates that the server 2843 is aware that it has erred or is incapable of performing the 2844 requested method. Except when responding to a HEAD request, the 2845 server SHOULD send a representation containing an explanation of the 2846 error situation, and whether it is a temporary or permanent 2847 condition. User agents SHOULD display any included representation to 2848 the user. These response codes are applicable to any request method. 2850 6.6.1. 500 Internal Server Error 2852 The 500 (Internal Server Error) status code indicates that the server 2853 encountered an unexpected condition that prevented it from fulfilling 2854 the request. 2856 6.6.2. 501 Not Implemented 2858 The 501 (Not Implemented) status code indicates that the server does 2859 not support the functionality required to fulfill the request. This 2860 is the appropriate response when the server does not recognize the 2861 request method and is not capable of supporting it for any resource. 2863 A 501 response is cacheable unless otherwise indicated by the method 2864 definition or explicit cache controls (see Section 4.1.2 of [Part6]). 2866 6.6.3. 502 Bad Gateway 2868 The 502 (Bad Gateway) status code indicates that the server, while 2869 acting as a gateway or proxy, received an invalid response from an 2870 inbound server it accessed while attempting to fulfill the request. 2872 6.6.4. 503 Service Unavailable 2874 The 503 (Service Unavailable) status code indicates that the server 2875 is currently unable to handle the request due to a temporary overload 2876 or scheduled maintenance, which will likely be alleviated after some 2877 delay. The server MAY send a Retry-After header field 2878 (Section 7.1.3) to suggest an appropriate amount of time for the 2879 client to wait before retrying the request. 2881 Note: The existence of the 503 status code does not imply that a 2882 server has to use it when becoming overloaded. Some servers might 2883 simply refuse the connection. 2885 6.6.5. 504 Gateway Timeout 2887 The 504 (Gateway Timeout) status code indicates that the server, 2888 while acting as a gateway or proxy, did not receive a timely response 2889 from an upstream server it needed to access in order to complete the 2890 request. 2892 6.6.6. 505 HTTP Version Not Supported 2894 The 505 (HTTP Version Not Supported) status code indicates that the 2895 server does not support, or refuses to support, the protocol version 2896 that was used in the request message. The server is indicating that 2897 it is unable or unwilling to complete the request using the same 2898 major version as the client, as described in Section 2.6 of [Part1], 2899 other than with this error message. The server SHOULD generate a 2900 representation for the 505 response that describes why that version 2901 is not supported and what other protocols are supported by that 2902 server. 2904 7. Response Header Fields 2906 The response header fields allow the server to pass additional 2907 information about the response beyond what is placed in the status- 2908 line. These header fields give information about the server, about 2909 further access to the target resource, or about related resources. 2911 Although each response header field has a defined meaning, in 2912 general, the precise semantics might be further refined by the 2913 semantics of the request method and/or response status code. 2915 7.1. Control Data 2917 Response header fields can supply control data that supplements the 2918 status code, directs caching, or instructs the client where to go 2919 next. 2921 +-------------------+------------------------+ 2922 | Header Field Name | Defined in... | 2923 +-------------------+------------------------+ 2924 | Age | Section 7.1 of [Part6] | 2925 | Cache-Control | Section 7.2 of [Part6] | 2926 | Expires | Section 7.3 of [Part6] | 2927 | Date | Section 7.1.1.2 | 2928 | Location | Section 7.1.2 | 2929 | Retry-After | Section 7.1.3 | 2930 | Vary | Section 7.1.4 | 2931 | Warning | Section 7.5 of [Part6] | 2932 +-------------------+------------------------+ 2934 7.1.1. Origination Date 2936 7.1.1.1. Date/Time Formats 2938 Prior to 1995, there were three different formats commonly used by 2939 servers to communicate timestamps. For compatibility with old 2940 implementations, all three are defined here. The preferred format is 2941 a fixed-length and single-zone subset of the date and time 2942 specification used by the Internet Message Format [RFC5322]. 2944 HTTP-date = IMF-fixdate / obs-date 2946 An example of the preferred format is 2948 Sun, 06 Nov 1994 08:49:37 GMT ; IMF-fixdate 2950 Examples of the two obsolete formats are 2952 Sunday, 06-Nov-94 08:49:37 GMT ; obsolete RFC 850 format 2953 Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format 2955 A recipient that parses a timestamp value in an HTTP header field 2956 MUST accept all three formats. A sender MUST generate the IMF- 2957 fixdate format when sending an HTTP-date value in a header field. 2959 An HTTP-date value represents time as an instance of Coordinated 2960 Universal Time (UTC). The first two formats indicate UTC by the 2961 three-letter abbreviation for Greenwich Mean Time, "GMT", a 2962 predecessor of the UTC name; values in the asctime format are assumed 2963 to be in UTC. A sender that generates HTTP-date values from a local 2964 clock ought to use NTP ([RFC1305]) or some similar protocol to 2965 synchronize its clock to UTC. 2967 Preferred format: 2969 IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT 2970 ; fixed length/zone subset of the format defined in 2971 ; Section 3.3 of [RFC5322] 2973 day-name = %x4D.6F.6E ; "Mon", case-sensitive 2974 / %x54.75.65 ; "Tue", case-sensitive 2975 / %x57.65.64 ; "Wed", case-sensitive 2976 / %x54.68.75 ; "Thu", case-sensitive 2977 / %x46.72.69 ; "Fri", case-sensitive 2978 / %x53.61.74 ; "Sat", case-sensitive 2979 / %x53.75.6E ; "Sun", case-sensitive 2981 date1 = day SP month SP year 2982 ; e.g., 02 Jun 1982 2984 day = 2DIGIT 2985 month = %x4A.61.6E ; "Jan", case-sensitive 2986 / %x46.65.62 ; "Feb", case-sensitive 2987 / %x4D.61.72 ; "Mar", case-sensitive 2988 / %x41.70.72 ; "Apr", case-sensitive 2989 / %x4D.61.79 ; "May", case-sensitive 2990 / %x4A.75.6E ; "Jun", case-sensitive 2991 / %x4A.75.6C ; "Jul", case-sensitive 2992 / %x41.75.67 ; "Aug", case-sensitive 2993 / %x53.65.70 ; "Sep", case-sensitive 2994 / %x4F.63.74 ; "Oct", case-sensitive 2995 / %x4E.6F.76 ; "Nov", case-sensitive 2996 / %x44.65.63 ; "Dec", case-sensitive 2997 year = 4DIGIT 2999 GMT = %x47.4D.54 ; "GMT", case-sensitive 3001 time-of-day = hour ":" minute ":" second 3002 ; 00:00:00 - 23:59:60 (leap second) 3004 hour = 2DIGIT 3005 minute = 2DIGIT 3006 second = 2DIGIT 3008 Obsolete formats: 3010 obs-date = rfc850-date / asctime-date 3012 rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT 3013 date2 = day "-" month "-" 2DIGIT 3014 ; e.g., 02-Jun-82 3016 day-name-l = %x4D.6F.6E.64.61.79 ; "Monday", case-sensitive 3017 / %x54.75.65.73.64.61.79 ; "Tuesday", case-sensitive 3018 / %x57.65.64.6E.65.73.64.61.79 ; "Wednesday", case-sensitive 3019 / %x54.68.75.72.73.64.61.79 ; "Thursday", case-sensitive 3020 / %x46.72.69.64.61.79 ; "Friday", case-sensitive 3021 / %x53.61.74.75.72.64.61.79 ; "Saturday", case-sensitive 3022 / %x53.75.6E.64.61.79 ; "Sunday", case-sensitive 3024 asctime-date = day-name SP date3 SP time-of-day SP year 3025 date3 = month SP ( 2DIGIT / ( SP 1DIGIT )) 3026 ; e.g., Jun 2 3028 HTTP-date is case sensitive. A sender MUST NOT generate additional 3029 whitespace in an HTTP-date beyond that specifically included as SP in 3030 the grammar. The semantics of day-name, day, month, year, and time- 3031 of-day are the same as those defined for the Internet Message Format 3032 constructs with the corresponding name ([RFC5322], Section 3.3). 3034 Recipients of a timestamp value in rfc850-date format, which uses a 3035 two-digit year, SHOULD interpret a timestamp that appears to be more 3036 than 50 years in the future as representing the most recent year in 3037 the past that had the same last two digits. 3039 Recipients of timestamp values are encouraged to be robust in parsing 3040 timestamps unless otherwise restricted by the field definition. For 3041 example, messages are occasionally forwarded over HTTP from a non- 3042 HTTP source that might generate any of the date and time 3043 specifications defined by the Internet Message Format. 3045 Note: HTTP requirements for the date/time stamp format apply only 3046 to their usage within the protocol stream. Implementations are 3047 not required to use these formats for user presentation, request 3048 logging, etc. 3050 7.1.1.2. Date 3052 The "Date" header field represents the date and time at which the 3053 message was originated, having the same semantics as the Origination 3054 Date Field (orig-date) defined in Section 3.6.1 of [RFC5322]. The 3055 field value is an HTTP-date, as defined in Section 7.1.1.1. 3057 Date = HTTP-date 3059 An example is 3061 Date: Tue, 15 Nov 1994 08:12:31 GMT 3063 When a Date header field is generated, the sender SHOULD generate its 3064 field value as the best available approximation of the date and time 3065 of message generation. In theory, the date ought to represent the 3066 moment just before the payload is generated. In practice, the date 3067 can be generated at any time during message origination. 3069 An origin server MUST NOT send a Date header field if it does not 3070 have a clock capable of providing a reasonable approximation of the 3071 current instance in Coordinated Universal Time. An origin server MAY 3072 send a Date header field if the response is in the 1xx 3073 (Informational) or 5xx (Server Error) class of status codes. An 3074 origin server MUST send a Date header field in all other cases. 3076 A recipient with a clock that receives a response message without a 3077 Date header field MUST record the time it was received and append a 3078 corresponding Date header field to the message's header block if it 3079 is cached or forwarded downstream. 3081 A user agent MAY send a Date header field in a request, though 3082 generally will not do so unless it is believed to convey useful 3083 information to the server. For example, custom applications of HTTP 3084 might convey a Date if the server is expected to adjust its 3085 interpretation of the user's request based on differences between the 3086 user agent and server clocks. 3088 7.1.2. Location 3090 The "Location" header field is used in some responses to refer to a 3091 specific resource in relation to the response. The type of 3092 relationship is defined by the combination of request method and 3093 status code semantics. 3095 Location = URI-reference 3097 The field value consists of a single URI-reference. When it has the 3098 form of a relative reference ([RFC3986], Section 4.2), the final 3099 value is computed by resolving it against the effective request URI 3100 ([RFC3986], Section 5). 3102 For 201 (Created) responses, the Location value refers to the primary 3103 resource created by the request. For 3xx (Redirection) responses, 3104 the Location value refers to the preferred target resource for 3105 automatically redirecting the request. 3107 When Location is provided in a 3xx (Redirection) response and the URI 3108 reference that the user agent used to generate the request target 3109 contains a fragment identifier, the user agent SHOULD process the 3110 redirection as if the Location field value inherits the original 3111 fragment. In other words, if the Location does not have a fragment 3112 component, the user agent SHOULD interpret the Location reference as 3113 if it had the original reference's fragment. 3115 For example, a GET request generated for the URI reference 3116 "http://www.example.org/~tim" might result in a 303 (See Other) 3117 response containing the header field: 3119 Location: /People.html#tim 3121 which suggests that the user agent redirect to 3122 "http://www.example.org/People.html#tim" 3124 Likewise, a GET request generated for the URI reference 3125 "http://www.example.org/index.html#larry" might result in a 301 3126 (Moved Permanently) response containing the header field: 3128 Location: http://www.example.net/index.html 3130 which suggests that the user agent redirect to 3131 "http://www.example.net/index.html#larry", preserving the original 3132 fragment identifier. 3134 There are circumstances in which a fragment identifier in a Location 3135 value would not be appropriate. For example, the Location header 3136 field in a 201 (Created) response is supposed to provide a URI that 3137 is specific to the created resource. 3139 Note: Some recipients attempt to recover from Location fields that 3140 are not valid URI references. This specification does not mandate 3141 or define such processing, but does allow it for the sake of 3142 robustness. 3144 Note: The Content-Location header field (Section 3.1.4.2) differs 3145 from Location in that the Content-Location refers to the most 3146 specific resource corresponding to the enclosed representation. 3147 It is therefore possible for a response to contain both the 3148 Location and Content-Location header fields. 3150 7.1.3. Retry-After 3152 Servers send the "Retry-After" header field to indicate how long the 3153 user agent ought to wait before making a follow-up request. When 3154 sent with a 503 (Service Unavailable) response, Retry-After indicates 3155 how long the service is expected to be unavailable to the client. 3156 When sent with any 3xx (Redirection) response, Retry-After indicates 3157 the minimum time that the user agent is asked to wait before issuing 3158 the redirected request. 3160 The value of this field can be either an HTTP-date or an integer 3161 number of seconds (in decimal) after the time of the response. 3163 Retry-After = HTTP-date / delta-seconds 3165 Time spans are non-negative decimal integers, representing time in 3166 seconds. 3168 delta-seconds = 1*DIGIT 3170 Two examples of its use are 3172 Retry-After: Fri, 31 Dec 1999 23:59:59 GMT 3173 Retry-After: 120 3175 In the latter example, the delay is 2 minutes. 3177 7.1.4. Vary 3179 The "Vary" header field describes what parts of a request message, 3180 aside from the method and request target, might influence the origin 3181 server's process for selecting and representing the response. The 3182 value consists of either a single asterisk ("*") or a list of header 3183 field names (case-insensitive). 3185 Vary = "*" / 1#field-name 3187 A Vary field value of "*" signals that anything about the request 3188 might play a role in selecting the response representation, possibly 3189 including elements outside the message syntax (e.g., the client's 3190 network address), and thus a recipient will not be able to determine 3191 whether this response is appropriate for a later request without 3192 forwarding the request to the origin server. A proxy MUST NOT 3193 generate a Vary field with a "*" value. 3195 A Vary field value consisting of a comma-separated list of names 3196 indicates that the named request header fields, known as the 3197 selecting header fields, might have a role in selecting the 3198 representation. The potential selecting header fields are not 3199 limited to those defined by this specification. 3201 For example, a response that contains 3203 Vary: accept-encoding, accept-language 3205 indicates that the origin server might have used the request's 3206 Accept-Encoding and Accept-Language fields (or lack thereof) as 3207 determining factors while choosing the content for this response. 3209 An origin server might send Vary with a list of fields for two 3210 purposes: 3212 1. To inform cache recipients that they MUST NOT use this response 3213 to satisfy a later request unless the later request has the same 3214 values for the listed fields as the original request (Section 4.3 3215 of [Part6]). In other words, Vary expands the cache key required 3216 to match a new request to the stored cache entry. 3218 2. To inform user agent recipients that this response is subject to 3219 content negotiation (Section 5.3) and that a different 3220 representation might be sent in a subsequent request if 3221 additional parameters are provided in the listed header fields 3222 (proactive negotiation). 3224 An origin server SHOULD send a Vary header field when its algorithm 3225 for selecting a representation varies based on aspects of the request 3226 message other than the method and request target, unless the variance 3227 cannot be crossed or the origin server has been deliberately 3228 configured to prevent cache transparency. For example, there is no 3229 need to send the Authorization field name in Vary because reuse 3230 across users is constrained by the field definition (Section 4.1 of 3231 [Part7]). Likewise, an origin server might use Cache-Control 3232 directives (Section 7.2 of [Part6]) to supplant Vary if it considers 3233 the variance less significant than the performance cost of Vary's 3234 impact on caching. 3236 7.2. Validator Header Fields 3238 Validator header fields convey metadata about the selected 3239 representation (Section 3). In responses to safe requests, validator 3240 fields describe the selected representation chosen by the origin 3241 server while handling the response. Note that, depending on the 3242 status code semantics, the selected representation for a given 3243 response is not necessarily the same as the representation enclosed 3244 as response payload. 3246 In a successful response to a state-changing request, validator 3247 fields describe the new representation that has replaced the prior 3248 selected representation as a result of processing the request. 3250 For example, an ETag header field in a 201 response communicates the 3251 entity-tag of the newly created resource's representation, so that it 3252 can be used in later conditional requests to prevent the "lost 3253 update" problem [Part4]. 3255 +-------------------+------------------------+ 3256 | Header Field Name | Defined in... | 3257 +-------------------+------------------------+ 3258 | ETag | Section 2.3 of [Part4] | 3259 | Last-Modified | Section 2.2 of [Part4] | 3260 +-------------------+------------------------+ 3262 7.3. Authentication Challenges 3264 Authentication challenges indicate what mechanisms are available for 3265 the client to provide authentication credentials in future requests. 3267 +--------------------+------------------------+ 3268 | Header Field Name | Defined in... | 3269 +--------------------+------------------------+ 3270 | WWW-Authenticate | Section 4.4 of [Part7] | 3271 | Proxy-Authenticate | Section 4.2 of [Part7] | 3272 +--------------------+------------------------+ 3274 7.4. Response Context 3276 The remaining response header fields provide more information about 3277 the target resource for potential use in later requests. 3279 +-------------------+------------------------+ 3280 | Header Field Name | Defined in... | 3281 +-------------------+------------------------+ 3282 | Accept-Ranges | Section 2.3 of [Part5] | 3283 | Allow | Section 7.4.1 | 3284 | Server | Section 7.4.2 | 3285 +-------------------+------------------------+ 3287 7.4.1. Allow 3289 The "Allow" header field lists the set of methods advertised as 3290 supported by the target resource. The purpose of this field is 3291 strictly to inform the recipient of valid request methods associated 3292 with the resource. 3294 Allow = #method 3296 Example of use: 3298 Allow: GET, HEAD, PUT 3300 The actual set of allowed methods is defined by the origin server at 3301 the time of each request. An origin server MUST generate an Allow 3302 field in a 405 (Method Not Allowed) response and MAY do so in any 3303 other response. An empty Allow field value indicates that the 3304 resource allows no methods, which might occur in a 405 response if 3305 the resource has been temporarily disabled by configuration. 3307 A proxy MUST NOT modify the Allow header field -- it does not need to 3308 understand all of the indicated methods in order to handle them 3309 according to the generic message handling rules. 3311 7.4.2. Server 3313 The "Server" header field contains information about the software 3314 used by the origin server to handle the request, which is often used 3315 by clients to help identify the scope of reported interoperability 3316 problems, to work around or tailor requests to avoid particular 3317 server limitations, and for analytics regarding server or operating 3318 system use. An origin server MAY generate a Server field in its 3319 responses. 3321 Server = product *( RWS ( product / comment ) ) 3323 The Server field-value consists of one or more product identifiers, 3324 each followed by zero or more comments (Section 3.2 of [Part1]), 3325 which together identify the origin server software and its 3326 significant subproducts. By convention, the product identifiers are 3327 listed in decreasing order of their significance for identifying the 3328 origin server software. Each product identifier consists of a name 3329 and optional version, as defined in Section 5.5.3. 3331 Example: 3333 Server: CERN/3.0 libwww/2.17 3335 An origin server SHOULD NOT generate a Server field containing 3336 needlessly fine-grained detail and SHOULD limit the addition of 3337 subproducts by third parties. Overly long and detailed Server field 3338 values increase response latency and potentially reveal internal 3339 implementation details that might make it (slightly) easier for 3340 attackers to find and exploit known security holes. 3342 8. IANA Considerations 3344 8.1. Method Registry 3346 The HTTP Method Registry defines the name space for the request 3347 method token (Section 4). The method registry is maintained at 3348 . 3350 8.1.1. Procedure 3352 HTTP method registrations MUST include the following fields: 3354 o Method Name (see Section 4) 3356 o Safe ("yes" or "no", see Section 4.2.1) 3358 o Idempotent ("yes" or "no", see Section 4.2.2) 3360 o Pointer to specification text 3362 Values to be added to this name space require IETF Review (see 3363 [RFC5226], Section 4.1). 3365 8.1.2. Considerations for New Methods 3367 Standardized methods are generic; that is, they are potentially 3368 applicable to any resource, not just one particular media type, kind 3369 of resource, or application. As such, it is preferred that new 3370 methods be registered in a document that isn't specific to a single 3371 application or data format, since orthogonal technologies deserve 3372 orthogonal specification. 3374 Since message parsing (Section 3.3 of [Part1]) needs to be 3375 independent of method semantics (aside from responses to HEAD), 3376 definitions of new methods cannot change the parsing algorithm or 3377 prohibit the presence of a message body on either the request or the 3378 response message. Definitions of new methods can specify that only a 3379 zero-length message body is allowed by requiring a Content-Length 3380 header field with a value of "0". 3382 A new method definition needs to indicate whether it is safe 3383 (Section 4.2.1), idempotent (Section 4.2.2), cacheable 3384 (Section 4.2.3), what semantics are to be associated with the payload 3385 body if any is present in the request, and what refinements the 3386 method makes to header field or status code semantics. If the new 3387 method is cacheable, its definition ought to describe how, and under 3388 what conditions, a cache can store a response and use it to satisfy a 3389 subsequent request. The new method ought to describe whether it can 3390 be made conditional (Section 5.2) and, if so, how a server responds 3391 when the condition is false. Likewise, if the new method might have 3392 some use for partial response semantics ([Part5]), it ought to 3393 document this too. 3395 8.1.3. Registrations 3397 The HTTP Method Registry shall be populated with the registrations 3398 below: 3400 +---------+------+------------+---------------+ 3401 | Method | Safe | Idempotent | Reference | 3402 +---------+------+------------+---------------+ 3403 | CONNECT | no | no | Section 4.3.6 | 3404 | DELETE | no | yes | Section 4.3.5 | 3405 | GET | yes | yes | Section 4.3.1 | 3406 | HEAD | yes | yes | Section 4.3.2 | 3407 | OPTIONS | yes | yes | Section 4.3.7 | 3408 | POST | no | no | Section 4.3.3 | 3409 | PUT | no | yes | Section 4.3.4 | 3410 | TRACE | yes | yes | Section 4.3.8 | 3411 +---------+------+------------+---------------+ 3413 8.2. Status Code Registry 3415 The HTTP Status Code Registry defines the name space for the response 3416 status-code token (Section 6). The status code registry is 3417 maintained at . 3419 This section replaces the registration procedure for HTTP Status 3420 Codes previously defined in Section 7.1 of [RFC2817]. 3422 8.2.1. Procedure 3424 Values to be added to the HTTP status code name space require IETF 3425 Review (see [RFC5226], Section 4.1). 3427 8.2.2. Considerations for New Status Codes 3429 When it is necessary to express semantics for a response that are not 3430 defined by current status codes, a new status code can be registered. 3432 Status codes are generic; they are potentially applicable to any 3433 resource, not just one particular media type, kind of resource, or 3434 application of HTTP. As such, it is preferred that new status codes 3435 be registered in a document that isn't specific to a single 3436 application. 3438 New status codes are required to fall under one of the categories 3439 defined in Section 6. To allow existing parsers to process the 3440 response message, new status codes cannot disallow a payload, 3441 although they can mandate a zero-length payload body. 3443 Proposals for new status codes that are not yet widely deployed ought 3444 to avoid allocating a specific number for the code until there is 3445 clear consensus that it will be registered; instead, early drafts can 3446 use a notation such as "4NN", or "3N0" .. "3N9", to indicate the 3447 class of the proposed status code(s) without consuming a number 3448 prematurely. 3450 The definition of a new status code ought to explain the request 3451 conditions that would cause a response containing that status code 3452 (e.g., combinations of request header fields and/or method(s)) along 3453 with any dependencies on response header fields (e.g., what fields 3454 are required, what fields can modify the semantics, and what header 3455 field semantics are further refined when used with the new status 3456 code). 3458 The definition of a new status code ought to specify whether or not 3459 it is cacheable. Note that all status codes can be cached if the 3460 response they occur in has explicit freshness information; however, 3461 status codes that are defined as being cacheable are allowed to be 3462 cached without explicit freshness information. Likewise, the 3463 definition of a status code can place constraints upon cache 3464 behaviour. See [Part6] for more information. 3466 Finally, the definition of a new status code ought to indicate 3467 whether the payload has any implied association with an identified 3468 resource (Section 3.1.4.1). 3470 8.2.3. Registrations 3472 The HTTP Status Code Registry shall be updated with the registrations 3473 below: 3475 +-------+-------------------------------+----------------+ 3476 | Value | Description | Reference | 3477 +-------+-------------------------------+----------------+ 3478 | 100 | Continue | Section 6.2.1 | 3479 | 101 | Switching Protocols | Section 6.2.2 | 3480 | 200 | OK | Section 6.3.1 | 3481 | 201 | Created | Section 6.3.2 | 3482 | 202 | Accepted | Section 6.3.3 | 3483 | 203 | Non-Authoritative Information | Section 6.3.4 | 3484 | 204 | No Content | Section 6.3.5 | 3485 | 205 | Reset Content | Section 6.3.6 | 3486 | 300 | Multiple Choices | Section 6.4.1 | 3487 | 301 | Moved Permanently | Section 6.4.2 | 3488 | 302 | Found | Section 6.4.3 | 3489 | 303 | See Other | Section 6.4.4 | 3490 | 305 | Use Proxy | Section 6.4.5 | 3491 | 306 | (Unused) | Section 6.4.6 | 3492 | 307 | Temporary Redirect | Section 6.4.7 | 3493 | 400 | Bad Request | Section 6.5.1 | 3494 | 402 | Payment Required | Section 6.5.2 | 3495 | 403 | Forbidden | Section 6.5.3 | 3496 | 404 | Not Found | Section 6.5.4 | 3497 | 405 | Method Not Allowed | Section 6.5.5 | 3498 | 406 | Not Acceptable | Section 6.5.6 | 3499 | 408 | Request Timeout | Section 6.5.7 | 3500 | 409 | Conflict | Section 6.5.8 | 3501 | 410 | Gone | Section 6.5.9 | 3502 | 411 | Length Required | Section 6.5.10 | 3503 | 413 | Payload Too Large | Section 6.5.11 | 3504 | 414 | URI Too Long | Section 6.5.12 | 3505 | 415 | Unsupported Media Type | Section 6.5.13 | 3506 | 417 | Expectation Failed | Section 6.5.14 | 3507 | 426 | Upgrade Required | Section 6.5.15 | 3508 | 500 | Internal Server Error | Section 6.6.1 | 3509 | 501 | Not Implemented | Section 6.6.2 | 3510 | 502 | Bad Gateway | Section 6.6.3 | 3511 | 503 | Service Unavailable | Section 6.6.4 | 3512 | 504 | Gateway Timeout | Section 6.6.5 | 3513 | 505 | HTTP Version Not Supported | Section 6.6.6 | 3514 +-------+-------------------------------+----------------+ 3516 8.3. Header Field Registry 3518 HTTP header fields are registered within the Message Header Field 3519 Registry located at , as defined by [BCP90]. 3522 8.3.1. Considerations for New Header Fields 3524 Header fields are key:value pairs that can be used to communicate 3525 data about the message, its payload, the target resource, or the 3526 connection (i.e., control data). See Section 3.2 of [Part1] for a 3527 general definition of header field syntax in HTTP messages. 3529 The requirements for header field names are defined in [BCP90]. 3530 Authors of specifications defining new fields are advised to keep the 3531 name as short as practical and to not prefix the name with "X-" 3532 unless the header field will never be used on the Internet. (The 3533 "x-" prefix idiom has been extensively misused in practice; it was 3534 intended to only be used as a mechanism for avoiding name collisions 3535 inside proprietary software or intranet processing, since the prefix 3536 would ensure that private names never collide with a newly registered 3537 Internet name.) 3539 New header field values typically have their syntax defined using 3540 ABNF ([RFC5234]), using the extension defined in Appendix B of 3541 [Part1] as necessary, and are usually constrained to the range of 3542 ASCII characters. Header fields needing a greater range of 3543 characters can use an encoding such as the one defined in [RFC5987]. 3545 Leading and trailing whitespace in raw field values is removed upon 3546 field parsing (Section 3.2.4 of [Part1]). Field definitions where 3547 leading or trailing whitespace in values is significant will have to 3548 use a container syntax such as quoted-string. 3550 Because commas (",") are used as a generic delimiter between field- 3551 values, they need to be treated with care if they are allowed in the 3552 field-value. Typically, components that might contain a comma are 3553 protected with double-quotes using the quoted-string ABNF production 3554 (Section 3.2.6 of [Part1]). 3556 For example, a textual date and a URI (either of which might contain 3557 a comma) could be safely carried in field-values like these: 3559 Example-URI-Field: "http://example.com/a.html,foo", 3560 "http://without-a-comma.example.com/" 3561 Example-Date-Field: "Sat, 04 May 1996", "Wed, 14 Sep 2005" 3563 Note that double-quote delimiters almost always are used with the 3564 quoted-string production; using a different syntax inside double- 3565 quotes will likely cause unnecessary confusion. 3567 Many header fields use a format including (case-insensitively) named 3568 parameters (for instance, Content-Type, defined in Section 3.1.1.5). 3569 Allowing both unquoted (token) and quoted (quoted-string) syntax for 3570 the parameter value enables recipients to use existing parser 3571 components. When allowing both forms, the meaning of a parameter 3572 value ought to be independent of the syntax used for it (for an 3573 example, see the notes on parameter handling for media types in 3574 Section 3.1.1.1). 3576 Authors of specifications defining new header fields are advised to 3577 consider documenting: 3579 o Whether the field is a single value, or whether it can be a list 3580 (delimited by commas; see Section 3.2 of [Part1]). 3582 If it does not use the list syntax, document how to treat messages 3583 where the field occurs multiple times (a sensible default would be 3584 to ignore the field, but this might not always be the right 3585 choice). 3587 Note that intermediaries and software libraries might combine 3588 multiple header field instances into a single one, despite the 3589 field's definition not allowing the list syntax. A robust format 3590 enables recipients to discover these situations (good example: 3591 "Content-Type", as the comma can only appear inside quoted 3592 strings; bad example: "Location", as a comma can occur inside a 3593 URI). 3595 o Under what conditions the header field can be used; e.g., only in 3596 responses or requests, in all messages, only on responses to a 3597 particular request method, etc. 3599 o Whether the field semantics are further refined by the context, 3600 such as by existing request methods or status codes. 3602 o Whether it is appropriate to list the field-name in the Connection 3603 header field (i.e., if the header field is to be hop-by-hop; see 3604 Section 6.1 of [Part1]). 3606 o Under what conditions intermediaries are allowed to insert, 3607 delete, or modify the field's value. 3609 o How the header field might interact with caching (see [Part6]). 3611 o Whether the header field is useful or allowable in trailers (see 3612 Section 4.1 of [Part1]). 3614 o Whether the header field ought to be preserved across redirects. 3616 8.3.2. Registrations 3618 The Message Header Field Registry shall be updated with the following 3619 permanent registrations: 3621 +-------------------+----------+----------+-----------------+ 3622 | Header Field Name | Protocol | Status | Reference | 3623 +-------------------+----------+----------+-----------------+ 3624 | Accept | http | standard | Section 5.3.2 | 3625 | Accept-Charset | http | standard | Section 5.3.3 | 3626 | Accept-Encoding | http | standard | Section 5.3.4 | 3627 | Accept-Language | http | standard | Section 5.3.5 | 3628 | Allow | http | standard | Section 7.4.1 | 3629 | Content-Encoding | http | standard | Section 3.1.2.2 | 3630 | Content-Language | http | standard | Section 3.1.3.2 | 3631 | Content-Location | http | standard | Section 3.1.4.2 | 3632 | Content-Type | http | standard | Section 3.1.1.5 | 3633 | Date | http | standard | Section 7.1.1.2 | 3634 | Expect | http | standard | Section 5.1.1 | 3635 | From | http | standard | Section 5.5.1 | 3636 | Location | http | standard | Section 7.1.2 | 3637 | MIME-Version | http | standard | Appendix A.1 | 3638 | Max-Forwards | http | standard | Section 5.1.2 | 3639 | Referer | http | standard | Section 5.5.2 | 3640 | Retry-After | http | standard | Section 7.1.3 | 3641 | Server | http | standard | Section 7.4.2 | 3642 | User-Agent | http | standard | Section 5.5.3 | 3643 | Vary | http | standard | Section 7.1.4 | 3644 +-------------------+----------+----------+-----------------+ 3646 The change controller for the above registrations is: "IETF 3647 (iesg@ietf.org) - Internet Engineering Task Force". 3649 8.4. Content Coding Registry 3651 The HTTP Content Coding Registry defines the name space for content 3652 coding names (Section 4.2 of [Part1]). The content coding registry 3653 is maintained at . 3655 8.4.1. Procedure 3657 Content Coding registrations MUST include the following fields: 3659 o Name 3661 o Description 3662 o Pointer to specification text 3664 Names of content codings MUST NOT overlap with names of transfer 3665 codings (Section 4 of [Part1]), unless the encoding transformation is 3666 identical (as is the case for the compression codings defined in 3667 Section 4.2 of [Part1]). 3669 Values to be added to this name space require IETF Review (see 3670 Section 4.1 of [RFC5226]), and MUST conform to the purpose of content 3671 coding defined in this section. 3673 8.4.2. Registrations 3675 The HTTP Content Codings Registry shall be updated with the 3676 registrations below: 3678 +----------+----------------------------------------+---------------+ 3679 | Name | Description | Reference | 3680 +----------+----------------------------------------+---------------+ 3681 | compress | UNIX "compress" program method | Section 4.2.1 | 3682 | | | of [Part1] | 3683 | deflate | "deflate" compression mechanism | Section 4.2.2 | 3684 | | ([RFC1951]) used inside the "zlib" | of [Part1] | 3685 | | data format ([RFC1950]) | | 3686 | gzip | Same as GNU zip [RFC1952] | Section 4.2.3 | 3687 | | | of [Part1] | 3688 | identity | reserved (synonym for "no encoding" in | Section 5.3.4 | 3689 | | Accept-Encoding header field) | | 3690 +----------+----------------------------------------+---------------+ 3692 9. Security Considerations 3694 This section is meant to inform developers, information providers, 3695 and users of known security concerns relevant to HTTP/1.1 semantics 3696 and its use for transferring information over the Internet. 3698 9.1. Attacks Based On File and Path Names 3700 Origin servers frequently make use of their local file system to 3701 manage the mapping from effective request URI to resource 3702 representations. Implementors need to be aware that most file 3703 systems are not designed to protect against malicious file or path 3704 names, and thus depend on the origin server to avoid mapping to file 3705 names, folders, or directories that have special significance to the 3706 system. 3708 For example, UNIX, Microsoft Windows, and other operating systems use 3709 ".." as a path component to indicate a directory level above the 3710 current one, and use specially named paths or file names to send data 3711 to system devices. Similar naming conventions might exist within 3712 other types of storage systems. Likewise, local storage systems have 3713 an annoying tendency to prefer user-friendliness over security when 3714 handling invalid or unexpected characters, recomposition of 3715 decomposed characters, and case-normalization of case-insensitive 3716 names. 3718 Attacks based on such special names tend to focus on either denial of 3719 service (e.g., telling the server to read from a COM port) or 3720 disclosure of configuration and source files that are not meant to be 3721 served. 3723 9.2. Personal Information 3725 Clients are often privy to large amounts of personal information, 3726 including both information provided by the user to interact with 3727 resources (e.g., the user's name, location, mail address, passwords, 3728 encryption keys, etc.) and information about the user's browsing 3729 activity over time (e.g., history, bookmarks, etc.). Implementations 3730 need to prevent unintentional leakage of personal information. 3732 9.3. Sensitive Information in URIs 3734 URIs are intended to be shared, not secured, even when they identify 3735 secure resources. URIs are often shown on displays, added to 3736 templates when a page is printed, and stored in a variety of 3737 unprotected bookmark lists. It is therefore unwise to include 3738 information within a URI that is sensitive, personally identifiable, 3739 or a risk to disclose. 3741 Authors of services ought to avoid GET-based forms for the submission 3742 of sensitive data because that data will be placed in the request- 3743 target. Many existing servers, proxies, and user agents log or 3744 display the request-target in places where it might be visible to 3745 third parties. Such services ought to use POST-based form submission 3746 instead. 3748 Since the Referer header field tells a target site about the context 3749 that resulted in a request, it has the potential to reveal 3750 information about the user's immediate browsing history and any 3751 personal information that might be found in the referring resource's 3752 URI. Limitations on Referer are described in Section 5.5.2 to 3753 address some of its security considerations. 3755 9.4. Product Information 3757 The User-Agent (Section 5.5.3), Via (Section 5.7.1 of [Part1]), and 3758 Server (Section 7.4.2) header fields often reveal information about 3759 the respective sender's software systems. In theory, this can make 3760 it easier for an attacker to exploit known security holes; in 3761 practice, attackers tend to try all potential holes regardless of the 3762 apparent software versions being used. 3764 Proxies that serve as a portal through a network firewall ought to 3765 take special precautions regarding the transfer of header information 3766 that might identify hosts behind the firewall. The Via header field 3767 allows intermediaries to replace sensitive machine names with 3768 pseudonyms. 3770 9.5. Fragment after Redirects 3772 Although fragment identifiers used within URI references are not sent 3773 in requests, implementers ought to be aware that they will be visible 3774 to the user agent and any extensions or scripts running as a result 3775 of the response. In particular, when a redirect occurs and the 3776 original request's fragment identifier is inherited by the new 3777 reference in Location (Section 7.1.2), this might have the effect of 3778 leaking one site's fragment to another site. If the first site uses 3779 personal information in fragments, it ought to ensure that redirects 3780 to other sites include a (possibly empty) fragment component in order 3781 to block that inheritance. 3783 9.6. Browser Fingerprinting 3785 Browser fingerprinting is a set of techniques for identifying a 3786 specific user agent over time through its unique set of 3787 characteristics. These characteristics might include information 3788 related to its TCP behavior, feature capabilities, and scripting 3789 environment, though of particular interest here is the set of unique 3790 characteristics that might be communicated via HTTP. Fingerprinting 3791 is considered a privacy concern because it enables tracking of a user 3792 agent's behavior over time without the corresponding controls that 3793 the user might have over other forms of data collection (e.g., 3794 cookies). Many general-purpose user agents (i.e., Web browsers) have 3795 taken steps to reduce their fingerprints. 3797 There are a number of request header fields that might reveal 3798 information to servers that is sufficiently unique to enable 3799 fingerprinting. The From header field is the most obvious, though it 3800 is expected that From will only be sent when self-identification is 3801 desired by the user. Likewise, Cookie header fields are deliberately 3802 designed to enable re-identification, so we can assume that 3803 fingerprinting concerns only apply to situations where cookies are 3804 disabled or restricted by browser configuration. 3806 The User-Agent header field might contain enough information to 3807 uniquely identify a specific device, usually when combined with other 3808 characteristics, particularly if the user agent sends excessive 3809 details about the user's system or extensions. However, the source 3810 of unique information that is least expected by users is proactive 3811 negotiation (Section 5.3), including the Accept, Accept-Charset, 3812 Accept-Encoding, and Accept-Language header fields. 3814 In addition to the fingerprinting concern, detailed use of the 3815 Accept-Language header field can reveal information the user might 3816 consider to be of a private nature, because the understanding of 3817 particular languages is often strongly correlated to membership in a 3818 particular ethnic group. An approach that limits such loss of 3819 privacy would be for a user agent to omit the sending of Accept- 3820 Language except for sites that have been whitelisted, perhaps via 3821 interaction after detecting a Vary header field that would indicate 3822 language negotiation might be useful. 3824 In environments where proxies are used to enhance privacy, user 3825 agents ought to be conservative in sending proactive negotiation 3826 header fields. General-purpose user agents that provide a high 3827 degree of header field configurability ought to inform users about 3828 the loss of privacy that might result if too much detail is provided. 3829 As an extreme privacy measure, proxies could filter the proactive 3830 negotiation header fields in relayed requests. 3832 10. Acknowledgments 3834 See Section 9 of [Part1]. 3836 11. References 3838 11.1. Normative References 3840 [Part1] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext 3841 Transfer Protocol (HTTP/1.1): Message Syntax and 3842 Routing", draft-ietf-httpbis-p1-messaging-22 (work in 3843 progress), February 2013. 3845 [Part4] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext 3846 Transfer Protocol (HTTP/1.1): Conditional Requests", 3847 draft-ietf-httpbis-p4-conditional-22 (work in 3848 progress), February 2013. 3850 [Part5] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 3851 "Hypertext Transfer Protocol (HTTP/1.1): Range 3852 Requests", draft-ietf-httpbis-p5-range-22 (work in 3853 progress), February 2013. 3855 [Part6] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 3856 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 3857 draft-ietf-httpbis-p6-cache-22 (work in progress), 3858 February 2013. 3860 [Part7] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext 3861 Transfer Protocol (HTTP/1.1): Authentication", 3862 draft-ietf-httpbis-p7-auth-22 (work in progress), 3863 February 2013. 3865 [RFC1950] Deutsch, L. and J-L. Gailly, "ZLIB Compressed Data 3866 Format Specification version 3.3", RFC 1950, May 1996. 3868 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format 3869 Specification version 1.3", RFC 1951, May 1996. 3871 [RFC1952] Deutsch, P., Gailly, J-L., Adler, M., Deutsch, L., and 3872 G. Randers-Pehrson, "GZIP file format specification 3873 version 4.3", RFC 1952, May 1996. 3875 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet 3876 Mail Extensions (MIME) Part One: Format of Internet 3877 Message Bodies", RFC 2045, November 1996. 3879 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet 3880 Mail Extensions (MIME) Part Two: Media Types", 3881 RFC 2046, November 1996. 3883 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3884 Requirement Levels", BCP 14, RFC 2119, March 1997. 3886 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, 3887 "Uniform Resource Identifier (URI): Generic Syntax", 3888 STD 66, RFC 3986, January 2005. 3890 [RFC4647] Phillips, A., Ed. and M. Davis, Ed., "Matching of 3891 Language Tags", BCP 47, RFC 4647, September 2006. 3893 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for 3894 Syntax Specifications: ABNF", STD 68, RFC 5234, 3895 January 2008. 3897 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for 3898 Identifying Languages", BCP 47, RFC 5646, 3899 September 2009. 3901 [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in 3902 Internationalization in the IETF", BCP 166, RFC 6365, 3903 September 2011. 3905 11.2. Informative References 3907 [BCP13] Freed, N., Klensin, J., and T. Hansen, "Media Type 3908 Specifications and Registration Procedures", BCP 13, 3909 RFC 6838, January 2013. 3911 [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration 3912 Procedures for Message Header Fields", BCP 90, 3913 RFC 3864, September 2004. 3915 [REST] Fielding, R., "Architectural Styles and the Design of 3916 Network-based Software Architectures", Doctoral 3917 Dissertation, University of California, Irvine , 3918 September 2000, 3919 . 3921 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 3922 Specification, Implementation", RFC 1305, March 1992. 3924 [RFC1945] Berners-Lee, T., Fielding, R., and H. Nielsen, 3925 "Hypertext Transfer Protocol -- HTTP/1.0", RFC 1945, 3926 May 1996. 3928 [RFC2049] Freed, N. and N. Borenstein, "Multipurpose Internet 3929 Mail Extensions (MIME) Part Five: Conformance Criteria 3930 and Examples", RFC 2049, November 1996. 3932 [RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and 3933 T. Berners-Lee, "Hypertext Transfer Protocol -- 3934 HTTP/1.1", RFC 2068, January 1997. 3936 [RFC2295] Holtman, K. and A. Mutz, "Transparent Content 3937 Negotiation in HTTP", RFC 2295, March 1998. 3939 [RFC2388] Masinter, L., "Returning Values from Forms: multipart/ 3940 form-data", RFC 2388, August 1998. 3942 [RFC2557] Palme, F., Hopmann, A., Shelness, N., and E. Stefferud, 3943 "MIME Encapsulation of Aggregate Documents, such as 3944 HTML (MHTML)", RFC 2557, March 1999. 3946 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 3947 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 3948 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 3950 [RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within 3951 HTTP/1.1", RFC 2817, May 2000. 3953 [RFC2978] Freed, N. and J. Postel, "IANA Charset Registration 3954 Procedures", BCP 19, RFC 2978, October 2000. 3956 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing 3957 an IANA Considerations Section in RFCs", BCP 26, 3958 RFC 5226, May 2008. 3960 [RFC5322] Resnick, P., "Internet Message Format", RFC 5322, 3961 October 2008. 3963 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 3964 RFC 5789, March 2010. 3966 [RFC5987] Reschke, J., "Character Set and Language Encoding for 3967 Hypertext Transfer Protocol (HTTP) Header Field 3968 Parameters", RFC 5987, August 2010. 3970 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 3972 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 3973 April 2011. 3975 [RFC6266] Reschke, J., "Use of the Content-Disposition Header 3976 Field in the Hypertext Transfer Protocol (HTTP)", 3977 RFC 6266, June 2011. 3979 [status-308] Reschke, J., "The Hypertext Transfer Protocol (HTTP) 3980 Status Code 308 (Permanent Redirect)", 3981 draft-reschke-http-status-308-07 (work in progress), 3982 March 2012. 3984 Appendix A. Differences between HTTP and MIME 3986 HTTP/1.1 uses many of the constructs defined for the Internet Message 3987 Format [RFC5322] and the Multipurpose Internet Mail Extensions (MIME) 3988 [RFC2045] to allow a message body to be transmitted in an open 3989 variety of representations and with extensible header fields. 3990 However, RFC 2045 is focused only on email; applications of HTTP have 3991 many characteristics that differ from email, and hence HTTP has 3992 features that differ from MIME. These differences were carefully 3993 chosen to optimize performance over binary connections, to allow 3994 greater freedom in the use of new media types, to make date 3995 comparisons easier, and to acknowledge the practice of some early 3996 HTTP servers and clients. 3998 This appendix describes specific areas where HTTP differs from MIME. 3999 Proxies and gateways to and from strict MIME environments need to be 4000 aware of these differences and provide the appropriate conversions 4001 where necessary. 4003 A.1. MIME-Version 4005 HTTP is not a MIME-compliant protocol. However, messages can include 4006 a single MIME-Version header field to indicate what version of the 4007 MIME protocol was used to construct the message. Use of the MIME- 4008 Version header field indicates that the message is in full 4009 conformance with the MIME protocol (as defined in [RFC2045]). 4010 Senders are responsible for ensuring full conformance (where 4011 possible) when exporting HTTP messages to strict MIME environments. 4013 A.2. Conversion to Canonical Form 4015 MIME requires that an Internet mail body part be converted to 4016 canonical form prior to being transferred, as described in Section 4 4017 of [RFC2049]. Section 3.1.1.3 of this document describes the forms 4018 allowed for subtypes of the "text" media type when transmitted over 4019 HTTP. [RFC2046] requires that content with a type of "text" 4020 represent line breaks as CRLF and forbids the use of CR or LF outside 4021 of line break sequences. HTTP allows CRLF, bare CR, and bare LF to 4022 indicate a line break within text content. 4024 A proxy or gateway from HTTP to a strict MIME environment ought to 4025 translate all line breaks within the text media types described in 4026 Section 3.1.1.3 of this document to the RFC 2049 canonical form of 4027 CRLF. Note, however, this might be complicated by the presence of a 4028 Content-Encoding and by the fact that HTTP allows the use of some 4029 charsets that do not use octets 13 and 10 to represent CR and LF, 4030 respectively. 4032 Conversion will break any cryptographic checksums applied to the 4033 original content unless the original content is already in canonical 4034 form. Therefore, the canonical form is recommended for any content 4035 that uses such checksums in HTTP. 4037 A.3. Conversion of Date Formats 4039 HTTP/1.1 uses a restricted set of date formats (Section 7.1.1.1) to 4040 simplify the process of date comparison. Proxies and gateways from 4041 other protocols ought to ensure that any Date header field present in 4042 a message conforms to one of the HTTP/1.1 formats and rewrite the 4043 date if necessary. 4045 A.4. Conversion of Content-Encoding 4047 MIME does not include any concept equivalent to HTTP/1.1's Content- 4048 Encoding header field. Since this acts as a modifier on the media 4049 type, proxies and gateways from HTTP to MIME-compliant protocols 4050 ought to either change the value of the Content-Type header field or 4051 decode the representation before forwarding the message. (Some 4052 experimental applications of Content-Type for Internet mail have used 4053 a media-type parameter of ";conversions=" to perform 4054 a function equivalent to Content-Encoding. However, this parameter 4055 is not part of the MIME standards). 4057 A.5. Conversion of Content-Transfer-Encoding 4059 HTTP does not use the Content-Transfer-Encoding field of MIME. 4060 Proxies and gateways from MIME-compliant protocols to HTTP need to 4061 remove any Content-Transfer-Encoding prior to delivering the response 4062 message to an HTTP client. 4064 Proxies and gateways from HTTP to MIME-compliant protocols are 4065 responsible for ensuring that the message is in the correct format 4066 and encoding for safe transport on that protocol, where "safe 4067 transport" is defined by the limitations of the protocol being used. 4068 Such a proxy or gateway ought to transform and label the data with an 4069 appropriate Content-Transfer-Encoding if doing so will improve the 4070 likelihood of safe transport over the destination protocol. 4072 A.6. MHTML and Line Length Limitations 4074 HTTP implementations that share code with MHTML [RFC2557] 4075 implementations need to be aware of MIME line length limitations. 4076 Since HTTP does not have this limitation, HTTP does not fold long 4077 lines. MHTML messages being transported by HTTP follow all 4078 conventions of MHTML, including line length limitations and folding, 4079 canonicalization, etc., since HTTP transfers message-bodies as 4080 payload and, aside from the "multipart/byteranges" type (Appendix A 4081 of [Part5]), does not interpret the content or any MIME header lines 4082 that might be contained therein. 4084 Appendix B. Changes from RFC 2616 4086 The primary changes in this revision have been editorial in nature: 4087 extracting the messaging syntax and partitioning HTTP semantics into 4088 separate documents for the core features, conditional requests, 4089 partial requests, caching, and authentication. The conformance 4090 language has been revised to clearly target requirements and the 4091 terminology has been improved to distinguish payload from 4092 representations and representations from resources. An algorithm has 4093 been added for determining if a payload is associated with a specific 4094 identifier (Section 3.1.4.1). 4096 A new requirement has been added that semantics embedded in a URI 4097 should be disabled when those semantics are inconsistent with the 4098 request method, since this is a common cause of interoperability 4099 failure. 4101 The default charset of ISO-8859-1 for text media types has been 4102 removed; the default is now whatever the media type definition says 4103 (Section 3.1.1.3). Likewise, special treatment of ISO-8859-1 has 4104 been removed from the Accept-Charset header field (Section 5.3.3). 4106 The Content-Disposition header field has been removed since it is now 4107 defined by [RFC6266]. 4109 The definition of Content-Location has been changed to no longer 4110 affect the base URI for resolving relative URI references, due to 4111 poor implementation support and the undesirable effect of potentially 4112 breaking relative links in content-negotiated resources 4113 (Section 3.1.4.2). 4115 The Content-MD5 header field has been removed because it was 4116 inconsistently implemented with respect to partial responses. 4118 To be consistent with the method-neutral parsing algorithm of 4119 [Part1], the definition of GET has been relaxed so that requests can 4120 have a body, even though a body has no meaning for GET 4121 (Section 4.3.1). 4123 Servers are no longer required to handle all Content-* header fields 4124 and use of Content-Range has been explicitly banned in PUT requests 4125 (Section 4.3.4). 4127 Definition of the CONNECT method has been moved from [RFC2817] to 4128 this specification (Section 4.3.6). 4130 The OPTIONS (Section 4.3.7) and TRACE (Section 4.3.8) request methods 4131 have been defined as being safe. 4133 The definition of Expect has been both fixed to allow parameters for 4134 value-less expectations and simplified to allow trailing semicolons 4135 after "100-continue" (Section 5.1.1). 4137 The Max-Forwards header field (Section 5.1.2) has been restricted to 4138 the OPTIONS and TRACE methods; previously, extension methods could 4139 have used it as well. 4141 The "about:blank" URI has been suggested as a value for the Referer 4142 header field when no referring URI is applicable, which distinguishes 4143 that case from others where the Referer field is not sent or has been 4144 removed (Section 5.5.2). 4146 The 201 (Created) status description has been changed to allow for 4147 the possibility that more than one resource has been created 4148 (Section 6.3.2). 4150 The definition of 203 (Non-Authoritative Information) has been 4151 broadened to include cases of payload transformations as well 4152 (Section 6.3.4). 4154 The redirect status codes 301, 302, and 307 no longer have normative 4155 requirements on response payloads and user interaction (Section 6.4). 4157 The request methods that are safe to automatically redirect is no 4158 longer a closed set; user agents are able to make that determination 4159 based upon the request method semantics (Section 6.4). 4161 The description of 303 (See Other) status code has been changed to 4162 allow it to be cached if explicit freshness information is given, and 4163 a specific definition has been added for a 303 response to GET 4164 (Section 6.4.4). 4166 The status codes 301 and 302 (sections 6.4.2 and 6.4.3) have been 4167 changed to allow user agents to rewrite the method from POST to GET. 4169 The 305 (Use Proxy) status code has been deprecated due to security 4170 concerns regarding in-band configuration of a proxy (Section 6.4.5). 4172 The 400 (Bad Request) status code has been relaxed so that it isn't 4173 limited to syntax errors (Section 6.5.1). 4175 The 426 (Upgrade Required) status code has been incorporated from 4176 [RFC2817] (Section 6.5.15). 4178 The following status codes are now cacheable (that is, they can be 4179 stored and reused by a cache without explicit freshness information 4180 present): 204, 404, 405, 414, 501. 4182 Allow has been reclassified as a response header field, removing the 4183 option to specify it in a PUT request. Requirements relating to the 4184 content of Allow have been relaxed; correspondingly, clients are not 4185 required to always trust its value (Section 7.4.1). 4187 The target of requirements on HTTP-date and the Date header field 4188 have been reduced to those systems generating the date, rather than 4189 all systems sending a date (Section 7.1.1). 4191 The syntax of the Location header field has been changed to allow all 4192 URI references, including relative references and fragments, along 4193 with some clarifications as to when use of fragments would not be 4194 appropriate (Section 7.1.2). 4196 A Method Registry has been defined (Section 8.1). 4198 The Status Code Registry (Section 8.2) has been redefined by this 4199 specification; previously, it was defined in Section 7.1 of 4200 [RFC2817]. 4202 Registration of Content Codings has been changed to require IETF 4203 Review (Section 8.4). 4205 Appendix C. Imported ABNF 4207 The following core rules are included by reference, as defined in 4208 Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), 4209 CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double 4210 quote), HEXDIG (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF 4211 (line feed), OCTET (any 8-bit sequence of data), SP (space), and 4212 VCHAR (any visible US-ASCII character). 4214 The rules below are defined in [Part1]: 4216 BWS = 4217 OWS = 4218 RWS = 4219 URI-reference = 4220 absolute-URI = 4221 comment = 4222 field-name = 4223 partial-URI = 4224 quoted-string = 4225 token = 4226 word = 4228 Appendix D. Collected ABNF 4230 Accept = [ ( "," / ( media-range [ accept-params ] ) ) *( OWS "," [ 4231 OWS ( media-range [ accept-params ] ) ] ) ] 4232 Accept-Charset = *( "," OWS ) ( ( charset / "*" ) [ weight ] ) *( OWS 4233 "," [ OWS ( ( charset / "*" ) [ weight ] ) ] ) 4235 Accept-Encoding = [ ( "," / ( codings [ weight ] ) ) *( OWS "," [ OWS 4236 ( codings [ weight ] ) ] ) ] 4237 Accept-Language = *( "," OWS ) ( language-range [ weight ] ) *( OWS 4238 "," [ OWS ( language-range [ weight ] ) ] ) 4239 Allow = [ ( "," / method ) *( OWS "," [ OWS method ] ) ] 4241 BWS = 4243 Content-Encoding = *( "," OWS ) content-coding *( OWS "," [ OWS 4244 content-coding ] ) 4245 Content-Language = *( "," OWS ) language-tag *( OWS "," [ OWS 4246 language-tag ] ) 4247 Content-Location = absolute-URI / partial-URI 4248 Content-Type = media-type 4250 Date = HTTP-date 4252 Expect = *( "," OWS ) expectation *( OWS "," [ OWS expectation ] ) 4254 From = mailbox 4256 GMT = %x47.4D.54 ; GMT 4258 HTTP-date = IMF-fixdate / obs-date 4260 IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT 4262 Location = URI-reference 4264 Max-Forwards = 1*DIGIT 4266 OWS = 4268 RWS = 4269 Referer = absolute-URI / partial-URI 4270 Retry-After = HTTP-date / delta-seconds 4272 Server = product *( RWS ( product / comment ) ) 4274 URI-reference = 4275 User-Agent = product *( RWS ( product / comment ) ) 4277 Vary = "*" / ( *( "," OWS ) field-name *( OWS "," [ OWS field-name ] 4278 ) ) 4280 absolute-URI = 4281 accept-ext = OWS ";" OWS token [ "=" word ] 4282 accept-params = weight *accept-ext 4283 asctime-date = day-name SP date3 SP time-of-day SP year 4284 attribute = token 4286 charset = token 4287 codings = content-coding / "identity" / "*" 4288 comment = 4289 content-coding = token 4291 date1 = day SP month SP year 4292 date2 = day "-" month "-" 2DIGIT 4293 date3 = month SP ( 2DIGIT / ( SP DIGIT ) ) 4294 day = 2DIGIT 4295 day-name = %x4D.6F.6E ; Mon 4296 / %x54.75.65 ; Tue 4297 / %x57.65.64 ; Wed 4298 / %x54.68.75 ; Thu 4299 / %x46.72.69 ; Fri 4300 / %x53.61.74 ; Sat 4301 / %x53.75.6E ; Sun 4302 day-name-l = %x4D.6F.6E.64.61.79 ; Monday 4303 / %x54.75.65.73.64.61.79 ; Tuesday 4304 / %x57.65.64.6E.65.73.64.61.79 ; Wednesday 4305 / %x54.68.75.72.73.64.61.79 ; Thursday 4306 / %x46.72.69.64.61.79 ; Friday 4307 / %x53.61.74.75.72.64.61.79 ; Saturday 4308 / %x53.75.6E.64.61.79 ; Sunday 4309 delta-seconds = 1*DIGIT 4311 expect-name = token 4312 expect-param = expect-name [ BWS "=" BWS expect-value ] 4313 expect-value = token / quoted-string 4314 expectation = expect-name [ BWS "=" BWS expect-value ] *( OWS ";" [ 4315 OWS expect-param ] ) 4317 field-name = 4319 hour = 2DIGIT 4321 language-range = 4322 language-tag = 4324 mailbox = 4325 media-range = ( "*/*" / ( type "/*" ) / ( type "/" subtype ) ) *( OWS 4326 ";" OWS parameter ) 4327 media-type = type "/" subtype *( OWS ";" OWS parameter ) 4328 method = token 4329 minute = 2DIGIT 4330 month = %x4A.61.6E ; Jan 4331 / %x46.65.62 ; Feb 4332 / %x4D.61.72 ; Mar 4333 / %x41.70.72 ; Apr 4334 / %x4D.61.79 ; May 4335 / %x4A.75.6E ; Jun 4336 / %x4A.75.6C ; Jul 4337 / %x41.75.67 ; Aug 4338 / %x53.65.70 ; Sep 4339 / %x4F.63.74 ; Oct 4340 / %x4E.6F.76 ; Nov 4341 / %x44.65.63 ; Dec 4343 obs-date = rfc850-date / asctime-date 4345 parameter = attribute "=" value 4346 partial-URI = 4347 product = token [ "/" product-version ] 4348 product-version = token 4350 quoted-string = 4351 qvalue = ( "0" [ "." *3DIGIT ] ) / ( "1" [ "." *3"0" ] ) 4353 rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT 4355 second = 2DIGIT 4356 subtype = token 4358 time-of-day = hour ":" minute ":" second 4359 token = 4360 type = token 4362 value = word 4364 weight = OWS ";" OWS "q=" qvalue 4365 word = 4367 year = 4DIGIT 4369 Appendix E. Change Log (to be removed by RFC Editor before publication) 4371 E.1. Since RFC 2616 4373 Changes up to the first Working Group Last Call draft are summarized 4374 in . 4377 E.2. Since draft-ietf-httpbis-p2-semantics-21 4379 Closed issues: 4381 o : "ETag (and 4382 other metadata) in status messages" 4384 o : "Conditional 4385 GET text" 4387 o : "Clarify 4388 description of 405 (Not Allowed)" 4390 o : "Allowing 4391 heuristic caching for new status codes" 4393 o : "method 4394 semantics: retrieval/representation" 4396 o : "User 4397 confirmation for unsafe methods" 4399 o : "Tentative 4400 Status Codes" 4402 o : "No-Transform" 4404 o : "p2 editorial 4405 feedback" 4407 o : "Absence of 4408 Accept-Encoding" 4410 o : "Accept- 4411 Language ordering for identical qvalues" 4413 o : "Identify 4414 additional status codes as cacheable by default" 4416 o : "mention in 4417 header field considerations that leading/trailing WS is lossy" 4419 Index 4421 1 4422 1xx Informational (status code class) 49 4424 2 4425 2xx Successful (status code class) 50 4427 3 4428 3xx Redirection (status code class) 53 4430 4 4431 4xx Client Error (status code class) 57 4433 5 4434 5xx Server Error (status code class) 61 4436 1 4437 100 Continue (status code) 49 4438 100-continue (expect value) 33 4439 101 Switching Protocols (status code) 50 4441 2 4442 200 OK (status code) 50 4443 201 Created (status code) 51 4444 202 Accepted (status code) 51 4445 203 Non-Authoritative Information (status code) 51 4446 204 No Content (status code) 52 4447 205 Reset Content (status code) 52 4449 3 4450 300 Multiple Choices (status code) 54 4451 301 Moved Permanently (status code) 55 4452 302 Found (status code) 55 4453 303 See Other (status code) 56 4454 305 Use Proxy (status code) 56 4455 306 (Unused) (status code) 56 4456 307 Temporary Redirect (status code) 57 4458 4 4459 400 Bad Request (status code) 57 4460 402 Payment Required (status code) 57 4461 403 Forbidden (status code) 57 4462 404 Not Found (status code) 58 4463 405 Method Not Allowed (status code) 58 4464 406 Not Acceptable (status code) 58 4465 408 Request Timeout (status code) 59 4466 409 Conflict (status code) 59 4467 410 Gone (status code) 59 4468 411 Length Required (status code) 60 4469 413 Payload Too Large (status code) 60 4470 414 URI Too Long (status code) 60 4471 415 Unsupported Media Type (status code) 60 4472 417 Expectation Failed (status code) 61 4473 426 Upgrade Required (status code) 61 4475 5 4476 500 Internal Server Error (status code) 61 4477 501 Not Implemented (status code) 61 4478 502 Bad Gateway (status code) 62 4479 503 Service Unavailable (status code) 62 4480 504 Gateway Timeout (status code) 62 4481 505 HTTP Version Not Supported (status code) 62 4483 A 4484 Accept header field 38 4485 Accept-Charset header field 40 4486 Accept-Encoding header field 41 4487 Accept-Language header field 42 4488 Allow header field 71 4490 C 4491 cacheable 23 4492 compress (content coding) 11 4493 conditional request 36 4494 CONNECT method 29 4495 content coding 11 4496 content negotiation 6 4497 Content-Encoding header field 12 4498 Content-Language header field 13 4499 Content-Location header field 15 4500 Content-Transfer-Encoding header field 87 4501 Content-Type header field 10 4503 D 4504 Date header field 66 4505 deflate (content coding) 11 4506 DELETE method 28 4508 E 4509 Expect header field 33 4510 Expect Values 4511 100-continue 33 4513 F 4514 From header field 44 4516 G 4517 GET method 24 4518 Grammar 4519 Accept 38 4520 Accept-Charset 40 4521 Accept-Encoding 41 4522 accept-ext 38 4523 Accept-Language 42 4524 accept-params 38 4525 Allow 71 4526 asctime-date 65 4527 attribute 8 4528 charset 9 4529 codings 41 4530 content-coding 11 4531 Content-Encoding 12 4532 Content-Language 13 4533 Content-Location 15 4534 Content-Type 10 4535 Date 66 4536 date1 64 4537 day 64 4538 day-name 64 4539 day-name-l 64 4540 delta-seconds 68 4541 Expect 33 4542 expect-name 33 4543 expect-param 33 4544 expect-value 33 4545 expectation 33 4546 From 44 4547 GMT 64 4548 hour 64 4549 HTTP-date 63 4550 IMF-fixdate 64 4551 language-range 42 4552 language-tag 13 4553 Location 66 4554 Max-Forwards 36 4555 media-range 38 4556 media-type 8 4557 method 20 4558 minute 64 4559 month 64 4560 obs-date 65 4561 parameter 8 4562 product 46 4563 product-version 46 4564 qvalue 37 4565 Referer 44 4566 Retry-After 68 4567 rfc850-date 65 4568 second 64 4569 Server 71 4570 subtype 8 4571 time-of-day 64 4572 type 8 4573 User-Agent 45 4574 value 8 4575 Vary 68 4576 weight 37 4577 year 64 4578 gzip (content coding) 11 4580 H 4581 HEAD method 24 4583 I 4584 idempotent 23 4586 L 4587 Location header field 66 4589 M 4590 Max-Forwards header field 36 4591 MIME-Version header field 86 4593 O 4594 OPTIONS method 31 4596 P 4597 payload 17 4598 POST method 25 4599 PUT method 26 4601 R 4602 Referer header field 44 4603 representation 7 4604 Retry-After header field 68 4606 S 4607 safe 22 4608 selected representation 7, 69 4609 Server header field 71 4610 Status Codes Classes 4611 1xx Informational 49 4612 2xx Successful 50 4613 3xx Redirection 53 4614 4xx Client Error 57 4615 5xx Server Error 61 4617 T 4618 TRACE method 32 4620 U 4621 User-Agent header field 45 4623 V 4624 Vary header field 68 4626 X 4627 x-compress (content coding) 11 4628 x-gzip (content coding) 11 4630 Authors' Addresses 4632 Roy T. Fielding (editor) 4633 Adobe Systems Incorporated 4634 345 Park Ave 4635 San Jose, CA 95110 4636 USA 4638 EMail: fielding@gbiv.com 4639 URI: http://roy.gbiv.com/ 4641 Julian F. Reschke (editor) 4642 greenbytes GmbH 4643 Hafenweg 16 4644 Muenster, NW 48155 4645 Germany 4647 EMail: julian.reschke@greenbytes.de 4648 URI: http://greenbytes.de/tech/webdav/