idnits 2.17.1 draft-ietf-httpbis-p2-semantics-20.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 (July 16, 2012) is 4295 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-20 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-20 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-20 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-20 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-20 ** 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 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 4288 (Obsoleted by RFC 6838) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 5987 (Obsoleted by RFC 8187) Summary: 3 errors (**), 0 flaws (~~), 6 warnings (==), 11 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) Y. Lafon, Ed. 5 Updates: 2817 (if approved) W3C 6 Intended status: Standards Track J. Reschke, Ed. 7 Expires: January 17, 2013 greenbytes 8 July 16, 2012 10 HTTP/1.1, part 2: Semantics and Payloads 11 draft-ietf-httpbis-p2-semantics-20 13 Abstract 15 The Hypertext Transfer Protocol (HTTP) is an application-level 16 protocol for distributed, collaborative, hypertext information 17 systems. This document defines the semantics of HTTP/1.1 messages, 18 as expressed by request methods, request header fields, response 19 status codes, and response header fields, along with the payload of 20 messages (metadata and body content) and mechanisms for content 21 negotiation. 23 Editorial Note (To be removed by RFC Editor) 25 Discussion of this draft takes place on the HTTPBIS working group 26 mailing list (ietf-http-wg@w3.org), which is archived at 27 . 29 The current issues list is at 30 and related 31 documents (including fancy diffs) can be found at 32 . 34 The changes in this draft are summarized in Appendix F.40. 36 Status of This Memo 38 This Internet-Draft is submitted in full conformance with the 39 provisions of BCP 78 and BCP 79. 41 Internet-Drafts are working documents of the Internet Engineering 42 Task Force (IETF). Note that other groups may also distribute 43 working documents as Internet-Drafts. The list of current Internet- 44 Drafts is at http://datatracker.ietf.org/drafts/current/. 46 Internet-Drafts are draft documents valid for a maximum of six months 47 and may be updated, replaced, or obsoleted by other documents at any 48 time. It is inappropriate to use Internet-Drafts as reference 49 material or to cite them other than as "work in progress." 51 This Internet-Draft will expire on January 17, 2013. 53 Copyright Notice 55 Copyright (c) 2012 IETF Trust and the persons identified as the 56 document authors. All rights reserved. 58 This document is subject to BCP 78 and the IETF Trust's Legal 59 Provisions Relating to IETF Documents 60 (http://trustee.ietf.org/license-info) in effect on the date of 61 publication of this document. Please review these documents 62 carefully, as they describe your rights and restrictions with respect 63 to this document. Code Components extracted from this document must 64 include Simplified BSD License text as described in Section 4.e of 65 the Trust Legal Provisions and are provided without warranty as 66 described in the Simplified BSD License. 68 This document may contain material from IETF Documents or IETF 69 Contributions published or made publicly available before November 70 10, 2008. The person(s) controlling the copyright in some of this 71 material may not have granted the IETF Trust the right to allow 72 modifications of such material outside the IETF Standards Process. 73 Without obtaining an adequate license from the person(s) controlling 74 the copyright in such materials, this document may not be modified 75 outside the IETF Standards Process, and derivative works of it may 76 not be created outside the IETF Standards Process, except to format 77 it for publication as an RFC or to translate it into languages other 78 than English. 80 Table of Contents 82 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7 83 1.1. Conformance and Error Handling . . . . . . . . . . . . . 7 84 1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 8 85 2. Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 86 2.1. Safe and Idempotent Methods . . . . . . . . . . . . . . . 9 87 2.1.1. Safe Methods . . . . . . . . . . . . . . . . . . . . 9 88 2.1.2. Idempotent Methods . . . . . . . . . . . . . . . . . 9 89 2.2. Method Registry . . . . . . . . . . . . . . . . . . . . . 9 90 2.2.1. Considerations for New Methods . . . . . . . . . . . 10 91 2.3. Method Definitions . . . . . . . . . . . . . . . . . . . 10 92 2.3.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . 11 93 2.3.2. GET . . . . . . . . . . . . . . . . . . . . . . . . . 12 94 2.3.3. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 12 95 2.3.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 13 96 2.3.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 14 97 2.3.6. DELETE . . . . . . . . . . . . . . . . . . . . . . . 16 98 2.3.7. TRACE . . . . . . . . . . . . . . . . . . . . . . . . 16 99 2.3.8. CONNECT . . . . . . . . . . . . . . . . . . . . . . . 17 100 3. Header Fields . . . . . . . . . . . . . . . . . . . . . . . . 18 101 3.1. Considerations for Creating Header Fields . . . . . . . . 18 102 3.2. Request Header Fields . . . . . . . . . . . . . . . . . . 20 103 3.3. Response Header Fields . . . . . . . . . . . . . . . . . 21 104 4. Status Codes . . . . . . . . . . . . . . . . . . . . . . . . 22 105 4.1. Overview of Status Codes . . . . . . . . . . . . . . . . 22 106 4.2. Status Code Registry . . . . . . . . . . . . . . . . . . 24 107 4.2.1. Considerations for New Status Codes . . . . . . . . . 24 108 4.3. Informational 1xx . . . . . . . . . . . . . . . . . . . . 25 109 4.3.1. 100 Continue . . . . . . . . . . . . . . . . . . . . 25 110 4.3.2. 101 Switching Protocols . . . . . . . . . . . . . . . 25 111 4.4. Successful 2xx . . . . . . . . . . . . . . . . . . . . . 26 112 4.4.1. 200 OK . . . . . . . . . . . . . . . . . . . . . . . 26 113 4.4.2. 201 Created . . . . . . . . . . . . . . . . . . . . . 26 114 4.4.3. 202 Accepted . . . . . . . . . . . . . . . . . . . . 27 115 4.4.4. 203 Non-Authoritative Information . . . . . . . . . . 27 116 4.4.5. 204 No Content . . . . . . . . . . . . . . . . . . . 27 117 4.4.6. 205 Reset Content . . . . . . . . . . . . . . . . . . 28 118 4.5. Redirection 3xx . . . . . . . . . . . . . . . . . . . . . 28 119 4.5.1. 300 Multiple Choices . . . . . . . . . . . . . . . . 29 120 4.5.2. 301 Moved Permanently . . . . . . . . . . . . . . . . 30 121 4.5.3. 302 Found . . . . . . . . . . . . . . . . . . . . . . 30 122 4.5.4. 303 See Other . . . . . . . . . . . . . . . . . . . . 31 123 4.5.5. 305 Use Proxy . . . . . . . . . . . . . . . . . . . . 31 124 4.5.6. 306 (Unused) . . . . . . . . . . . . . . . . . . . . 31 125 4.5.7. 307 Temporary Redirect . . . . . . . . . . . . . . . 32 126 4.6. Client Error 4xx . . . . . . . . . . . . . . . . . . . . 32 127 4.6.1. 400 Bad Request . . . . . . . . . . . . . . . . . . . 32 128 4.6.2. 402 Payment Required . . . . . . . . . . . . . . . . 32 129 4.6.3. 403 Forbidden . . . . . . . . . . . . . . . . . . . . 32 130 4.6.4. 404 Not Found . . . . . . . . . . . . . . . . . . . . 33 131 4.6.5. 405 Method Not Allowed . . . . . . . . . . . . . . . 33 132 4.6.6. 406 Not Acceptable . . . . . . . . . . . . . . . . . 33 133 4.6.7. 408 Request Timeout . . . . . . . . . . . . . . . . . 33 134 4.6.8. 409 Conflict . . . . . . . . . . . . . . . . . . . . 34 135 4.6.9. 410 Gone . . . . . . . . . . . . . . . . . . . . . . 34 136 4.6.10. 411 Length Required . . . . . . . . . . . . . . . . . 34 137 4.6.11. 413 Request Representation Too Large . . . . . . . . 35 138 4.6.12. 414 URI Too Long . . . . . . . . . . . . . . . . . . 35 139 4.6.13. 415 Unsupported Media Type . . . . . . . . . . . . . 35 140 4.6.14. 417 Expectation Failed . . . . . . . . . . . . . . . 35 141 4.6.15. 426 Upgrade Required . . . . . . . . . . . . . . . . 35 142 4.7. Server Error 5xx . . . . . . . . . . . . . . . . . . . . 36 143 4.7.1. 500 Internal Server Error . . . . . . . . . . . . . . 36 144 4.7.2. 501 Not Implemented . . . . . . . . . . . . . . . . . 36 145 4.7.3. 502 Bad Gateway . . . . . . . . . . . . . . . . . . . 36 146 4.7.4. 503 Service Unavailable . . . . . . . . . . . . . . . 36 147 4.7.5. 504 Gateway Timeout . . . . . . . . . . . . . . . . . 37 148 4.7.6. 505 HTTP Version Not Supported . . . . . . . . . . . 37 149 5. Protocol Parameters . . . . . . . . . . . . . . . . . . . . . 37 150 5.1. Date/Time Formats . . . . . . . . . . . . . . . . . . . . 37 151 5.2. Product Tokens . . . . . . . . . . . . . . . . . . . . . 40 152 5.3. Character Encodings (charset) . . . . . . . . . . . . . . 41 153 5.4. Content Codings . . . . . . . . . . . . . . . . . . . . . 41 154 5.4.1. Content Coding Registry . . . . . . . . . . . . . . . 42 155 5.5. Media Types . . . . . . . . . . . . . . . . . . . . . . . 42 156 5.5.1. Canonicalization and Text Defaults . . . . . . . . . 43 157 5.5.2. Multipart Types . . . . . . . . . . . . . . . . . . . 44 158 5.6. Language Tags . . . . . . . . . . . . . . . . . . . . . . 44 159 6. Payload . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 160 6.1. Payload Header Fields . . . . . . . . . . . . . . . . . . 45 161 6.2. Payload Body . . . . . . . . . . . . . . . . . . . . . . 45 162 7. Representation . . . . . . . . . . . . . . . . . . . . . . . 45 163 7.1. Identifying the Resource Associated with a 164 Representation . . . . . . . . . . . . . . . . . . . . . 46 165 7.2. Representation Header Fields . . . . . . . . . . . . . . 47 166 7.3. Representation Data . . . . . . . . . . . . . . . . . . . 48 167 8. Content Negotiation . . . . . . . . . . . . . . . . . . . . . 49 168 8.1. Server-driven Negotiation . . . . . . . . . . . . . . . . 50 169 8.2. Agent-driven Negotiation . . . . . . . . . . . . . . . . 51 170 9. Header Field Definitions . . . . . . . . . . . . . . . . . . 52 171 9.1. Accept . . . . . . . . . . . . . . . . . . . . . . . . . 52 172 9.2. Accept-Charset . . . . . . . . . . . . . . . . . . . . . 54 173 9.3. Accept-Encoding . . . . . . . . . . . . . . . . . . . . . 55 174 9.4. Accept-Language . . . . . . . . . . . . . . . . . . . . . 56 175 9.5. Allow . . . . . . . . . . . . . . . . . . . . . . . . . . 57 176 9.6. Content-Encoding . . . . . . . . . . . . . . . . . . . . 57 177 9.7. Content-Language . . . . . . . . . . . . . . . . . . . . 58 178 9.8. Content-Location . . . . . . . . . . . . . . . . . . . . 59 179 9.9. Content-Type . . . . . . . . . . . . . . . . . . . . . . 61 180 9.10. Date . . . . . . . . . . . . . . . . . . . . . . . . . . 61 181 9.11. Expect . . . . . . . . . . . . . . . . . . . . . . . . . 62 182 9.12. From . . . . . . . . . . . . . . . . . . . . . . . . . . 63 183 9.13. Location . . . . . . . . . . . . . . . . . . . . . . . . 63 184 9.14. Max-Forwards . . . . . . . . . . . . . . . . . . . . . . 65 185 9.15. Referer . . . . . . . . . . . . . . . . . . . . . . . . . 65 186 9.16. Retry-After . . . . . . . . . . . . . . . . . . . . . . . 66 187 9.17. Server . . . . . . . . . . . . . . . . . . . . . . . . . 66 188 9.18. User-Agent . . . . . . . . . . . . . . . . . . . . . . . 67 189 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 67 190 10.1. Method Registry . . . . . . . . . . . . . . . . . . . . . 67 191 10.2. Status Code Registry . . . . . . . . . . . . . . . . . . 68 192 10.3. Header Field Registration . . . . . . . . . . . . . . . . 69 193 10.4. Content Coding Registry . . . . . . . . . . . . . . . . . 70 194 11. Security Considerations . . . . . . . . . . . . . . . . . . . 71 195 11.1. Transfer of Sensitive Information . . . . . . . . . . . . 71 196 11.2. Encoding Sensitive Information in URIs . . . . . . . . . 72 197 11.3. Location Header Fields: Spoofing and Information 198 Leakage . . . . . . . . . . . . . . . . . . . . . . . . . 72 199 11.4. Security Considerations for CONNECT . . . . . . . . . . . 73 200 11.5. Privacy Issues Connected to Accept Header Fields . . . . 73 201 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 74 202 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 74 203 13.1. Normative References . . . . . . . . . . . . . . . . . . 74 204 13.2. Informative References . . . . . . . . . . . . . . . . . 75 205 Appendix A. Differences between HTTP and MIME . . . . . . . . . 77 206 A.1. MIME-Version . . . . . . . . . . . . . . . . . . . . . . 78 207 A.2. Conversion to Canonical Form . . . . . . . . . . . . . . 78 208 A.3. Conversion of Date Formats . . . . . . . . . . . . . . . 79 209 A.4. Introduction of Content-Encoding . . . . . . . . . . . . 79 210 A.5. No Content-Transfer-Encoding . . . . . . . . . . . . . . 79 211 A.6. MHTML and Line Length Limitations . . . . . . . . . . . . 80 212 Appendix B. Additional Features . . . . . . . . . . . . . . . . 80 213 Appendix C. Changes from RFC 2616 . . . . . . . . . . . . . . . 80 214 Appendix D. Imported ABNF . . . . . . . . . . . . . . . . . . . 82 215 Appendix E. Collected ABNF . . . . . . . . . . . . . . . . . . . 83 216 Appendix F. Change Log (to be removed by RFC Editor before 217 publication) . . . . . . . . . . . . . . . . . . . . 85 218 F.1. Since RFC 2616 . . . . . . . . . . . . . . . . . . . . . 85 219 F.2. Since draft-ietf-httpbis-p2-semantics-00 . . . . . . . . 86 220 F.3. Since draft-ietf-httpbis-p3-payload-00 . . . . . . . . . 86 221 F.4. Since draft-ietf-httpbis-p2-semantics-01 . . . . . . . . 87 222 F.5. Since draft-ietf-httpbis-p3-payload-01 . . . . . . . . . 88 223 F.6. Since draft-ietf-httpbis-p2-semantics-02 . . . . . . . . 88 224 F.7. Since draft-ietf-httpbis-p3-payload-02 . . . . . . . . . 89 225 F.8. Since draft-ietf-httpbis-p2-semantics-03 . . . . . . . . 89 226 F.9. Since draft-ietf-httpbis-p3-payload-03 . . . . . . . . . 89 227 F.10. Since draft-ietf-httpbis-p2-semantics-04 . . . . . . . . 90 228 F.11. Since draft-ietf-httpbis-p3-payload-04 . . . . . . . . . 90 229 F.12. Since draft-ietf-httpbis-p2-semantics-05 . . . . . . . . 91 230 F.13. Since draft-ietf-httpbis-p3-payload-05 . . . . . . . . . 91 231 F.14. Since draft-ietf-httpbis-p2-semantics-06 . . . . . . . . 91 232 F.15. Since draft-ietf-httpbis-p3-payload-06 . . . . . . . . . 92 233 F.16. Since draft-ietf-httpbis-p2-semantics-07 . . . . . . . . 92 234 F.17. Since draft-ietf-httpbis-p3-payload-07 . . . . . . . . . 92 235 F.18. Since draft-ietf-httpbis-p2-semantics-08 . . . . . . . . 93 236 F.19. Since draft-ietf-httpbis-p3-payload-08 . . . . . . . . . 93 237 F.20. Since draft-ietf-httpbis-p2-semantics-09 . . . . . . . . 93 238 F.21. Since draft-ietf-httpbis-p3-payload-09 . . . . . . . . . 94 239 F.22. Since draft-ietf-httpbis-p2-semantics-10 . . . . . . . . 94 240 F.23. Since draft-ietf-httpbis-p3-payload-10 . . . . . . . . . 95 241 F.24. Since draft-ietf-httpbis-p2-semantics-11 . . . . . . . . 95 242 F.25. Since draft-ietf-httpbis-p3-payload-11 . . . . . . . . . 96 243 F.26. Since draft-ietf-httpbis-p2-semantics-12 . . . . . . . . 96 244 F.27. Since draft-ietf-httpbis-p3-payload-12 . . . . . . . . . 97 245 F.28. Since draft-ietf-httpbis-p2-semantics-13 . . . . . . . . 97 246 F.29. Since draft-ietf-httpbis-p3-payload-13 . . . . . . . . . 98 247 F.30. Since draft-ietf-httpbis-p2-semantics-14 . . . . . . . . 98 248 F.31. Since draft-ietf-httpbis-p3-payload-14 . . . . . . . . . 98 249 F.32. Since draft-ietf-httpbis-p2-semantics-15 . . . . . . . . 98 250 F.33. Since draft-ietf-httpbis-p3-payload-15 . . . . . . . . . 99 251 F.34. Since draft-ietf-httpbis-p2-semantics-16 . . . . . . . . 99 252 F.35. Since draft-ietf-httpbis-p3-payload-16 . . . . . . . . . 99 253 F.36. Since draft-ietf-httpbis-p2-semantics-17 . . . . . . . . 99 254 F.37. Since draft-ietf-httpbis-p3-payload-17 . . . . . . . . . 100 255 F.38. Since draft-ietf-httpbis-p2-semantics-18 . . . . . . . . 100 256 F.39. Since draft-ietf-httpbis-p3-payload-18 . . . . . . . . . 101 257 F.40. Since draft-ietf-httpbis-p2-semantics-19 and 258 draft-ietf-httpbis-p3-payload-19 . . . . . . . . . . . . 101 259 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 261 1. Introduction 263 Each HTTP message is either a request or a response. A server 264 listens on a connection for a request, parses each message received, 265 interprets the message semantics in relation to the identified 266 request target, and responds to that request with one or more 267 response messages. This document defines HTTP/1.1 request and 268 response semantics in terms of the architecture, syntax notation, and 269 conformance criteria defined in [Part1]. 271 HTTP provides a uniform interface for interacting with resources 272 regardless of their type, nature, or implementation. HTTP semantics 273 includes the intentions defined by each request method, extensions to 274 those semantics that might be described in request header fields, the 275 meaning of status codes to indicate a machine-readable response, and 276 additional control data and resource metadata that might be given in 277 response header fields. 279 In addition, this document defines the payload of messages (a.k.a., 280 content), the associated metadata header fields that define how the 281 payload is intended to be interpreted by a recipient, the request 282 header fields that might influence content selection, and the various 283 selection algorithms that are collectively referred to as "content 284 negotiation". 286 Note: This document is currently disorganized in order to minimize 287 changes between drafts and enable reviewers to see the smaller 288 errata changes. A future draft will reorganize the sections to 289 better reflect the content. In particular, the sections will be 290 ordered according to the typical processing of an HTTP request 291 message (after message parsing): resource mapping, methods, 292 request modifying header fields, response status, status modifying 293 header fields, and resource metadata. The current mess reflects 294 how widely dispersed these topics and associated requirements had 295 become in [RFC2616]. 297 1.1. Conformance and Error Handling 299 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 300 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 301 document are to be interpreted as described in [RFC2119]. 303 This specification targets conformance criteria according to the role 304 of a participant in HTTP communication. Hence, HTTP requirements are 305 placed on senders, recipients, clients, servers, user agents, 306 intermediaries, origin servers, proxies, gateways, or caches, 307 depending on what behavior is being constrained by the requirement. 308 See Section 2 of [Part1] for definitions of these terms. 310 The verb "generate" is used instead of "send" where a requirement 311 differentiates between creating a protocol element and merely 312 forwarding a received element downstream. 314 An implementation is considered conformant if it complies with all of 315 the requirements associated with the roles it partakes in HTTP. Note 316 that SHOULD-level requirements are relevant here, unless one of the 317 documented exceptions is applicable. 319 This document also uses ABNF to define valid protocol elements 320 (Section 1.2). In addition to the prose requirements placed upon 321 them, senders MUST NOT generate protocol elements that do not match 322 the grammar defined by the ABNF rules for those protocol elements 323 that are applicable to the sender's role. If a received protocol 324 element is processed, the recipient MUST be able to parse any value 325 that would match the ABNF rules for that protocol element, excluding 326 only those rules not applicable to the recipient's role. 328 Unless noted otherwise, a recipient MAY attempt to recover a usable 329 protocol element from an invalid construct. HTTP does not define 330 specific error handling mechanisms except when they have a direct 331 impact on security, since different applications of the protocol 332 require different error handling strategies. For example, a Web 333 browser might wish to transparently recover from a response where the 334 Location header field doesn't parse according to the ABNF, whereas a 335 systems control client might consider any form of error recovery to 336 be dangerous. 338 1.2. Syntax Notation 340 This specification uses the Augmented Backus-Naur Form (ABNF) 341 notation of [RFC5234] with the list rule extension defined in Section 342 1.2 of [Part1]. Appendix D describes rules imported from other 343 documents. Appendix E shows the collected ABNF with the list rule 344 expanded. 346 2. Methods 348 The method token indicates the request method to be performed on the 349 target resource (Section 5.5 of [Part1]). The method is case- 350 sensitive. 352 method = token 354 The list of methods allowed by a resource can be specified in an 355 Allow header field (Section 9.5). The status code of the response 356 always notifies the client whether a method is currently allowed on a 357 resource, since the set of allowed methods can change dynamically. 359 An origin server SHOULD respond with the status code 405 (Method Not 360 Allowed) if the method is known by the origin server but not allowed 361 for the resource, and 501 (Not Implemented) if the method is 362 unrecognized or not implemented by the origin server. The methods 363 GET and HEAD MUST be supported by all general-purpose servers. All 364 other methods are OPTIONAL; however, if the above methods are 365 implemented, they MUST be implemented with the same semantics as 366 those specified in Section 2.3. 368 2.1. Safe and Idempotent Methods 370 2.1.1. Safe Methods 372 Implementers need to be aware that the software represents the user 373 in their interactions over the Internet, and need to allow the user 374 to be aware of any actions they take which might have an unexpected 375 significance to themselves or others. 377 In particular, the convention has been established that the GET, 378 HEAD, OPTIONS, and TRACE request methods SHOULD NOT have the 379 significance of taking an action other than retrieval. These request 380 methods ought to be considered "safe". This allows user agents to 381 represent other methods, such as POST, PUT and DELETE, in a special 382 way, so that the user is made aware of the fact that a possibly 383 unsafe action is being requested. 385 Naturally, it is not possible to ensure that the server does not 386 generate side-effects as a result of performing a GET request; in 387 fact, some dynamic resources consider that a feature. The important 388 distinction here is that the user did not request the side-effects, 389 so therefore cannot be held accountable for them. 391 2.1.2. Idempotent Methods 393 Request methods can also have the property of "idempotence" in that, 394 aside from error or expiration issues, the intended effect of 395 multiple identical requests is the same as for a single request. 396 PUT, DELETE, and all safe request methods are idempotent. It is 397 important to note that idempotence refers only to changes requested 398 by the client: a server is free to change its state due to multiple 399 requests for the purpose of tracking those requests, versioning of 400 results, etc. 402 2.2. Method Registry 404 The HTTP Method Registry defines the name space for the method token 405 in the Request line of an HTTP request. 407 Registrations MUST include the following fields: 409 o Method Name (see Section 2) 411 o Safe ("yes" or "no", see Section 2.1.1) 413 o Idempotent ("yes" or "no", see Section 2.1.1) 415 o Pointer to specification text 417 Values to be added to this name space require IETF Review (see 418 [RFC5226], Section 4.1). 420 The registry itself is maintained at 421 . 423 2.2.1. Considerations for New Methods 425 When it is necessary to express new semantics for a HTTP request that 426 aren't specific to a single application or media type, and currently 427 defined methods are inadequate, it might be appropriate to register a 428 new method. 430 HTTP methods are generic; that is, they are potentially applicable to 431 any resource, not just one particular media type, "type" of resource, 432 or application. As such, it is preferred that new HTTP methods be 433 registered in a document that isn't specific to a single application, 434 so that this is clear. 436 Due to the parsing rules defined in Section 3.3 of [Part1], 437 definitions of HTTP methods cannot prohibit the presence of a message 438 body on either the request or the response message (with responses to 439 HEAD requests being the single exception). Definitions of new 440 methods cannot change this rule, but they can specify that only zero- 441 length bodies (as opposed to absent bodies) are allowed. 443 New method definitions need to indicate whether they are safe 444 (Section 2.1.1), what semantics (if any) the request body has, and 445 whether they are idempotent (Section 2.1.2). They also need to state 446 whether they can be cached ([Part6]); in particular under what 447 conditions a cache can store the response, and under what conditions 448 such a stored response can be used to satisfy a subsequent request. 450 2.3. Method Definitions 451 2.3.1. OPTIONS 453 The OPTIONS method requests information about the communication 454 options available on the request/response chain identified by the 455 effective request URI. This method allows a client to determine the 456 options and/or requirements associated with a resource, or the 457 capabilities of a server, without implying a resource action or 458 initiating a resource retrieval. 460 Responses to the OPTIONS method are not cacheable. 462 If the OPTIONS request includes a message body (as indicated by the 463 presence of Content-Length or Transfer-Encoding), then the media type 464 MUST be indicated by a Content-Type field. Although this 465 specification does not define any use for such a body, future 466 extensions to HTTP might use the OPTIONS body to make more detailed 467 queries on the server. 469 If the request-target (Section 5.3 of [Part1]) is an asterisk ("*"), 470 the OPTIONS request is intended to apply to the server in general 471 rather than to a specific resource. Since a server's communication 472 options typically depend on the resource, the "*" request is only 473 useful as a "ping" or "no-op" type of method; it does nothing beyond 474 allowing the client to test the capabilities of the server. For 475 example, this can be used to test a proxy for HTTP/1.1 conformance 476 (or lack thereof). 478 If the request-target is not an asterisk, the OPTIONS request applies 479 only to the options that are available when communicating with that 480 resource. 482 A 200 (OK) response SHOULD include any header fields that indicate 483 optional features implemented by the server and applicable to that 484 resource (e.g., Allow), possibly including extensions not defined by 485 this specification. The response body, if any, SHOULD also include 486 information about the communication options. The format for such a 487 body is not defined by this specification, but might be defined by 488 future extensions to HTTP. Content negotiation MAY be used to select 489 the appropriate response format. If no response body is included, 490 the response MUST include a Content-Length field with a field-value 491 of "0". 493 The Max-Forwards header field MAY be used to target a specific proxy 494 in the request chain (see Section 9.14). If no Max-Forwards field is 495 present in the request, then the forwarded request MUST NOT include a 496 Max-Forwards field. 498 2.3.2. GET 500 The GET method requests transfer of a current representation of the 501 target resource. 503 If the target resource is a data-producing process, it is the 504 produced data which shall be returned as the representation in the 505 response and not the source text of the process, unless that text 506 happens to be the output of the process. 508 The semantics of the GET method change to a "conditional GET" if the 509 request message includes an If-Modified-Since, If-Unmodified-Since, 510 If-Match, If-None-Match, or If-Range header field ([Part4]). A 511 conditional GET requests that the representation be transferred only 512 under the circumstances described by the conditional header field(s). 513 The conditional GET request is intended to reduce unnecessary network 514 usage by allowing cached representations to be refreshed without 515 requiring multiple requests or transferring data already held by the 516 client. 518 The semantics of the GET method change to a "partial GET" if the 519 request message includes a Range header field ([Part5]). A partial 520 GET requests that only part of the representation be transferred, as 521 described in Section 5.4 of [Part5]. The partial GET request is 522 intended to reduce unnecessary network usage by allowing partially- 523 retrieved representations to be completed without transferring data 524 already held by the client. 526 Bodies on GET requests have no defined semantics. Note that sending 527 a body on a GET request might cause some existing implementations to 528 reject the request. 530 The response to a GET request is cacheable and MAY be used to satisfy 531 subsequent GET and HEAD requests (see [Part6]). 533 See Section 11.2 for security considerations when used for forms. 535 2.3.3. HEAD 537 The HEAD method is identical to GET except that the server MUST NOT 538 return a message body in the response. The metadata contained in the 539 HTTP header fields in response to a HEAD request SHOULD be identical 540 to the information sent in response to a GET request. This method 541 can be used for obtaining metadata about the representation implied 542 by the request without transferring the representation body. This 543 method is often used for testing hypertext links for validity, 544 accessibility, and recent modification. 546 The response to a HEAD request is cacheable and MAY be used to 547 satisfy a subsequent HEAD request. It also has potential side 548 effects on previously stored responses to GET; see Section 5 of 549 [Part6]. 551 Bodies on HEAD requests have no defined semantics. Note that sending 552 a body on a HEAD request might cause some existing implementations to 553 reject the request. 555 2.3.4. POST 557 The POST method requests that the origin server accept the 558 representation enclosed in the request as data to be processed by the 559 target resource. POST is designed to allow a uniform method to cover 560 the following functions: 562 o Annotation of existing resources; 564 o Posting a message to a bulletin board, newsgroup, mailing list, or 565 similar group of articles; 567 o Providing a block of data, such as the result of submitting a 568 form, to a data-handling process; 570 o Extending a database through an append operation. 572 The actual function performed by the POST method is determined by the 573 server and is usually dependent on the effective request URI. 575 The action performed by the POST method might not result in a 576 resource that can be identified by a URI. In this case, either 200 577 (OK) or 204 (No Content) is the appropriate response status code, 578 depending on whether or not the response includes a representation 579 that describes the result. 581 If a resource has been created on the origin server, the response 582 SHOULD be 201 (Created) and contain a representation which describes 583 the status of the request and refers to the new resource, and a 584 Location header field (see Section 9.13). 586 Responses to POST requests are only cacheable when they include 587 explicit freshness information (see Section 4.1.1 of [Part6]). A 588 cached POST response with a Content-Location header field (see 589 Section 9.8) whose value is the effective Request URI MAY be used to 590 satisfy subsequent GET and HEAD requests. 592 Note that POST caching is not widely implemented. However, the 303 593 (See Other) response can be used to direct the user agent to retrieve 594 a cacheable representation of the resource. 596 2.3.5. PUT 598 The PUT method requests that the state of the target resource be 599 created or replaced with the state defined by the representation 600 enclosed in the request message payload. A successful PUT of a given 601 representation would suggest that a subsequent GET on that same 602 target resource will result in an equivalent representation being 603 returned in a 200 (OK) response. However, there is no guarantee that 604 such a state change will be observable, since the target resource 605 might be acted upon by other user agents in parallel, or might be 606 subject to dynamic processing by the origin server, before any 607 subsequent GET is received. A successful response only implies that 608 the user agent's intent was achieved at the time of its processing by 609 the origin server. 611 If the target resource does not have a current representation and the 612 PUT successfully creates one, then the origin server MUST inform the 613 user agent by sending a 201 (Created) response. If the target 614 resource does have a current representation and that representation 615 is successfully modified in accordance with the state of the enclosed 616 representation, then either a 200 (OK) or 204 (No Content) response 617 SHOULD be sent to indicate successful completion of the request. 619 Unrecognized header fields SHOULD be ignored (i.e., not saved as part 620 of the resource state). 622 An origin server SHOULD verify that the PUT representation is 623 consistent with any constraints which the server has for the target 624 resource that cannot or will not be changed by the PUT. This is 625 particularly important when the origin server uses internal 626 configuration information related to the URI in order to set the 627 values for representation metadata on GET responses. When a PUT 628 representation is inconsistent with the target resource, the origin 629 server SHOULD either make them consistent, by transforming the 630 representation or changing the resource configuration, or respond 631 with an appropriate error message containing sufficient information 632 to explain why the representation is unsuitable. The 409 (Conflict) 633 or 415 (Unsupported Media Type) status codes are suggested, with the 634 latter being specific to constraints on Content-Type values. 636 For example, if the target resource is configured to always have a 637 Content-Type of "text/html" and the representation being PUT has a 638 Content-Type of "image/jpeg", then the origin server SHOULD do one 639 of: 641 a. reconfigure the target resource to reflect the new media type; 643 b. transform the PUT representation to a format consistent with that 644 of the resource before saving it as the new resource state; or, 646 c. reject the request with a 415 (Unsupported Media Type) response 647 indicating that the target resource is limited to "text/html", 648 perhaps including a link to a different resource that would be a 649 suitable target for the new representation. 651 HTTP does not define exactly how a PUT method affects the state of an 652 origin server beyond what can be expressed by the intent of the user 653 agent request and the semantics of the origin server response. It 654 does not define what a resource might be, in any sense of that word, 655 beyond the interface provided via HTTP. It does not define how 656 resource state is "stored", nor how such storage might change as a 657 result of a change in resource state, nor how the origin server 658 translates resource state into representations. Generally speaking, 659 all implementation details behind the resource interface are 660 intentionally hidden by the server. 662 The fundamental difference between the POST and PUT methods is 663 highlighted by the different intent for the target resource. The 664 target resource in a POST request is intended to handle the enclosed 665 representation as a data-accepting process, such as for a gateway to 666 some other protocol or a document that accepts annotations. In 667 contrast, the target resource in a PUT request is intended to take 668 the enclosed representation as a new or replacement value. Hence, 669 the intent of PUT is idempotent and visible to intermediaries, even 670 though the exact effect is only known by the origin server. 672 Proper interpretation of a PUT request presumes that the user agent 673 knows what target resource is desired. A service that is intended to 674 select a proper URI on behalf of the client, after receiving a state- 675 changing request, SHOULD be implemented using the POST method rather 676 than PUT. If the origin server will not make the requested PUT state 677 change to the target resource and instead wishes to have it applied 678 to a different resource, such as when the resource has been moved to 679 a different URI, then the origin server MUST send a 301 (Moved 680 Permanently) response; the user agent MAY then make its own decision 681 regarding whether or not to redirect the request. 683 A PUT request applied to the target resource MAY have side-effects on 684 other resources. For example, an article might have a URI for 685 identifying "the current version" (a resource) which is separate from 686 the URIs identifying each particular version (different resources 687 that at one point shared the same state as the current version 688 resource). A successful PUT request on "the current version" URI 689 might therefore create a new version resource in addition to changing 690 the state of the target resource, and might also cause links to be 691 added between the related resources. 693 An origin server SHOULD reject any PUT request that contains a 694 Content-Range header field (Section 5.2 of [Part5]), since it might 695 be misinterpreted as partial content (or might be partial content 696 that is being mistakenly PUT as a full representation). Partial 697 content updates are possible by targeting a separately identified 698 resource with state that overlaps a portion of the larger resource, 699 or by using a different method that has been specifically defined for 700 partial updates (for example, the PATCH method defined in [RFC5789]). 702 Responses to the PUT method are not cacheable. If a PUT request 703 passes through a cache that has one or more stored responses for the 704 effective request URI, those stored responses will be invalidated 705 (see Section 6 of [Part6]). 707 2.3.6. DELETE 709 The DELETE method requests that the origin server delete the target 710 resource. This method MAY be overridden by human intervention (or 711 other means) on the origin server. The client cannot be guaranteed 712 that the operation has been carried out, even if the status code 713 returned from the origin server indicates that the action has been 714 completed successfully. However, the server SHOULD NOT indicate 715 success unless, at the time the response is given, it intends to 716 delete the resource or move it to an inaccessible location. 718 A successful response SHOULD be 200 (OK) if the response includes a 719 representation describing the status, 202 (Accepted) if the action 720 has not yet been enacted, or 204 (No Content) if the action has been 721 enacted but the response does not include a representation. 723 Bodies on DELETE requests have no defined semantics. Note that 724 sending a body on a DELETE request might cause some existing 725 implementations to reject the request. 727 Responses to the DELETE method are not cacheable. If a DELETE 728 request passes through a cache that has one or more stored responses 729 for the effective request URI, those stored responses will be 730 invalidated (see Section 6 of [Part6]). 732 2.3.7. TRACE 734 The TRACE method requests a remote, application-layer loop-back of 735 the request message. The final recipient of the request SHOULD 736 reflect the message received back to the client as the message body 737 of a 200 (OK) response. The final recipient is either the origin 738 server or the first proxy to receive a Max-Forwards value of zero (0) 739 in the request (see Section 9.14). A TRACE request MUST NOT include 740 a message body. 742 TRACE allows the client to see what is being received at the other 743 end of the request chain and use that data for testing or diagnostic 744 information. The value of the Via header field (Section 6.2 of 745 [Part1]) is of particular interest, since it acts as a trace of the 746 request chain. Use of the Max-Forwards header field allows the 747 client to limit the length of the request chain, which is useful for 748 testing a chain of proxies forwarding messages in an infinite loop. 750 If the request is valid, the response SHOULD have a Content-Type of 751 "message/http" (see Section 7.3.1 of [Part1]) and contain a message 752 body that encloses a copy of the entire request message. Responses 753 to the TRACE method are not cacheable. 755 2.3.8. CONNECT 757 The CONNECT method requests that the proxy establish a tunnel to the 758 request-target and, if successful, thereafter restrict its behavior 759 to blind forwarding of packets until the connection is closed. 761 When using CONNECT, the request-target MUST use the authority form 762 (Section 5.3 of [Part1]); i.e., the request-target consists of only 763 the host name and port number of the tunnel destination, separated by 764 a colon. For example, 766 CONNECT server.example.com:80 HTTP/1.1 767 Host: server.example.com:80 769 Any 2xx (Successful) response to a CONNECT request indicates that the 770 proxy has established a connection to the requested host and port, 771 and has switched to tunneling the current connection to that server 772 connection. The tunneled data from the server begins immediately 773 after the blank line that concludes the successful response's header 774 block. 776 A server SHOULD NOT send any Transfer-Encoding or Content-Length 777 header fields in a successful response. A client MUST ignore any 778 Content-Length or Transfer-Encoding header fields received in a 779 successful response. 781 Any response other than a successful response indicates that the 782 tunnel has not yet been formed and that the connection remains 783 governed by HTTP. 785 Proxy authentication might be used to establish the authority to 786 create a tunnel: 788 CONNECT server.example.com:80 HTTP/1.1 789 Host: server.example.com:80 790 Proxy-Authorization: basic aGVsbG86d29ybGQ= 792 A message body on a CONNECT request has no defined semantics. 793 Sending a body on a CONNECT request might cause existing 794 implementations to reject the request. 796 Similar to a pipelined HTTP/1.1 request, data to be tunneled from 797 client to server MAY be sent immediately after the request (before a 798 response is received). The usual caveats also apply: data can be 799 discarded if the eventual response is negative, and the connection 800 can be reset with no response if more than one TCP segment is 801 outstanding. 803 It might be the case that the proxy itself can only reach the 804 requested origin server through another proxy. In this case, the 805 first proxy SHOULD make a CONNECT request of that next proxy, 806 requesting a tunnel to the authority. A proxy MUST NOT respond with 807 any 2xx status code unless it has either a direct or tunnel 808 connection established to the authority. 810 If at any point either one of the peers gets disconnected, any 811 outstanding data that came from that peer will be passed to the other 812 one, and after that also the other connection will be terminated by 813 the proxy. If there is outstanding data to that peer undelivered, 814 that data will be discarded. 816 An origin server which receives a CONNECT request for itself MAY 817 respond with a 2xx status code to indicate that a connection is 818 established. However, most origin servers do not implement CONNECT. 820 3. Header Fields 822 Header fields are key value pairs that can be used to communicate 823 data about the message, its payload, the target resource, or about 824 the connection itself (i.e., control data). See Section 3.2 of 825 [Part1] for a general definition of their syntax. 827 3.1. Considerations for Creating Header Fields 829 New header fields are registered using the procedures described in 830 [RFC3864]. 832 The requirements for header field names are defined in Section 4.1 of 833 [RFC3864]. Authors of specifications defining new fields are advised 834 to keep the name as short as practical, and not to prefix them with 835 "X-" if they are to be registered (either immediately or in the 836 future). 838 New header field values typically have their syntax defined using 839 ABNF ([RFC5234]), using the extension defined in Appendix B of 840 [Part1] as necessary, and are usually constrained to the range of 841 ASCII characters. Header fields needing a greater range of 842 characters can use an encoding such as the one defined in [RFC5987]. 844 Because commas (",") are used as a generic delimiter between field- 845 values, they need to be treated with care if they are allowed in the 846 field-value's payload. Typically, components that might contain a 847 comma are protected with double-quotes using the quoted-string ABNF 848 production (Section 3.2.4 of [Part1]). 850 For example, a textual date and a URI (either of which might contain 851 a comma) could be safely carried in field-values like these: 853 Example-URI-Field: "http://example.com/a.html,foo", 854 "http://without-a-comma.example.com/" 855 Example-Date-Field: "Sat, 04 May 1996", "Wed, 14 Sep 2005" 857 Note that double quote delimiters almost always are used with the 858 quoted-string production; using a different syntax inside double 859 quotes will likely cause unnecessary confusion. 861 Many header fields use a format including (case-insensitively) named 862 parameters (for instance, Content-Type, defined in Section 9.9). 863 Allowing both unquoted (token) and quoted (quoted-string) syntax for 864 the parameter value enables recipients to use existing parser 865 components. When allowing both forms, the meaning of a parameter 866 value ought to be independent of the syntax used for it (for an 867 example, see the notes on parameter handling for media types in 868 Section 5.5). 870 Authors of specifications defining new header fields are advised to 871 consider documenting: 873 o Whether the field is a single value, or whether it can be a list 874 (delimited by commas; see Section 3.2 of [Part1]). 876 If it does not use the list syntax, document how to treat messages 877 where the header field occurs multiple times (a sensible default 878 would be to ignore the header field, but this might not always be 879 the right choice). 881 Note that intermediaries and software libraries might combine 882 multiple header field instances into a single one, despite the 883 header field not allowing this. A robust format enables 884 recipients to discover these situations (good example: "Content- 885 Type", as the comma can only appear inside quoted strings; bad 886 example: "Location", as a comma can occur inside a URI). 888 o Under what conditions the header field can be used; e.g., only in 889 responses or requests, in all messages, only on responses to a 890 particular request method. 892 o Whether it is appropriate to list the field-name in the Connection 893 header field (i.e., if the header field is to be hop-by-hop, see 894 Section 6.1 of [Part1]). 896 o Under what conditions intermediaries are allowed to modify the 897 header field's value, insert or delete it. 899 o How the header field might interact with caching (see [Part6]). 901 o Whether the header field is useful or allowable in trailers (see 902 Section 4.1 of [Part1]). 904 o Whether the header field ought to be preserved across redirects. 906 3.2. Request Header Fields 908 The request header fields allow the client to pass additional 909 information about the request, and about the client itself, to the 910 server. These fields act as request modifiers, with semantics 911 equivalent to the parameters on a programming language method 912 invocation. 914 +---------------------+------------------------+ 915 | Header Field Name | Defined in... | 916 +---------------------+------------------------+ 917 | Accept | Section 9.1 | 918 | Accept-Charset | Section 9.2 | 919 | Accept-Encoding | Section 9.3 | 920 | Accept-Language | Section 9.4 | 921 | Authorization | Section 4.1 of [Part7] | 922 | Expect | Section 9.11 | 923 | From | Section 9.12 | 924 | Host | Section 5.4 of [Part1] | 925 | If-Match | Section 3.1 of [Part4] | 926 | If-Modified-Since | Section 3.3 of [Part4] | 927 | If-None-Match | Section 3.2 of [Part4] | 928 | If-Range | Section 5.3 of [Part5] | 929 | If-Unmodified-Since | Section 3.4 of [Part4] | 930 | Max-Forwards | Section 9.14 | 931 | Proxy-Authorization | Section 4.3 of [Part7] | 932 | Range | Section 5.4 of [Part5] | 933 | Referer | Section 9.15 | 934 | TE | Section 4.3 of [Part1] | 935 | User-Agent | Section 9.18 | 936 +---------------------+------------------------+ 938 3.3. Response Header Fields 940 The response header fields allow the server to pass additional 941 information about the response which cannot be placed in the status- 942 line. These header fields give information about the server and 943 about further access to the target resource (Section 5.5 of [Part1]). 945 +--------------------+------------------------+ 946 | Header Field Name | Defined in... | 947 +--------------------+------------------------+ 948 | Accept-Ranges | Section 5.1 of [Part5] | 949 | Age | Section 7.1 of [Part6] | 950 | Allow | Section 9.5 | 951 | Date | Section 9.10 | 952 | ETag | Section 2.3 of [Part4] | 953 | Location | Section 9.13 | 954 | Proxy-Authenticate | Section 4.2 of [Part7] | 955 | Retry-After | Section 9.16 | 956 | Server | Section 9.17 | 957 | Vary | Section 7.5 of [Part6] | 958 | WWW-Authenticate | Section 4.4 of [Part7] | 959 +--------------------+------------------------+ 961 4. Status Codes 963 The status-code element is a 3-digit integer result code of the 964 attempt to understand and satisfy the request. 966 HTTP status codes are extensible. HTTP applications are not required 967 to understand the meaning of all registered status codes, though such 968 understanding is obviously desirable. However, applications MUST 969 understand the class of any status code, as indicated by the first 970 digit, and treat any unrecognized response as being equivalent to the 971 x00 status code of that class, with the exception that an 972 unrecognized response MUST NOT be cached. For example, if an 973 unrecognized status code of 431 is received by the client, it can 974 safely assume that there was something wrong with its request and 975 treat the response as if it had received a 400 status code. In such 976 cases, user agents SHOULD present to the user the representation 977 enclosed with the response, since that representation is likely to 978 include human-readable information which will explain the unusual 979 status. 981 The first digit of the status-code defines the class of response. 982 The last two digits do not have any categorization role. There are 5 983 values for the first digit: 985 o 1xx (Informational): Request received, continuing process 987 o 2xx (Successful): The action was successfully received, 988 understood, and accepted 990 o 3xx (Redirection): Further action needs to be taken in order to 991 complete the request 993 o 4xx (Client Error): The request contains bad syntax or cannot be 994 fulfilled 996 o 5xx (Server Error): The server failed to fulfill an apparently 997 valid request 999 For most status codes the response can carry a payload, in which case 1000 a Content-Type header field indicates the payload's media type 1001 (Section 9.9). 1003 4.1. Overview of Status Codes 1005 The status codes listed below are defined in this specification, 1006 Section 4 of [Part4], Section 3 of [Part5], and Section 3 of [Part7]. 1007 The reason phrases listed here are only recommendations -- they can 1008 be replaced by local equivalents without affecting the protocol. 1010 +-------------+------------------------------+----------------------+ 1011 | status-code | reason-phrase | Defined in... | 1012 +-------------+------------------------------+----------------------+ 1013 | 100 | Continue | Section 4.3.1 | 1014 | 101 | Switching Protocols | Section 4.3.2 | 1015 | 200 | OK | Section 4.4.1 | 1016 | 201 | Created | Section 4.4.2 | 1017 | 202 | Accepted | Section 4.4.3 | 1018 | 203 | Non-Authoritative | Section 4.4.4 | 1019 | | Information | | 1020 | 204 | No Content | Section 4.4.5 | 1021 | 205 | Reset Content | Section 4.4.6 | 1022 | 206 | Partial Content | Section 3.1 of | 1023 | | | [Part5] | 1024 | 300 | Multiple Choices | Section 4.5.1 | 1025 | 301 | Moved Permanently | Section 4.5.2 | 1026 | 302 | Found | Section 4.5.3 | 1027 | 303 | See Other | Section 4.5.4 | 1028 | 304 | Not Modified | Section 4.1 of | 1029 | | | [Part4] | 1030 | 305 | Use Proxy | Section 4.5.5 | 1031 | 307 | Temporary Redirect | Section 4.5.7 | 1032 | 400 | Bad Request | Section 4.6.1 | 1033 | 401 | Unauthorized | Section 3.1 of | 1034 | | | [Part7] | 1035 | 402 | Payment Required | Section 4.6.2 | 1036 | 403 | Forbidden | Section 4.6.3 | 1037 | 404 | Not Found | Section 4.6.4 | 1038 | 405 | Method Not Allowed | Section 4.6.5 | 1039 | 406 | Not Acceptable | Section 4.6.6 | 1040 | 407 | Proxy Authentication | Section 3.2 of | 1041 | | Required | [Part7] | 1042 | 408 | Request Time-out | Section 4.6.7 | 1043 | 409 | Conflict | Section 4.6.8 | 1044 | 410 | Gone | Section 4.6.9 | 1045 | 411 | Length Required | Section 4.6.10 | 1046 | 412 | Precondition Failed | Section 4.2 of | 1047 | | | [Part4] | 1048 | 413 | Request Representation Too | Section 4.6.11 | 1049 | | Large | | 1050 | 414 | URI Too Long | Section 4.6.12 | 1051 | 415 | Unsupported Media Type | Section 4.6.13 | 1052 | 416 | Requested range not | Section 3.2 of | 1053 | | satisfiable | [Part5] | 1054 | 417 | Expectation Failed | Section 4.6.14 | 1055 | 426 | Upgrade Required | Section 4.6.15 | 1056 | 500 | Internal Server Error | Section 4.7.1 | 1057 | 501 | Not Implemented | Section 4.7.2 | 1058 | 502 | Bad Gateway | Section 4.7.3 | 1059 | 503 | Service Unavailable | Section 4.7.4 | 1060 | 504 | Gateway Time-out | Section 4.7.5 | 1061 | 505 | HTTP Version not supported | Section 4.7.6 | 1062 +-------------+------------------------------+----------------------+ 1064 Note that this list is not exhaustive -- it does not include 1065 extension status codes defined in other specifications. 1067 4.2. Status Code Registry 1069 The HTTP Status Code Registry defines the name space for the status- 1070 code token in the status-line of an HTTP response. 1072 Values to be added to this name space require IETF Review (see 1073 [RFC5226], Section 4.1). 1075 The registry itself is maintained at 1076 . 1078 4.2.1. Considerations for New Status Codes 1080 When it is necessary to express new semantics for a HTTP response 1081 that aren't specific to a single application or media type, and 1082 currently defined status codes are inadequate, a new status code can 1083 be registered. 1085 HTTP status codes are generic; that is, they are potentially 1086 applicable to any resource, not just one particular media type, 1087 "type" of resource, or application. As such, it is preferred that 1088 new HTTP status codes be registered in a document that isn't specific 1089 to a single application, so that this is clear. 1091 Definitions of new HTTP status codes typically explain the request 1092 conditions that produce a response containing the status code (e.g., 1093 combinations of request header fields and/or method(s)), along with 1094 any interactions with response header fields (e.g., those that are 1095 required, those that modify the semantics of the response). 1097 New HTTP status codes are required to fall under one of the 1098 categories defined in Section 4. To allow existing parsers to 1099 properly handle them, new status codes cannot disallow a response 1100 body, although they can mandate a zero-length response body. They 1101 can require the presence of one or more particular HTTP response 1102 header field(s). 1104 Likewise, their definitions can specify that caches are allowed to 1105 use heuristics to determine their freshness (see [Part6]; by default, 1106 it is not allowed), and can define how to determine the resource 1107 which they carry a representation for (see Section 7.1; by default, 1108 it is anonymous). 1110 4.3. Informational 1xx 1112 This class of status code indicates a provisional response, 1113 consisting only of the status-line and optional header fields, and is 1114 terminated by an empty line. There are no required header fields for 1115 this class of status code. Since HTTP/1.0 did not define any 1xx 1116 status codes, servers MUST NOT send a 1xx response to an HTTP/1.0 1117 client except under experimental conditions. 1119 A client MUST be prepared to accept one or more 1xx status responses 1120 prior to a regular response, even if the client does not expect a 100 1121 (Continue) status message. Unexpected 1xx status responses MAY be 1122 ignored by a user agent. 1124 Proxies MUST forward 1xx responses, unless the connection between the 1125 proxy and its client has been closed, or unless the proxy itself 1126 requested the generation of the 1xx response. (For example, if a 1127 proxy adds an "Expect: 100-continue" field when it forwards a 1128 request, then it need not forward the corresponding 100 (Continue) 1129 response(s).) 1131 4.3.1. 100 Continue 1133 The client SHOULD continue with its request. This interim response 1134 is used to inform the client that the initial part of the request has 1135 been received and has not yet been rejected by the server. The 1136 client SHOULD continue by sending the remainder of the request or, if 1137 the request has already been completed, ignore this response. The 1138 server MUST send a final response after the request has been 1139 completed. See Section 6.4.3 of [Part1] for detailed discussion of 1140 the use and handling of this status code. 1142 4.3.2. 101 Switching Protocols 1144 The server understands and is willing to comply with the client's 1145 request, via the Upgrade message header field (Section 6.5 of 1146 [Part1]), for a change in the application protocol being used on this 1147 connection. The server will switch protocols to those defined by the 1148 response's Upgrade header field immediately after the empty line 1149 which terminates the 101 response. 1151 The protocol SHOULD be switched only when it is advantageous to do 1152 so. For example, switching to a newer version of HTTP is 1153 advantageous over older versions, and switching to a real-time, 1154 synchronous protocol might be advantageous when delivering resources 1155 that use such features. 1157 4.4. Successful 2xx 1159 This class of status code indicates that the client's request was 1160 successfully received, understood, and accepted. 1162 4.4.1. 200 OK 1164 The request has succeeded. The payload returned with the response is 1165 dependent on the method used in the request, for example: 1167 GET a representation of the target resource is sent in the response; 1169 HEAD the same representation as GET, except without the message 1170 body; 1172 POST a representation describing or containing the result of the 1173 action; 1175 TRACE a representation containing the request message as received by 1176 the end server. 1178 Caches MAY use a heuristic (see Section 4.1.2 of [Part6]) to 1179 determine freshness for 200 responses. 1181 4.4.2. 201 Created 1183 The request has been fulfilled and has resulted in one or more new 1184 resources being created. 1186 Newly created resources are typically linked to from the response 1187 payload, with the most relevant URI also being carried in the 1188 Location header field. If the newly created resource's URI is the 1189 same as the Effective Request URI, this information can be omitted 1190 (e.g., in the case of a response to a PUT request). 1192 The origin server MUST create the resource(s) before returning the 1193 201 status code. If the action cannot be carried out immediately, 1194 the server SHOULD respond with 202 (Accepted) response instead. 1196 A 201 response MAY contain an ETag response header field indicating 1197 the current value of the entity-tag for the representation of the 1198 resource identified by the Location header field or, in case the 1199 Location header field was omitted, by the Effective Request URI (see 1200 Section 2.3 of [Part4]). 1202 4.4.3. 202 Accepted 1204 The request has been accepted for processing, but the processing has 1205 not been completed. The request might or might not eventually be 1206 acted upon, as it might be disallowed when processing actually takes 1207 place. There is no facility for re-sending a status code from an 1208 asynchronous operation such as this. 1210 The 202 response is intentionally non-committal. Its purpose is to 1211 allow a server to accept a request for some other process (perhaps a 1212 batch-oriented process that is only run once per day) without 1213 requiring that the user agent's connection to the server persist 1214 until the process is completed. The representation returned with 1215 this response SHOULD include an indication of the request's current 1216 status and either a pointer to a status monitor or some estimate of 1217 when the user can expect the request to be fulfilled. 1219 4.4.4. 203 Non-Authoritative Information 1221 The representation in the response has been transformed or otherwise 1222 modified by a transforming proxy (Section 2.4 of [Part1]). Note that 1223 the behavior of transforming intermediaries is controlled by the no- 1224 transform Cache-Control directive (Section 7.2 of [Part6]). 1226 This status code is only appropriate when the response status code 1227 would have been 200 (OK) otherwise. When the status code before 1228 transformation would have been different, the 214 Transformation 1229 Applied warn-code (Section 7.6 of [Part6]) is appropriate. 1231 Caches MAY use a heuristic (see Section 4.1.2 of [Part6]) to 1232 determine freshness for 203 responses. 1234 4.4.5. 204 No Content 1236 The 204 (No Content) status code indicates that the server has 1237 successfully fulfilled the request and that there is no additional 1238 content to return in the response payload body. Metadata in the 1239 response header fields refer to the target resource and its current 1240 representation after the requested action. 1242 For example, if a 204 status code is received in response to a PUT 1243 request and the response contains an ETag header field, then the PUT 1244 was successful and the ETag field-value contains the entity-tag for 1245 the new representation of that target resource. 1247 The 204 response allows a server to indicate that the action has been 1248 successfully applied to the target resource while implying that the 1249 user agent SHOULD NOT traverse away from its current "document view" 1250 (if any). The server assumes that the user agent will provide some 1251 indication of the success to its user, in accord with its own 1252 interface, and apply any new or updated metadata in the response to 1253 the active representation. 1255 For example, a 204 status code is commonly used with document editing 1256 interfaces corresponding to a "save" action, such that the document 1257 being saved remains available to the user for editing. It is also 1258 frequently used with interfaces that expect automated data transfers 1259 to be prevalent, such as within distributed version control systems. 1261 The 204 response MUST NOT include a message body, and thus is always 1262 terminated by the first empty line after the header fields. 1264 4.4.6. 205 Reset Content 1266 The server has fulfilled the request and the user agent SHOULD reset 1267 the document view which caused the request to be sent. This response 1268 is primarily intended to allow input for actions to take place via 1269 user input, followed by a clearing of the form in which the input is 1270 given so that the user can easily initiate another input action. 1272 The message body included with the response MUST be empty. Note that 1273 receivers still need to parse the response according to the algorithm 1274 defined in Section 3.3 of [Part1]. 1276 4.5. Redirection 3xx 1278 This class of status code indicates that further action needs to be 1279 taken by the user agent in order to fulfill the request. If the 1280 required action involves a subsequent HTTP request, it MAY be carried 1281 out by the user agent without interaction with the user if and only 1282 if the method used in the second request is known to be "safe", as 1283 defined in Section 2.1.1. 1285 There are several types of redirects: 1287 1. Redirects of the request to another URI, either temporarily or 1288 permanently. The new URI is specified in the Location header 1289 field. In this specification, the status codes 301 (Moved 1290 Permanently), 302 (Found), and 307 (Temporary Redirect) fall 1291 under this category. 1293 2. Redirection to a new location that represents an indirect 1294 response to the request, such as the result of a POST operation 1295 to be retrieved with a subsequent GET request. This is status 1296 code 303 (See Other). 1298 3. Redirection offering a choice of matching resources for use by 1299 agent-driven content negotiation (Section 8.2). This is status 1300 code 300 (Multiple Choices). 1302 4. Other kinds of redirection, such as to a cached result (status 1303 code 304 (Not Modified), see Section 4.1 of [Part4]). 1305 Note: In HTTP/1.0, only the status codes 301 (Moved Permanently) 1306 and 302 (Found) were defined for the first type of redirect, and 1307 the second type did not exist at all ([RFC1945], Section 9.3). 1308 However it turned out that web forms using POST expected redirects 1309 to change the operation for the subsequent request to retrieval 1310 (GET). To address this use case, HTTP/1.1 introduced the second 1311 type of redirect with the status code 303 (See Other) ([RFC2068], 1312 Section 10.3.4). As user agents did not change their behavior to 1313 maintain backwards compatibility, the first revision of HTTP/1.1 1314 added yet another status code, 307 (Temporary Redirect), for which 1315 the backwards compatibility problems did not apply ([RFC2616], 1316 Section 10.3.8). Over 10 years later, most user agents still do 1317 method rewriting for status codes 301 and 302, therefore this 1318 specification makes that behavior conformant in case the original 1319 request was POST. 1321 A Location header field on a 3xx response indicates that a client MAY 1322 automatically redirect to the URI provided; see Section 9.13. 1324 Note that for methods not known to be "safe", as defined in 1325 Section 2.1.1, automatic redirection needs to done with care, since 1326 the redirect might change the conditions under which the request was 1327 issued. 1329 Clients SHOULD detect and intervene in cyclical redirections (i.e., 1330 "infinite" redirection loops). 1332 Note: An earlier version of this specification recommended a 1333 maximum of five redirections ([RFC2068], Section 10.3). Content 1334 developers need to be aware that some clients might implement such 1335 a fixed limitation. 1337 4.5.1. 300 Multiple Choices 1339 The target resource has more than one representation, each with its 1340 own specific location, and agent-driven negotiation information 1341 (Section 8) is being provided so that the user (or user agent) can 1342 select a preferred representation by redirecting its request to that 1343 location. 1345 Unless it was a HEAD request, the response SHOULD include a 1346 representation containing a list of representation metadata and 1347 location(s) from which the user or user agent can choose the one most 1348 appropriate. Depending upon the format and the capabilities of the 1349 user agent, selection of the most appropriate choice MAY be performed 1350 automatically. However, this specification does not define any 1351 standard for such automatic selection. 1353 If the server has a preferred choice of representation, it SHOULD 1354 include the specific URI for that representation in the Location 1355 field; user agents MAY use the Location field value for automatic 1356 redirection. 1358 Caches MAY use a heuristic (see Section 4.1.2 of [Part6]) to 1359 determine freshness for 300 responses. 1361 4.5.2. 301 Moved Permanently 1363 The target resource has been assigned a new permanent URI and any 1364 future references to this resource SHOULD use one of the returned 1365 URIs. Clients with link editing capabilities ought to automatically 1366 re-link references to the effective request URI to one or more of the 1367 new references returned by the server, where possible. 1369 Caches MAY use a heuristic (see Section 4.1.2 of [Part6]) to 1370 determine freshness for 301 responses. 1372 The new permanent URI SHOULD be given by the Location field in the 1373 response. A response payload can contain a short hypertext note with 1374 a hyperlink to the new URI(s). 1376 Note: For historic reasons, user agents MAY change the request 1377 method from POST to GET for the subsequent request. If this 1378 behavior is undesired, status code 307 (Temporary Redirect) can be 1379 used instead. 1381 4.5.3. 302 Found 1383 The target resource resides temporarily under a different URI. Since 1384 the redirection might be altered on occasion, the client SHOULD 1385 continue to use the effective request URI for future requests. 1387 The temporary URI SHOULD be given by the Location field in the 1388 response. A response payload can contain a short hypertext note with 1389 a hyperlink to the new URI(s). 1391 Note: For historic reasons, user agents MAY change the request 1392 method from POST to GET for the subsequent request. If this 1393 behavior is undesired, status code 307 (Temporary Redirect) can be 1394 used instead. 1396 4.5.4. 303 See Other 1398 The 303 status code indicates that the server is redirecting the user 1399 agent to a different resource, as indicated by a URI in the Location 1400 header field, that is intended to provide an indirect response to the 1401 original request. In order to satisfy the original request, a user 1402 agent SHOULD perform a retrieval request using the Location URI (a 1403 GET or HEAD request if using HTTP), which can itself be redirected 1404 further, and present the eventual result as an answer to the original 1405 request. Note that the new URI in the Location header field is not 1406 considered equivalent to the effective request URI. 1408 This status code is generally applicable to any HTTP method. It is 1409 primarily used to allow the output of a POST action to redirect the 1410 user agent to a selected resource, since doing so provides the 1411 information corresponding to the POST response in a form that can be 1412 separately identified, bookmarked, and cached independent of the 1413 original request. 1415 A 303 response to a GET request indicates that the requested resource 1416 does not have a representation of its own that can be transferred by 1417 the server over HTTP. The Location URI indicates a resource that is 1418 descriptive of the target resource, such that the follow-on 1419 representation might be useful to recipients without implying that it 1420 adequately represents the target resource. Note that answers to the 1421 questions of what can be represented, what representations are 1422 adequate, and what might be a useful description are outside the 1423 scope of HTTP and thus entirely determined by the URI owner(s). 1425 Except for responses to a HEAD request, the representation of a 303 1426 response SHOULD contain a short hypertext note with a hyperlink to 1427 the Location URI. 1429 4.5.5. 305 Use Proxy 1431 The 305 status code was defined in a previous version of this 1432 specification (see Appendix C), and is now deprecated. 1434 4.5.6. 306 (Unused) 1436 The 306 status code was used in a previous version of the 1437 specification, is no longer used, and the code is reserved. 1439 4.5.7. 307 Temporary Redirect 1441 The target resource resides temporarily under a different URI. Since 1442 the redirection can change over time, the client SHOULD continue to 1443 use the effective request URI for future requests. 1445 The temporary URI SHOULD be given by the Location field in the 1446 response. A response payload can contain a short hypertext note with 1447 a hyperlink to the new URI(s). 1449 Note: This status code is similar to 302 (Found), except that it 1450 does not allow rewriting the request method from POST to GET. 1451 This specification defines no equivalent counterpart for 301 1452 (Moved Permanently) ([draft-reschke-http-status-308], however, 1453 defines the status code 308 (Permanent Redirect) for this 1454 purpose). 1456 4.6. Client Error 4xx 1458 The 4xx class of status code is intended for cases in which the 1459 client seems to have erred. Except when responding to a HEAD 1460 request, the server SHOULD include a representation containing an 1461 explanation of the error situation, and whether it is a temporary or 1462 permanent condition. These status codes are applicable to any 1463 request method. User agents SHOULD display any included 1464 representation to the user. 1466 4.6.1. 400 Bad Request 1468 The server cannot or will not process the request, due to a client 1469 error (e.g., malformed syntax). 1471 4.6.2. 402 Payment Required 1473 This code is reserved for future use. 1475 4.6.3. 403 Forbidden 1477 The server understood the request, but refuses to authorize it. 1478 Providing different user authentication credentials might be 1479 successful, but any credentials that were provided in the request are 1480 insufficient. The request SHOULD NOT be repeated with the same 1481 credentials. 1483 If the request method was not HEAD and the server wishes to make 1484 public why the request has not been fulfilled, it SHOULD describe the 1485 reason for the refusal in the representation. If the server does not 1486 wish to make this information available to the client, the status 1487 code 404 (Not Found) MAY be used instead. 1489 4.6.4. 404 Not Found 1491 The server has not found anything matching the effective request URI. 1492 No indication is given of whether the condition is temporary or 1493 permanent. The 410 (Gone) status code SHOULD be used if the server 1494 knows, through some internally configurable mechanism, that an old 1495 resource is permanently unavailable and has no forwarding address. 1496 This status code is commonly used when the server does not wish to 1497 reveal exactly why the request has been refused, or when no other 1498 response is applicable. 1500 4.6.5. 405 Method Not Allowed 1502 The method specified in the request-line is not allowed for the 1503 target resource. The response MUST include an Allow header field 1504 containing a list of valid methods for the requested resource. 1506 4.6.6. 406 Not Acceptable 1508 The resource identified by the request is only capable of generating 1509 response representations which have content characteristics not 1510 acceptable according to the Accept and Accept-* header fields sent in 1511 the request. 1513 Unless it was a HEAD request, the response SHOULD include a 1514 representation containing a list of available representation 1515 characteristics and location(s) from which the user or user agent can 1516 choose the one most appropriate. Depending upon the format and the 1517 capabilities of the user agent, selection of the most appropriate 1518 choice MAY be performed automatically. However, this specification 1519 does not define any standard for such automatic selection. 1521 Note: HTTP/1.1 servers are allowed to return responses which are 1522 not acceptable according to the accept header fields sent in the 1523 request. In some cases, this might even be preferable to sending 1524 a 406 response. User agents are encouraged to inspect the header 1525 fields of an incoming response to determine if it is acceptable. 1527 If the response could be unacceptable, a user agent SHOULD 1528 temporarily stop receipt of more data and query the user for a 1529 decision on further actions. 1531 4.6.7. 408 Request Timeout 1533 The client did not produce a request within the time that the server 1534 was prepared to wait. The client MAY repeat the request without 1535 modifications at any later time. 1537 4.6.8. 409 Conflict 1539 The request could not be completed due to a conflict with the current 1540 state of the resource. This code is only allowed in situations where 1541 it is expected that the user might be able to resolve the conflict 1542 and resubmit the request. The response body SHOULD include enough 1543 information for the user to recognize the source of the conflict. 1544 Ideally, the response representation would include enough information 1545 for the user or user agent to fix the problem; however, that might 1546 not be possible and is not required. 1548 Conflicts are most likely to occur in response to a PUT request. For 1549 example, if versioning were being used and the representation being 1550 PUT included changes to a resource which conflict with those made by 1551 an earlier (third-party) request, the server might use the 409 1552 response to indicate that it can't complete the request. In this 1553 case, the response representation would likely contain a list of the 1554 differences between the two versions. 1556 4.6.9. 410 Gone 1558 The target resource is no longer available at the server and no 1559 forwarding address is known. This condition is expected to be 1560 considered permanent. Clients with link editing capabilities SHOULD 1561 delete references to the effective request URI after user approval. 1562 If the server does not know, or has no facility to determine, whether 1563 or not the condition is permanent, the status code 404 (Not Found) 1564 SHOULD be used instead. 1566 The 410 response is primarily intended to assist the task of web 1567 maintenance by notifying the recipient that the resource is 1568 intentionally unavailable and that the server owners desire that 1569 remote links to that resource be removed. Such an event is common 1570 for limited-time, promotional services and for resources belonging to 1571 individuals no longer working at the server's site. It is not 1572 necessary to mark all permanently unavailable resources as "gone" or 1573 to keep the mark for any length of time -- that is left to the 1574 discretion of the server owner. 1576 Caches MAY use a heuristic (see Section 4.1.2 of [Part6]) to 1577 determine freshness for 410 responses. 1579 4.6.10. 411 Length Required 1581 The server refuses to accept the request without a defined Content- 1582 Length. The client MAY repeat the request if it adds a valid 1583 Content-Length header field containing the length of the message body 1584 in the request message. 1586 4.6.11. 413 Request Representation Too Large 1588 The server is refusing to process a request because the request 1589 representation is larger than the server is willing or able to 1590 process. The server MAY close the connection to prevent the client 1591 from continuing the request. 1593 If the condition is temporary, the server SHOULD include a Retry- 1594 After header field to indicate that it is temporary and after what 1595 time the client MAY try again. 1597 4.6.12. 414 URI Too Long 1599 The server is refusing to service the request because the effective 1600 request URI is longer than the server is willing to interpret. This 1601 rare condition is only likely to occur when a client has improperly 1602 converted a POST request to a GET request with long query 1603 information, when the client has descended into a URI "black hole" of 1604 redirection (e.g., a redirected URI prefix that points to a suffix of 1605 itself), or when the server is under attack by a client attempting to 1606 exploit security holes present in some servers using fixed-length 1607 buffers for reading or manipulating the request-target. 1609 4.6.13. 415 Unsupported Media Type 1611 The server is refusing to service the request because the request 1612 payload is in a format not supported by this request method on the 1613 target resource. 1615 4.6.14. 417 Expectation Failed 1617 The expectation given in an Expect header field (see Section 9.11) 1618 could not be met by this server, or, if the server is a proxy, the 1619 server has unambiguous evidence that the request could not be met by 1620 the next-hop server. 1622 4.6.15. 426 Upgrade Required 1624 The request can not be completed without a prior protocol upgrade. 1625 This response MUST include an Upgrade header field (Section 6.5 of 1626 [Part1]) specifying the required protocols. 1628 Example: 1630 HTTP/1.1 426 Upgrade Required 1631 Upgrade: HTTP/3.0 1632 Connection: Upgrade 1633 Content-Length: 53 1634 Content-Type: text/plain 1636 This service requires use of the HTTP/3.0 protocol. 1638 The server SHOULD include a message body in the 426 response which 1639 indicates in human readable form the reason for the error and 1640 describes any alternative courses which might be available to the 1641 user. 1643 4.7. Server Error 5xx 1645 Response status codes beginning with the digit "5" indicate cases in 1646 which the server is aware that it has erred or is incapable of 1647 performing the request. Except when responding to a HEAD request, 1648 the server SHOULD include a representation containing an explanation 1649 of the error situation, and whether it is a temporary or permanent 1650 condition. User agents SHOULD display any included representation to 1651 the user. These response codes are applicable to any request method. 1653 4.7.1. 500 Internal Server Error 1655 The server encountered an unexpected condition which prevented it 1656 from fulfilling the request. 1658 4.7.2. 501 Not Implemented 1660 The server does not support the functionality required to fulfill the 1661 request. This is the appropriate response when the server does not 1662 recognize the request method and is not capable of supporting it for 1663 any resource. 1665 4.7.3. 502 Bad Gateway 1667 The server, while acting as a gateway or proxy, received an invalid 1668 response from the upstream server it accessed in attempting to 1669 fulfill the request. 1671 4.7.4. 503 Service Unavailable 1673 The server is currently unable to handle the request due to a 1674 temporary overloading or maintenance of the server. 1676 The implication is that this is a temporary condition which will be 1677 alleviated after some delay. If known, the length of the delay MAY 1678 be indicated in a Retry-After header field (Section 9.16). If no 1679 Retry-After is given, the client SHOULD handle the response as it 1680 would for a 500 (Internal Server Error) response. 1682 Note: The existence of the 503 status code does not imply that a 1683 server has to use it when becoming overloaded. Some servers might 1684 wish to simply refuse the connection. 1686 4.7.5. 504 Gateway Timeout 1688 The server, while acting as a gateway or proxy, did not receive a 1689 timely response from the upstream server specified by the URI (e.g., 1690 HTTP, FTP, LDAP) or some other auxiliary server (e.g., DNS) it needed 1691 to access in attempting to complete the request. 1693 Note to implementers: some deployed proxies are known to return 1694 400 (Bad Request) or 500 (Internal Server Error) when DNS lookups 1695 time out. 1697 4.7.6. 505 HTTP Version Not Supported 1699 The server does not support, or refuses to support, the protocol 1700 version that was used in the request message. The server is 1701 indicating that it is unable or unwilling to complete the request 1702 using the same major version as the client, as described in Section 1703 2.7 of [Part1], other than with this error message. The response 1704 SHOULD contain a representation describing why that version is not 1705 supported and what other protocols are supported by that server. 1707 5. Protocol Parameters 1709 5.1. Date/Time Formats 1711 HTTP applications have historically allowed three different formats 1712 for date/time stamps. However, the preferred format is a fixed- 1713 length subset of that defined by [RFC1123]: 1715 Sun, 06 Nov 1994 08:49:37 GMT ; RFC 1123 1717 The other formats are described here only for compatibility with 1718 obsolete implementations. 1720 Sunday, 06-Nov-94 08:49:37 GMT ; obsolete RFC 850 format 1721 Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format 1723 HTTP/1.1 clients and servers that parse a date value MUST accept all 1724 three formats (for compatibility with HTTP/1.0), though they MUST 1725 only generate the RFC 1123 format for representing HTTP-date values 1726 in header fields. 1728 All HTTP date/time stamps MUST be represented in Greenwich Mean Time 1729 (GMT), without exception. For the purposes of HTTP, GMT is exactly 1730 equal to UTC (Coordinated Universal Time). This is indicated in the 1731 first two formats by the inclusion of "GMT" as the three-letter 1732 abbreviation for time zone, and MUST be assumed when reading the 1733 asctime format. HTTP-date is case sensitive and MUST NOT include 1734 additional whitespace beyond that specifically included as SP in the 1735 grammar. 1737 HTTP-date = rfc1123-date / obs-date 1739 Preferred format: 1741 rfc1123-date = day-name "," SP date1 SP time-of-day SP GMT 1742 ; fixed length subset of the format defined in 1743 ; Section 5.2.14 of [RFC1123] 1745 day-name = %x4D.6F.6E ; "Mon", case-sensitive 1746 / %x54.75.65 ; "Tue", case-sensitive 1747 / %x57.65.64 ; "Wed", case-sensitive 1748 / %x54.68.75 ; "Thu", case-sensitive 1749 / %x46.72.69 ; "Fri", case-sensitive 1750 / %x53.61.74 ; "Sat", case-sensitive 1751 / %x53.75.6E ; "Sun", case-sensitive 1753 date1 = day SP month SP year 1754 ; e.g., 02 Jun 1982 1756 day = 2DIGIT 1757 month = %x4A.61.6E ; "Jan", case-sensitive 1758 / %x46.65.62 ; "Feb", case-sensitive 1759 / %x4D.61.72 ; "Mar", case-sensitive 1760 / %x41.70.72 ; "Apr", case-sensitive 1761 / %x4D.61.79 ; "May", case-sensitive 1762 / %x4A.75.6E ; "Jun", case-sensitive 1763 / %x4A.75.6C ; "Jul", case-sensitive 1764 / %x41.75.67 ; "Aug", case-sensitive 1765 / %x53.65.70 ; "Sep", case-sensitive 1766 / %x4F.63.74 ; "Oct", case-sensitive 1767 / %x4E.6F.76 ; "Nov", case-sensitive 1768 / %x44.65.63 ; "Dec", case-sensitive 1769 year = 4DIGIT 1771 GMT = %x47.4D.54 ; "GMT", case-sensitive 1773 time-of-day = hour ":" minute ":" second 1774 ; 00:00:00 - 23:59:59 1776 hour = 2DIGIT 1777 minute = 2DIGIT 1778 second = 2DIGIT 1780 The semantics of day-name, day, month, year, and time-of-day are the 1781 same as those defined for the RFC 5322 constructs with the 1782 corresponding name ([RFC5322], Section 3.3). 1784 Obsolete formats: 1786 obs-date = rfc850-date / asctime-date 1787 rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT 1788 date2 = day "-" month "-" 2DIGIT 1789 ; day-month-year (e.g., 02-Jun-82) 1791 day-name-l = %x4D.6F.6E.64.61.79 ; "Monday", case-sensitive 1792 / %x54.75.65.73.64.61.79 ; "Tuesday", case-sensitive 1793 / %x57.65.64.6E.65.73.64.61.79 ; "Wednesday", case-sensitive 1794 / %x54.68.75.72.73.64.61.79 ; "Thursday", case-sensitive 1795 / %x46.72.69.64.61.79 ; "Friday", case-sensitive 1796 / %x53.61.74.75.72.64.61.79 ; "Saturday", case-sensitive 1797 / %x53.75.6E.64.61.79 ; "Sunday", case-sensitive 1799 asctime-date = day-name SP date3 SP time-of-day SP year 1800 date3 = month SP ( 2DIGIT / ( SP 1DIGIT )) 1801 ; month day (e.g., Jun 2) 1803 Note: Recipients of date values are encouraged to be robust in 1804 accepting date values that might have been sent by non-HTTP 1805 applications, as is sometimes the case when retrieving or posting 1806 messages via proxies/gateways to SMTP or NNTP. 1808 Note: HTTP requirements for the date/time stamp format apply only 1809 to their usage within the protocol stream. Clients and servers 1810 are not required to use these formats for user presentation, 1811 request logging, etc. 1813 5.2. Product Tokens 1815 Product tokens are used to allow communicating applications to 1816 identify themselves by software name and version. Most fields using 1817 product tokens also allow sub-products which form a significant part 1818 of the application to be listed, separated by whitespace. By 1819 convention, the products are listed in order of their significance 1820 for identifying the application. 1822 product = token ["/" product-version] 1823 product-version = token 1825 Examples: 1827 User-Agent: CERN-LineMode/2.15 libwww/2.17b3 1828 Server: Apache/0.8.4 1830 Product tokens SHOULD be short and to the point. They MUST NOT be 1831 used for advertising or other non-essential information. Although 1832 any token octet MAY appear in a product-version, this token SHOULD 1833 only be used for a version identifier (i.e., successive versions of 1834 the same product SHOULD only differ in the product-version portion of 1835 the product value). 1837 5.3. Character Encodings (charset) 1839 HTTP uses charset names to indicate the character encoding of a 1840 textual representation. 1842 A character encoding is identified by a case-insensitive token. The 1843 complete set of tokens is defined by the IANA Character Set registry 1844 (). 1846 charset = token 1848 Although HTTP allows an arbitrary token to be used as a charset 1849 value, any token that has a predefined value within the IANA 1850 Character Set registry MUST represent the character encoding defined 1851 by that registry. Applications SHOULD limit their use of character 1852 encodings to those defined within the IANA registry. 1854 HTTP uses charset in two contexts: within an Accept-Charset request 1855 header field (in which the charset value is an unquoted token) and as 1856 the value of a parameter in a Content-Type header field (within a 1857 request or response), in which case the parameter value of the 1858 charset parameter can be quoted. 1860 Implementers need to be aware of IETF character set requirements 1861 [RFC3629] [RFC2277]. 1863 5.4. Content Codings 1865 Content coding values indicate an encoding transformation that has 1866 been or can be applied to a representation. Content codings are 1867 primarily used to allow a representation to be compressed or 1868 otherwise usefully transformed without losing the identity of its 1869 underlying media type and without loss of information. Frequently, 1870 the representation is stored in coded form, transmitted directly, and 1871 only decoded by the recipient. 1873 content-coding = token 1875 All content-coding values are case-insensitive. HTTP/1.1 uses 1876 content-coding values in the Accept-Encoding (Section 9.3) and 1877 Content-Encoding (Section 9.6) header fields. Although the value 1878 describes the content-coding, what is more important is that it 1879 indicates what decoding mechanism will be required to remove the 1880 encoding. 1882 compress 1884 See Section 4.2.1 of [Part1]. 1886 deflate 1888 See Section 4.2.2 of [Part1]. 1890 gzip 1892 See Section 4.2.3 of [Part1]. 1894 5.4.1. Content Coding Registry 1896 The HTTP Content Coding Registry defines the name space for the 1897 content coding names. 1899 Registrations MUST include the following fields: 1901 o Name 1903 o Description 1905 o Pointer to specification text 1907 Names of content codings MUST NOT overlap with names of transfer 1908 codings (Section 4 of [Part1]), unless the encoding transformation is 1909 identical (as is the case for the compression codings defined in 1910 Section 4.2 of [Part1]). 1912 Values to be added to this name space require IETF Review (see 1913 Section 4.1 of [RFC5226]), and MUST conform to the purpose of content 1914 coding defined in this section. 1916 The registry itself is maintained at 1917 . 1919 5.5. Media Types 1921 HTTP uses Internet Media Types [RFC2046] in the Content-Type 1922 (Section 9.9) and Accept (Section 9.1) header fields in order to 1923 provide open and extensible data typing and type negotiation. 1925 media-type = type "/" subtype *( OWS ";" OWS parameter ) 1926 type = token 1927 subtype = token 1929 The type/subtype MAY be followed by parameters in the form of 1930 attribute/value pairs. 1932 parameter = attribute "=" value 1933 attribute = token 1934 value = word 1936 The type, subtype, and parameter attribute names are case- 1937 insensitive. Parameter values might or might not be case-sensitive, 1938 depending on the semantics of the parameter name. The presence or 1939 absence of a parameter might be significant to the processing of a 1940 media-type, depending on its definition within the media type 1941 registry. 1943 A parameter value that matches the token production can be 1944 transmitted as either a token or within a quoted-string. The quoted 1945 and unquoted values are equivalent. 1947 Note that some older HTTP applications do not recognize media type 1948 parameters. When sending data to older HTTP applications, 1949 implementations SHOULD only use media type parameters when they are 1950 required by that type/subtype definition. 1952 Media-type values are registered with the Internet Assigned Number 1953 Authority (IANA). The media type registration process is outlined in 1954 [RFC4288]. Use of non-registered media types is discouraged. 1956 5.5.1. Canonicalization and Text Defaults 1958 Internet media types are registered with a canonical form. A 1959 representation transferred via HTTP messages MUST be in the 1960 appropriate canonical form prior to its transmission except for 1961 "text" types, as defined in the next paragraph. 1963 When in canonical form, media subtypes of the "text" type use CRLF as 1964 the text line break. HTTP relaxes this requirement and allows the 1965 transport of text media with plain CR or LF alone representing a line 1966 break when it is done consistently for an entire representation. 1967 HTTP applications MUST accept CRLF, bare CR, and bare LF as 1968 indicating a line break in text media received via HTTP. In 1969 addition, if the text is in a character encoding that does not use 1970 octets 13 and 10 for CR and LF respectively, as is the case for some 1971 multi-byte character encodings, HTTP allows the use of whatever octet 1972 sequences are defined by that character encoding to represent the 1973 equivalent of CR and LF for line breaks. This flexibility regarding 1974 line breaks applies only to text media in the payload body; a bare CR 1975 or LF MUST NOT be substituted for CRLF within any of the HTTP control 1976 structures (such as header fields and multipart boundaries). 1978 If a representation is encoded with a content-coding, the underlying 1979 data MUST be in a form defined above prior to being encoded. 1981 5.5.2. Multipart Types 1983 MIME provides for a number of "multipart" types -- encapsulations of 1984 one or more representations within a single message body. All 1985 multipart types share a common syntax, as defined in Section 5.1.1 of 1986 [RFC2046], and MUST include a boundary parameter as part of the media 1987 type value. The message body is itself a protocol element and MUST 1988 therefore use only CRLF to represent line breaks between body-parts. 1990 In general, HTTP treats a multipart message body no differently than 1991 any other media type: strictly as payload. HTTP does not use the 1992 multipart boundary as an indicator of message body length. In all 1993 other respects, an HTTP user agent SHOULD follow the same or similar 1994 behavior as a MIME user agent would upon receipt of a multipart type. 1995 The MIME header fields within each body-part of a multipart message 1996 body do not have any significance to HTTP beyond that defined by 1997 their MIME semantics. 1999 If an application receives an unrecognized multipart subtype, the 2000 application MUST treat it as being equivalent to "multipart/mixed". 2002 Note: The "multipart/form-data" type has been specifically defined 2003 for carrying form data suitable for processing via the POST 2004 request method, as described in [RFC2388]. 2006 5.6. Language Tags 2008 A language tag, as defined in [RFC5646], identifies a natural 2009 language spoken, written, or otherwise conveyed by human beings for 2010 communication of information to other human beings. Computer 2011 languages are explicitly excluded. HTTP uses language tags within 2012 the Accept-Language and Content-Language fields. 2014 In summary, a language tag is composed of one or more parts: A 2015 primary language subtag followed by a possibly empty series of 2016 subtags: 2018 language-tag = 2020 White space is not allowed within the tag and all tags are case- 2021 insensitive. The name space of language subtags is administered by 2022 the IANA (see 2023 ). 2025 Example tags include: 2027 en, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN 2029 See [RFC5646] for further information. 2031 6. Payload 2033 HTTP messages MAY transfer a payload if not otherwise restricted by 2034 the request method or response status code. The payload consists of 2035 metadata, in the form of header fields, and data, in the form of the 2036 sequence of octets in the message body after any transfer-coding has 2037 been decoded. 2039 A "payload" in HTTP is always a partial or complete representation of 2040 some resource. We use separate terms for payload and representation 2041 because some messages contain only the associated representation's 2042 header fields (e.g., responses to HEAD) or only some part(s) of the 2043 representation (e.g., the 206 (Partial Content) status code). 2045 6.1. Payload Header Fields 2047 HTTP header fields that specifically define the payload, rather than 2048 the associated representation, are referred to as "payload header 2049 fields". The following payload header fields are defined by 2050 HTTP/1.1: 2052 +-------------------+--------------------------+ 2053 | Header Field Name | Defined in... | 2054 +-------------------+--------------------------+ 2055 | Content-Length | Section 3.3.2 of [Part1] | 2056 | Content-Range | Section 5.2 of [Part5] | 2057 +-------------------+--------------------------+ 2059 6.2. Payload Body 2061 A payload body is only present in a message when a message body is 2062 present, as described in Section 3.3 of [Part1]. The payload body is 2063 obtained from the message body by decoding any Transfer-Encoding that 2064 might have been applied to ensure safe and proper transfer of the 2065 message. 2067 7. Representation 2069 A "representation" is information in a format that can be readily 2070 communicated from one party to another. A resource representation is 2071 information that reflects the state of that resource, as observed at 2072 some point in the past (e.g., in a response to GET) or to be desired 2073 at some point in the future (e.g., in a PUT request). 2075 Most, but not all, representations transferred via HTTP are intended 2076 to be a representation of the target resource (the resource 2077 identified by the effective request URI). The precise semantics of a 2078 representation are determined by the type of message (request or 2079 response), the request method, the response status code, and the 2080 representation metadata. For example, the above semantic is true for 2081 the representation in any 200 (OK) response to GET and for the 2082 representation in any PUT request. A 200 response to PUT, in 2083 contrast, contains either a representation that describes the 2084 successful action or a representation of the target resource, with 2085 the latter indicated by a Content-Location header field with the same 2086 value as the effective request URI. Likewise, response messages with 2087 an error status code usually contain a representation that describes 2088 the error and what next steps are suggested for resolving it. 2090 Request and Response messages MAY transfer a representation if not 2091 otherwise restricted by the request method or response status code. 2092 A representation consists of metadata (representation header fields) 2093 and data (representation body). When a complete or partial 2094 representation is enclosed in an HTTP message, it is referred to as 2095 the payload of the message. 2097 A representation body is only present in a message when a message 2098 body is present, as described in Section 3.3 of [Part1]. The 2099 representation body is obtained from the message body by decoding any 2100 Transfer-Encoding that might have been applied to ensure safe and 2101 proper transfer of the message. 2103 7.1. Identifying the Resource Associated with a Representation 2105 It is sometimes necessary to determine an identifier for the resource 2106 associated with a representation. 2108 An HTTP request representation, when present, is always associated 2109 with an anonymous (i.e., unidentified) resource. 2111 In the common case, an HTTP response is a representation of the 2112 target resource (see Section 5.5 of [Part1]). However, this is not 2113 always the case. To determine the URI of the resource a response is 2114 associated with, the following rules are used (with the first 2115 applicable one being selected): 2117 1. If the response status code is 200 (OK) or 203 (Non-Authoritative 2118 Information) and the request method was GET, the response payload 2119 is a representation of the target resource. 2121 2. If the response status code is 204 (No Content), 206 (Partial 2122 Content), or 304 (Not Modified) and the request method was GET or 2123 HEAD, the response payload is a partial representation of the 2124 target resource. 2126 3. If the response has a Content-Location header field, and that URI 2127 is the same as the effective request URI, the response payload is 2128 a representation of the target resource. 2130 4. If the response has a Content-Location header field, and that URI 2131 is not the same as the effective request URI, then the response 2132 asserts that its payload is a representation of the resource 2133 identified by the Content-Location URI. However, such an 2134 assertion cannot be trusted unless it can be verified by other 2135 means (not defined by HTTP). 2137 5. Otherwise, the response is a representation of an anonymous 2138 (i.e., unidentified) resource. 2140 [[TODO-req-uri: The comparison function is going to have to be 2141 defined somewhere, because we already need to compare URIs for things 2142 like cache invalidation.]] 2144 7.2. Representation Header Fields 2146 Representation header fields define metadata about the representation 2147 data enclosed in the message body or, if no message body is present, 2148 about the representation that would have been transferred in a 200 2149 (OK) response to a simultaneous GET request with the same effective 2150 request URI. 2152 The following header fields are defined as representation metadata: 2154 +-------------------+------------------------+ 2155 | Header Field Name | Defined in... | 2156 +-------------------+------------------------+ 2157 | Content-Encoding | Section 9.6 | 2158 | Content-Language | Section 9.7 | 2159 | Content-Location | Section 9.8 | 2160 | Content-Type | Section 9.9 | 2161 | Expires | Section 7.3 of [Part6] | 2162 +-------------------+------------------------+ 2164 We use the term "selected representation" to refer to the the current 2165 representation of a target resource that would have been selected in 2166 a successful response if the same request had used the method GET and 2167 excluded any conditional request header fields. 2169 Additional header fields define metadata about the selected 2170 representation, which might differ from the representation included 2171 in the message for responses to some state-changing methods. The 2172 following header fields are defined as selected representation 2173 metadata: 2175 +-------------------+------------------------+ 2176 | Header Field Name | Defined in... | 2177 +-------------------+------------------------+ 2178 | ETag | Section 2.3 of [Part4] | 2179 | Last-Modified | Section 2.2 of [Part4] | 2180 +-------------------+------------------------+ 2182 7.3. Representation Data 2184 The representation body associated with an HTTP message is either 2185 provided as the payload body of the message or referred to by the 2186 message semantics and the effective request URI. The representation 2187 data is in a format and encoding defined by the representation 2188 metadata header fields. 2190 The data type of the representation data is determined via the header 2191 fields Content-Type and Content-Encoding. These define a two-layer, 2192 ordered encoding model: 2194 representation-data := Content-Encoding( Content-Type( bits ) ) 2196 Content-Type specifies the media type of the underlying data, which 2197 defines both the data format and how that data SHOULD be processed by 2198 the recipient (within the scope of the request method semantics). 2199 Any HTTP/1.1 message containing a payload body SHOULD include a 2200 Content-Type header field defining the media type of the associated 2201 representation unless that metadata is unknown to the sender. If the 2202 Content-Type header field is not present, it indicates that the 2203 sender does not know the media type of the representation; recipients 2204 MAY either assume that the media type is "application/octet-stream" 2205 ([RFC2046], Section 4.5.1) or examine the content to determine its 2206 type. 2208 In practice, resource owners do not always properly configure their 2209 origin server to provide the correct Content-Type for a given 2210 representation, with the result that some clients will examine a 2211 response body's content and override the specified type. Clients 2212 that do so risk drawing incorrect conclusions, which might expose 2213 additional security risks (e.g., "privilege escalation"). 2214 Furthermore, it is impossible to determine the sender's intent by 2215 examining the data format: many data formats match multiple media 2216 types that differ only in processing semantics. Implementers are 2217 encouraged to provide a means of disabling such "content sniffing" 2218 when it is used. 2220 Content-Encoding is used to indicate any additional content codings 2221 applied to the data, usually for the purpose of data compression, 2222 that are a property of the representation. If Content-Encoding is 2223 not present, then there is no additional encoding beyond that defined 2224 by the Content-Type header field. 2226 8. Content Negotiation 2228 HTTP responses include a representation which contains information 2229 for interpretation, whether by a human user or for further 2230 processing. Often, the server has different ways of representing the 2231 same information; for example, in different formats, languages, or 2232 using different character encodings. 2234 HTTP clients and their users might have different or variable 2235 capabilities, characteristics or preferences which would influence 2236 which representation, among those available from the server, would be 2237 best for the server to deliver. For this reason, HTTP provides 2238 mechanisms for "content negotiation" -- a process of allowing 2239 selection of a representation of a given resource, when more than one 2240 is available. 2242 This specification defines two patterns of content negotiation; 2243 "server-driven", where the server selects the representation based 2244 upon the client's stated preferences, and "agent-driven" negotiation, 2245 where the server provides a list of representations for the client to 2246 choose from, based upon their metadata. In addition, there are other 2247 patterns: some applications use an "active content" pattern, where 2248 the server returns active content which runs on the client and, based 2249 on client available parameters, selects additional resources to 2250 invoke. "Transparent Content Negotiation" ([RFC2295]) has also been 2251 proposed. 2253 These patterns are all widely used, and have trade-offs in 2254 applicability and practicality. In particular, when the number of 2255 preferences or capabilities to be expressed by a client are large 2256 (such as when many different formats are supported by a user-agent), 2257 server-driven negotiation becomes unwieldy, and might not be 2258 appropriate. Conversely, when the number of representations to 2259 choose from is very large, agent-driven negotiation might not be 2260 appropriate. 2262 Note that in all cases, the supplier of representations has the 2263 responsibility for determining which representations might be 2264 considered to be the "same information". 2266 8.1. Server-driven Negotiation 2268 If the selection of the best representation for a response is made by 2269 an algorithm located at the server, it is called server-driven 2270 negotiation. Selection is based on the available representations of 2271 the response (the dimensions over which it can vary; e.g., language, 2272 content-coding, etc.) and the contents of particular header fields in 2273 the request message or on other information pertaining to the request 2274 (such as the network address of the client). 2276 Server-driven negotiation is advantageous when the algorithm for 2277 selecting from among the available representations is difficult to 2278 describe to the user agent, or when the server desires to send its 2279 "best guess" to the client along with the first response (hoping to 2280 avoid the round-trip delay of a subsequent request if the "best 2281 guess" is good enough for the user). In order to improve the 2282 server's guess, the user agent MAY include request header fields 2283 (Accept, Accept-Language, Accept-Encoding, etc.) which describe its 2284 preferences for such a response. 2286 Server-driven negotiation has disadvantages: 2288 1. It is impossible for the server to accurately determine what 2289 might be "best" for any given user, since that would require 2290 complete knowledge of both the capabilities of the user agent and 2291 the intended use for the response (e.g., does the user want to 2292 view it on screen or print it on paper?). 2294 2. Having the user agent describe its capabilities in every request 2295 can be both very inefficient (given that only a small percentage 2296 of responses have multiple representations) and a potential 2297 violation of the user's privacy. 2299 3. It complicates the implementation of an origin server and the 2300 algorithms for generating responses to a request. 2302 4. It might limit a public cache's ability to use the same response 2303 for multiple user's requests. 2305 Server-driven negotiation allows the user agent to specify its 2306 preferences, but it cannot expect responses to always honor them. 2307 For example, the origin server might not implement server-driven 2308 negotiation, or it might decide that sending a response that doesn't 2309 conform to them is better than sending a 406 (Not Acceptable) 2310 response. 2312 Many of the mechanisms for expressing preferences use quality values 2313 to declare relative preference. See Section 4.3.1 of [Part1] for 2314 more information. 2316 HTTP/1.1 includes the following header fields for enabling server- 2317 driven negotiation through description of user agent capabilities and 2318 user preferences: Accept (Section 9.1), Accept-Charset (Section 9.2), 2319 Accept-Encoding (Section 9.3), Accept-Language (Section 9.4), and 2320 User-Agent (Section 9.18). However, an origin server is not limited 2321 to these dimensions and MAY vary the response based on any aspect of 2322 the request, including aspects of the connection (e.g., IP address) 2323 or information within extension header fields not defined by this 2324 specification. 2326 Note: In practice, User-Agent based negotiation is fragile, 2327 because new clients might not be recognized. 2329 The Vary header field (Section 7.5 of [Part6]) can be used to express 2330 the parameters the server uses to select a representation that is 2331 subject to server-driven negotiation. 2333 8.2. Agent-driven Negotiation 2335 With agent-driven negotiation, selection of the best representation 2336 for a response is performed by the user agent after receiving an 2337 initial response from the origin server. Selection is based on a 2338 list of the available representations of the response included within 2339 the header fields or body of the initial response, with each 2340 representation identified by its own URI. Selection from among the 2341 representations can be performed automatically (if the user agent is 2342 capable of doing so) or manually by the user selecting from a 2343 generated (possibly hypertext) menu. 2345 Agent-driven negotiation is advantageous when the response would vary 2346 over commonly-used dimensions (such as type, language, or encoding), 2347 when the origin server is unable to determine a user agent's 2348 capabilities from examining the request, and generally when public 2349 caches are used to distribute server load and reduce network usage. 2351 Agent-driven negotiation suffers from the disadvantage of needing a 2352 second request to obtain the best alternate representation. This 2353 second request is only efficient when caching is used. In addition, 2354 this specification does not define any mechanism for supporting 2355 automatic selection, though it also does not prevent any such 2356 mechanism from being developed as an extension and used within 2357 HTTP/1.1. 2359 This specification defines the 300 (Multiple Choices) and 406 (Not 2360 Acceptable) status codes for enabling agent-driven negotiation when 2361 the server is unwilling or unable to provide a varying response using 2362 server-driven negotiation. 2364 9. Header Field Definitions 2366 This section defines the syntax and semantics of HTTP/1.1 header 2367 fields related to request and response semantics and to the payload 2368 of messages. 2370 9.1. Accept 2372 The "Accept" header field can be used by user agents to specify 2373 response media types that are acceptable. Accept header fields can 2374 be used to indicate that the request is specifically limited to a 2375 small set of desired types, as in the case of a request for an in- 2376 line image. 2378 Accept = #( media-range [ accept-params ] ) 2380 media-range = ( "*/*" 2381 / ( type "/" "*" ) 2382 / ( type "/" subtype ) 2383 ) *( OWS ";" OWS parameter ) 2384 accept-params = OWS ";" OWS "q=" qvalue *( accept-ext ) 2385 accept-ext = OWS ";" OWS token [ "=" word ] 2387 The asterisk "*" character is used to group media types into ranges, 2388 with "*/*" indicating all media types and "type/*" indicating all 2389 subtypes of that type. The media-range MAY include media type 2390 parameters that are applicable to that range. 2392 Each media-range MAY be followed by one or more accept-params, 2393 beginning with the "q" parameter for indicating a relative quality 2394 factor. The first "q" parameter (if any) separates the media-range 2395 parameter(s) from the accept-params. Quality factors allow the user 2396 or user agent to indicate the relative degree of preference for that 2397 media-range, using the qvalue scale from 0 to 1 (Section 4.3.1 of 2398 [Part1]). The default value is q=1. 2400 Note: Use of the "q" parameter name to separate media type 2401 parameters from Accept extension parameters is due to historical 2402 practice. Although this prevents any media type parameter named 2403 "q" from being used with a media range, such an event is believed 2404 to be unlikely given the lack of any "q" parameters in the IANA 2405 media type registry and the rare usage of any media type 2406 parameters in Accept. Future media types are discouraged from 2407 registering any parameter named "q". 2409 The example 2410 Accept: audio/*; q=0.2, audio/basic 2412 SHOULD be interpreted as "I prefer audio/basic, but send me any audio 2413 type if it is the best available after an 80% mark-down in quality". 2415 A request without any Accept header field implies that the user agent 2416 will accept any media type in response. If an Accept header field is 2417 present in a request and none of the available representations for 2418 the response have a media type that is listed as acceptable, the 2419 origin server MAY either honor the Accept header field by sending a 2420 406 (Not Acceptable) response or disregard the Accept header field by 2421 treating the response as if it is not subject to content negotiation. 2423 A more elaborate example is 2425 Accept: text/plain; q=0.5, text/html, 2426 text/x-dvi; q=0.8, text/x-c 2428 Verbally, this would be interpreted as "text/html and text/x-c are 2429 the preferred media types, but if they do not exist, then send the 2430 text/x-dvi representation, and if that does not exist, send the text/ 2431 plain representation". 2433 Media ranges can be overridden by more specific media ranges or 2434 specific media types. If more than one media range applies to a 2435 given type, the most specific reference has precedence. For example, 2437 Accept: text/*, text/plain, text/plain;format=flowed, */* 2439 have the following precedence: 2441 1. text/plain;format=flowed 2443 2. text/plain 2445 3. text/* 2447 4. */* 2449 The media type quality factor associated with a given type is 2450 determined by finding the media range with the highest precedence 2451 which matches that type. For example, 2453 Accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1, 2454 text/html;level=2;q=0.4, */*;q=0.5 2456 would cause the following values to be associated: 2458 +-------------------+---------------+ 2459 | Media Type | Quality Value | 2460 +-------------------+---------------+ 2461 | text/html;level=1 | 1 | 2462 | text/html | 0.7 | 2463 | text/plain | 0.3 | 2464 | image/jpeg | 0.5 | 2465 | text/html;level=2 | 0.4 | 2466 | text/html;level=3 | 0.7 | 2467 +-------------------+---------------+ 2469 Note: A user agent might be provided with a default set of quality 2470 values for certain media ranges. However, unless the user agent is a 2471 closed system which cannot interact with other rendering agents, this 2472 default set ought to be configurable by the user. 2474 9.2. Accept-Charset 2476 The "Accept-Charset" header field can be used by user agents to 2477 indicate what character encodings are acceptable in a response 2478 payload. This field allows clients capable of understanding more 2479 comprehensive or special-purpose character encodings to signal that 2480 capability to a server which is capable of representing documents in 2481 those character encodings. 2483 Accept-Charset = 1#( ( charset / "*" ) 2484 [ OWS ";" OWS "q=" qvalue ] ) 2486 Character encoding values (a.k.a., charsets) are described in 2487 Section 5.3. Each charset MAY be given an associated quality value 2488 which represents the user's preference for that charset. The default 2489 value is q=1. An example is 2491 Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 2493 The special value "*", if present in the Accept-Charset field, 2494 matches every character encoding which is not mentioned elsewhere in 2495 the Accept-Charset field. If no "*" is present in an Accept-Charset 2496 field, then all character encodings not explicitly mentioned get a 2497 quality value of 0. 2499 A request without any Accept-Charset header field implies that the 2500 user agent will accept any character encoding in response. If an 2501 Accept-Charset header field is present in a request and none of the 2502 available representations for the response have a character encoding 2503 that is listed as acceptable, the origin server MAY either honor the 2504 Accept-Charset header field by sending a 406 (Not Acceptable) 2505 response or disregard the Accept-Charset header field by treating the 2506 response as if it is not subject to content negotiation. 2508 9.3. Accept-Encoding 2510 The "Accept-Encoding" header field can be used by user agents to 2511 indicate what response content-codings (Section 5.4) are acceptable 2512 in the response. An "identity" token is used as a synonym for "no 2513 encoding" in order to communicate when no encoding is preferred. 2515 Accept-Encoding = #( codings [ OWS ";" OWS "q=" qvalue ] ) 2516 codings = content-coding / "identity" / "*" 2518 Each codings value MAY be given an associated quality value which 2519 represents the preference for that encoding. The default value is 2520 q=1. 2522 For example, 2524 Accept-Encoding: compress, gzip 2525 Accept-Encoding: 2526 Accept-Encoding: * 2527 Accept-Encoding: compress;q=0.5, gzip;q=1.0 2528 Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0 2530 A server tests whether a content-coding for a given representation is 2531 acceptable, according to an Accept-Encoding field, using these rules: 2533 1. The special "*" symbol in an Accept-Encoding field matches any 2534 available content-coding not explicitly listed in the header 2535 field. 2537 2. If the representation has no content-coding, then it is 2538 acceptable by default unless specifically excluded by the Accept- 2539 Encoding field stating either "identity;q=0" or "*;q=0" without a 2540 more specific entry for "identity". 2542 3. If the representation's content-coding is one of the content- 2543 codings listed in the Accept-Encoding field, then it is 2544 acceptable unless it is accompanied by a qvalue of 0. (As 2545 defined in Section 4.3.1 of [Part1], a qvalue of 0 means "not 2546 acceptable".) 2548 4. If multiple content-codings are acceptable, then the acceptable 2549 content-coding with the highest non-zero qvalue is preferred. 2551 An Accept-Encoding header field with a combined field-value that is 2552 empty implies that the user agent does not want any content-coding in 2553 response. If an Accept-Encoding header field is present in a request 2554 and none of the available representations for the response have a 2555 content-coding that is listed as acceptable, the origin server SHOULD 2556 send a response without any content-coding. 2558 A request without an Accept-Encoding header field implies that the 2559 user agent will accept any content-coding in response, but a 2560 representation without content-coding is preferred for compatibility 2561 with the widest variety of user agents. 2563 Note: Most HTTP/1.0 applications do not recognize or obey qvalues 2564 associated with content-codings. This means that qvalues will not 2565 work and are not permitted with x-gzip or x-compress. 2567 9.4. Accept-Language 2569 The "Accept-Language" header field can be used by user agents to 2570 indicate the set of natural languages that are preferred in the 2571 response. Language tags are defined in Section 5.6. 2573 Accept-Language = 2574 1#( language-range [ OWS ";" OWS "q=" qvalue ] ) 2575 language-range = 2576 2578 Each language-range can be given an associated quality value which 2579 represents an estimate of the user's preference for the languages 2580 specified by that range. The quality value defaults to "q=1". For 2581 example, 2583 Accept-Language: da, en-gb;q=0.8, en;q=0.7 2585 would mean: "I prefer Danish, but will accept British English and 2586 other types of English". (see also Section 2.3 of [RFC4647]) 2588 For matching, Section 3 of [RFC4647] defines several matching 2589 schemes. Implementations can offer the most appropriate matching 2590 scheme for their requirements. 2592 Note: The "Basic Filtering" scheme ([RFC4647], Section 3.3.1) is 2593 identical to the matching scheme that was previously defined in 2594 Section 14.4 of [RFC2616]. 2596 It might be contrary to the privacy expectations of the user to send 2597 an Accept-Language header field with the complete linguistic 2598 preferences of the user in every request. For a discussion of this 2599 issue, see Section 11.5. 2601 As intelligibility is highly dependent on the individual user, it is 2602 recommended that client applications make the choice of linguistic 2603 preference available to the user. If the choice is not made 2604 available, then the Accept-Language header field MUST NOT be given in 2605 the request. 2607 Note: When making the choice of linguistic preference available to 2608 the user, we remind implementers of the fact that users are not 2609 familiar with the details of language matching as described above, 2610 and ought to be provided appropriate guidance. As an example, 2611 users might assume that on selecting "en-gb", they will be served 2612 any kind of English document if British English is not available. 2613 A user agent might suggest in such a case to add "en" to get the 2614 best matching behavior. 2616 9.5. Allow 2618 The "Allow" header field lists the set of methods advertised as 2619 supported by the target resource. The purpose of this field is 2620 strictly to inform the recipient of valid request methods associated 2621 with the resource. 2623 Allow = #method 2625 Example of use: 2627 Allow: GET, HEAD, PUT 2629 The actual set of allowed methods is defined by the origin server at 2630 the time of each request. 2632 A proxy MUST NOT modify the Allow header field -- it does not need to 2633 understand all the methods specified in order to handle them 2634 according to the generic message handling rules. 2636 9.6. Content-Encoding 2638 The "Content-Encoding" header field indicates what content-codings 2639 have been applied to the representation beyond those inherent in the 2640 media type, and thus what decoding mechanisms have to be applied in 2641 order to obtain the media-type referenced by the Content-Type header 2642 field. Content-Encoding is primarily used to allow a representation 2643 to be compressed without losing the identity of its underlying media 2644 type. 2646 Content-Encoding = 1#content-coding 2648 Content codings are defined in Section 5.4. An example of its use is 2649 Content-Encoding: gzip 2651 The content-coding is a characteristic of the representation. 2652 Typically, the representation body is stored with this encoding and 2653 is only decoded before rendering or analogous usage. However, a 2654 transforming proxy MAY modify the content-coding if the new coding is 2655 known to be acceptable to the recipient, unless the "no-transform" 2656 cache-control directive is present in the message. 2658 If the media type includes an inherent encoding, such as a data 2659 format that is always compressed, then that encoding would not be 2660 restated as a Content-Encoding even if it happens to be the same 2661 algorithm as one of the content-codings. Such a content-coding would 2662 only be listed if, for some bizarre reason, it is applied a second 2663 time to form the representation. Likewise, an origin server might 2664 choose to publish the same payload data as multiple representations 2665 that differ only in whether the coding is defined as part of Content- 2666 Type or Content-Encoding, since some user agents will behave 2667 differently in their handling of each response (e.g., open a "Save as 2668 ..." dialog instead of automatic decompression and rendering of 2669 content). 2671 A representation that has a content-coding applied to it MUST include 2672 a Content-Encoding header field that lists the content-coding(s) 2673 applied. 2675 If multiple encodings have been applied to a representation, the 2676 content codings MUST be listed in the order in which they were 2677 applied. Additional information about the encoding parameters MAY be 2678 provided by other header fields not defined by this specification. 2680 If the content-coding of a representation in a request message is not 2681 acceptable to the origin server, the server SHOULD respond with a 2682 status code of 415 (Unsupported Media Type). 2684 9.7. Content-Language 2686 The "Content-Language" header field describes the natural language(s) 2687 of the intended audience for the representation. Note that this 2688 might not be equivalent to all the languages used within the 2689 representation. 2691 Content-Language = 1#language-tag 2693 Language tags are defined in Section 5.6. The primary purpose of 2694 Content-Language is to allow a user to identify and differentiate 2695 representations according to the user's own preferred language. 2696 Thus, if the body content is intended only for a Danish-literate 2697 audience, the appropriate field is 2699 Content-Language: da 2701 If no Content-Language is specified, the default is that the content 2702 is intended for all language audiences. This might mean that the 2703 sender does not consider it to be specific to any natural language, 2704 or that the sender does not know for which language it is intended. 2706 Multiple languages MAY be listed for content that is intended for 2707 multiple audiences. For example, a rendition of the "Treaty of 2708 Waitangi", presented simultaneously in the original Maori and English 2709 versions, would call for 2711 Content-Language: mi, en 2713 However, just because multiple languages are present within a 2714 representation does not mean that it is intended for multiple 2715 linguistic audiences. An example would be a beginner's language 2716 primer, such as "A First Lesson in Latin", which is clearly intended 2717 to be used by an English-literate audience. In this case, the 2718 Content-Language would properly only include "en". 2720 Content-Language MAY be applied to any media type -- it is not 2721 limited to textual documents. 2723 9.8. Content-Location 2725 The "Content-Location" header field supplies a URI that can be used 2726 as a specific identifier for the representation in this message. In 2727 other words, if one were to perform a GET on this URI at the time of 2728 this message's generation, then a 200 (OK) response would contain the 2729 same representation that is enclosed as payload in this message. 2731 Content-Location = absolute-URI / partial-URI 2733 The Content-Location value is not a replacement for the effective 2734 Request URI (Section 5.5 of [Part1]). It is representation metadata. 2735 It has the same syntax and semantics as the header field of the same 2736 name defined for MIME body parts in Section 4 of [RFC2557]. However, 2737 its appearance in an HTTP message has some special implications for 2738 HTTP recipients. 2740 If Content-Location is included in a response message and its value 2741 is the same as the effective request URI, then the response payload 2742 SHOULD be considered a current representation of that resource. For 2743 a GET or HEAD request, this is the same as the default semantics when 2744 no Content-Location is provided by the server. For a state-changing 2745 request like PUT or POST, it implies that the server's response 2746 contains the new representation of that resource, thereby 2747 distinguishing it from representations that might only report about 2748 the action (e.g., "It worked!"). This allows authoring applications 2749 to update their local copies without the need for a subsequent GET 2750 request. 2752 If Content-Location is included in a response message and its value 2753 differs from the effective request URI, then the origin server is 2754 informing recipients that this representation has its own, presumably 2755 more specific, identifier. For a GET or HEAD request, this is an 2756 indication that the effective request URI identifies a resource that 2757 is subject to content negotiation and the selected representation for 2758 this response can also be found at the identified URI. For other 2759 methods, such a Content-Location indicates that this representation 2760 contains a report on the action's status and the same report is 2761 available (for future access with GET) at the given URI. For 2762 example, a purchase transaction made via a POST request might include 2763 a receipt document as the payload of the 200 (OK) response; the 2764 Content-Location value provides an identifier for retrieving a copy 2765 of that same receipt in the future. 2767 If Content-Location is included in a request message, then it MAY be 2768 interpreted by the origin server as an indication of where the user 2769 agent originally obtained the content of the enclosed representation 2770 (prior to any subsequent modification of the content by that user 2771 agent). In other words, the user agent is providing the same 2772 representation metadata that it received with the original 2773 representation. However, such interpretation MUST NOT be used to 2774 alter the semantics of the method requested by the client. For 2775 example, if a client makes a PUT request on a negotiated resource and 2776 the origin server accepts that PUT (without redirection), then the 2777 new set of values for that resource is expected to be consistent with 2778 the one representation supplied in that PUT; the Content-Location 2779 cannot be used as a form of reverse content selection that identifies 2780 only one of the negotiated representations to be updated. If the 2781 user agent had wanted the latter semantics, it would have applied the 2782 PUT directly to the Content-Location URI. 2784 A Content-Location field received in a request message is transitory 2785 information that SHOULD NOT be saved with other representation 2786 metadata for use in later responses. The Content-Location's value 2787 might be saved for use in other contexts, such as within source links 2788 or other metadata. 2790 A cache cannot assume that a representation with a Content-Location 2791 different from the URI used to retrieve it can be used to respond to 2792 later requests on that Content-Location URI. 2794 If the Content-Location value is a partial URI, the partial URI is 2795 interpreted relative to the effective request URI. 2797 9.9. Content-Type 2799 The "Content-Type" header field indicates the media type of the 2800 representation. In the case of responses to the HEAD method, the 2801 media type is that which would have been sent had the request been a 2802 GET. 2804 Content-Type = media-type 2806 Media types are defined in Section 5.5. An example of the field is 2808 Content-Type: text/html; charset=ISO-8859-4 2810 Further discussion of Content-Type is provided in Section 7.3. 2812 9.10. Date 2814 The "Date" header field represents the date and time at which the 2815 message was originated, having the same semantics as the Origination 2816 Date Field (orig-date) defined in Section 3.6.1 of [RFC5322]. The 2817 field value is an HTTP-date, as defined in Section 5.1; it MUST be 2818 sent in rfc1123-date format. 2820 Date = HTTP-date 2822 An example is 2824 Date: Tue, 15 Nov 1994 08:12:31 GMT 2826 Origin servers MUST include a Date header field in all responses, 2827 except in these cases: 2829 1. If the response status code is 100 (Continue) or 101 (Switching 2830 Protocols), the response MAY include a Date header field, at the 2831 server's option. 2833 2. If the response status code conveys a server error, e.g., 500 2834 (Internal Server Error) or 503 (Service Unavailable), and it is 2835 inconvenient or impossible to generate a valid Date. 2837 3. If the server does not have a clock that can provide a reasonable 2838 approximation of the current time, its responses MUST NOT include 2839 a Date header field. 2841 A received message that does not have a Date header field MUST be 2842 assigned one by the recipient if the message will be cached by that 2843 recipient. 2845 Clients can use the Date header field as well; in order to keep 2846 request messages small, they are advised not to include it when it 2847 doesn't convey any useful information (as is usually the case for 2848 requests that do not contain a payload). 2850 The HTTP-date sent in a Date header field SHOULD NOT represent a date 2851 and time subsequent to the generation of the message. It SHOULD 2852 represent the best available approximation of the date and time of 2853 message generation, unless the implementation has no means of 2854 generating a reasonably accurate date and time. In theory, the date 2855 ought to represent the moment just before the payload is generated. 2856 In practice, the date can be generated at any time during the message 2857 origination without affecting its semantic value. 2859 9.11. Expect 2861 The "Expect" header field is used to indicate that particular server 2862 behaviors are required by the client. 2864 Expect = 1#expectation 2866 expectation = expect-name [ BWS "=" BWS expect-value ] 2867 *( OWS ";" [ OWS expect-param ] ) 2868 expect-param = expect-name [ BWS "=" BWS expect-value ] 2870 expect-name = token 2871 expect-value = token / quoted-string 2873 If all received Expect header field(s) are syntactically valid but 2874 contain an expectation that the recipient does not understand or 2875 cannot comply with, the recipient MUST respond with a 417 2876 (Expectation Failed) status code. A recipient of a syntactically 2877 invalid Expectation header field MUST respond with a 4xx status code 2878 other than 417. 2880 The only expectation defined by this specification is: 2882 100-continue 2884 The "100-continue" expectation is defined Section 6.4.3 of 2885 [Part1]. It does not support any expect-params. 2887 Comparison is case-insensitive for names (expect-name), and case- 2888 sensitive for values (expect-value). 2890 The Expect mechanism is hop-by-hop: the above requirements apply to 2891 any server, including proxies. However, the Expect header field 2892 itself is end-to-end; it MUST be forwarded if the request is 2893 forwarded. 2895 Many older HTTP/1.0 and HTTP/1.1 applications do not understand the 2896 Expect header field. 2898 9.12. From 2900 The "From" header field, if given, SHOULD contain an Internet e-mail 2901 address for the human user who controls the requesting user agent. 2902 The address SHOULD be machine-usable, as defined by "mailbox" in 2903 Section 3.4 of [RFC5322]: 2905 From = mailbox 2907 mailbox = 2909 An example is: 2911 From: webmaster@example.org 2913 This header field MAY be used for logging purposes and as a means for 2914 identifying the source of invalid or unwanted requests. It SHOULD 2915 NOT be used as an insecure form of access protection. The 2916 interpretation of this field is that the request is being performed 2917 on behalf of the person given, who accepts responsibility for the 2918 method performed. In particular, robot agents SHOULD include this 2919 header field so that the person responsible for running the robot can 2920 be contacted if problems occur on the receiving end. 2922 The Internet e-mail address in this field MAY be separate from the 2923 Internet host which issued the request. For example, when a request 2924 is passed through a proxy the original issuer's address SHOULD be 2925 used. 2927 The client SHOULD NOT send the From header field without the user's 2928 approval, as it might conflict with the user's privacy interests or 2929 their site's security policy. It is strongly recommended that the 2930 user be able to disable, enable, and modify the value of this field 2931 at any time prior to a request. 2933 9.13. Location 2935 The "Location" header field MAY be sent in responses to refer to a 2936 specific resource in accordance with the semantics of the status 2937 code. 2939 Location = URI-reference 2941 For 201 (Created) responses, the Location is the URI of the new 2942 resource which was created by the request. For 3xx (Redirection) 2943 responses, the location SHOULD indicate the server's preferred URI 2944 for automatic redirection to the resource. 2946 The field value consists of a single URI-reference. When it has the 2947 form of a relative reference ([RFC3986], Section 4.2), the final 2948 value is computed by resolving it against the effective request URI 2949 ([RFC3986], Section 5). If the original URI, as navigated to by the 2950 user agent, did contain a fragment identifier, and the final value 2951 does not, then the original URI's fragment identifier is added to the 2952 final value. 2954 For example, the original URI "http://www.example.org/~tim", combined 2955 with a field value given as: 2957 Location: /pub/WWW/People.html#tim 2959 would result in a final value of 2960 "http://www.example.org/pub/WWW/People.html#tim" 2962 An original URI "http://www.example.org/index.html#larry", combined 2963 with a field value given as: 2965 Location: http://www.example.net/index.html 2967 would result in a final value of 2968 "http://www.example.net/index.html#larry", preserving the original 2969 fragment identifier. 2971 Note: Some recipients attempt to recover from Location fields that 2972 are not valid URI references. This specification does not mandate 2973 or define such processing, but does allow it. 2975 There are circumstances in which a fragment identifier in a Location 2976 URI would not be appropriate. For instance, when it appears in a 201 2977 (Created) response, where the Location header field specifies the URI 2978 for the entire created resource. 2980 Note: The Content-Location header field (Section 9.8) differs from 2981 Location in that the Content-Location identifies the most specific 2982 resource corresponding to the enclosed representation. It is 2983 therefore possible for a response to contain header fields for 2984 both Location and Content-Location. 2986 9.14. Max-Forwards 2988 The "Max-Forwards" header field provides a mechanism with the TRACE 2989 (Section 2.3.7) and OPTIONS (Section 2.3.1) methods to limit the 2990 number of times that the request is forwarded by proxies. This can 2991 be useful when the client is attempting to trace a request which 2992 appears to be failing or looping mid-chain. 2994 Max-Forwards = 1*DIGIT 2996 The Max-Forwards value is a decimal integer indicating the remaining 2997 number of times this request message can be forwarded. 2999 Each recipient of a TRACE or OPTIONS request containing a Max- 3000 Forwards header field MUST check and update its value prior to 3001 forwarding the request. If the received value is zero (0), the 3002 recipient MUST NOT forward the request; instead, it MUST respond as 3003 the final recipient. If the received Max-Forwards value is greater 3004 than zero, then the forwarded message MUST contain an updated Max- 3005 Forwards field with a value decremented by one (1). 3007 The Max-Forwards header field MAY be ignored for all other request 3008 methods. 3010 9.15. Referer 3012 The "Referer" [sic] header field allows the client to specify the URI 3013 of the resource from which the target URI was obtained (the 3014 "referrer", although the header field is misspelled.). 3016 The Referer header field allows servers to generate lists of back- 3017 links to resources for interest, logging, optimized caching, etc. It 3018 also allows obsolete or mistyped links to be traced for maintenance. 3019 Some servers use Referer as a means of controlling where they allow 3020 links from (so-called "deep linking"), but legitimate requests do not 3021 always contain a Referer header field. 3023 If the target URI was obtained from a source that does not have its 3024 own URI (e.g., input from the user keyboard), the Referer field MUST 3025 either be sent with the value "about:blank", or not be sent at all. 3026 Note that this requirement does not apply to sources with non-HTTP 3027 URIs (e.g., FTP). 3029 Referer = absolute-URI / partial-URI 3031 Example: 3033 Referer: http://www.example.org/hypertext/Overview.html 3035 If the field value is a relative URI, it SHOULD be interpreted 3036 relative to the effective request URI. The URI MUST NOT include a 3037 fragment. See Section 11.2 for security considerations. 3039 9.16. Retry-After 3041 The header "Retry-After" field can be used with a 503 (Service 3042 Unavailable) response to indicate how long the service is expected to 3043 be unavailable to the requesting client. This field MAY also be used 3044 with any 3xx (Redirection) response to indicate the minimum time the 3045 user-agent is asked to wait before issuing the redirected request. 3047 The value of this field can be either an HTTP-date or an integer 3048 number of seconds (in decimal) after the time of the response. 3050 Retry-After = HTTP-date / delta-seconds 3052 Time spans are non-negative decimal integers, representing time in 3053 seconds. 3055 delta-seconds = 1*DIGIT 3057 Two examples of its use are 3059 Retry-After: Fri, 31 Dec 1999 23:59:59 GMT 3060 Retry-After: 120 3062 In the latter example, the delay is 2 minutes. 3064 9.17. Server 3066 The "Server" header field contains information about the software 3067 used by the origin server to handle the request. 3069 The field can contain multiple product tokens (Section 5.2) and 3070 comments (Section 3.2 of [Part1]) identifying the server and any 3071 significant subproducts. The product tokens are listed in order of 3072 their significance for identifying the application. 3074 Server = product *( RWS ( product / comment ) ) 3076 Example: 3078 Server: CERN/3.0 libwww/2.17 3080 If the response is being forwarded through a proxy, the proxy 3081 application MUST NOT modify the Server header field. Instead, it 3082 MUST include a Via field (as described in Section 6.2 of [Part1]). 3084 Note: Revealing the specific software version of the server might 3085 allow the server machine to become more vulnerable to attacks 3086 against software that is known to contain security holes. Server 3087 implementers are encouraged to make this field a configurable 3088 option. 3090 9.18. User-Agent 3092 The "User-Agent" header field contains information about the user 3093 agent originating the request. User agents SHOULD include this field 3094 with requests. 3096 Typically, it is used for statistical purposes, the tracing of 3097 protocol violations, and tailoring responses to avoid particular user 3098 agent limitations. 3100 The field can contain multiple product tokens (Section 5.2) and 3101 comments (Section 3.2 of [Part1]) identifying the agent and its 3102 significant subproducts. By convention, the product tokens are 3103 listed in order of their significance for identifying the 3104 application. 3106 Because this field is usually sent on every request a user agent 3107 makes, implementations are encouraged not to include needlessly fine- 3108 grained detail, and to limit (or even prohibit) the addition of 3109 subproducts by third parties. Overly long and detailed User-Agent 3110 field values make requests larger and can also be used to identify 3111 ("fingerprint") the user against their wishes. 3113 Likewise, implementations are encouraged not to use the product 3114 tokens of other implementations in order to declare compatibility 3115 with them, as this circumvents the purpose of the field. Finally, 3116 they are encouraged not to use comments to identify products; doing 3117 so makes the field value more difficult to parse. 3119 User-Agent = product *( RWS ( product / comment ) ) 3121 Example: 3123 User-Agent: CERN-LineMode/2.15 libwww/2.17b3 3125 10. IANA Considerations 3127 10.1. Method Registry 3129 The registration procedure for HTTP request methods is defined by 3130 Section 2.2 of this document. 3132 The HTTP Method Registry shall be created at 3133 and be populated with 3134 the registrations below: 3136 +---------+------+------------+---------------+ 3137 | Method | Safe | Idempotent | Reference | 3138 +---------+------+------------+---------------+ 3139 | CONNECT | no | no | Section 2.3.8 | 3140 | DELETE | no | yes | Section 2.3.6 | 3141 | GET | yes | yes | Section 2.3.2 | 3142 | HEAD | yes | yes | Section 2.3.3 | 3143 | OPTIONS | yes | yes | Section 2.3.1 | 3144 | POST | no | no | Section 2.3.4 | 3145 | PUT | no | yes | Section 2.3.5 | 3146 | TRACE | yes | yes | Section 2.3.7 | 3147 +---------+------+------------+---------------+ 3149 10.2. Status Code Registry 3151 The registration procedure for HTTP Status Codes -- previously 3152 defined in Section 7.1 of [RFC2817] -- is now defined by Section 4.2 3153 of this document. 3155 The HTTP Status Code Registry located at 3156 shall be updated 3157 with the registrations below: 3159 +-------+----------------------------------+----------------+ 3160 | Value | Description | Reference | 3161 +-------+----------------------------------+----------------+ 3162 | 100 | Continue | Section 4.3.1 | 3163 | 101 | Switching Protocols | Section 4.3.2 | 3164 | 200 | OK | Section 4.4.1 | 3165 | 201 | Created | Section 4.4.2 | 3166 | 202 | Accepted | Section 4.4.3 | 3167 | 203 | Non-Authoritative Information | Section 4.4.4 | 3168 | 204 | No Content | Section 4.4.5 | 3169 | 205 | Reset Content | Section 4.4.6 | 3170 | 300 | Multiple Choices | Section 4.5.1 | 3171 | 301 | Moved Permanently | Section 4.5.2 | 3172 | 302 | Found | Section 4.5.3 | 3173 | 303 | See Other | Section 4.5.4 | 3174 | 305 | Use Proxy | Section 4.5.5 | 3175 | 306 | (Unused) | Section 4.5.6 | 3176 | 307 | Temporary Redirect | Section 4.5.7 | 3177 | 400 | Bad Request | Section 4.6.1 | 3178 | 402 | Payment Required | Section 4.6.2 | 3179 | 403 | Forbidden | Section 4.6.3 | 3180 | 404 | Not Found | Section 4.6.4 | 3181 | 405 | Method Not Allowed | Section 4.6.5 | 3182 | 406 | Not Acceptable | Section 4.6.6 | 3183 | 408 | Request Timeout | Section 4.6.7 | 3184 | 409 | Conflict | Section 4.6.8 | 3185 | 410 | Gone | Section 4.6.9 | 3186 | 411 | Length Required | Section 4.6.10 | 3187 | 413 | Request Representation Too Large | Section 4.6.11 | 3188 | 414 | URI Too Long | Section 4.6.12 | 3189 | 415 | Unsupported Media Type | Section 4.6.13 | 3190 | 417 | Expectation Failed | Section 4.6.14 | 3191 | 426 | Upgrade Required | Section 4.6.15 | 3192 | 500 | Internal Server Error | Section 4.7.1 | 3193 | 501 | Not Implemented | Section 4.7.2 | 3194 | 502 | Bad Gateway | Section 4.7.3 | 3195 | 503 | Service Unavailable | Section 4.7.4 | 3196 | 504 | Gateway Timeout | Section 4.7.5 | 3197 | 505 | HTTP Version Not Supported | Section 4.7.6 | 3198 +-------+----------------------------------+----------------+ 3200 10.3. Header Field Registration 3202 The Message Header Field Registry located at shall be 3204 updated with the permanent registrations below (see [RFC3864]): 3206 +-------------------+----------+----------+--------------+ 3207 | Header Field Name | Protocol | Status | Reference | 3208 +-------------------+----------+----------+--------------+ 3209 | Accept | http | standard | Section 9.1 | 3210 | Accept-Charset | http | standard | Section 9.2 | 3211 | Accept-Encoding | http | standard | Section 9.3 | 3212 | Accept-Language | http | standard | Section 9.4 | 3213 | Allow | http | standard | Section 9.5 | 3214 | Content-Encoding | http | standard | Section 9.6 | 3215 | Content-Language | http | standard | Section 9.7 | 3216 | Content-Location | http | standard | Section 9.8 | 3217 | Content-Type | http | standard | Section 9.9 | 3218 | Date | http | standard | Section 9.10 | 3219 | Expect | http | standard | Section 9.11 | 3220 | From | http | standard | Section 9.12 | 3221 | Location | http | standard | Section 9.13 | 3222 | MIME-Version | http | standard | Appendix A.1 | 3223 | Max-Forwards | http | standard | Section 9.14 | 3224 | Referer | http | standard | Section 9.15 | 3225 | Retry-After | http | standard | Section 9.16 | 3226 | Server | http | standard | Section 9.17 | 3227 | User-Agent | http | standard | Section 9.18 | 3228 +-------------------+----------+----------+--------------+ 3230 The change controller is: "IETF (iesg@ietf.org) - Internet 3231 Engineering Task Force". 3233 10.4. Content Coding Registry 3235 The registration procedure for HTTP Content Codings is now defined by 3236 Section 5.4.1 of this document. 3238 The HTTP Content Codings Registry located at 3239 shall be updated 3240 with the registration below: 3242 +----------+------------------------------------------+-------------+ 3243 | Name | Description | Reference | 3244 +----------+------------------------------------------+-------------+ 3245 | compress | UNIX "compress" program method | Section | 3246 | | | 4.2.1 of | 3247 | | | [Part1] | 3248 | deflate | "deflate" compression mechanism | Section | 3249 | | ([RFC1951]) used inside the "zlib" data | 4.2.2 of | 3250 | | format ([RFC1950]) | [Part1] | 3251 | gzip | Same as GNU zip [RFC1952] | Section | 3252 | | | 4.2.3 of | 3253 | | | [Part1] | 3254 | identity | reserved (synonym for "no encoding" in | Section 9.3 | 3255 | | Accept-Encoding header field) | | 3256 +----------+------------------------------------------+-------------+ 3258 11. Security Considerations 3260 This section is meant to inform application developers, information 3261 providers, and users of the security limitations in HTTP/1.1 as 3262 described by this document. The discussion does not include 3263 definitive solutions to the problems revealed, though it does make 3264 some suggestions for reducing security risks. 3266 11.1. Transfer of Sensitive Information 3268 Like any generic data transfer protocol, HTTP cannot regulate the 3269 content of the data that is transferred, nor is there any a priori 3270 method of determining the sensitivity of any particular piece of 3271 information within the context of any given request. Therefore, 3272 applications SHOULD supply as much control over this information as 3273 possible to the provider of that information. Four header fields are 3274 worth special mention in this context: Server, Via, Referer and From. 3276 Revealing the specific software version of the server might allow the 3277 server machine to become more vulnerable to attacks against software 3278 that is known to contain security holes. Implementers SHOULD make 3279 the Server header field a configurable option. 3281 Proxies which serve as a portal through a network firewall SHOULD 3282 take special precautions regarding the transfer of header information 3283 that identifies the hosts behind the firewall. In particular, they 3284 SHOULD remove, or replace with sanitized versions, any Via fields 3285 generated behind the firewall. 3287 The Referer header field allows reading patterns to be studied and 3288 reverse links drawn. Although it can be very useful, its power can 3289 be abused if user details are not separated from the information 3290 contained in the Referer. Even when the personal information has 3291 been removed, the Referer header field might indicate a private 3292 document's URI whose publication would be inappropriate. 3294 The information sent in the From field might conflict with the user's 3295 privacy interests or their site's security policy, and hence it 3296 SHOULD NOT be transmitted without the user being able to disable, 3297 enable, and modify the contents of the field. The user MUST be able 3298 to set the contents of this field within a user preference or 3299 application defaults configuration. 3301 We suggest, though do not require, that a convenient toggle interface 3302 be provided for the user to enable or disable the sending of From and 3303 Referer information. 3305 The User-Agent (Section 9.18) or Server (Section 9.17) header fields 3306 can sometimes be used to determine that a specific client or server 3307 has a particular security hole which might be exploited. 3308 Unfortunately, this same information is often used for other valuable 3309 purposes for which HTTP currently has no better mechanism. 3311 Furthermore, the User-Agent header field might contain enough entropy 3312 to be used, possibly in conjunction with other material, to uniquely 3313 identify the user. 3315 Some request methods, like TRACE (Section 2.3.7), expose information 3316 that was sent in request header fields within the body of their 3317 response. Clients SHOULD be careful with sensitive information, like 3318 Cookies, Authorization credentials, and other header fields that 3319 might be used to collect data from the client. 3321 11.2. Encoding Sensitive Information in URIs 3323 Because the source of a link might be private information or might 3324 reveal an otherwise private information source, it is strongly 3325 recommended that the user be able to select whether or not the 3326 Referer field is sent. For example, a browser client could have a 3327 toggle switch for browsing openly/anonymously, which would 3328 respectively enable/disable the sending of Referer and From 3329 information. 3331 Clients SHOULD NOT include a Referer header field in a (non-secure) 3332 HTTP request if the referring page was transferred with a secure 3333 protocol. 3335 Authors of services SHOULD NOT use GET-based forms for the submission 3336 of sensitive data because that data will be placed in the request- 3337 target. Many existing servers, proxies, and user agents log or 3338 display the request-target in places where it might be visible to 3339 third parties. Such services can use POST-based form submission 3340 instead. 3342 11.3. Location Header Fields: Spoofing and Information Leakage 3344 If a single server supports multiple organizations that do not trust 3345 one another, then it MUST check the values of Location and Content- 3346 Location header fields in responses that are generated under control 3347 of said organizations to make sure that they do not attempt to 3348 invalidate resources over which they have no authority. 3350 Furthermore, appending the fragment identifier from one URI to 3351 another one obtained from a Location header field might leak 3352 confidential information to the target server -- although the 3353 fragment identifier is not transmitted in the final request, it might 3354 be visible to the user agent through other means, such as scripting. 3356 11.4. Security Considerations for CONNECT 3358 Since tunneled data is opaque to the proxy, there are additional 3359 risks to tunneling to other well-known or reserved ports. A HTTP 3360 client CONNECTing to port 25 could relay spam via SMTP, for example. 3361 As such, proxies SHOULD restrict CONNECT access to a small number of 3362 known ports. 3364 11.5. Privacy Issues Connected to Accept Header Fields 3366 Accept header fields can reveal information about the user to all 3367 servers which are accessed. The Accept-Language header field in 3368 particular can reveal information the user would consider to be of a 3369 private nature, because the understanding of particular languages is 3370 often strongly correlated to the membership of a particular ethnic 3371 group. User agents which offer the option to configure the contents 3372 of an Accept-Language header field to be sent in every request are 3373 strongly encouraged to let the configuration process include a 3374 message which makes the user aware of the loss of privacy involved. 3376 An approach that limits the loss of privacy would be for a user agent 3377 to omit the sending of Accept-Language header fields by default, and 3378 to ask the user whether or not to start sending Accept-Language 3379 header fields to a server if it detects, by looking for any Vary 3380 header fields generated by the server, that such sending could 3381 improve the quality of service. 3383 Elaborate user-customized accept header fields sent in every request, 3384 in particular if these include quality values, can be used by servers 3385 as relatively reliable and long-lived user identifiers. Such user 3386 identifiers would allow content providers to do click-trail tracking, 3387 and would allow collaborating content providers to match cross-server 3388 click-trails or form submissions of individual users. Note that for 3389 many users not behind a proxy, the network address of the host 3390 running the user agent will also serve as a long-lived user 3391 identifier. In environments where proxies are used to enhance 3392 privacy, user agents ought to be conservative in offering accept 3393 header field configuration options to end users. As an extreme 3394 privacy measure, proxies could filter the accept header fields in 3395 relayed requests. General purpose user agents which provide a high 3396 degree of header field configurability SHOULD warn users about the 3397 loss of privacy which can be involved. 3399 12. Acknowledgments 3401 See Section 9 of [Part1]. 3403 13. References 3405 13.1. Normative References 3407 [Part1] Fielding, R., Ed., Lafon, Y., Ed., 3408 and J. Reschke, Ed., "HTTP/1.1, part 3409 1: Message Routing and Syntax"", 3410 draft-ietf-httpbis-p1-messaging-20 3411 (work in progress), July 2012. 3413 [Part4] Fielding, R., Ed., Lafon, Y., Ed., 3414 and J. Reschke, Ed., "HTTP/1.1, part 3415 4: Conditional Requests", 3416 draft-ietf-httpbis-p4-conditional-20 3417 (work in progress), July 2012. 3419 [Part5] Fielding, R., Ed., Lafon, Y., Ed., 3420 and J. Reschke, Ed., "HTTP/1.1, part 3421 5: Range Requests", 3422 draft-ietf-httpbis-p5-range-20 (work 3423 in progress), July 2012. 3425 [Part6] Fielding, R., Ed., Lafon, Y., Ed., 3426 Nottingham, M., Ed., and J. Reschke, 3427 Ed., "HTTP/1.1, part 6: Caching", 3428 draft-ietf-httpbis-p6-cache-20 (work 3429 in progress), July 2012. 3431 [Part7] Fielding, R., Ed., Lafon, Y., Ed., 3432 and J. Reschke, Ed., "HTTP/1.1, part 3433 7: Authentication", 3434 draft-ietf-httpbis-p7-auth-20 (work 3435 in progress), July 2012. 3437 [RFC1950] Deutsch, L. and J-L. Gailly, "ZLIB 3438 Compressed Data Format Specification 3439 version 3.3", RFC 1950, May 1996. 3441 [RFC1951] Deutsch, P., "DEFLATE Compressed 3442 Data Format Specification version 3443 1.3", RFC 1951, May 1996. 3445 [RFC1952] Deutsch, P., Gailly, J-L., Adler, 3446 M., Deutsch, L., and G. Randers- 3447 Pehrson, "GZIP file format 3448 specification version 4.3", 3449 RFC 1952, May 1996. 3451 [RFC2045] Freed, N. and N. Borenstein, 3452 "Multipurpose Internet Mail 3453 Extensions (MIME) Part One: Format 3454 of Internet Message Bodies", 3455 RFC 2045, November 1996. 3457 [RFC2046] Freed, N. and N. Borenstein, 3458 "Multipurpose Internet Mail 3459 Extensions (MIME) Part Two: Media 3460 Types", RFC 2046, November 1996. 3462 [RFC2119] Bradner, S., "Key words for use in 3463 RFCs to Indicate Requirement 3464 Levels", BCP 14, RFC 2119, 3465 March 1997. 3467 [RFC3986] Berners-Lee, T., Fielding, R., and 3468 L. Masinter, "Uniform Resource 3469 Identifier (URI): Generic Syntax", 3470 STD 66, RFC 3986, January 2005. 3472 [RFC4647] Phillips, A., Ed. and M. Davis, Ed., 3473 "Matching of Language Tags", BCP 47, 3474 RFC 4647, September 2006. 3476 [RFC5234] Crocker, D., Ed. and P. Overell, 3477 "Augmented BNF for Syntax 3478 Specifications: ABNF", STD 68, 3479 RFC 5234, January 2008. 3481 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., 3482 "Tags for Identifying Languages", 3483 BCP 47, RFC 5646, September 2009. 3485 13.2. Informative References 3487 [RFC1123] Braden, R., "Requirements for 3488 Internet Hosts - Application and 3489 Support", STD 3, RFC 1123, 3490 October 1989. 3492 [RFC1945] Berners-Lee, T., Fielding, R., and 3493 H. Nielsen, "Hypertext Transfer 3494 Protocol -- HTTP/1.0", RFC 1945, 3495 May 1996. 3497 [RFC2049] Freed, N. and N. Borenstein, 3498 "Multipurpose Internet Mail 3499 Extensions (MIME) Part Five: 3500 Conformance Criteria and Examples", 3501 RFC 2049, November 1996. 3503 [RFC2068] Fielding, R., Gettys, J., Mogul, J., 3504 Nielsen, H., and T. Berners-Lee, 3505 "Hypertext Transfer Protocol -- 3506 HTTP/1.1", RFC 2068, January 1997. 3508 [RFC2076] Palme, J., "Common Internet Message 3509 Headers", RFC 2076, February 1997. 3511 [RFC2277] Alvestrand, H., "IETF Policy on 3512 Character Sets and Languages", 3513 BCP 18, RFC 2277, January 1998. 3515 [RFC2295] Holtman, K. and A. Mutz, 3516 "Transparent Content Negotiation in 3517 HTTP", RFC 2295, March 1998. 3519 [RFC2388] Masinter, L., "Returning Values from 3520 Forms: multipart/form-data", 3521 RFC 2388, August 1998. 3523 [RFC2557] Palme, F., Hopmann, A., Shelness, 3524 N., and E. Stefferud, "MIME 3525 Encapsulation of Aggregate 3526 Documents, such as HTML (MHTML)", 3527 RFC 2557, March 1999. 3529 [RFC2616] Fielding, R., Gettys, J., Mogul, J., 3530 Frystyk, H., Masinter, L., Leach, 3531 P., and T. Berners-Lee, "Hypertext 3532 Transfer Protocol -- HTTP/1.1", 3533 RFC 2616, June 1999. 3535 [RFC2817] Khare, R. and S. Lawrence, 3536 "Upgrading to TLS Within HTTP/1.1", 3537 RFC 2817, May 2000. 3539 [RFC3629] Yergeau, F., "UTF-8, a 3540 transformation format of ISO 10646", 3541 STD 63, RFC 3629, November 2003. 3543 [RFC3864] Klyne, G., Nottingham, M., and J. 3544 Mogul, "Registration Procedures for 3545 Message Header Fields", BCP 90, 3546 RFC 3864, September 2004. 3548 [RFC4288] Freed, N. and J. Klensin, "Media 3549 Type Specifications and Registration 3550 Procedures", BCP 13, RFC 4288, 3551 December 2005. 3553 [RFC5226] Narten, T. and H. Alvestrand, 3554 "Guidelines for Writing an IANA 3555 Considerations Section in RFCs", 3556 BCP 26, RFC 5226, May 2008. 3558 [RFC5322] Resnick, P., "Internet Message 3559 Format", RFC 5322, October 2008. 3561 [RFC5789] Dusseault, L. and J. Snell, "PATCH 3562 Method for HTTP", RFC 5789, 3563 March 2010. 3565 [RFC5987] Reschke, J., "Character Set and 3566 Language Encoding for Hypertext 3567 Transfer Protocol (HTTP) Header 3568 Field Parameters", RFC 5987, 3569 August 2010. 3571 [RFC6151] Turner, S. and L. Chen, "Updated 3572 Security Considerations for the MD5 3573 Message-Digest and the HMAC-MD5 3574 Algorithms", RFC 6151, March 2011. 3576 [RFC6266] Reschke, J., "Use of the Content- 3577 Disposition Header Field in the 3578 Hypertext Transfer Protocol (HTTP)", 3579 RFC 6266, June 2011. 3581 [draft-reschke-http-status-308] Reschke, J., "The Hypertext Transfer 3582 Protocol (HTTP) Status Code 308 3583 (Permanent Redirect)", 3584 draft-reschke-http-status-308-07 3585 (work in progress), March 2012. 3587 Appendix A. Differences between HTTP and MIME 3589 HTTP/1.1 uses many of the constructs defined for Internet Mail 3590 ([RFC5322]) and the Multipurpose Internet Mail Extensions (MIME 3592 [RFC2045]) to allow a message body to be transmitted in an open 3593 variety of representations and with extensible mechanisms. However, 3594 RFC 2045 discusses mail, and HTTP has a few features that are 3595 different from those described in MIME. These differences were 3596 carefully chosen to optimize performance over binary connections, to 3597 allow greater freedom in the use of new media types, to make date 3598 comparisons easier, and to acknowledge the practice of some early 3599 HTTP servers and clients. 3601 This appendix describes specific areas where HTTP differs from MIME. 3602 Proxies and gateways to strict MIME environments SHOULD be aware of 3603 these differences and provide the appropriate conversions where 3604 necessary. Proxies and gateways from MIME environments to HTTP also 3605 need to be aware of the differences because some conversions might be 3606 required. 3608 A.1. MIME-Version 3610 HTTP is not a MIME-compliant protocol. However, HTTP/1.1 messages 3611 MAY include a single MIME-Version header field to indicate what 3612 version of the MIME protocol was used to construct the message. Use 3613 of the MIME-Version header field indicates that the message is in 3614 full conformance with the MIME protocol (as defined in [RFC2045]). 3615 Proxies/gateways are responsible for ensuring full conformance (where 3616 possible) when exporting HTTP messages to strict MIME environments. 3618 MIME-Version = 1*DIGIT "." 1*DIGIT 3620 MIME version "1.0" is the default for use in HTTP/1.1. However, 3621 HTTP/1.1 message parsing and semantics are defined by this document 3622 and not the MIME specification. 3624 A.2. Conversion to Canonical Form 3626 MIME requires that an Internet mail body-part be converted to 3627 canonical form prior to being transferred, as described in Section 4 3628 of [RFC2049]. Section 5.5.1 of this document describes the forms 3629 allowed for subtypes of the "text" media type when transmitted over 3630 HTTP. [RFC2046] requires that content with a type of "text" 3631 represent line breaks as CRLF and forbids the use of CR or LF outside 3632 of line break sequences. HTTP allows CRLF, bare CR, and bare LF to 3633 indicate a line break within text content when a message is 3634 transmitted over HTTP. 3636 Where it is possible, a proxy or gateway from HTTP to a strict MIME 3637 environment SHOULD translate all line breaks within the text media 3638 types described in Section 5.5.1 of this document to the RFC 2049 3639 canonical form of CRLF. Note, however, that this might be 3640 complicated by the presence of a Content-Encoding and by the fact 3641 that HTTP allows the use of some character encodings which do not use 3642 octets 13 and 10 to represent CR and LF, respectively, as is the case 3643 for some multi-byte character encodings. 3645 Conversion will break any cryptographic checksums applied to the 3646 original content unless the original content is already in canonical 3647 form. Therefore, the canonical form is recommended for any content 3648 that uses such checksums in HTTP. 3650 A.3. Conversion of Date Formats 3652 HTTP/1.1 uses a restricted set of date formats (Section 5.1) to 3653 simplify the process of date comparison. Proxies and gateways from 3654 other protocols SHOULD ensure that any Date header field present in a 3655 message conforms to one of the HTTP/1.1 formats and rewrite the date 3656 if necessary. 3658 A.4. Introduction of Content-Encoding 3660 MIME does not include any concept equivalent to HTTP/1.1's Content- 3661 Encoding header field. Since this acts as a modifier on the media 3662 type, proxies and gateways from HTTP to MIME-compliant protocols MUST 3663 either change the value of the Content-Type header field or decode 3664 the representation before forwarding the message. (Some experimental 3665 applications of Content-Type for Internet mail have used a media-type 3666 parameter of ";conversions=" to perform a function 3667 equivalent to Content-Encoding. However, this parameter is not part 3668 of the MIME standards). 3670 A.5. No Content-Transfer-Encoding 3672 HTTP does not use the Content-Transfer-Encoding field of MIME. 3673 Proxies and gateways from MIME-compliant protocols to HTTP MUST 3674 remove any Content-Transfer-Encoding prior to delivering the response 3675 message to an HTTP client. 3677 Proxies and gateways from HTTP to MIME-compliant protocols are 3678 responsible for ensuring that the message is in the correct format 3679 and encoding for safe transport on that protocol, where "safe 3680 transport" is defined by the limitations of the protocol being used. 3681 Such a proxy or gateway SHOULD label the data with an appropriate 3682 Content-Transfer-Encoding if doing so will improve the likelihood of 3683 safe transport over the destination protocol. 3685 A.6. MHTML and Line Length Limitations 3687 HTTP implementations which share code with MHTML [RFC2557] 3688 implementations need to be aware of MIME line length limitations. 3689 Since HTTP does not have this limitation, HTTP does not fold long 3690 lines. MHTML messages being transported by HTTP follow all 3691 conventions of MHTML, including line length limitations and folding, 3692 canonicalization, etc., since HTTP transports all message-bodies as 3693 payload (see Section 5.5.2) and does not interpret the content or any 3694 MIME header lines that might be contained therein. 3696 Appendix B. Additional Features 3698 [RFC1945] and [RFC2068] document protocol elements used by some 3699 existing HTTP implementations, but not consistently and correctly 3700 across most HTTP/1.1 applications. Implementers are advised to be 3701 aware of these features, but cannot rely upon their presence in, or 3702 interoperability with, other HTTP/1.1 applications. Some of these 3703 describe proposed experimental features, and some describe features 3704 that experimental deployment found lacking that are now addressed in 3705 the base HTTP/1.1 specification. 3707 A number of other header fields, such as Content-Disposition and 3708 Title, from SMTP and MIME are also often implemented (see [RFC6266] 3709 and [RFC2076]). 3711 Appendix C. Changes from RFC 2616 3713 Introduce Method Registry. (Section 2.2) 3715 Clarify definition of POST. (Section 2.3.4) 3717 Remove requirement to handle all Content-* header fields; ban use of 3718 Content-Range with PUT. (Section 2.3.5) 3720 Take over definition of CONNECT method from [RFC2817]. 3721 (Section 2.3.8) 3723 Take over the Status Code Registry, previously defined in Section 7.1 3724 of [RFC2817]. (Section 4.2) 3726 Broadened the definition of 203 (Non-Authoritative Information) to 3727 include cases of payload transformations as well. (Section 4.4.4) 3729 Status codes 301, 302, and 307: removed the normative requirements on 3730 both response payloads and user interaction. (Section 4.5) 3732 Failed to consider that there are many other request methods that are 3733 safe to automatically redirect, and further that the user agent is 3734 able to make that determination based on the request method 3735 semantics. Furthermore, allow user agents to rewrite the method from 3736 POST to GET for status codes 301 and 302. (Sections 4.5.2, 4.5.3 and 3737 4.5.7) 3739 Deprecate 305 (Use Proxy) status code, because user agents did not 3740 implement it. It used to indicate that the target resource needs to 3741 be accessed through the proxy given by the Location field. The 3742 Location field gave the URI of the proxy. The recipient was expected 3743 to repeat this single request via the proxy. (Section 4.5.5) 3745 Define status 426 (Upgrade Required) (this was incorporated from 3746 [RFC2817]). (Section 4.6.15) 3748 Change ABNF productions for header fields to only define the field 3749 value. (Section 9) 3751 Reclassify "Allow" as response header field, removing the option to 3752 specify it in a PUT request. Relax the server requirement on the 3753 contents of the Allow header field and remove requirement on clients 3754 to always trust the header field value. (Section 9.5) 3756 The ABNF for the Expect header field has been both fixed (allowing 3757 parameters for value-less expectations as well) and simplified 3758 (allowing trailing semicolons after "100-continue" when they were 3759 invalid before). (Section 9.11) 3761 Correct syntax of Location header field to allow URI references 3762 (including relative references and fragments), as referred symbol 3763 "absoluteURI" wasn't what was expected, and add some clarifications 3764 as to when use of fragments would not be appropriate. (Section 9.13) 3766 Restrict Max-Forwards header field to OPTIONS and TRACE (previously, 3767 extension methods could have used it as well). (Section 9.14) 3769 Allow Referer field value of "about:blank" as alternative to not 3770 specifying it. (Section 9.15) 3772 In the description of the Server header field, the Via field was 3773 described as a SHOULD. The requirement was and is stated correctly 3774 in the description of the Via header field in Section 6.2 of [Part1]. 3775 (Section 9.17) 3777 Clarify contexts that charset is used in. (Section 5.3) 3779 Registration of Content Codings now requires IETF Review 3780 (Section 5.4.1) 3781 Remove the default character encoding of "ISO-8859-1" for text media 3782 types; the default now is whatever the media type definition says. 3783 (Section 5.5.1) 3785 Change ABNF productions for header fields to only define the field 3786 value. (Section 9) 3788 Remove definition of Content-MD5 header field because it was 3789 inconsistently implemented with respect to partial responses, and 3790 also because of known deficiencies in the hash algorithm itself (see 3791 [RFC6151] for details). (Section 9) 3793 Remove ISO-8859-1 special-casing in Accept-Charset. (Section 9.2) 3795 Remove base URI setting semantics for Content-Location due to poor 3796 implementation support, which was caused by too many broken servers 3797 emitting bogus Content-Location header fields, and also the 3798 potentially undesirable effect of potentially breaking relative links 3799 in content-negotiated resources. (Section 9.8) 3801 Remove reference to non-existant identity transfer-coding value 3802 tokens. (Appendix A.5) 3804 Remove discussion of Content-Disposition header field, it is now 3805 defined by [RFC6266]. (Appendix B) 3807 Appendix D. Imported ABNF 3809 The following core rules are included by reference, as defined in 3810 Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), 3811 CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double 3812 quote), HEXDIG (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF 3813 (line feed), OCTET (any 8-bit sequence of data), SP (space), and 3814 VCHAR (any visible US-ASCII character). 3816 The rules below are defined in [Part1]: 3818 BWS = 3819 OWS = 3820 RWS = 3821 quoted-string = 3822 token = 3823 word = 3825 absolute-URI = 3826 comment = 3827 partial-URI = 3828 qvalue = 3829 URI-reference = 3831 Appendix E. Collected ABNF 3833 Accept = [ ( "," / ( media-range [ accept-params ] ) ) *( OWS "," [ 3834 OWS ( media-range [ accept-params ] ) ] ) ] 3835 Accept-Charset = *( "," OWS ) ( ( charset / "*" ) [ OWS ";" OWS "q=" 3836 qvalue ] ) *( OWS "," [ OWS ( ( charset / "*" ) [ OWS ";" OWS "q=" 3837 qvalue ] ) ] ) 3838 Accept-Encoding = [ ( "," / ( codings [ OWS ";" OWS "q=" qvalue ] ) ) 3839 *( OWS "," [ OWS ( codings [ OWS ";" OWS "q=" qvalue ] ) ] ) ] 3840 Accept-Language = *( "," OWS ) ( language-range [ OWS ";" OWS "q=" 3841 qvalue ] ) *( OWS "," [ OWS ( language-range [ OWS ";" OWS "q=" 3842 qvalue ] ) ] ) 3843 Allow = [ ( "," / method ) *( OWS "," [ OWS method ] ) ] 3845 BWS = 3847 Content-Encoding = *( "," OWS ) content-coding *( OWS "," [ OWS 3848 content-coding ] ) 3849 Content-Language = *( "," OWS ) language-tag *( OWS "," [ OWS 3850 language-tag ] ) 3851 Content-Location = absolute-URI / partial-URI 3852 Content-Type = media-type 3854 Date = HTTP-date 3856 Expect = *( "," OWS ) expectation *( OWS "," [ OWS expectation ] ) 3858 From = mailbox 3860 GMT = %x47.4D.54 ; GMT 3862 HTTP-date = rfc1123-date / obs-date 3864 Location = URI-reference 3866 MIME-Version = 1*DIGIT "." 1*DIGIT 3867 Max-Forwards = 1*DIGIT 3869 OWS = 3871 RWS = 3872 Referer = absolute-URI / partial-URI 3873 Retry-After = HTTP-date / delta-seconds 3875 Server = product *( RWS ( product / comment ) ) 3876 URI-reference = 3877 User-Agent = product *( RWS ( product / comment ) ) 3879 absolute-URI = 3880 accept-ext = OWS ";" OWS token [ "=" word ] 3881 accept-params = OWS ";" OWS "q=" qvalue *accept-ext 3882 asctime-date = day-name SP date3 SP time-of-day SP year 3883 attribute = token 3885 charset = token 3886 codings = content-coding / "identity" / "*" 3887 comment = 3888 content-coding = token 3890 date1 = day SP month SP year 3891 date2 = day "-" month "-" 2DIGIT 3892 date3 = month SP ( 2DIGIT / ( SP DIGIT ) ) 3893 day = 2DIGIT 3894 day-name = %x4D.6F.6E ; Mon 3895 / %x54.75.65 ; Tue 3896 / %x57.65.64 ; Wed 3897 / %x54.68.75 ; Thu 3898 / %x46.72.69 ; Fri 3899 / %x53.61.74 ; Sat 3900 / %x53.75.6E ; Sun 3901 day-name-l = %x4D.6F.6E.64.61.79 ; Monday 3902 / %x54.75.65.73.64.61.79 ; Tuesday 3903 / %x57.65.64.6E.65.73.64.61.79 ; Wednesday 3904 / %x54.68.75.72.73.64.61.79 ; Thursday 3905 / %x46.72.69.64.61.79 ; Friday 3906 / %x53.61.74.75.72.64.61.79 ; Saturday 3907 / %x53.75.6E.64.61.79 ; Sunday 3908 delta-seconds = 1*DIGIT 3910 expect-name = token 3911 expect-param = expect-name [ BWS "=" BWS expect-value ] 3912 expect-value = token / quoted-string 3913 expectation = expect-name [ BWS "=" BWS expect-value ] *( OWS ";" [ 3914 OWS expect-param ] ) 3916 hour = 2DIGIT 3918 language-range = 3919 language-tag = 3921 mailbox = 3922 media-range = ( "*/*" / ( type "/*" ) / ( type "/" subtype ) ) *( OWS 3923 ";" OWS parameter ) 3925 media-type = type "/" subtype *( OWS ";" OWS parameter ) 3926 method = token 3927 minute = 2DIGIT 3928 month = %x4A.61.6E ; Jan 3929 / %x46.65.62 ; Feb 3930 / %x4D.61.72 ; Mar 3931 / %x41.70.72 ; Apr 3932 / %x4D.61.79 ; May 3933 / %x4A.75.6E ; Jun 3934 / %x4A.75.6C ; Jul 3935 / %x41.75.67 ; Aug 3936 / %x53.65.70 ; Sep 3937 / %x4F.63.74 ; Oct 3938 / %x4E.6F.76 ; Nov 3939 / %x44.65.63 ; Dec 3941 obs-date = rfc850-date / asctime-date 3943 parameter = attribute "=" value 3944 partial-URI = 3945 product = token [ "/" product-version ] 3946 product-version = token 3948 quoted-string = 3949 qvalue = 3951 rfc1123-date = day-name "," SP date1 SP time-of-day SP GMT 3952 rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT 3954 second = 2DIGIT 3955 subtype = token 3957 time-of-day = hour ":" minute ":" second 3958 token = 3959 type = token 3961 value = word 3963 word = 3965 year = 4DIGIT 3967 Appendix F. Change Log (to be removed by RFC Editor before publication) 3969 F.1. Since RFC 2616 3971 Extracted relevant partitions from [RFC2616]. 3973 F.2. Since draft-ietf-httpbis-p2-semantics-00 3975 Closed issues: 3977 o : "Via is a MUST" 3978 () 3980 o : "Fragments 3981 allowed in Location" 3982 () 3984 o : "Safe Methods 3985 vs Redirection" () 3987 o : "Revise 3988 description of the POST method" 3989 () 3991 o : "Normative and 3992 Informative references" 3994 o : "RFC2606 3995 Compliance" 3997 o : "Informative 3998 references" 4000 o : "Redundant 4001 cross-references" 4003 Other changes: 4005 o Move definitions of 304 and 412 condition codes to [Part4] 4007 F.3. Since draft-ietf-httpbis-p3-payload-00 4009 Closed issues: 4011 o : "Media Type 4012 Registrations" () 4014 o : "Clarification 4015 regarding quoting of charset values" 4016 () 4018 o : "Remove 4019 'identity' token references" 4020 () 4022 o : "Accept- 4023 Encoding BNF" 4025 o : "Normative and 4026 Informative references" 4028 o : "RFC1700 4029 references" 4031 o : "Updating to 4032 RFC4288" 4034 o : "Informative 4035 references" 4037 o : "ISO-8859-1 4038 Reference" 4040 o : "Encoding 4041 References Normative" 4043 o : "Normative up- 4044 to-date references" 4046 F.4. Since draft-ietf-httpbis-p2-semantics-01 4048 Closed issues: 4050 o : "PUT side 4051 effects" 4053 o : "Duplicate Host 4054 header requirements" 4056 Ongoing work on ABNF conversion 4057 (): 4059 o Move "Product Tokens" section (back) into Part 1, as "token" is 4060 used in the definition of the Upgrade header field. 4062 o Add explicit references to BNF syntax and rules imported from 4063 other parts of the specification. 4065 o Copy definition of delta-seconds from Part6 instead of referencing 4066 it. 4068 F.5. Since draft-ietf-httpbis-p3-payload-01 4070 Ongoing work on ABNF conversion 4071 (): 4073 o Add explicit references to BNF syntax and rules imported from 4074 other parts of the specification. 4076 F.6. Since draft-ietf-httpbis-p2-semantics-02 4078 Closed issues: 4080 o : "Requiring 4081 Allow in 405 responses" 4083 o : "Status Code 4084 Registry" 4086 o : "Redirection 4087 vs. Location" 4089 o : "Cacheability 4090 of 303 response" 4092 o : "305 Use Proxy" 4094 o : 4095 "Classification for Allow header field" 4097 o : "PUT - 'store 4098 under' vs 'store at'" 4100 Ongoing work on IANA Message Header Field Registration 4101 (): 4103 o Reference RFC 3984, and update header field registrations for 4104 header fields defined in this document. 4106 Ongoing work on ABNF conversion 4107 (): 4109 o Replace string literals when the string really is case-sensitive 4110 (method). 4112 F.7. Since draft-ietf-httpbis-p3-payload-02 4114 Closed issues: 4116 o : "Quoting 4117 Charsets" 4119 o : 4120 "Classification for Allow header field" 4122 o : "missing 4123 default for qvalue in description of Accept-Encoding" 4125 Ongoing work on IANA Message Header Field Registration 4126 (): 4128 o Reference RFC 3984, and update header field registrations for 4129 header fields defined in this document. 4131 F.8. Since draft-ietf-httpbis-p2-semantics-03 4133 Closed issues: 4135 o : "OPTIONS 4136 request bodies" 4138 o : "Description 4139 of CONNECT should refer to RFC2817" 4141 o : "Location 4142 Content-Location reference request/response mixup" 4144 Ongoing work on Method Registry 4145 (): 4147 o Added initial proposal for registration process, plus initial 4148 content (non-HTTP/1.1 methods to be added by a separate 4149 specification). 4151 F.9. Since draft-ietf-httpbis-p3-payload-03 4153 Closed issues: 4155 o : "Quoting 4156 Charsets" 4158 o : "language tag 4159 matching (Accept-Language) vs RFC4647" 4161 o : "RFC 1806 has 4162 been replaced by RFC2183" 4164 Other changes: 4166 o : "Encoding 4167 References Normative" -- rephrase the annotation and reference 4168 BCP97. 4170 F.10. Since draft-ietf-httpbis-p2-semantics-04 4172 Closed issues: 4174 o : "Content-*" 4176 o : "RFC 2822 is 4177 updated by RFC 5322" 4179 Ongoing work on ABNF conversion 4180 (): 4182 o Use "/" instead of "|" for alternatives. 4184 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 4185 whitespace ("OWS") and required whitespace ("RWS"). 4187 o Rewrite ABNFs to spell out whitespace rules, factor out header 4188 field value format definitions. 4190 F.11. Since draft-ietf-httpbis-p3-payload-04 4192 Closed issues: 4194 o : "RFC 2822 is 4195 updated by RFC 5322" 4197 Ongoing work on ABNF conversion 4198 (): 4200 o Use "/" instead of "|" for alternatives. 4202 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 4203 whitespace ("OWS") and required whitespace ("RWS"). 4205 o Rewrite ABNFs to spell out whitespace rules, factor out header 4206 field value format definitions. 4208 F.12. Since draft-ietf-httpbis-p2-semantics-05 4210 Closed issues: 4212 o : "reason-phrase 4213 BNF" 4215 Final work on ABNF conversion 4216 (): 4218 o Add appendix containing collected and expanded ABNF, reorganize 4219 ABNF introduction. 4221 F.13. Since draft-ietf-httpbis-p3-payload-05 4223 Closed issues: 4225 o : "Join 4226 "Differences Between HTTP Entities and RFC 2045 Entities"?" 4228 Final work on ABNF conversion 4229 (): 4231 o Add appendix containing collected and expanded ABNF, reorganize 4232 ABNF introduction. 4234 Other changes: 4236 o Move definition of quality values into Part 1. 4238 F.14. Since draft-ietf-httpbis-p2-semantics-06 4240 Closed issues: 4242 o : "Clarify when 4243 Referer is sent" 4245 o : "status codes 4246 vs methods" 4248 o : "Do not 4249 require "updates" relation for specs that register status codes or 4250 method names" 4252 F.15. Since draft-ietf-httpbis-p3-payload-06 4254 Closed issues: 4256 o : "Content- 4257 Location isn't special" 4259 o : "Content 4260 Sniffing" 4262 F.16. Since draft-ietf-httpbis-p2-semantics-07 4264 Closed issues: 4266 o : "Idempotency" 4268 o : "TRACE security 4269 considerations" 4271 o : "Clarify rules 4272 for determining what entities a response carries" 4274 o : "update note 4275 citing RFC 1945 and 2068" 4277 o : "update note 4278 about redirect limit" 4280 o : "Location 4281 header field ABNF should use 'URI'" 4283 o : "fragments in 4284 Location vs status 303" 4286 o : "move IANA 4287 registrations for optional status codes" 4289 Partly resolved issues: 4291 o : "Are OPTIONS 4292 and TRACE safe?" 4294 F.17. Since draft-ietf-httpbis-p3-payload-07 4296 Closed issues: 4298 o : "Updated 4299 reference for language tags" 4301 o : "Clarify rules 4302 for determining what entities a response carries" 4304 o : "Content- 4305 Location base-setting problems" 4307 o : "Content 4308 Sniffing" 4310 o : "pick IANA 4311 policy (RFC5226) for Transfer Coding / Content Coding" 4313 o : "move 4314 definitions of gzip/deflate/compress to part 1" 4316 Partly resolved issues: 4318 o : "update IANA 4319 requirements wrt Transfer-Coding values" (add the IANA 4320 Considerations subsection) 4322 o : "update IANA 4323 requirements wrt Content-Coding values" (add the IANA 4324 Considerations subsection) 4326 F.18. Since draft-ietf-httpbis-p2-semantics-08 4328 Closed issues: 4330 o : "Safe Methods 4331 vs Redirection" (we missed the introduction to the 3xx status 4332 codes when fixing this previously) 4334 F.19. Since draft-ietf-httpbis-p3-payload-08 4336 Closed issues: 4338 o : "Content 4339 Negotiation for media types" 4341 o : "Accept- 4342 Language: which RFC4647 filtering?" 4344 F.20. Since draft-ietf-httpbis-p2-semantics-09 4346 Closed issues: 4348 o : "Fragment 4349 combination / precedence during redirects" 4351 Partly resolved issues: 4353 o : "Location 4354 header field payload handling" 4356 o : "Term for the 4357 requested resource's URI" 4359 F.21. Since draft-ietf-httpbis-p3-payload-09 4361 Closed issues: 4363 o : "MIME-Version 4364 not listed in P1, general header fields" 4366 o : "IANA registry 4367 for content/transfer encodings" 4369 o : "Content 4370 Sniffing" 4372 o : "use of term 4373 "word" when talking about header field structure" 4375 Partly resolved issues: 4377 o : "Term for the 4378 requested resource's URI" 4380 F.22. Since draft-ietf-httpbis-p2-semantics-10 4382 Closed issues: 4384 o : "Clarify 4385 'Requested Variant'" 4387 o : "Clarify 4388 entity / representation / variant terminology" 4390 o : "Methods and 4391 Caching" 4393 o : "OPTIONS vs 4394 Max-Forwards" 4396 o : "Status codes 4397 and caching" 4399 o : "consider 4400 removing the 'changes from 2068' sections" 4402 F.23. Since draft-ietf-httpbis-p3-payload-10 4404 Closed issues: 4406 o : "Clarify 4407 'Requested Variant'" 4409 o : "Content- 4410 Location isn't special" 4412 o : "Delimiting 4413 messages with multipart/byteranges" 4415 o : "Clarify 4416 entity / representation / variant terminology" 4418 o : "confusing 4419 req. language for Content-Location" 4421 o : "Content- 4422 Location on 304 responses" 4424 o : "'requested 4425 resource' in content-encoding definition" 4427 o : "consider 4428 removing the 'changes from 2068' sections" 4430 Partly resolved issues: 4432 o : "Content-MD5 4433 and partial responses" 4435 F.24. Since draft-ietf-httpbis-p2-semantics-11 4437 Closed issues: 4439 o : 4440 "Considerations for new status codes" 4442 o : 4443 "Considerations for new methods" 4445 o : "User-Agent 4446 guidelines" (relating to the 'User-Agent' header field) 4448 F.25. Since draft-ietf-httpbis-p3-payload-11 4450 Closed issues: 4452 o : "Factor out 4453 Content-Disposition" 4455 F.26. Since draft-ietf-httpbis-p2-semantics-12 4457 Closed issues: 4459 o : "Fragment 4460 combination / precedence during redirects" (added warning about 4461 having a fragid on the redirect might cause inconvenience in some 4462 cases) 4464 o : "Content-* vs. 4465 PUT" 4467 o : "205 Bodies" 4469 o : "Understanding 4470 Content-* on non-PUT requests" 4472 o : "Content-*" 4474 o : "Header field 4475 type defaulting" 4477 o : "PUT - 'store 4478 under' vs 'store at'" 4480 o : "duplicate 4481 ABNF for reason-phrase" 4483 o : "Note special 4484 status of Content-* prefix in header field registration 4485 procedures" 4487 o : "Max-Forwards 4488 vs extension methods" 4490 o : "What is the 4491 value space of HTTP status codes?" (actually fixed in 4492 draft-ietf-httpbis-p2-semantics-11) 4494 o : "Header Field 4495 Classification" 4497 o : "PUT side 4498 effect: invalidation or just stale?" 4500 o : "proxies not 4501 supporting certain methods" 4503 o : "Migrate 4504 CONNECT from RFC2817 to p2" 4506 o : "Migrate 4507 Upgrade details from RFC2817" 4509 o : "clarify PUT 4510 semantics'" 4512 o : "duplicate 4513 ABNF for 'Method'" 4515 o : "untangle 4516 ABNFs for header fields" 4518 F.27. Since draft-ietf-httpbis-p3-payload-12 4520 Closed issues: 4522 o : "Header Field 4523 Classification" 4525 o : "untangle 4526 ABNFs for header fields" 4528 o : "potentially 4529 misleading MAY in media-type def" 4531 F.28. Since draft-ietf-httpbis-p2-semantics-13 4533 Closed issues: 4535 o : "untangle 4536 ABNFs for header fields" 4538 o : "message body 4539 in CONNECT request" 4541 F.29. Since draft-ietf-httpbis-p3-payload-13 4543 Closed issues: 4545 o : "Default 4546 charsets for text media types" 4548 o : "Content-MD5 4549 and partial responses" 4551 o : "untangle 4552 ABNFs for header fields" 4554 o : "confusing 4555 undefined parameter in media range example" 4557 F.30. Since draft-ietf-httpbis-p2-semantics-14 4559 Closed issues: 4561 o : "Clarify 4562 status code for rate limiting" 4564 o : "clarify 403 4565 forbidden" 4567 o : "Clarify 203 4568 Non-Authoritative Information" 4570 o : "update 4571 default reason phrase for 413" 4573 F.31. Since draft-ietf-httpbis-p3-payload-14 4575 None. 4577 F.32. Since draft-ietf-httpbis-p2-semantics-15 4579 Closed issues: 4581 o : "Strength of 4582 requirements on Accept re: 406" 4584 o : "400 response 4585 isn't generic" 4587 F.33. Since draft-ietf-httpbis-p3-payload-15 4589 Closed issues: 4591 o : "Strength of 4592 requirements on Accept re: 406" 4594 F.34. Since draft-ietf-httpbis-p2-semantics-16 4596 Closed issues: 4598 o : "Redirects and 4599 non-GET methods" 4601 o : "Document 4602 HTTP's error-handling philosophy" 4604 o : 4605 "Considerations for new header fields" 4607 o : "clarify 303 4608 redirect on HEAD" 4610 F.35. Since draft-ietf-httpbis-p3-payload-16 4612 Closed issues: 4614 o : "Document 4615 HTTP's error-handling philosophy" 4617 F.36. Since draft-ietf-httpbis-p2-semantics-17 4619 Closed issues: 4621 o : "Location 4622 header field payload handling" 4624 o : "Clarify 4625 status code for rate limiting" (change backed out because a new 4626 status code is being defined for this purpose) 4628 o : "should there 4629 be a permanent variant of 307" 4631 o : "When are 4632 Location's semantics triggered?" 4634 o : "'expect' 4635 grammar missing OWS" 4637 o : "header field 4638 considerations: quoted-string vs use of double quotes" 4640 F.37. Since draft-ietf-httpbis-p3-payload-17 4642 Closed issues: 4644 o : "intended 4645 maturity level vs normative references" 4647 F.38. Since draft-ietf-httpbis-p2-semantics-18 4649 Closed issues: 4651 o : "Combining 4652 HEAD responses" 4654 o : "Requirements 4655 for user intervention during redirects" 4657 o : "message-body 4658 in CONNECT response" 4660 o : "Applying 4661 original fragment to 'plain' redirected URI" 4663 o : "Misplaced 4664 text on connection handling in p2" 4666 o : "clarify that 4667 201 doesn't require Location header fields" 4669 o : "relax 4670 requirements on hypertext in 3/4/5xx error responses" 4672 o : "example for 4673 426 response should have a payload" 4675 o : "drop 4676 indirection entries for status codes" 4678 F.39. Since draft-ietf-httpbis-p3-payload-18 4680 Closed issues: 4682 o : "is ETag a 4683 representation header field?" 4685 o : "Content- 4686 Location doesn't constrain the cardinality of representations" 4688 o : "make IANA 4689 policy definitions consistent" 4691 F.40. Since draft-ietf-httpbis-p2-semantics-19 and 4692 draft-ietf-httpbis-p3-payload-19 4694 Closed issues: 4696 o : "should there 4697 be a permanent variant of 307" 4699 o : "clarify that 4700 201 can imply *multiple* resources were created" 4702 o : "merge P2 and 4703 P3" 4705 o : "ABNF 4706 requirements for recipients" 4708 o : "Capturing 4709 more information in the method registry" 4711 o : "note 4712 introduction of new IANA registries as normative changes" 4714 Index 4716 1 4717 1xx Informational (status code class) 25 4719 2 4720 2xx Successful (status code class) 26 4722 3 4723 3xx Redirection (status code class) 28 4725 4 4726 4xx Client Error (status code class) 32 4728 5 4729 5xx Server Error (status code class) 36 4731 1 4732 100 Continue (status code) 25 4733 100-continue (expect value) 62 4734 101 Switching Protocols (status code) 25 4736 2 4737 200 OK (status code) 26 4738 201 Created (status code) 26 4739 202 Accepted (status code) 27 4740 203 Non-Authoritative Information (status code) 27 4741 204 No Content (status code) 27 4742 205 Reset Content (status code) 28 4744 3 4745 300 Multiple Choices (status code) 29 4746 301 Moved Permanently (status code) 30 4747 302 Found (status code) 30 4748 303 See Other (status code) 31 4749 305 Use Proxy (status code) 31 4750 306 (Unused) (status code) 31 4751 307 Temporary Redirect (status code) 32 4753 4 4754 400 Bad Request (status code) 32 4755 402 Payment Required (status code) 32 4756 403 Forbidden (status code) 32 4757 404 Not Found (status code) 33 4758 405 Method Not Allowed (status code) 33 4759 406 Not Acceptable (status code) 33 4760 408 Request Timeout (status code) 33 4761 409 Conflict (status code) 34 4762 410 Gone (status code) 34 4763 411 Length Required (status code) 34 4764 413 Request Representation Too Large (status code) 35 4765 414 URI Too Long (status code) 35 4766 415 Unsupported Media Type (status code) 35 4767 417 Expectation Failed (status code) 35 4768 426 Upgrade Required (status code) 35 4770 5 4771 500 Internal Server Error (status code) 36 4772 501 Not Implemented (status code) 36 4773 502 Bad Gateway (status code) 36 4774 503 Service Unavailable (status code) 36 4775 504 Gateway Timeout (status code) 37 4776 505 HTTP Version Not Supported (status code) 37 4778 A 4779 Accept header field 52 4780 Accept-Charset header field 54 4781 Accept-Encoding header field 55 4782 Accept-Language header field 56 4783 Allow header field 57 4785 C 4786 Coding Format 4787 compress 42 4788 deflate 42 4789 gzip 42 4790 compress (Coding Format) 42 4791 CONNECT method 17 4792 content negotiation 7 4793 Content-Encoding header field 57 4794 Content-Language header field 58 4795 Content-Location header field 59 4796 Content-Transfer-Encoding header field 79 4797 Content-Type header field 61 4799 D 4800 Date header field 61 4801 deflate (Coding Format) 42 4802 DELETE method 16 4804 E 4805 Expect header field 62 4806 Expect Values 4807 100-continue 62 4809 F 4810 From header field 63 4812 G 4813 GET method 12 4814 Grammar 4815 Accept 52 4816 Accept-Charset 54 4817 Accept-Encoding 55 4818 accept-ext 52 4819 Accept-Language 56 4820 accept-params 52 4821 Allow 57 4822 asctime-date 40 4823 attribute 43 4824 charset 41 4825 codings 55 4826 content-coding 41 4827 Content-Encoding 57 4828 Content-Language 58 4829 Content-Location 59 4830 Content-Type 61 4831 Date 61 4832 date1 39 4833 day 39 4834 day-name 39 4835 day-name-l 39 4836 delta-seconds 66 4837 Expect 62 4838 expect-name 62 4839 expect-param 62 4840 expect-value 62 4841 expectation 62 4842 From 63 4843 GMT 39 4844 hour 39 4845 HTTP-date 38 4846 language-range 56 4847 language-tag 44 4848 Location 64 4849 Max-Forwards 65 4850 media-range 52 4851 media-type 42 4852 method 8 4853 MIME-Version 78 4854 minute 39 4855 month 39 4856 obs-date 39 4857 parameter 43 4858 product 40 4859 product-version 40 4860 Referer 65 4861 Retry-After 66 4862 rfc850-date 40 4863 rfc1123-date 39 4864 second 39 4865 Server 66 4866 subtype 42 4867 time-of-day 39 4868 type 42 4869 User-Agent 67 4870 value 43 4871 year 39 4872 gzip (Coding Format) 42 4874 H 4875 HEAD method 12 4876 Header Fields 4877 Accept 52 4878 Accept-Charset 54 4879 Accept-Encoding 55 4880 Accept-Language 56 4881 Allow 57 4882 Content-Encoding 57 4883 Content-Language 58 4884 Content-Location 59 4885 Content-Transfer-Encoding 79 4886 Content-Type 61 4887 Date 61 4888 Expect 62 4889 From 63 4890 Location 63 4891 Max-Forwards 65 4892 MIME-Version 78 4893 Referer 65 4894 Retry-After 66 4895 Server 66 4896 User-Agent 67 4898 I 4899 Idempotent Methods 9 4901 L 4902 Location header field 63 4904 M 4905 Max-Forwards header field 65 4906 Methods 4907 CONNECT 17 4908 DELETE 16 4909 GET 12 4910 HEAD 12 4911 OPTIONS 11 4912 POST 13 4913 PUT 14 4914 TRACE 16 4915 MIME-Version header field 78 4917 O 4918 OPTIONS method 11 4920 P 4921 payload 45 4922 POST method 13 4923 PUT method 14 4925 R 4926 Referer header field 65 4927 representation 45 4928 Retry-After header field 66 4930 S 4931 Safe Methods 9 4932 selected representation 47 4933 Server header field 66 4934 Status Codes 4935 100 Continue 25 4936 101 Switching Protocols 25 4937 200 OK 26 4938 201 Created 26 4939 202 Accepted 27 4940 203 Non-Authoritative Information 27 4941 204 No Content 27 4942 205 Reset Content 28 4943 300 Multiple Choices 29 4944 301 Moved Permanently 30 4945 302 Found 30 4946 303 See Other 31 4947 305 Use Proxy 31 4948 306 (Unused) 31 4949 307 Temporary Redirect 32 4950 400 Bad Request 32 4951 402 Payment Required 32 4952 403 Forbidden 32 4953 404 Not Found 33 4954 405 Method Not Allowed 33 4955 406 Not Acceptable 33 4956 408 Request Timeout 33 4957 409 Conflict 34 4958 410 Gone 34 4959 411 Length Required 34 4960 413 Request Representation Too Large 35 4961 414 URI Too Long 35 4962 415 Unsupported Media Type 35 4963 417 Expectation Failed 35 4964 426 Upgrade Required 35 4965 500 Internal Server Error 36 4966 501 Not Implemented 36 4967 502 Bad Gateway 36 4968 503 Service Unavailable 36 4969 504 Gateway Timeout 37 4970 505 HTTP Version Not Supported 37 4971 Status Codes Classes 4972 1xx Informational 25 4973 2xx Successful 26 4974 3xx Redirection 28 4975 4xx Client Error 32 4976 5xx Server Error 36 4978 T 4979 TRACE method 16 4981 U 4982 User-Agent header field 67 4984 Authors' Addresses 4986 Roy T. Fielding (editor) 4987 Adobe Systems Incorporated 4988 345 Park Ave 4989 San Jose, CA 95110 4990 USA 4992 EMail: fielding@gbiv.com 4993 URI: http://roy.gbiv.com/ 4995 Yves Lafon (editor) 4996 World Wide Web Consortium 4997 W3C / ERCIM 4998 2004, rte des Lucioles 4999 Sophia-Antipolis, AM 06902 5000 France 5002 EMail: ylafon@w3.org 5003 URI: http://www.raubacapeu.net/people/yves/ 5004 Julian F. Reschke (editor) 5005 greenbytes GmbH 5006 Hafenweg 16 5007 Muenster, NW 48155 5008 Germany 5010 EMail: julian.reschke@greenbytes.de 5011 URI: http://greenbytes.de/tech/webdav/