idnits 2.17.1 draft-lafon-rfc2616bis-02.txt: -(5895): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 29. ** The document seems to lack an RFC 3978 Section 5.4 Reference to BCP 78. ** The document seems to lack an RFC 3978 Section 5.5 (updated by RFC 4748) Disclaimer. ** The document seems to lack an RFC 3979 Section 5, para. 1 IPR Disclosure Acknowledgement. ** The document seems to lack an RFC 3979 Section 5, para. 2 IPR Disclosure Acknowledgement. ** The document seems to lack an RFC 3979 Section 5, para. 3 IPR Disclosure Invitation. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack an Authors' Addresses Section. ** The abstract seems to contain references ([2], [RFC2616], [RFC2026], [RFC2324], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. -- The draft header indicates that this document obsoletes RFC2616, but the abstract doesn't seem to directly say this. It does mention RFC2616 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 19, 2006) is 6339 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) -- Missing reference section? 'RFC2324' on line 427 looks like a reference -- Missing reference section? '1' on line 72 looks like a reference -- Missing reference section? '2' on line 73 looks like a reference -- Missing reference section? 'RFC2616' on line 79 looks like a reference -- Missing reference section? 'RFC2026' on line 82 looks like a reference -- Missing reference section? 'RFC1945' on line 409 looks like a reference -- Missing reference section? 'RFC1630' on line 992 looks like a reference -- Missing reference section? 'RFC1738' on line 1006 looks like a reference -- Missing reference section? 'RFC1737' on line 994 looks like a reference -- Missing reference section? 'RFC822' on line 1620 looks like a reference -- Missing reference section? 'RFC2045' on line 1282 looks like a reference -- Missing reference section? 'RFC821' on line 437 looks like a reference -- Missing reference section? 'RFC977' on line 437 looks like a reference -- Missing reference section? 'RFC959' on line 437 looks like a reference -- Missing reference section? 'RFC1436' on line 438 looks like a reference -- Missing reference section? 'WAIS' on line 438 looks like a reference -- Missing reference section? 'RFC2119' on line 447 looks like a reference -- Missing reference section? 'RFC1700' on line 1394 looks like a reference -- Missing reference section? 'USASCII' on line 850 looks like a reference -- Missing reference section? 'CRLF' on line 879 looks like a reference -- Missing reference section? 'ISO-8859' on line 884 looks like a reference -- Missing reference section? 'RFC2047' on line 885 looks like a reference -- Missing reference section? 'RFC2145' on line 965 looks like a reference -- Missing reference section? 'RFC2068' on line 3125 looks like a reference -- Missing reference section? 'RFC1808' on line 1006 looks like a reference -- Missing reference section? 'RFC2396' on line 1897 looks like a reference -- Missing reference section? 'RFC1900' on line 1035 looks like a reference -- Missing reference section? 'RFC1123' on line 1078 looks like a reference -- Missing reference section? 'RFC1036' on line 1080 looks like a reference -- Missing reference section? 'RFC2279' on line 1176 looks like a reference -- Missing reference section? 'RFC2277' on line 1176 looks like a reference -- Missing reference section? 'RFC1952' on line 1219 looks like a reference -- Missing reference section? 'RFC1950' on line 1237 looks like a reference -- Missing reference section? 'RFC1951' on line 1238 looks like a reference -- Missing reference section? 'RFC1590' on line 1395 looks like a reference -- Missing reference section? 'RFC2046' on line 1436 looks like a reference -- Missing reference section? 'RFC1867' on line 1464 looks like a reference -- Missing reference section? 'RFC1766' on line 1517 looks like a reference -- Missing reference section? 'Pad1995' on line 2207 looks like a reference -- Missing reference section? 'Spero' on line 2207 looks like a reference -- Missing reference section? 'Nie1997' on line 2209 looks like a reference -- Missing reference section? 'Tou1998' on line 2210 looks like a reference -- Missing reference section? 'Luo1998' on line 2816 looks like a reference -- Missing reference section? 'RFC2617' on line 5172 looks like a reference -- Missing reference section? 'RFC1305' on line 3921 looks like a reference -- Missing reference section? 'RFC1864' on line 5843 looks like a reference Summary: 10 errors (**), 0 flaws (~~), 2 warnings (==), 51 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Fielding 3 Internet-Draft Day Software 4 Obsoletes: 2616 (if approved) J. Gettys 5 Intended status: Standards Track J. Mogul 6 Expires: May 23, 2007 HP 7 H. Frystyk 8 Microsoft 9 L. Masinter 10 Adobe Systems 11 P. Leach 12 Microsoft 13 T. Berners-Lee 14 W3C/MIT 15 Y. Lafon, Ed. 16 W3C 17 J. Reschke, Ed. 18 greenbytes 19 November 19, 2006 21 Hypertext Transfer Protocol -- HTTP/1.1 22 draft-lafon-rfc2616bis-02 24 Status of this Memo 26 By submitting this Internet-Draft, each author represents that any 27 applicable patent or other IPR claims of which he or she is aware 28 have been or will be disclosed, and any of which he or she becomes 29 aware will be disclosed, in accordance with Section 6 of BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF), its areas, and its working groups. Note that 33 other groups may also distribute working documents as Internet- 34 Drafts. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 The list of current Internet-Drafts can be accessed at 42 http://www.ietf.org/ietf/1id-abstracts.txt. 44 The list of Internet-Draft Shadow Directories can be accessed at 45 http://www.ietf.org/shadow.html. 47 This Internet-Draft will expire on May 23, 2007. 49 Copyright Notice 51 Copyright (C) The IETF Trust (2006). 53 Abstract 55 The Hypertext Transfer Protocol (HTTP) is an application-level 56 protocol for distributed, collaborative, hypermedia information 57 systems. It is a generic, stateless, protocol which can be used for 58 many tasks beyond its use for hypertext, such as name servers and 59 distributed object management systems, through extension of its 60 request methods, error codes and headers [RFC2324]. A feature of 61 HTTP is the typing and negotiation of data representation, allowing 62 systems to be built independently of the data being transferred. 64 HTTP has been in use by the World-Wide Web global information 65 initiative since 1990. This specification defines the protocol 66 referred to as "HTTP/1.1", and is an update to RFC2616. 68 Editorial Note (To be removed by RFC Editor before publication) 70 Distribution of this document is unlimited. Please send comments to 71 the Hypertext Transfer Protocol (HTTP) mailing list at 72 ietf-http-wg@w3.org [1], which may be joined by sending a message 73 with subject "subscribe" to ietf-http-wg-request@w3.org [2]. 74 Discussions of the HTTP working group are archived at 75 . XML versions, 76 latest edits and the issues list for this document are available from 77 . 79 The purpose of this document is to revise [RFC2616], doing only 80 minimal corrections. For now, it is not planned to advance the 81 standards level of HTTP, thus - if published - the specification will 82 still be a "Proposed Standard" (see [RFC2026]). 84 The current plan is to incorporate known errata, and to update the 85 specification text according to the current IETF publication 86 guidelines. In particular: 88 o Incorporate the corrections collected in the RFC2616 errata 89 document () (most of the 90 suggested fixes have been applied to draft 01). 92 o Incorporate corrections for newly discovered and agreed-upon 93 problems, using the HTTP WG mailing list as forum and 94 as 95 issues list. 97 o Update references, and re-classify them into "Normative" and 98 "Informative", based on the prior work done by Jim Gettys in 99 . 101 This document is based on a variant of the original RFC2616 102 specification formatted using Marshall T. Rose's "xml2rfc" tool (see 103 ) and therefore deviates from the original 104 text in word wrapping, page breaks, list formatting, reference 105 formatting, whitespace usage and appendix numbering. Otherwise, it 106 is supposed to contain an accurate copy of the original specification 107 text. See for a comparison between both 109 documents, as generated by "rfcdiff" 110 (). 112 Table of Contents 114 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 11 115 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . 11 116 1.2. Requirements . . . . . . . . . . . . . . . . . . . . . . 11 117 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . 12 118 1.4. Overall Operation . . . . . . . . . . . . . . . . . . . 16 119 2. Notational Conventions and Generic Grammar . . . . . . . . . 19 120 2.1. Augmented BNF . . . . . . . . . . . . . . . . . . . . . 19 121 2.2. Basic Rules . . . . . . . . . . . . . . . . . . . . . . 21 122 3. Protocol Parameters . . . . . . . . . . . . . . . . . . . . . 23 123 3.1. HTTP Version . . . . . . . . . . . . . . . . . . . . . . 23 124 3.2. Uniform Resource Identifiers . . . . . . . . . . . . . . 24 125 3.2.1. General Syntax . . . . . . . . . . . . . . . . . . . 24 126 3.2.2. http URL . . . . . . . . . . . . . . . . . . . . . . 25 127 3.2.3. URI Comparison . . . . . . . . . . . . . . . . . . . 25 128 3.3. Date/Time Formats . . . . . . . . . . . . . . . . . . . 26 129 3.3.1. Full Date . . . . . . . . . . . . . . . . . . . . . 26 130 3.3.2. Delta Seconds . . . . . . . . . . . . . . . . . . . 27 131 3.4. Character Sets . . . . . . . . . . . . . . . . . . . . . 27 132 3.4.1. Missing Charset . . . . . . . . . . . . . . . . . . 28 133 3.5. Content Codings . . . . . . . . . . . . . . . . . . . . 29 134 3.6. Transfer Codings . . . . . . . . . . . . . . . . . . . . 30 135 3.6.1. Chunked Transfer Coding . . . . . . . . . . . . . . 31 136 3.7. Media Types . . . . . . . . . . . . . . . . . . . . . . 32 137 3.7.1. Canonicalization and Text Defaults . . . . . . . . . 33 138 3.7.2. Multipart Types . . . . . . . . . . . . . . . . . . 34 139 3.8. Product Tokens . . . . . . . . . . . . . . . . . . . . . 34 140 3.9. Quality Values . . . . . . . . . . . . . . . . . . . . . 35 141 3.10. Language Tags . . . . . . . . . . . . . . . . . . . . . 35 142 3.11. Entity Tags . . . . . . . . . . . . . . . . . . . . . . 36 143 3.12. Range Units . . . . . . . . . . . . . . . . . . . . . . 36 144 4. HTTP Message . . . . . . . . . . . . . . . . . . . . . . . . 38 145 4.1. Message Types . . . . . . . . . . . . . . . . . . . . . 38 146 4.2. Message Headers . . . . . . . . . . . . . . . . . . . . 38 147 4.3. Message Body . . . . . . . . . . . . . . . . . . . . . . 39 148 4.4. Message Length . . . . . . . . . . . . . . . . . . . . . 40 149 4.5. General Header Fields . . . . . . . . . . . . . . . . . 41 150 5. Request . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 151 5.1. Request-Line . . . . . . . . . . . . . . . . . . . . . . 43 152 5.1.1. Method . . . . . . . . . . . . . . . . . . . . . . . 43 153 5.1.2. Request-URI . . . . . . . . . . . . . . . . . . . . 44 154 5.2. The Resource Identified by a Request . . . . . . . . . . 45 155 5.3. Request Header Fields . . . . . . . . . . . . . . . . . 46 156 6. Response . . . . . . . . . . . . . . . . . . . . . . . . . . 47 157 6.1. Status-Line . . . . . . . . . . . . . . . . . . . . . . 47 158 6.1.1. Status Code and Reason Phrase . . . . . . . . . . . 47 159 6.2. Response Header Fields . . . . . . . . . . . . . . . . . 50 161 7. Entity . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 162 7.1. Entity Header Fields . . . . . . . . . . . . . . . . . . 51 163 7.2. Entity Body . . . . . . . . . . . . . . . . . . . . . . 51 164 7.2.1. Type . . . . . . . . . . . . . . . . . . . . . . . . 52 165 7.2.2. Entity Length . . . . . . . . . . . . . . . . . . . 52 166 8. Connections . . . . . . . . . . . . . . . . . . . . . . . . . 53 167 8.1. Persistent Connections . . . . . . . . . . . . . . . . . 53 168 8.1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . 53 169 8.1.2. Overall Operation . . . . . . . . . . . . . . . . . 53 170 8.1.3. Proxy Servers . . . . . . . . . . . . . . . . . . . 55 171 8.1.4. Practical Considerations . . . . . . . . . . . . . . 55 172 8.2. Message Transmission Requirements . . . . . . . . . . . 56 173 8.2.1. Persistent Connections and Flow Control . . . . . . 56 174 8.2.2. Monitoring Connections for Error Status Messages . . 56 175 8.2.3. Use of the 100 (Continue) Status . . . . . . . . . . 57 176 8.2.4. Client Behavior if Server Prematurely Closes 177 Connection . . . . . . . . . . . . . . . . . . . . . 59 178 9. Method Definitions . . . . . . . . . . . . . . . . . . . . . 60 179 9.1. Safe and Idempotent Methods . . . . . . . . . . . . . . 60 180 9.1.1. Safe Methods . . . . . . . . . . . . . . . . . . . . 60 181 9.1.2. Idempotent Methods . . . . . . . . . . . . . . . . . 60 182 9.2. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . 61 183 9.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . 62 184 9.4. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 62 185 9.5. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 63 186 9.6. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . 64 187 9.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 65 188 9.8. TRACE . . . . . . . . . . . . . . . . . . . . . . . . . 65 189 9.9. CONNECT . . . . . . . . . . . . . . . . . . . . . . . . 66 190 10. Status Code Definitions . . . . . . . . . . . . . . . . . . . 67 191 10.1. Informational 1xx . . . . . . . . . . . . . . . . . . . 67 192 10.1.1. 100 Continue . . . . . . . . . . . . . . . . . . . . 67 193 10.1.2. 101 Switching Protocols . . . . . . . . . . . . . . 67 194 10.2. Successful 2xx . . . . . . . . . . . . . . . . . . . . . 68 195 10.2.1. 200 OK . . . . . . . . . . . . . . . . . . . . . . . 68 196 10.2.2. 201 Created . . . . . . . . . . . . . . . . . . . . 68 197 10.2.3. 202 Accepted . . . . . . . . . . . . . . . . . . . . 68 198 10.2.4. 203 Non-Authoritative Information . . . . . . . . . 69 199 10.2.5. 204 No Content . . . . . . . . . . . . . . . . . . . 69 200 10.2.6. 205 Reset Content . . . . . . . . . . . . . . . . . 69 201 10.2.7. 206 Partial Content . . . . . . . . . . . . . . . . 70 202 10.3. Redirection 3xx . . . . . . . . . . . . . . . . . . . . 70 203 10.3.1. 300 Multiple Choices . . . . . . . . . . . . . . . . 71 204 10.3.2. 301 Moved Permanently . . . . . . . . . . . . . . . 71 205 10.3.3. 302 Found . . . . . . . . . . . . . . . . . . . . . 72 206 10.3.4. 303 See Other . . . . . . . . . . . . . . . . . . . 72 207 10.3.5. 304 Not Modified . . . . . . . . . . . . . . . . . . 73 208 10.3.6. 305 Use Proxy . . . . . . . . . . . . . . . . . . . 73 209 10.3.7. 306 (Unused) . . . . . . . . . . . . . . . . . . . . 74 210 10.3.8. 307 Temporary Redirect . . . . . . . . . . . . . . . 74 211 10.4. Client Error 4xx . . . . . . . . . . . . . . . . . . . . 74 212 10.4.1. 400 Bad Request . . . . . . . . . . . . . . . . . . 75 213 10.4.2. 401 Unauthorized . . . . . . . . . . . . . . . . . . 75 214 10.4.3. 402 Payment Required . . . . . . . . . . . . . . . . 75 215 10.4.4. 403 Forbidden . . . . . . . . . . . . . . . . . . . 75 216 10.4.5. 404 Not Found . . . . . . . . . . . . . . . . . . . 75 217 10.4.6. 405 Method Not Allowed . . . . . . . . . . . . . . . 76 218 10.4.7. 406 Not Acceptable . . . . . . . . . . . . . . . . . 76 219 10.4.8. 407 Proxy Authentication Required . . . . . . . . . 76 220 10.4.9. 408 Request Timeout . . . . . . . . . . . . . . . . 77 221 10.4.10. 409 Conflict . . . . . . . . . . . . . . . . . . . . 77 222 10.4.11. 410 Gone . . . . . . . . . . . . . . . . . . . . . . 77 223 10.4.12. 411 Length Required . . . . . . . . . . . . . . . . 78 224 10.4.13. 412 Precondition Failed . . . . . . . . . . . . . . 78 225 10.4.14. 413 Request Entity Too Large . . . . . . . . . . . . 78 226 10.4.15. 414 Request-URI Too Long . . . . . . . . . . . . . . 78 227 10.4.16. 415 Unsupported Media Type . . . . . . . . . . . . . 78 228 10.4.17. 416 Requested Range Not Satisfiable . . . . . . . . 78 229 10.4.18. 417 Expectation Failed . . . . . . . . . . . . . . . 79 230 10.5. Server Error 5xx . . . . . . . . . . . . . . . . . . . . 79 231 10.5.1. 500 Internal Server Error . . . . . . . . . . . . . 79 232 10.5.2. 501 Not Implemented . . . . . . . . . . . . . . . . 79 233 10.5.3. 502 Bad Gateway . . . . . . . . . . . . . . . . . . 79 234 10.5.4. 503 Service Unavailable . . . . . . . . . . . . . . 80 235 10.5.5. 504 Gateway Timeout . . . . . . . . . . . . . . . . 80 236 10.5.6. 505 HTTP Version Not Supported . . . . . . . . . . . 80 237 11. Access Authentication . . . . . . . . . . . . . . . . . . . . 81 238 12. Content Negotiation . . . . . . . . . . . . . . . . . . . . . 82 239 12.1. Server-driven Negotiation . . . . . . . . . . . . . . . 82 240 12.2. Agent-driven Negotiation . . . . . . . . . . . . . . . . 83 241 12.3. Transparent Negotiation . . . . . . . . . . . . . . . . 84 242 13. Caching in HTTP . . . . . . . . . . . . . . . . . . . . . . . 85 243 13.1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 244 13.1.1. Cache Correctness . . . . . . . . . . . . . . . . . 86 245 13.1.2. Warnings . . . . . . . . . . . . . . . . . . . . . . 87 246 13.1.3. Cache-control Mechanisms . . . . . . . . . . . . . . 88 247 13.1.4. Explicit User Agent Warnings . . . . . . . . . . . . 88 248 13.1.5. Exceptions to the Rules and Warnings . . . . . . . . 89 249 13.1.6. Client-controlled Behavior . . . . . . . . . . . . . 89 250 13.2. Expiration Model . . . . . . . . . . . . . . . . . . . . 90 251 13.2.1. Server-Specified Expiration . . . . . . . . . . . . 90 252 13.2.2. Heuristic Expiration . . . . . . . . . . . . . . . . 90 253 13.2.3. Age Calculations . . . . . . . . . . . . . . . . . . 91 254 13.2.4. Expiration Calculations . . . . . . . . . . . . . . 93 255 13.2.5. Disambiguating Expiration Values . . . . . . . . . . 94 256 13.2.6. Disambiguating Multiple Responses . . . . . . . . . 95 258 13.3. Validation Model . . . . . . . . . . . . . . . . . . . . 95 259 13.3.1. Last-Modified Dates . . . . . . . . . . . . . . . . 96 260 13.3.2. Entity Tag Cache Validators . . . . . . . . . . . . 96 261 13.3.3. Weak and Strong Validators . . . . . . . . . . . . . 97 262 13.3.4. Rules for When to Use Entity Tags and 263 Last-Modified Dates . . . . . . . . . . . . . . . . 99 264 13.3.5. Non-validating Conditionals . . . . . . . . . . . . 101 265 13.4. Response Cacheability . . . . . . . . . . . . . . . . . 101 266 13.5. Constructing Responses From Caches . . . . . . . . . . . 102 267 13.5.1. End-to-end and Hop-by-hop Headers . . . . . . . . . 102 268 13.5.2. Non-modifiable Headers . . . . . . . . . . . . . . . 103 269 13.5.3. Combining Headers . . . . . . . . . . . . . . . . . 104 270 13.5.4. Combining Byte Ranges . . . . . . . . . . . . . . . 105 271 13.6. Caching Negotiated Responses . . . . . . . . . . . . . . 106 272 13.7. Shared and Non-Shared Caches . . . . . . . . . . . . . . 107 273 13.8. Errors or Incomplete Response Cache Behavior . . . . . . 107 274 13.9. Side Effects of GET and HEAD . . . . . . . . . . . . . . 108 275 13.10. Invalidation After Updates or Deletions . . . . . . . . 108 276 13.11. Write-Through Mandatory . . . . . . . . . . . . . . . . 109 277 13.12. Cache Replacement . . . . . . . . . . . . . . . . . . . 109 278 13.13. History Lists . . . . . . . . . . . . . . . . . . . . . 110 279 14. Header Field Definitions . . . . . . . . . . . . . . . . . . 111 280 14.1. Accept . . . . . . . . . . . . . . . . . . . . . . . . . 111 281 14.2. Accept-Charset . . . . . . . . . . . . . . . . . . . . . 113 282 14.3. Accept-Encoding . . . . . . . . . . . . . . . . . . . . 113 283 14.4. Accept-Language . . . . . . . . . . . . . . . . . . . . 115 284 14.5. Accept-Ranges . . . . . . . . . . . . . . . . . . . . . 116 285 14.6. Age . . . . . . . . . . . . . . . . . . . . . . . . . . 116 286 14.7. Allow . . . . . . . . . . . . . . . . . . . . . . . . . 117 287 14.8. Authorization . . . . . . . . . . . . . . . . . . . . . 117 288 14.9. Cache-Control . . . . . . . . . . . . . . . . . . . . . 118 289 14.9.1. What is Cacheable . . . . . . . . . . . . . . . . . 120 290 14.9.2. What May be Stored by Caches . . . . . . . . . . . . 121 291 14.9.3. Modifications of the Basic Expiration Mechanism . . 122 292 14.9.4. Cache Revalidation and Reload Controls . . . . . . . 124 293 14.9.5. No-Transform Directive . . . . . . . . . . . . . . . 126 294 14.9.6. Cache Control Extensions . . . . . . . . . . . . . . 127 295 14.10. Connection . . . . . . . . . . . . . . . . . . . . . . . 128 296 14.11. Content-Encoding . . . . . . . . . . . . . . . . . . . . 129 297 14.12. Content-Language . . . . . . . . . . . . . . . . . . . . 129 298 14.13. Content-Length . . . . . . . . . . . . . . . . . . . . . 130 299 14.14. Content-Location . . . . . . . . . . . . . . . . . . . . 131 300 14.15. Content-MD5 . . . . . . . . . . . . . . . . . . . . . . 132 301 14.16. Content-Range . . . . . . . . . . . . . . . . . . . . . 133 302 14.17. Content-Type . . . . . . . . . . . . . . . . . . . . . . 135 303 14.18. Date . . . . . . . . . . . . . . . . . . . . . . . . . . 135 304 14.18.1. Clockless Origin Server Operation . . . . . . . . . 136 305 14.19. ETag . . . . . . . . . . . . . . . . . . . . . . . . . . 137 306 14.20. Expect . . . . . . . . . . . . . . . . . . . . . . . . . 137 307 14.21. Expires . . . . . . . . . . . . . . . . . . . . . . . . 138 308 14.22. From . . . . . . . . . . . . . . . . . . . . . . . . . . 139 309 14.23. Host . . . . . . . . . . . . . . . . . . . . . . . . . . 139 310 14.24. If-Match . . . . . . . . . . . . . . . . . . . . . . . . 140 311 14.25. If-Modified-Since . . . . . . . . . . . . . . . . . . . 141 312 14.26. If-None-Match . . . . . . . . . . . . . . . . . . . . . 143 313 14.27. If-Range . . . . . . . . . . . . . . . . . . . . . . . . 144 314 14.28. If-Unmodified-Since . . . . . . . . . . . . . . . . . . 145 315 14.29. Last-Modified . . . . . . . . . . . . . . . . . . . . . 145 316 14.30. Location . . . . . . . . . . . . . . . . . . . . . . . . 146 317 14.31. Max-Forwards . . . . . . . . . . . . . . . . . . . . . . 147 318 14.32. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . 147 319 14.33. Proxy-Authenticate . . . . . . . . . . . . . . . . . . . 148 320 14.34. Proxy-Authorization . . . . . . . . . . . . . . . . . . 148 321 14.35. Range . . . . . . . . . . . . . . . . . . . . . . . . . 149 322 14.35.1. Byte Ranges . . . . . . . . . . . . . . . . . . . . 149 323 14.35.2. Range Retrieval Requests . . . . . . . . . . . . . . 150 324 14.36. Referer . . . . . . . . . . . . . . . . . . . . . . . . 151 325 14.37. Retry-After . . . . . . . . . . . . . . . . . . . . . . 152 326 14.38. Server . . . . . . . . . . . . . . . . . . . . . . . . . 152 327 14.39. TE . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 328 14.40. Trailer . . . . . . . . . . . . . . . . . . . . . . . . 154 329 14.41. Transfer-Encoding . . . . . . . . . . . . . . . . . . . 154 330 14.42. Upgrade . . . . . . . . . . . . . . . . . . . . . . . . 155 331 14.43. User-Agent . . . . . . . . . . . . . . . . . . . . . . . 156 332 14.44. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . 156 333 14.45. Via . . . . . . . . . . . . . . . . . . . . . . . . . . 157 334 14.46. Warning . . . . . . . . . . . . . . . . . . . . . . . . 159 335 14.47. WWW-Authenticate . . . . . . . . . . . . . . . . . . . . 161 336 15. Security Considerations . . . . . . . . . . . . . . . . . . . 162 337 15.1. Personal Information . . . . . . . . . . . . . . . . . . 162 338 15.1.1. Abuse of Server Log Information . . . . . . . . . . 162 339 15.1.2. Transfer of Sensitive Information . . . . . . . . . 162 340 15.1.3. Encoding Sensitive Information in URI's . . . . . . 163 341 15.1.4. Privacy Issues Connected to Accept Headers . . . . . 164 342 15.2. Attacks Based On File and Path Names . . . . . . . . . . 164 343 15.3. DNS Spoofing . . . . . . . . . . . . . . . . . . . . . . 165 344 15.4. Location Headers and Spoofing . . . . . . . . . . . . . 165 345 15.5. Content-Disposition Issues . . . . . . . . . . . . . . . 166 346 15.6. Authentication Credentials and Idle Clients . . . . . . 166 347 15.7. Proxies and Caching . . . . . . . . . . . . . . . . . . 166 348 15.7.1. Denial of Service Attacks on Proxies . . . . . . . . 167 349 16. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 168 350 16.1. (RFC2616) . . . . . . . . . . . . . . . . . . . . . . . 168 351 16.2. (This Document) . . . . . . . . . . . . . . . . . . . . 169 352 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 170 353 17.1. References . . . . . . . . . . . . . . . . . . . . . . . 170 354 17.2. Informative References . . . . . . . . . . . . . . . . . 174 355 Appendix A. Internet Media Type message/http and 356 application/http . . . . . . . . . . . . . . . . . . 176 357 Appendix B. Internet Media Type multipart/byteranges . . . . . . 178 358 Appendix C. Tolerant Applications . . . . . . . . . . . . . . . 180 359 Appendix D. Differences Between HTTP Entities and RFC 2045 360 Entities . . . . . . . . . . . . . . . . . . . . . . 181 361 D.1. MIME-Version . . . . . . . . . . . . . . . . . . . . . . 181 362 D.2. Conversion to Canonical Form . . . . . . . . . . . . . . 181 363 D.3. Conversion of Date Formats . . . . . . . . . . . . . . . 182 364 D.4. Introduction of Content-Encoding . . . . . . . . . . . . 182 365 D.5. No Content-Transfer-Encoding . . . . . . . . . . . . . . 182 366 D.6. Introduction of Transfer-Encoding . . . . . . . . . . . 183 367 D.7. MHTML and Line Length Limitations . . . . . . . . . . . 183 368 Appendix E. Additional Features . . . . . . . . . . . . . . . . 184 369 E.1. Content-Disposition . . . . . . . . . . . . . . . . . . 184 370 Appendix F. Compatibility with Previous Versions . . . . . . . . 185 371 F.1. Changes from HTTP/1.0 . . . . . . . . . . . . . . . . . 185 372 F.1.1. Changes to Simplify Multi-homed Web Servers and 373 Conserve IP Addresses . . . . . . . . . . . . . . . 185 374 F.2. Compatibility with HTTP/1.0 Persistent Connections . . . 186 375 F.3. Changes from RFC 2068 . . . . . . . . . . . . . . . . . 187 376 F.4. Changes from RFC 2616 . . . . . . . . . . . . . . . . . 189 377 Appendix G. Change Log (to be removed by RFC Editor before 378 publication) . . . . . . . . . . . . . . . . . . . . 191 379 G.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . 191 380 G.2. Since draft-lafon-rfc2616bis-00 . . . . . . . . . . . . 191 381 G.3. Since draft-lafon-rfc2616bis-01 . . . . . . . . . . . . 191 382 Appendix H. Resolved issues (to be removed by RFC Editor 383 before publication) . . . . . . . . . . . . . . . . 192 384 H.1. rfc2606-compliance . . . . . . . . . . . . . . . . . . . 192 385 H.2. references_style . . . . . . . . . . . . . . . . . . . . 192 386 H.3. media-reg . . . . . . . . . . . . . . . . . . . . . . . 192 387 H.4. location-fragments . . . . . . . . . . . . . . . . . . . 193 388 Appendix I. Open issues (to be removed by RFC Editor prior to 389 publication) . . . . . . . . . . . . . . . . . . . . 194 390 I.1. rfc2616bis . . . . . . . . . . . . . . . . . . . . . . . 194 391 I.2. unneeded_references . . . . . . . . . . . . . . . . . . 194 392 I.3. edit . . . . . . . . . . . . . . . . . . . . . . . . . . 194 393 I.4. rfc2048_informative_and_obsolete . . . . . . . . . . . . 194 394 I.5. languagetag . . . . . . . . . . . . . . . . . . . . . . 194 395 I.6. fragment-combination . . . . . . . . . . . . . . . . . . 195 396 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 397 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 207 398 Intellectual Property and Copyright Statements . . . . . . . . . 210 400 1. Introduction 402 1.1. Purpose 404 The Hypertext Transfer Protocol (HTTP) is an application-level 405 protocol for distributed, collaborative, hypermedia information 406 systems. HTTP has been in use by the World-Wide Web global 407 information initiative since 1990. The first version of HTTP, 408 referred to as HTTP/0.9, was a simple protocol for raw data transfer 409 across the Internet. HTTP/1.0, as defined by [RFC1945], improved the 410 protocol by allowing messages to be in the format of MIME-like 411 messages, containing metainformation about the data transferred and 412 modifiers on the request/response semantics. However, HTTP/1.0 does 413 not sufficiently take into consideration the effects of hierarchical 414 proxies, caching, the need for persistent connections, or virtual 415 hosts. In addition, the proliferation of incompletely-implemented 416 applications calling themselves "HTTP/1.0" has necessitated a 417 protocol version change in order for two communicating applications 418 to determine each other's true capabilities. 420 This specification defines the protocol referred to as "HTTP/1.1". 421 This protocol includes more stringent requirements than HTTP/1.0 in 422 order to ensure reliable implementation of its features. 424 Practical information systems require more functionality than simple 425 retrieval, including search, front-end update, and annotation. HTTP 426 allows an open-ended set of methods and headers that indicate the 427 purpose of a request [RFC2324]. It builds on the discipline of 428 reference provided by the Uniform Resource Identifier (URI) 429 [RFC1630], as a location (URL) [RFC1738] or name (URN) [RFC1737], for 430 indicating the resource to which a method is to be applied. Messages 431 are passed in a format similar to that used by Internet mail [RFC822] 432 as defined by the Multipurpose Internet Mail Extensions (MIME) 433 [RFC2045]. 435 HTTP is also used as a generic protocol for communication between 436 user agents and proxies/gateways to other Internet systems, including 437 those supported by the SMTP [RFC821], NNTP [RFC977], FTP [RFC959], 438 Gopher [RFC1436], and WAIS [WAIS] protocols. In this way, HTTP 439 allows basic hypermedia access to resources available from diverse 440 applications. 442 1.2. Requirements 444 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 445 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 446 document are to be interpreted as described in [RFC2119]. 448 An implementation is not compliant if it fails to satisfy one or more 449 of the MUST or REQUIRED level requirements for the protocols it 450 implements. An implementation that satisfies all the MUST or 451 REQUIRED level and all the SHOULD level requirements for its 452 protocols is said to be "unconditionally compliant"; one that 453 satisfies all the MUST level requirements but not all the SHOULD 454 level requirements for its protocols is said to be "conditionally 455 compliant." 457 1.3. Terminology 459 This specification uses a number of terms to refer to the roles 460 played by participants in, and objects of, the HTTP communication. 462 connection 464 A transport layer virtual circuit established between two programs 465 for the purpose of communication. 467 message 469 The basic unit of HTTP communication, consisting of a structured 470 sequence of octets matching the syntax defined in Section 4 and 471 transmitted via the connection. 473 request 475 An HTTP request message, as defined in Section 5. 477 response 479 An HTTP response message, as defined in Section 6. 481 resource 483 A network data object or service that can be identified by a URI, 484 as defined in Section 3.2. Resources may be available in multiple 485 representations (e.g. multiple languages, data formats, size, and 486 resolutions) or vary in other ways. 488 entity 490 The information transferred as the payload of a request or 491 response. An entity consists of metainformation in the form of 492 entity-header fields and content in the form of an entity-body, as 493 described in Section 7. 495 representation 496 An entity included with a response that is subject to content 497 negotiation, as described in Section 12. There may exist multiple 498 representations associated with a particular response status. 500 content negotiation 502 The mechanism for selecting the appropriate representation when 503 servicing a request, as described in Section 12. The 504 representation of entities in any response can be negotiated 505 (including error responses). 507 variant 509 A resource may have one, or more than one, representation(s) 510 associated with it at any given instant. Each of these 511 representations is termed a `variant'. Use of the term `variant' 512 does not necessarily imply that the resource is subject to content 513 negotiation. 515 client 517 A program that establishes connections for the purpose of sending 518 requests. 520 user agent 522 The client which initiates a request. These are often browsers, 523 editors, spiders (web-traversing robots), or other end user tools. 525 server 527 An application program that accepts connections in order to 528 service requests by sending back responses. Any given program may 529 be capable of being both a client and a server; our use of these 530 terms refers only to the role being performed by the program for a 531 particular connection, rather than to the program's capabilities 532 in general. Likewise, any server may act as an origin server, 533 proxy, gateway, or tunnel, switching behavior based on the nature 534 of each request. 536 origin server 538 The server on which a given resource resides or is to be created. 540 proxy 542 An intermediary program which acts as both a server and a client 543 for the purpose of making requests on behalf of other clients. 545 Requests are serviced internally or by passing them on, with 546 possible translation, to other servers. A proxy MUST implement 547 both the client and server requirements of this specification. A 548 "transparent proxy" is a proxy that does not modify the request or 549 response beyond what is required for proxy authentication and 550 identification. A "non-transparent proxy" is a proxy that 551 modifies the request or response in order to provide some added 552 service to the user agent, such as group annotation services, 553 media type transformation, protocol reduction, or anonymity 554 filtering. Except where either transparent or non-transparent 555 behavior is explicitly stated, the HTTP proxy requirements apply 556 to both types of proxies. 558 gateway 560 A server which acts as an intermediary for some other server. 561 Unlike a proxy, a gateway receives requests as if it were the 562 origin server for the requested resource; the requesting client 563 may not be aware that it is communicating with a gateway. 565 tunnel 567 An intermediary program which is acting as a blind relay between 568 two connections. Once active, a tunnel is not considered a party 569 to the HTTP communication, though the tunnel may have been 570 initiated by an HTTP request. The tunnel ceases to exist when 571 both ends of the relayed connections are closed. 573 cache 575 A program's local store of response messages and the subsystem 576 that controls its message storage, retrieval, and deletion. A 577 cache stores cacheable responses in order to reduce the response 578 time and network bandwidth consumption on future, equivalent 579 requests. Any client or server may include a cache, though a 580 cache cannot be used by a server that is acting as a tunnel. 582 cacheable 584 A response is cacheable if a cache is allowed to store a copy of 585 the response message for use in answering subsequent requests. 586 The rules for determining the cacheability of HTTP responses are 587 defined in Section 13. Even if a resource is cacheable, there may 588 be additional constraints on whether a cache can use the cached 589 copy for a particular request. 591 first-hand 592 A response is first-hand if it comes directly and without 593 unnecessary delay from the origin server, perhaps via one or more 594 proxies. A response is also first-hand if its validity has just 595 been checked directly with the origin server. 597 explicit expiration time 599 The time at which the origin server intends that an entity should 600 no longer be returned by a cache without further validation. 602 heuristic expiration time 604 An expiration time assigned by a cache when no explicit expiration 605 time is available. 607 age 609 The age of a response is the time since it was sent by, or 610 successfully validated with, the origin server. 612 freshness lifetime 614 The length of time between the generation of a response and its 615 expiration time. 617 fresh 619 A response is fresh if its age has not yet exceeded its freshness 620 lifetime. 622 stale 624 A response is stale if its age has passed its freshness lifetime. 626 semantically transparent 628 A cache behaves in a "semantically transparent" manner, with 629 respect to a particular response, when its use affects neither the 630 requesting client nor the origin server, except to improve 631 performance. When a cache is semantically transparent, the client 632 receives exactly the same response (except for hop-by-hop headers) 633 that it would have received had its request been handled directly 634 by the origin server. 636 validator 638 A protocol element (e.g., an entity tag or a Last-Modified time) 639 that is used to find out whether a cache entry is an equivalent 640 copy of an entity. 642 upstream/downstream 644 Upstream and downstream describe the flow of a message: all 645 messages flow from upstream to downstream. 647 inbound/outbound 649 Inbound and outbound refer to the request and response paths for 650 messages: "inbound" means "traveling toward the origin server", 651 and "outbound" means "traveling toward the user agent" 653 1.4. Overall Operation 655 The HTTP protocol is a request/response protocol. A client sends a 656 request to the server in the form of a request method, URI, and 657 protocol version, followed by a MIME-like message containing request 658 modifiers, client information, and possible body content over a 659 connection with a server. The server responds with a status line, 660 including the message's protocol version and a success or error code, 661 followed by a MIME-like message containing server information, entity 662 metainformation, and possible entity-body content. The relationship 663 between HTTP and MIME is described in Appendix D. 665 Most HTTP communication is initiated by a user agent and consists of 666 a request to be applied to a resource on some origin server. In the 667 simplest case, this may be accomplished via a single connection (v) 668 between the user agent (UA) and the origin server (O). 670 request chain ------------------------> 671 UA -------------------v------------------- O 672 <----------------------- response chain 674 A more complicated situation occurs when one or more intermediaries 675 are present in the request/response chain. There are three common 676 forms of intermediary: proxy, gateway, and tunnel. A proxy is a 677 forwarding agent, receiving requests for a URI in its absolute form, 678 rewriting all or part of the message, and forwarding the reformatted 679 request toward the server identified by the URI. A gateway is a 680 receiving agent, acting as a layer above some other server(s) and, if 681 necessary, translating the requests to the underlying server's 682 protocol. A tunnel acts as a relay point between two connections 683 without changing the messages; tunnels are used when the 684 communication needs to pass through an intermediary (such as a 685 firewall) even when the intermediary cannot understand the contents 686 of the messages. 688 request chain --------------------------------------> 689 UA -----v----- A -----v----- B -----v----- C -----v----- O 690 <------------------------------------- response chain 692 The figure above shows three intermediaries (A, B, and C) between the 693 user agent and origin server. A request or response message that 694 travels the whole chain will pass through four separate connections. 695 This distinction is important because some HTTP communication options 696 may apply only to the connection with the nearest, non-tunnel 697 neighbor, only to the end-points of the chain, or to all connections 698 along the chain. Although the diagram is linear, each participant 699 may be engaged in multiple, simultaneous communications. For 700 example, B may be receiving requests from many clients other than A, 701 and/or forwarding requests to servers other than C, at the same time 702 that it is handling A's request. 704 Any party to the communication which is not acting as a tunnel may 705 employ an internal cache for handling requests. The effect of a 706 cache is that the request/response chain is shortened if one of the 707 participants along the chain has a cached response applicable to that 708 request. The following illustrates the resulting chain if B has a 709 cached copy of an earlier response from O (via C) for a request which 710 has not been cached by UA or A. 712 request chain ----------> 713 UA -----v----- A -----v----- B - - - - - - C - - - - - - O 714 <--------- response chain 716 Not all responses are usefully cacheable, and some requests may 717 contain modifiers which place special requirements on cache behavior. 718 HTTP requirements for cache behavior and cacheable responses are 719 defined in Section 13. 721 In fact, there are a wide variety of architectures and configurations 722 of caches and proxies currently being experimented with or deployed 723 across the World Wide Web. These systems include national hierarchies 724 of proxy caches to save transoceanic bandwidth, systems that 725 broadcast or multicast cache entries, organizations that distribute 726 subsets of cached data via CD-ROM, and so on. HTTP systems are used 727 in corporate intranets over high-bandwidth links, and for access via 728 PDAs with low-power radio links and intermittent connectivity. The 729 goal of HTTP/1.1 is to support the wide diversity of configurations 730 already deployed while introducing protocol constructs that meet the 731 needs of those who build web applications that require high 732 reliability and, failing that, at least reliable indications of 733 failure. 735 HTTP communication usually takes place over TCP/IP connections. The 736 default port is TCP 80 [RFC1700], but other ports can be used. This 737 does not preclude HTTP from being implemented on top of any other 738 protocol on the Internet, or on other networks. HTTP only presumes a 739 reliable transport; any protocol that provides such guarantees can be 740 used; the mapping of the HTTP/1.1 request and response structures 741 onto the transport data units of the protocol in question is outside 742 the scope of this specification. 744 In HTTP/1.0, most implementations used a new connection for each 745 request/response exchange. In HTTP/1.1, a connection may be used for 746 one or more request/response exchanges, although connections may be 747 closed for a variety of reasons (see Section 8.1). 749 2. Notational Conventions and Generic Grammar 751 2.1. Augmented BNF 753 All of the mechanisms specified in this document are described in 754 both prose and an augmented Backus-Naur Form (BNF) similar to that 755 used by [RFC822]. Implementors will need to be familiar with the 756 notation in order to understand this specification. The augmented 757 BNF includes the following constructs: 759 name = definition 761 The name of a rule is simply the name itself (without any 762 enclosing "<" and ">") and is separated from its definition by the 763 equal "=" character. White space is only significant in that 764 indentation of continuation lines is used to indicate a rule 765 definition that spans more than one line. Certain basic rules are 766 in uppercase, such as SP, LWS, HT, CRLF, DIGIT, ALPHA, etc. Angle 767 brackets are used within definitions whenever their presence will 768 facilitate discerning the use of rule names. 770 "literal" 772 Quotation marks surround literal text. Unless stated otherwise, 773 the text is case-insensitive. 775 rule1 | rule2 777 Elements separated by a bar ("|") are alternatives, e.g., "yes | 778 no" will accept yes or no. 780 (rule1 rule2) 782 Elements enclosed in parentheses are treated as a single element. 783 Thus, "(elem (foo | bar) elem)" allows the token sequences "elem 784 foo elem" and "elem bar elem". 786 *rule 788 The character "*" preceding an element indicates repetition. The 789 full form is "*element" indicating at least and at most 790 occurrences of element. Default values are 0 and infinity so 791 that "*(element)" allows any number, including zero; "1*element" 792 requires at least one; and "1*2element" allows one or two. 794 [rule] 795 Square brackets enclose optional elements; "[foo bar]" is 796 equivalent to "*1(foo bar)". 798 N rule 800 Specific repetition: "(element)" is equivalent to 801 "*(element)"; that is, exactly occurrences of (element). 802 Thus 2DIGIT is a 2-digit number, and 3ALPHA is a string of three 803 alphabetic characters. 805 #rule 807 A construct "#" is defined, similar to "*", for defining lists of 808 elements. The full form is "#element" indicating at least 809 and at most elements, each separated by one or more commas 810 (",") and OPTIONAL linear white space (LWS). This makes the usual 811 form of lists very easy; a rule such as 813 ( *LWS element *( *LWS "," *LWS element )) 815 can be shown as 817 1#element 819 Wherever this construct is used, null elements are allowed, but do 820 not contribute to the count of elements present. That is, 821 "(element), , (element) " is permitted, but counts as only two 822 elements. Therefore, where at least one element is required, at 823 least one non-null element MUST be present. Default values are 0 824 and infinity so that "#element" allows any number, including zero; 825 "1#element" requires at least one; and "1#2element" allows one or 826 two. 828 ; comment 830 A semi-colon, set off some distance to the right of rule text, 831 starts a comment that continues to the end of line. This is a 832 simple way of including useful notes in parallel with the 833 specifications. 835 implied *LWS 837 The grammar described by this specification is word-based. Except 838 where noted otherwise, linear white space (LWS) can be included 839 between any two adjacent words (token or quoted-string), and 840 between adjacent words and separators, without changing the 841 interpretation of a field. At least one delimiter (LWS and/or 842 separators) MUST exist between any two tokens (for the definition 843 of "token" below), since they would otherwise be interpreted as a 844 single token. 846 2.2. Basic Rules 848 The following rules are used throughout this specification to 849 describe basic parsing constructs. The US-ASCII coded character set 850 is defined by ANSI X3.4-1986 [USASCII]. 852 OCTET = 853 CHAR = 854 UPALPHA = 855 LOALPHA = 856 ALPHA = UPALPHA | LOALPHA 857 DIGIT = 858 CTL = 860 CR = 861 LF = 862 SP = 863 HT = 864 <"> = 866 HTTP/1.1 defines the sequence CR LF as the end-of-line marker for all 867 protocol elements except the entity-body (see Appendix C for tolerant 868 applications). The end-of-line marker within an entity-body is 869 defined by its associated media type, as described in Section 3.7. 871 CRLF = CR LF 873 HTTP/1.1 header field values can be folded onto multiple lines if the 874 continuation line begins with a space or horizontal tab. All linear 875 white space, including folding, has the same semantics as SP. A 876 recipient MAY replace any linear white space with a single SP before 877 interpreting the field value or forwarding the message downstream. 879 LWS = [CRLF] 1*( SP | HT ) 881 The TEXT rule is only used for descriptive field contents and values 882 that are not intended to be interpreted by the message parser. Words 883 of *TEXT MAY contain characters from character sets other than ISO- 884 8859-1 [ISO-8859] only when encoded according to the rules of 885 [RFC2047]. 887 TEXT = 890 A CRLF is allowed in the definition of TEXT only as part of a header 891 field continuation. It is expected that the folding LWS will be 892 replaced with a single SP before interpretation of the TEXT value. 894 Hexadecimal numeric characters are used in several protocol elements. 896 HEX = "A" | "B" | "C" | "D" | "E" | "F" 897 | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT 899 Many HTTP/1.1 header field values consist of words separated by LWS 900 or special characters. These special characters MUST be in a quoted 901 string to be used within a parameter value (as defined in 902 Section 3.6). 904 token = 1* 905 separators = "(" | ")" | "<" | ">" | "@" 906 | "," | ";" | ":" | "\" | <"> 907 | "/" | "[" | "]" | "?" | "=" 908 | "{" | "}" | SP | HT 910 Comments can be included in some HTTP header fields by surrounding 911 the comment text with parentheses. Comments are only allowed in 912 fields containing "comment" as part of their field value definition. 913 In all other fields, parentheses are considered part of the field 914 value. 916 comment = "(" *( ctext | quoted-pair | comment ) ")" 917 ctext = 919 A string of text is parsed as a single word if it is quoted using 920 double-quote marks. 922 quoted-string = ( <"> *(qdtext | quoted-pair ) <"> ) 923 qdtext = > 925 The backslash character ("\") MAY be used as a single-character 926 quoting mechanism only within quoted-string and comment constructs. 928 quoted-pair = "\" CHAR 930 3. Protocol Parameters 932 3.1. HTTP Version 934 HTTP uses a "." numbering scheme to indicate versions 935 of the protocol. The protocol versioning policy is intended to allow 936 the sender to indicate the format of a message and its capacity for 937 understanding further HTTP communication, rather than the features 938 obtained via that communication. No change is made to the version 939 number for the addition of message components which do not affect 940 communication behavior or which only add to extensible field values. 941 The number is incremented when the changes made to the 942 protocol add features which do not change the general message parsing 943 algorithm, but which may add to the message semantics and imply 944 additional capabilities of the sender. The number is 945 incremented when the format of a message within the protocol is 946 changed. See [RFC2145] for a fuller explanation. 948 The version of an HTTP message is indicated by an HTTP-Version field 949 in the first line of the message. 951 HTTP-Version = "HTTP" "/" 1*DIGIT "." 1*DIGIT 953 Note that the major and minor numbers MUST be treated as separate 954 integers and that each MAY be incremented higher than a single digit. 955 Thus, HTTP/2.4 is a lower version than HTTP/2.13, which in turn is 956 lower than HTTP/12.3. Leading zeros MUST be ignored by recipients 957 and MUST NOT be sent. 959 An application that sends a request or response message that includes 960 HTTP-Version of "HTTP/1.1" MUST be at least conditionally compliant 961 with this specification. Applications that are at least 962 conditionally compliant with this specification SHOULD use an HTTP- 963 Version of "HTTP/1.1" in their messages, and MUST do so for any 964 message that is not compatible with HTTP/1.0. For more details on 965 when to send specific HTTP-Version values, see [RFC2145]. 967 The HTTP version of an application is the highest HTTP version for 968 which the application is at least conditionally compliant. HTTP- 969 Version is case-sensitive. 971 Proxy and gateway applications need to be careful when forwarding 972 messages in protocol versions different from that of the application. 973 Since the protocol version indicates the protocol capability of the 974 sender, a proxy/gateway MUST NOT send a message with a version 975 indicator which is greater than its actual version. If a higher 976 version request is received, the proxy/gateway MUST either downgrade 977 the request version, or respond with an error, or switch to tunnel 978 behavior. 980 Due to interoperability problems with HTTP/1.0 proxies discovered 981 since the publication of [RFC2068], caching proxies MUST, gateways 982 MAY, and tunnels MUST NOT upgrade the request to the highest version 983 they support. The proxy/gateway's response to that request MUST be 984 in the same major version as the request. 986 Note: Converting between versions of HTTP may involve modification 987 of header fields required or forbidden by the versions involved. 989 3.2. Uniform Resource Identifiers 991 URIs have been known by many names: WWW addresses, Universal Document 992 Identifiers, Universal Resource Identifiers [RFC1630], and finally 993 the combination of Uniform Resource Locators (URL) [RFC1738] and 994 Names (URN) [RFC1737]. As far as HTTP is concerned, Uniform Resource 995 Identifiers are simply formatted strings which identify--via name, 996 location, or any other characteristic--a resource. 998 3.2.1. General Syntax 1000 URIs in HTTP can be represented in absolute form or relative to some 1001 known base URI [RFC1808], depending upon the context of their use. 1002 The two forms are differentiated by the fact that absolute URIs 1003 always begin with a scheme name followed by a colon. For definitive 1004 information on URL syntax and semantics, see "Uniform Resource 1005 Identifiers (URI): Generic Syntax and Semantics," [RFC2396] (which 1006 replaces [RFC1738] and [RFC1808]). This specification adopts the 1007 definitions of "URI-reference", "absoluteURI", "relativeURI", "port", 1008 "host","abs_path", "rel_path", and "authority" from that 1009 specification. 1011 The HTTP protocol does not place any a priori limit on the length of 1012 a URI. Servers MUST be able to handle the URI of any resource they 1013 serve, and SHOULD be able to handle URIs of unbounded length if they 1014 provide GET-based forms that could generate such URIs. A server 1015 SHOULD return 414 (Request-URI Too Long) status if a URI is longer 1016 than the server can handle (see Section 10.4.15). 1018 Note: Servers ought to be cautious about depending on URI lengths 1019 above 255 bytes, because some older client or proxy 1020 implementations might not properly support these lengths. 1022 3.2.2. http URL 1024 The "http" scheme is used to locate network resources via the HTTP 1025 protocol. This section defines the scheme-specific syntax and 1026 semantics for http URLs. 1028 http_URL = "http:" "//" host [ ":" port ] [ abs_path [ "?" query ]] 1030 If the port is empty or not given, port 80 is assumed. The semantics 1031 are that the identified resource is located at the server listening 1032 for TCP connections on that port of that host, and the Request-URI 1033 for the resource is abs_path (Section 5.1.2). The use of IP 1034 addresses in URLs SHOULD be avoided whenever possible (see 1035 [RFC1900]). If the abs_path is not present in the URL, it MUST be 1036 given as "/" when used as a Request-URI for a resource 1037 (Section 5.1.2). If a proxy receives a host name which is not a 1038 fully qualified domain name, it MAY add its domain to the host name 1039 it received. If a proxy receives a fully qualified domain name, the 1040 proxy MUST NOT change the host name. 1042 3.2.3. URI Comparison 1044 When comparing two URIs to decide if they match or not, a client 1045 SHOULD use a case-sensitive octet-by-octet comparison of the entire 1046 URIs, with these exceptions: 1048 o A port that is empty or not given is equivalent to the default 1049 port for that URI-reference; 1051 o Comparisons of host names MUST be case-insensitive; 1053 o Comparisons of scheme names MUST be case-insensitive; 1055 o An empty abs_path is equivalent to an abs_path of "/". 1057 Characters other than those in the "reserved" set (see [RFC2396]) are 1058 equivalent to their ""%" HEX HEX" encoding. 1060 For example, the following three URIs are equivalent: 1062 http://example.com:80/~smith/home.html 1063 http://EXAMPLE.com/%7Esmith/home.html 1064 http://EXAMPLE.com:/%7esmith/home.html 1066 3.3. Date/Time Formats 1068 3.3.1. Full Date 1070 HTTP applications have historically allowed three different formats 1071 for the representation of date/time stamps: 1073 Sun, 06 Nov 1994 08:49:37 GMT ; [RFC822], updated by [RFC1123] 1074 Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by [RFC1036] 1075 Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format 1077 The first format is preferred as an Internet standard and represents 1078 a fixed-length subset of that defined by [RFC1123] (an update to 1079 [RFC822]). The second format is in common use, but is based on the 1080 obsolete RFC 850 [RFC1036] date format and lacks a four-digit year. 1081 HTTP/1.1 clients and servers that parse the date value MUST accept 1082 all three formats (for compatibility with HTTP/1.0), though they MUST 1083 only generate the RFC 1123 format for representing HTTP-date values 1084 in header fields. See Appendix C for further information. 1086 Note: Recipients of date values are encouraged to be robust in 1087 accepting date values that may have been sent by non-HTTP 1088 applications, as is sometimes the case when retrieving or posting 1089 messages via proxies/gateways to SMTP or NNTP. 1091 All HTTP date/time stamps MUST be represented in Greenwich Mean Time 1092 (GMT), without exception. For the purposes of HTTP, GMT is exactly 1093 equal to UTC (Coordinated Universal Time). This is indicated in the 1094 first two formats by the inclusion of "GMT" as the three-letter 1095 abbreviation for time zone, and MUST be assumed when reading the 1096 asctime format. HTTP-date is case sensitive and MUST NOT include 1097 additional LWS beyond that specifically included as SP in the 1098 grammar. 1100 HTTP-date = rfc1123-date | rfc850-date | asctime-date 1101 rfc1123-date = wkday "," SP date1 SP time SP "GMT" 1102 rfc850-date = weekday "," SP date2 SP time SP "GMT" 1103 asctime-date = wkday SP date3 SP time SP 4DIGIT 1104 date1 = 2DIGIT SP month SP 4DIGIT 1105 ; day month year (e.g., 02 Jun 1982) 1106 date2 = 2DIGIT "-" month "-" 2DIGIT 1107 ; day-month-year (e.g., 02-Jun-82) 1108 date3 = month SP ( 2DIGIT | ( SP 1DIGIT )) 1109 ; month day (e.g., Jun 2) 1110 time = 2DIGIT ":" 2DIGIT ":" 2DIGIT 1111 ; 00:00:00 - 23:59:59 1112 wkday = "Mon" | "Tue" | "Wed" 1113 | "Thu" | "Fri" | "Sat" | "Sun" 1114 weekday = "Monday" | "Tuesday" | "Wednesday" 1115 | "Thursday" | "Friday" | "Saturday" | "Sunday" 1116 month = "Jan" | "Feb" | "Mar" | "Apr" 1117 | "May" | "Jun" | "Jul" | "Aug" 1118 | "Sep" | "Oct" | "Nov" | "Dec" 1120 Note: HTTP requirements for the date/time stamp format apply only to 1121 their usage within the protocol stream. Clients and servers are not 1122 required to use these formats for user presentation, request logging, 1123 etc. 1125 3.3.2. Delta Seconds 1127 Some HTTP header fields allow a time value to be specified as an 1128 integer number of seconds, represented in decimal, after the time 1129 that the message was received. 1131 delta-seconds = 1*DIGIT 1133 3.4. Character Sets 1135 HTTP uses the same definition of the term "character set" as that 1136 described for MIME: 1138 The term "character set" is used in this document to refer to a 1139 method used with one or more tables to convert a sequence of octets 1140 into a sequence of characters. Note that unconditional conversion in 1141 the other direction is not required, in that not all characters may 1142 be available in a given character set and a character set may provide 1143 more than one sequence of octets to represent a particular character. 1144 This definition is intended to allow various kinds of character 1145 encoding, from simple single-table mappings such as US-ASCII to 1146 complex table switching methods such as those that use ISO-2022's 1147 techniques. However, the definition associated with a MIME character 1148 set name MUST fully specify the mapping to be performed from octets 1149 to characters. In particular, use of external profiling information 1150 to determine the exact mapping is not permitted. 1152 Note: This use of the term "character set" is more commonly 1153 referred to as a "character encoding." However, since HTTP and 1154 MIME share the same registry, it is important that the terminology 1155 also be shared. 1157 HTTP character sets are identified by case-insensitive tokens. The 1158 complete set of tokens is defined by the IANA Character Set registry 1159 [RFC1700]. 1161 charset = token 1163 Although HTTP allows an arbitrary token to be used as a charset 1164 value, any token that has a predefined value within the IANA 1165 Character Set registry [RFC1700] MUST represent the character set 1166 defined by that registry. Applications SHOULD limit their use of 1167 character sets to those defined by the IANA registry. 1169 HTTP uses charset in two contexts: within an Accept-Charset request 1170 header (in which the charset value is an unquoted token) and as the 1171 value of a parameter in a Content-Type header (within a request or 1172 response), in which case the parameter value of the charset parameter 1173 may be quoted. 1175 Implementors should be aware of IETF character set requirements 1176 [RFC2279] [RFC2277]. 1178 3.4.1. Missing Charset 1180 Some HTTP/1.0 software has interpreted a Content-Type header without 1181 charset parameter incorrectly to mean "recipient should guess." 1182 Senders wishing to defeat this behavior MAY include a charset 1183 parameter even when the charset is ISO-8859-1 and SHOULD do so when 1184 it is known that it will not confuse the recipient. 1186 Unfortunately, some older HTTP/1.0 clients did not deal properly with 1187 an explicit charset parameter. HTTP/1.1 recipients MUST respect the 1188 charset label provided by the sender; and those user agents that have 1189 a provision to "guess" a charset MUST use the charset from the 1190 content-type field if they support that charset, rather than the 1191 recipient's preference, when initially displaying a document. See 1192 Section 3.7.1. 1194 3.5. Content Codings 1196 Content coding values indicate an encoding transformation that has 1197 been or can be applied to an entity. Content codings are primarily 1198 used to allow a document to be compressed or otherwise usefully 1199 transformed without losing the identity of its underlying media type 1200 and without loss of information. Frequently, the entity is stored in 1201 coded form, transmitted directly, and only decoded by the recipient. 1203 content-coding = token 1205 All content-coding values are case-insensitive. HTTP/1.1 uses 1206 content-coding values in the Accept-Encoding (Section 14.3) and 1207 Content-Encoding (Section 14.11) header fields. Although the value 1208 describes the content-coding, what is more important is that it 1209 indicates what decoding mechanism will be required to remove the 1210 encoding. 1212 The Internet Assigned Numbers Authority (IANA) acts as a registry for 1213 content-coding value tokens. Initially, the registry contains the 1214 following tokens: 1216 gzip 1218 An encoding format produced by the file compression program "gzip" 1219 (GNU zip) as described in [RFC1952]. This format is a Lempel-Ziv 1220 coding (LZ77) with a 32 bit CRC. 1222 compress 1224 The encoding format produced by the common UNIX file compression 1225 program "compress". This format is an adaptive Lempel-Ziv-Welch 1226 coding (LZW). 1228 Use of program names for the identification of encoding formats is 1229 not desirable and is discouraged for future encodings. Their use 1230 here is representative of historical practice, not good design. 1231 For compatibility with previous implementations of HTTP, 1232 applications SHOULD consider "x-gzip" and "x-compress" to be 1233 equivalent to "gzip" and "compress" respectively. 1235 deflate 1237 The "zlib" format defined in [RFC1950] in combination with the 1238 "deflate" compression mechanism described in [RFC1951]. 1240 identity 1241 The default (identity) encoding; the use of no transformation 1242 whatsoever. This content-coding is used only in the Accept- 1243 Encoding header, and SHOULD NOT be used in the Content-Encoding 1244 header. 1246 New content-coding value tokens SHOULD be registered; to allow 1247 interoperability between clients and servers, specifications of the 1248 content coding algorithms needed to implement a new value SHOULD be 1249 publicly available and adequate for independent implementation, and 1250 conform to the purpose of content coding defined in this section. 1252 3.6. Transfer Codings 1254 Transfer-coding values are used to indicate an encoding 1255 transformation that has been, can be, or may need to be applied to an 1256 entity-body in order to ensure "safe transport" through the network. 1257 This differs from a content coding in that the transfer-coding is a 1258 property of the message, not of the original entity. 1260 transfer-coding = "chunked" | transfer-extension 1261 transfer-extension = token *( ";" parameter ) 1263 Parameters are in the form of attribute/value pairs. 1265 parameter = attribute "=" value 1266 attribute = token 1267 value = token | quoted-string 1269 All transfer-coding values are case-insensitive. HTTP/1.1 uses 1270 transfer-coding values in the TE header field (Section 14.39) and in 1271 the Transfer-Encoding header field (Section 14.41). 1273 Whenever a transfer-coding is applied to a message-body, the set of 1274 transfer-codings MUST include "chunked", unless the message is 1275 terminated by closing the connection. When the "chunked" transfer- 1276 coding is used, it MUST be the last transfer-coding applied to the 1277 message-body. The "chunked" transfer-coding MUST NOT be applied more 1278 than once to a message-body. These rules allow the recipient to 1279 determine the transfer-length of the message (Section 4.4). 1281 Transfer-codings are analogous to the Content-Transfer-Encoding 1282 values of MIME [RFC2045], which were designed to enable safe 1283 transport of binary data over a 7-bit transport service. However, 1284 safe transport has a different focus for an 8bit-clean transfer 1285 protocol. In HTTP, the only unsafe characteristic of message-bodies 1286 is the difficulty in determining the exact body length 1287 (Section 7.2.2), or the desire to encrypt data over a shared 1288 transport. 1290 The Internet Assigned Numbers Authority (IANA) acts as a registry for 1291 transfer-coding value tokens. Initially, the registry contains the 1292 following tokens: "chunked" (Section 3.6.1), "gzip" (Section 3.5), 1293 "compress" (Section 3.5), and "deflate" (Section 3.5). 1295 New transfer-coding value tokens SHOULD be registered in the same way 1296 as new content-coding value tokens (Section 3.5). 1298 A server which receives an entity-body with a transfer-coding it does 1299 not understand SHOULD return 501 (Unimplemented), and close the 1300 connection. A server MUST NOT send transfer-codings to an HTTP/1.0 1301 client. 1303 3.6.1. Chunked Transfer Coding 1305 The chunked encoding modifies the body of a message in order to 1306 transfer it as a series of chunks, each with its own size indicator, 1307 followed by an OPTIONAL trailer containing entity-header fields. 1308 This allows dynamically produced content to be transferred along with 1309 the information necessary for the recipient to verify that it has 1310 received the full message. 1312 Chunked-Body = *chunk 1313 last-chunk 1314 trailer 1315 CRLF 1317 chunk = chunk-size [ chunk-extension ] CRLF 1318 chunk-data CRLF 1319 chunk-size = 1*HEX 1320 last-chunk = 1*("0") [ chunk-extension ] CRLF 1322 chunk-extension= *( ";" chunk-ext-name [ "=" chunk-ext-val ] ) 1323 chunk-ext-name = token 1324 chunk-ext-val = token | quoted-string 1325 chunk-data = chunk-size(OCTET) 1326 trailer = *(entity-header CRLF) 1328 The chunk-size field is a string of hex digits indicating the size of 1329 the chunk-data in octets. The chunked encoding is ended by any chunk 1330 whose size is zero, followed by the trailer, which is terminated by 1331 an empty line. 1333 The trailer allows the sender to include additional HTTP header 1334 fields at the end of the message. The Trailer header field can be 1335 used to indicate which header fields are included in a trailer (see 1336 Section 14.40). 1338 A server using chunked transfer-coding in a response MUST NOT use the 1339 trailer for any header fields unless at least one of the following is 1340 true: 1342 1. the request included a TE header field that indicates "trailers" 1343 is acceptable in the transfer-coding of the response, as 1344 described in Section 14.39; or, 1346 2. the server is the origin server for the response, the trailer 1347 fields consist entirely of optional metadata, and the recipient 1348 could use the message (in a manner acceptable to the origin 1349 server) without receiving this metadata. In other words, the 1350 origin server is willing to accept the possibility that the 1351 trailer fields might be silently discarded along the path to the 1352 client. 1354 This requirement prevents an interoperability failure when the 1355 message is being received by an HTTP/1.1 (or later) proxy and 1356 forwarded to an HTTP/1.0 recipient. It avoids a situation where 1357 compliance with the protocol would have necessitated a possibly 1358 infinite buffer on the proxy. 1360 An example process for decoding a Chunked-Body is presented in 1361 Appendix D.6. 1363 All HTTP/1.1 applications MUST be able to receive and decode the 1364 "chunked" transfer-coding, and MUST ignore chunk-extension extensions 1365 they do not understand. 1367 3.7. Media Types 1369 HTTP uses Internet Media Types [RFC1590] in the Content-Type 1370 (Section 14.17) and Accept (Section 14.1) header fields in order to 1371 provide open and extensible data typing and type negotiation. 1373 media-type = type "/" subtype *( ";" parameter ) 1374 type = token 1375 subtype = token 1377 Parameters MAY follow the type/subtype in the form of attribute/value 1378 pairs (as defined in Section 3.6). 1380 The type, subtype, and parameter attribute names are case- 1381 insensitive. Parameter values might or might not be case-sensitive, 1382 depending on the semantics of the parameter name. Linear white space 1383 (LWS) MUST NOT be used between the type and subtype, nor between an 1384 attribute and its value. The presence or absence of a parameter 1385 might be significant to the processing of a media-type, depending on 1386 its definition within the media type registry. 1388 Note that some older HTTP applications do not recognize media type 1389 parameters. When sending data to older HTTP applications, 1390 implementations SHOULD only use media type parameters when they are 1391 required by that type/subtype definition. 1393 Media-type values are registered with the Internet Assigned Number 1394 Authority (IANA [RFC1700]). The media type registration process is 1395 outlined in [RFC1590]. Use of non-registered media types is 1396 discouraged. 1398 3.7.1. Canonicalization and Text Defaults 1400 Internet media types are registered with a canonical form. An 1401 entity-body transferred via HTTP messages MUST be represented in the 1402 appropriate canonical form prior to its transmission except for 1403 "text" types, as defined in the next paragraph. 1405 When in canonical form, media subtypes of the "text" type use CRLF as 1406 the text line break. HTTP relaxes this requirement and allows the 1407 transport of text media with plain CR or LF alone representing a line 1408 break when it is done consistently for an entire entity-body. HTTP 1409 applications MUST accept CRLF, bare CR, and bare LF as being 1410 representative of a line break in text media received via HTTP. In 1411 addition, if the text is represented in a character set that does not 1412 use octets 13 and 10 for CR and LF respectively, as is the case for 1413 some multi-byte character sets, HTTP allows the use of whatever octet 1414 sequences are defined by that character set to represent the 1415 equivalent of CR and LF for line breaks. This flexibility regarding 1416 line breaks applies only to text media in the entity-body; a bare CR 1417 or LF MUST NOT be substituted for CRLF within any of the HTTP control 1418 structures (such as header fields and multipart boundaries). 1420 If an entity-body is encoded with a content-coding, the underlying 1421 data MUST be in a form defined above prior to being encoded. 1423 The "charset" parameter is used with some media types to define the 1424 character set (Section 3.4) of the data. When no explicit charset 1425 parameter is provided by the sender, media subtypes of the "text" 1426 type are defined to have a default charset value of "ISO-8859-1" when 1427 received via HTTP. Data in character sets other than "ISO-8859-1" or 1428 its subsets MUST be labeled with an appropriate charset value. See 1429 Section 3.4.1 for compatibility problems. 1431 3.7.2. Multipart Types 1433 MIME provides for a number of "multipart" types -- encapsulations of 1434 one or more entities within a single message-body. All multipart 1435 types share a common syntax, as defined in Section 5.1.1 of 1436 [RFC2046], and MUST include a boundary parameter as part of the media 1437 type value. The message body is itself a protocol element and MUST 1438 therefore use only CRLF to represent line breaks between body-parts. 1439 Unlike in RFC 2046, the epilogue of any multipart message MUST be 1440 empty; HTTP applications MUST NOT transmit the epilogue (even if the 1441 original multipart contains an epilogue). These restrictions exist 1442 in order to preserve the self-delimiting nature of a multipart 1443 message-body, wherein the "end" of the message-body is indicated by 1444 the ending multipart boundary. 1446 In general, HTTP treats a multipart message-body no differently than 1447 any other media type: strictly as payload. The one exception is the 1448 "multipart/byteranges" type (Appendix B) when it appears in a 206 1449 (Partial Content) response, which will be interpreted by some HTTP 1450 caching mechanisms as described in Sections 13.5.4 and 14.16. In all 1451 other cases, an HTTP user agent SHOULD follow the same or similar 1452 behavior as a MIME user agent would upon receipt of a multipart type. 1453 The MIME header fields within each body-part of a multipart message- 1454 body do not have any significance to HTTP beyond that defined by 1455 their MIME semantics. 1457 In general, an HTTP user agent SHOULD follow the same or similar 1458 behavior as a MIME user agent would upon receipt of a multipart type. 1459 If an application receives an unrecognized multipart subtype, the 1460 application MUST treat it as being equivalent to "multipart/mixed". 1462 Note: The "multipart/form-data" type has been specifically defined 1463 for carrying form data suitable for processing via the POST 1464 request method, as described in [RFC1867]. 1466 3.8. Product Tokens 1468 Product tokens are used to allow communicating applications to 1469 identify themselves by software name and version. Most fields using 1470 product tokens also allow sub-products which form a significant part 1471 of the application to be listed, separated by white space. By 1472 convention, the products are listed in order of their significance 1473 for identifying the application. 1475 product = token ["/" product-version] 1476 product-version = token 1478 Examples: 1480 User-Agent: CERN-LineMode/2.15 libwww/2.17b3 1481 Server: Apache/0.8.4 1483 Product tokens SHOULD be short and to the point. They MUST NOT be 1484 used for advertising or other non-essential information. Although 1485 any token character MAY appear in a product-version, this token 1486 SHOULD only be used for a version identifier (i.e., successive 1487 versions of the same product SHOULD only differ in the product- 1488 version portion of the product value). 1490 3.9. Quality Values 1492 HTTP content negotiation (Section 12) uses short "floating point" 1493 numbers to indicate the relative importance ("weight") of various 1494 negotiable parameters. A weight is normalized to a real number in 1495 the range 0 through 1, where 0 is the minimum and 1 the maximum 1496 value. If a parameter has a quality value of 0, then content with 1497 this parameter is `not acceptable' for the client. HTTP/1.1 1498 applications MUST NOT generate more than three digits after the 1499 decimal point. User configuration of these values SHOULD also be 1500 limited in this fashion. 1502 qvalue = ( "0" [ "." 0*3DIGIT ] ) 1503 | ( "1" [ "." 0*3("0") ] ) 1505 "Quality values" is a misnomer, since these values merely represent 1506 relative degradation in desired quality. 1508 3.10. Language Tags 1510 A language tag identifies a natural language spoken, written, or 1511 otherwise conveyed by human beings for communication of information 1512 to other human beings. Computer languages are explicitly excluded. 1513 HTTP uses language tags within the Accept-Language and Content- 1514 Language fields. 1516 The syntax and registry of HTTP language tags is the same as that 1517 defined by [RFC1766]. In summary, a language tag is composed of 1 or 1518 more parts: A primary language tag and a possibly empty series of 1519 subtags: 1521 language-tag = primary-tag *( "-" subtag ) 1522 primary-tag = 1*8ALPHA 1523 subtag = 1*8ALPHA 1525 White space is not allowed within the tag and all tags are case- 1526 insensitive. The name space of language tags is administered by the 1527 IANA. Example tags include: 1529 en, en-US, en-cockney, i-cherokee, x-pig-latin 1531 where any two-letter primary-tag is an ISO-639 language abbreviation 1532 and any two-letter initial subtag is an ISO-3166 country code. (The 1533 last three tags above are not registered tags; all but the last are 1534 examples of tags which could be registered in future.) 1536 3.11. Entity Tags 1538 Entity tags are used for comparing two or more entities from the same 1539 requested resource. HTTP/1.1 uses entity tags in the ETag 1540 (Section 14.19), If-Match (Section 14.24), If-None-Match 1541 (Section 14.26), and If-Range (Section 14.27) header fields. The 1542 definition of how they are used and compared as cache validators is 1543 in Section 13.3.3. An entity tag consists of an opaque quoted 1544 string, possibly prefixed by a weakness indicator. 1546 entity-tag = [ weak ] opaque-tag 1547 weak = "W/" 1548 opaque-tag = quoted-string 1550 A "strong entity tag" MAY be shared by two entities of a resource 1551 only if they are equivalent by octet equality. 1553 A "weak entity tag," indicated by the "W/" prefix, MAY be shared by 1554 two entities of a resource only if the entities are equivalent and 1555 could be substituted for each other with no significant change in 1556 semantics. A weak entity tag can only be used for weak comparison. 1558 An entity tag MUST be unique across all versions of all entities 1559 associated with a particular resource. A given entity tag value MAY 1560 be used for entities obtained by requests on different URIs. The use 1561 of the same entity tag value in conjunction with entities obtained by 1562 requests on different URIs does not imply the equivalence of those 1563 entities. 1565 3.12. Range Units 1567 HTTP/1.1 allows a client to request that only part (a range of) the 1568 response entity be included within the response. HTTP/1.1 uses range 1569 units in the Range (Section 14.35) and Content-Range (Section 14.16) 1570 header fields. An entity can be broken down into subranges according 1571 to various structural units. 1573 range-unit = bytes-unit | other-range-unit 1574 bytes-unit = "bytes" 1575 other-range-unit = token 1577 The only range unit defined by HTTP/1.1 is "bytes". HTTP/1.1 1578 implementations MAY ignore ranges specified using other units. 1580 HTTP/1.1 has been designed to allow implementations of applications 1581 that do not depend on knowledge of ranges. 1583 4. HTTP Message 1585 4.1. Message Types 1587 HTTP messages consist of requests from client to server and responses 1588 from server to client. 1590 HTTP-message = Request | Response ; HTTP/1.1 messages 1592 Request (Section 5) and Response (Section 6) messages use the generic 1593 message format of [RFC822] for transferring entities (the payload of 1594 the message). Both types of message consist of a start-line, zero or 1595 more header fields (also known as "headers"), an empty line (i.e., a 1596 line with nothing preceding the CRLF) indicating the end of the 1597 header fields, and possibly a message-body. 1599 generic-message = start-line 1600 *(message-header CRLF) 1601 CRLF 1602 [ message-body ] 1603 start-line = Request-Line | Status-Line 1605 In the interest of robustness, servers SHOULD ignore any empty 1606 line(s) received where a Request-Line is expected. In other words, 1607 if the server is reading the protocol stream at the beginning of a 1608 message and receives a CRLF first, it should ignore the CRLF. 1610 Certain buggy HTTP/1.0 client implementations generate extra CRLF's 1611 after a POST request. To restate what is explicitly forbidden by the 1612 BNF, an HTTP/1.1 client MUST NOT preface or follow a request with an 1613 extra CRLF. 1615 4.2. Message Headers 1617 HTTP header fields, which include general-header (Section 4.5), 1618 request-header (Section 5.3), response-header (Section 6.2), and 1619 entity-header (Section 7.1) fields, follow the same generic format as 1620 that given in Section 3.1 of [RFC822]. Each header field consists of 1621 a name followed by a colon (":") and the field value. Field names 1622 are case-insensitive. The field value MAY be preceded by any amount 1623 of LWS, though a single SP is preferred. Header fields can be 1624 extended over multiple lines by preceding each extra line with at 1625 least one SP or HT. Applications ought to follow "common form", 1626 where one is known or indicated, when generating HTTP constructs, 1627 since there might exist some implementations that fail to accept 1628 anything beyond the common forms. 1630 message-header = field-name ":" [ field-value ] 1631 field-name = token 1632 field-value = *( field-content | LWS ) 1633 field-content = 1637 The field-content does not include any leading or trailing LWS: 1638 linear white space occurring before the first non-whitespace 1639 character of the field-value or after the last non-whitespace 1640 character of the field-value. Such leading or trailing LWS MAY be 1641 removed without changing the semantics of the field value. Any LWS 1642 that occurs between field-content MAY be replaced with a single SP 1643 before interpreting the field value or forwarding the message 1644 downstream. 1646 The order in which header fields with differing field names are 1647 received is not significant. However, it is "good practice" to send 1648 general-header fields first, followed by request-header or response- 1649 header fields, and ending with the entity-header fields. 1651 Multiple message-header fields with the same field-name MAY be 1652 present in a message if and only if the entire field-value for that 1653 header field is defined as a comma-separated list [i.e., #(values)]. 1654 It MUST be possible to combine the multiple header fields into one 1655 "field-name: field-value" pair, without changing the semantics of the 1656 message, by appending each subsequent field-value to the first, each 1657 separated by a comma. The order in which header fields with the same 1658 field-name are received is therefore significant to the 1659 interpretation of the combined field value, and thus a proxy MUST NOT 1660 change the order of these field values when a message is forwarded. 1662 4.3. Message Body 1664 The message-body (if any) of an HTTP message is used to carry the 1665 entity-body associated with the request or response. The message- 1666 body differs from the entity-body only when a transfer-coding has 1667 been applied, as indicated by the Transfer-Encoding header field 1668 (Section 14.41). 1670 message-body = entity-body 1671 | 1673 Transfer-Encoding MUST be used to indicate any transfer-codings 1674 applied by an application to ensure safe and proper transfer of the 1675 message. Transfer-Encoding is a property of the message, not of the 1676 entity, and thus MAY be added or removed by any application along the 1677 request/response chain. (However, Section 3.6 places restrictions on 1678 when certain transfer-codings may be used.) 1680 The rules for when a message-body is allowed in a message differ for 1681 requests and responses. 1683 The presence of a message-body in a request is signaled by the 1684 inclusion of a Content-Length or Transfer-Encoding header field in 1685 the request's message-headers. A message-body MUST NOT be included 1686 in a request if the specification of the request method 1687 (Section 5.1.1) does not allow sending an entity-body in requests. A 1688 server SHOULD read and forward a message-body on any request; if the 1689 request method does not include defined semantics for an entity-body, 1690 then the message-body SHOULD be ignored when handling the request. 1692 For response messages, whether or not a message-body is included with 1693 a message is dependent on both the request method and the response 1694 status code (Section 6.1.1). All responses to the HEAD request 1695 method MUST NOT include a message-body, even though the presence of 1696 entity-header fields might lead one to believe they do. All 1xx 1697 (informational), 204 (no content), and 304 (not modified) responses 1698 MUST NOT include a message-body. All other responses do include a 1699 message-body, although it MAY be of zero length. 1701 4.4. Message Length 1703 The transfer-length of a message is the length of the message-body as 1704 it appears in the message; that is, after any transfer-codings have 1705 been applied. When a message-body is included with a message, the 1706 transfer-length of that body is determined by one of the following 1707 (in order of precedence): 1709 1. Any response message which "MUST NOT" include a message-body 1710 (such as the 1xx, 204, and 304 responses and any response to a 1711 HEAD request) is always terminated by the first empty line after 1712 the header fields, regardless of the entity-header fields present 1713 in the message. 1715 2. If a Transfer-Encoding header field (Section 14.41) is present, 1716 then the transfer-length is defined by use of the "chunked" 1717 transfer-coding (Section 3.6), unless the message is terminated 1718 by closing the connection. 1720 3. If a Content-Length header field (Section 14.13) is present, its 1721 decimal value in OCTETs represents both the entity-length and the 1722 transfer-length. The Content-Length header field MUST NOT be 1723 sent if these two lengths are different (i.e., if a Transfer- 1724 Encoding header field is present). If a message is received with 1725 both a Transfer-Encoding header field and a Content-Length header 1726 field, the latter MUST be ignored. 1728 4. If the message uses the media type "multipart/byteranges", and 1729 the transfer-length is not otherwise specified, then this self- 1730 delimiting media type defines the transfer-length. This media 1731 type MUST NOT be used unless the sender knows that the recipient 1732 can parse it; the presence in a request of a Range header with 1733 multiple byte-range specifiers from a 1.1 client implies that the 1734 client can parse multipart/byteranges responses. 1736 A range header might be forwarded by a 1.0 proxy that does not 1737 understand multipart/byteranges; in this case the server MUST 1738 delimit the message using methods defined in items 1, 3 or 5 1739 of this section. 1741 5. By the server closing the connection. (Closing the connection 1742 cannot be used to indicate the end of a request body, since that 1743 would leave no possibility for the server to send back a 1744 response.) 1746 For compatibility with HTTP/1.0 applications, HTTP/1.1 requests 1747 containing a message-body MUST include a valid Content-Length header 1748 field unless the server is known to be HTTP/1.1 compliant. If a 1749 request contains a message-body and a Content-Length is not given, 1750 the server SHOULD respond with 400 (bad request) if it cannot 1751 determine the length of the message, or with 411 (length required) if 1752 it wishes to insist on receiving a valid Content-Length. 1754 All HTTP/1.1 applications that receive entities MUST accept the 1755 "chunked" transfer-coding (Section 3.6), thus allowing this mechanism 1756 to be used for messages when the message length cannot be determined 1757 in advance. 1759 Messages MUST NOT include both a Content-Length header field and a 1760 transfer-coding. If the message does include a transfer-coding, the 1761 Content-Length MUST be ignored. 1763 When a Content-Length is given in a message where a message-body is 1764 allowed, its field value MUST exactly match the number of OCTETs in 1765 the message-body. HTTP/1.1 user agents MUST notify the user when an 1766 invalid length is received and detected. 1768 4.5. General Header Fields 1770 There are a few header fields which have general applicability for 1771 both request and response messages, but which do not apply to the 1772 entity being transferred. These header fields apply only to the 1773 message being transmitted. 1775 general-header = Cache-Control ; Section 14.9 1776 | Connection ; Section 14.10 1777 | Date ; Section 14.18 1778 | Pragma ; Section 14.32 1779 | Trailer ; Section 14.40 1780 | Transfer-Encoding ; Section 14.41 1781 | Upgrade ; Section 14.42 1782 | Via ; Section 14.45 1783 | Warning ; Section 14.46 1785 General-header field names can be extended reliably only in 1786 combination with a change in the protocol version. However, new or 1787 experimental header fields may be given the semantics of general 1788 header fields if all parties in the communication recognize them to 1789 be general-header fields. Unrecognized header fields are treated as 1790 entity-header fields. 1792 5. Request 1794 A request message from a client to a server includes, within the 1795 first line of that message, the method to be applied to the resource, 1796 the identifier of the resource, and the protocol version in use. 1798 Request = Request-Line ; Section 5.1 1799 *(( general-header ; Section 4.5 1800 | request-header ; Section 5.3 1801 | entity-header ) CRLF) ; Section 7.1 1802 CRLF 1803 [ message-body ] ; Section 4.3 1805 5.1. Request-Line 1807 The Request-Line begins with a method token, followed by the Request- 1808 URI and the protocol version, and ending with CRLF. The elements are 1809 separated by SP characters. No CR or LF is allowed except in the 1810 final CRLF sequence. 1812 Request-Line = Method SP Request-URI SP HTTP-Version CRLF 1814 5.1.1. Method 1816 The Method token indicates the method to be performed on the resource 1817 identified by the Request-URI. The method is case-sensitive. 1819 Method = "OPTIONS" ; Section 9.2 1820 | "GET" ; Section 9.3 1821 | "HEAD" ; Section 9.4 1822 | "POST" ; Section 9.5 1823 | "PUT" ; Section 9.6 1824 | "DELETE" ; Section 9.7 1825 | "TRACE" ; Section 9.8 1826 | "CONNECT" ; Section 9.9 1827 | extension-method 1828 extension-method = token 1830 The list of methods allowed by a resource can be specified in an 1831 Allow header field (Section 14.7). The return code of the response 1832 always notifies the client whether a method is currently allowed on a 1833 resource, since the set of allowed methods can change dynamically. 1834 An origin server SHOULD return the status code 405 (Method Not 1835 Allowed) if the method is known by the origin server but not allowed 1836 for the requested resource, and 501 (Not Implemented) if the method 1837 is unrecognized or not implemented by the origin server. The methods 1838 GET and HEAD MUST be supported by all general-purpose servers. All 1839 other methods are OPTIONAL; however, if the above methods are 1840 implemented, they MUST be implemented with the same semantics as 1841 those specified in Section 9. 1843 5.1.2. Request-URI 1845 The Request-URI is a Uniform Resource Identifier (Section 3.2) and 1846 identifies the resource upon which to apply the request. 1848 Request-URI = "*" 1849 | absoluteURI 1850 | abs_path [ "?" query ] 1851 | authority 1853 The four options for Request-URI are dependent on the nature of the 1854 request. The asterisk "*" means that the request does not apply to a 1855 particular resource, but to the server itself, and is only allowed 1856 when the method used does not necessarily apply to a resource. One 1857 example would be 1859 OPTIONS * HTTP/1.1 1861 The absoluteURI form is REQUIRED when the request is being made to a 1862 proxy. The proxy is requested to forward the request or service it 1863 from a valid cache, and return the response. Note that the proxy MAY 1864 forward the request on to another proxy or directly to the server 1865 specified by the absoluteURI. In order to avoid request loops, a 1866 proxy MUST be able to recognize all of its server names, including 1867 any aliases, local variations, and the numeric IP address. An 1868 example Request-Line would be: 1870 GET http://www.example.org/pub/WWW/TheProject.html HTTP/1.1 1872 To allow for transition to absoluteURIs in all requests in future 1873 versions of HTTP, all HTTP/1.1 servers MUST accept the absoluteURI 1874 form in requests, even though HTTP/1.1 clients will only generate 1875 them in requests to proxies. 1877 The authority form is only used by the CONNECT method (Section 9.9). 1879 The most common form of Request-URI is that used to identify a 1880 resource on an origin server or gateway. In this case the absolute 1881 path of the URI MUST be transmitted (see Section 3.2.1, abs_path) as 1882 the Request-URI, and the network location of the URI (authority) MUST 1883 be transmitted in a Host header field. For example, a client wishing 1884 to retrieve the resource above directly from the origin server would 1885 create a TCP connection to port 80 of the host "www.example.org" and 1886 send the lines: 1888 GET /pub/WWW/TheProject.html HTTP/1.1 1889 Host: www.example.org 1891 followed by the remainder of the Request. Note that the absolute 1892 path cannot be empty; if none is present in the original URI, it MUST 1893 be given as "/" (the server root). 1895 The Request-URI is transmitted in the format specified in 1896 Section 3.2.1. If the Request-URI is encoded using the "% HEX HEX" 1897 encoding [RFC2396], the origin server MUST decode the Request-URI in 1898 order to properly interpret the request. Servers SHOULD respond to 1899 invalid Request-URIs with an appropriate status code. 1901 A transparent proxy MUST NOT rewrite the "abs_path" part of the 1902 received Request-URI when forwarding it to the next inbound server, 1903 except as noted above to replace a null abs_path with "/". 1905 Note: The "no rewrite" rule prevents the proxy from changing the 1906 meaning of the request when the origin server is improperly using 1907 a non-reserved URI character for a reserved purpose. Implementors 1908 should be aware that some pre-HTTP/1.1 proxies have been known to 1909 rewrite the Request-URI. 1911 5.2. The Resource Identified by a Request 1913 The exact resource identified by an Internet request is determined by 1914 examining both the Request-URI and the Host header field. 1916 An origin server that does not allow resources to differ by the 1917 requested host MAY ignore the Host header field value when 1918 determining the resource identified by an HTTP/1.1 request. (But see 1919 Appendix F.1.1 for other requirements on Host support in HTTP/1.1.) 1921 An origin server that does differentiate resources based on the host 1922 requested (sometimes referred to as virtual hosts or vanity host 1923 names) MUST use the following rules for determining the requested 1924 resource on an HTTP/1.1 request: 1926 1. If Request-URI is an absoluteURI, the host is part of the 1927 Request-URI. Any Host header field value in the request MUST be 1928 ignored. 1930 2. If the Request-URI is not an absoluteURI, and the request 1931 includes a Host header field, the host is determined by the Host 1932 header field value. 1934 3. If the host as determined by rule 1 or 2 is not a valid host on 1935 the server, the response MUST be a 400 (Bad Request) error 1936 message. 1938 Recipients of an HTTP/1.0 request that lacks a Host header field MAY 1939 attempt to use heuristics (e.g., examination of the URI path for 1940 something unique to a particular host) in order to determine what 1941 exact resource is being requested. 1943 5.3. Request Header Fields 1945 The request-header fields allow the client to pass additional 1946 information about the request, and about the client itself, to the 1947 server. These fields act as request modifiers, with semantics 1948 equivalent to the parameters on a programming language method 1949 invocation. 1951 request-header = Accept ; Section 14.1 1952 | Accept-Charset ; Section 14.2 1953 | Accept-Encoding ; Section 14.3 1954 | Accept-Language ; Section 14.4 1955 | Authorization ; Section 14.8 1956 | Expect ; Section 14.20 1957 | From ; Section 14.22 1958 | Host ; Section 14.23 1959 | If-Match ; Section 14.24 1960 | If-Modified-Since ; Section 14.25 1961 | If-None-Match ; Section 14.26 1962 | If-Range ; Section 14.27 1963 | If-Unmodified-Since ; Section 14.28 1964 | Max-Forwards ; Section 14.31 1965 | Proxy-Authorization ; Section 14.34 1966 | Range ; Section 14.35 1967 | Referer ; Section 14.36 1968 | TE ; Section 14.39 1969 | User-Agent ; Section 14.43 1971 Request-header field names can be extended reliably only in 1972 combination with a change in the protocol version. However, new or 1973 experimental header fields MAY be given the semantics of request- 1974 header fields if all parties in the communication recognize them to 1975 be request-header fields. Unrecognized header fields are treated as 1976 entity-header fields. 1978 6. Response 1980 After receiving and interpreting a request message, a server responds 1981 with an HTTP response message. 1983 Response = Status-Line ; Section 6.1 1984 *(( general-header ; Section 4.5 1985 | response-header ; Section 6.2 1986 | entity-header ) CRLF) ; Section 7.1 1987 CRLF 1988 [ message-body ] ; Section 7.2 1990 6.1. Status-Line 1992 The first line of a Response message is the Status-Line, consisting 1993 of the protocol version followed by a numeric status code and its 1994 associated textual phrase, with each element separated by SP 1995 characters. No CR or LF is allowed except in the final CRLF 1996 sequence. 1998 Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF 2000 6.1.1. Status Code and Reason Phrase 2002 The Status-Code element is a 3-digit integer result code of the 2003 attempt to understand and satisfy the request. These codes are fully 2004 defined in Section 10. The Reason-Phrase is intended to give a short 2005 textual description of the Status-Code. The Status-Code is intended 2006 for use by automata and the Reason-Phrase is intended for the human 2007 user. The client is not required to examine or display the Reason- 2008 Phrase. 2010 The first digit of the Status-Code defines the class of response. 2011 The last two digits do not have any categorization role. There are 5 2012 values for the first digit: 2014 o 1xx: Informational - Request received, continuing process 2016 o 2xx: Success - The action was successfully received, understood, 2017 and accepted 2019 o 3xx: Redirection - Further action must be taken in order to 2020 complete the request 2022 o 4xx: Client Error - The request contains bad syntax or cannot be 2023 fulfilled 2025 o 5xx: Server Error - The server failed to fulfill an apparently 2026 valid request 2028 The individual values of the numeric status codes defined for 2029 HTTP/1.1, and an example set of corresponding Reason-Phrase's, are 2030 presented below. The reason phrases listed here are only 2031 recommendations -- they MAY be replaced by local equivalents without 2032 affecting the protocol. 2034 Status-Code = 2035 "100" ; Section 10.1.1: Continue 2036 | "101" ; Section 10.1.2: Switching Protocols 2037 | "200" ; Section 10.2.1: OK 2038 | "201" ; Section 10.2.2: Created 2039 | "202" ; Section 10.2.3: Accepted 2040 | "203" ; Section 10.2.4: Non-Authoritative Information 2041 | "204" ; Section 10.2.5: No Content 2042 | "205" ; Section 10.2.6: Reset Content 2043 | "206" ; Section 10.2.7: Partial Content 2044 | "300" ; Section 10.3.1: Multiple Choices 2045 | "301" ; Section 10.3.2: Moved Permanently 2046 | "302" ; Section 10.3.3: Found 2047 | "303" ; Section 10.3.4: See Other 2048 | "304" ; Section 10.3.5: Not Modified 2049 | "305" ; Section 10.3.6: Use Proxy 2050 | "307" ; Section 10.3.8: Temporary Redirect 2051 | "400" ; Section 10.4.1: Bad Request 2052 | "401" ; Section 10.4.2: Unauthorized 2053 | "402" ; Section 10.4.3: Payment Required 2054 | "403" ; Section 10.4.4: Forbidden 2055 | "404" ; Section 10.4.5: Not Found 2056 | "405" ; Section 10.4.6: Method Not Allowed 2057 | "406" ; Section 10.4.7: Not Acceptable 2058 | "407" ; Section 10.4.8: Proxy Authentication Required 2059 | "408" ; Section 10.4.9: Request Time-out 2060 | "409" ; Section 10.4.10: Conflict 2061 | "410" ; Section 10.4.11: Gone 2062 | "411" ; Section 10.4.12: Length Required 2063 | "412" ; Section 10.4.13: Precondition Failed 2064 | "413" ; Section 10.4.14: Request Entity Too Large 2065 | "414" ; Section 10.4.15: Request-URI Too Large 2066 | "415" ; Section 10.4.16: Unsupported Media Type 2067 | "416" ; Section 10.4.17: Requested range not satisfiable 2068 | "417" ; Section 10.4.18: Expectation Failed 2069 | "500" ; Section 10.5.1: Internal Server Error 2070 | "501" ; Section 10.5.2: Not Implemented 2071 | "502" ; Section 10.5.3: Bad Gateway 2072 | "503" ; Section 10.5.4: Service Unavailable 2073 | "504" ; Section 10.5.5: Gateway Time-out 2074 | "505" ; Section 10.5.6: HTTP Version not supported 2075 | extension-code 2077 extension-code = 3DIGIT 2078 Reason-Phrase = * 2080 HTTP status codes are extensible. HTTP applications are not required 2081 to understand the meaning of all registered status codes, though such 2082 understanding is obviously desirable. However, applications MUST 2083 understand the class of any status code, as indicated by the first 2084 digit, and treat any unrecognized response as being equivalent to the 2085 x00 status code of that class, with the exception that an 2086 unrecognized response MUST NOT be cached. For example, if an 2087 unrecognized status code of 431 is received by the client, it can 2088 safely assume that there was something wrong with its request and 2089 treat the response as if it had received a 400 status code. In such 2090 cases, user agents SHOULD present to the user the entity returned 2091 with the response, since that entity is likely to include human- 2092 readable information which will explain the unusual status. 2094 6.2. Response Header Fields 2096 The response-header fields allow the server to pass additional 2097 information about the response which cannot be placed in the Status- 2098 Line. These header fields give information about the server and 2099 about further access to the resource identified by the Request-URI. 2101 response-header = Accept-Ranges ; Section 14.5 2102 | Age ; Section 14.6 2103 | ETag ; Section 14.19 2104 | Location ; Section 14.30 2105 | Proxy-Authenticate ; Section 14.33 2106 | Retry-After ; Section 14.37 2107 | Server ; Section 14.38 2108 | Vary ; Section 14.44 2109 | WWW-Authenticate ; Section 14.47 2111 Response-header field names can be extended reliably only in 2112 combination with a change in the protocol version. However, new or 2113 experimental header fields MAY be given the semantics of response- 2114 header fields if all parties in the communication recognize them to 2115 be response-header fields. Unrecognized header fields are treated as 2116 entity-header fields. 2118 7. Entity 2120 Request and Response messages MAY transfer an entity if not otherwise 2121 restricted by the request method or response status code. An entity 2122 consists of entity-header fields and an entity-body, although some 2123 responses will only include the entity-headers. 2125 In this section, both sender and recipient refer to either the client 2126 or the server, depending on who sends and who receives the entity. 2128 7.1. Entity Header Fields 2130 Entity-header fields define metainformation about the entity-body or, 2131 if no body is present, about the resource identified by the request. 2132 Some of this metainformation is OPTIONAL; some might be REQUIRED by 2133 portions of this specification. 2135 entity-header = Allow ; Section 14.7 2136 | Content-Encoding ; Section 14.11 2137 | Content-Language ; Section 14.12 2138 | Content-Length ; Section 14.13 2139 | Content-Location ; Section 14.14 2140 | Content-MD5 ; Section 14.15 2141 | Content-Range ; Section 14.16 2142 | Content-Type ; Section 14.17 2143 | Expires ; Section 14.21 2144 | Last-Modified ; Section 14.29 2145 | extension-header 2147 extension-header = message-header 2149 The extension-header mechanism allows additional entity-header fields 2150 to be defined without changing the protocol, but these fields cannot 2151 be assumed to be recognizable by the recipient. Unrecognized header 2152 fields SHOULD be ignored by the recipient and MUST be forwarded by 2153 transparent proxies. 2155 7.2. Entity Body 2157 The entity-body (if any) sent with an HTTP request or response is in 2158 a format and encoding defined by the entity-header fields. 2160 entity-body = *OCTET 2162 An entity-body is only present in a message when a message-body is 2163 present, as described in Section 4.3. The entity-body is obtained 2164 from the message-body by decoding any Transfer-Encoding that might 2165 have been applied to ensure safe and proper transfer of the message. 2167 7.2.1. Type 2169 When an entity-body is included with a message, the data type of that 2170 body is determined via the header fields Content-Type and Content- 2171 Encoding. These define a two-layer, ordered encoding model: 2173 entity-body := Content-Encoding( Content-Type( data ) ) 2175 Content-Type specifies the media type of the underlying data. 2176 Content-Encoding may be used to indicate any additional content 2177 codings applied to the data, usually for the purpose of data 2178 compression, that are a property of the requested resource. There is 2179 no default encoding. 2181 Any HTTP/1.1 message containing an entity-body SHOULD include a 2182 Content-Type header field defining the media type of that body. If 2183 and only if the media type is not given by a Content-Type field, the 2184 recipient MAY attempt to guess the media type via inspection of its 2185 content and/or the name extension(s) of the URI used to identify the 2186 resource. If the media type remains unknown, the recipient SHOULD 2187 treat it as type "application/octet-stream". 2189 7.2.2. Entity Length 2191 The entity-length of a message is the length of the message-body 2192 before any transfer-codings have been applied. Section 4.4 defines 2193 how the transfer-length of a message-body is determined. 2195 8. Connections 2197 8.1. Persistent Connections 2199 8.1.1. Purpose 2201 Prior to persistent connections, a separate TCP connection was 2202 established to fetch each URL, increasing the load on HTTP servers 2203 and causing congestion on the Internet. The use of inline images and 2204 other associated data often require a client to make multiple 2205 requests of the same server in a short amount of time. Analysis of 2206 these performance problems and results from a prototype 2207 implementation are available [Pad1995] [Spero]. Implementation 2208 experience and measurements of actual HTTP/1.1 (RFC 2068) 2209 implementations show good results [Nie1997]. Alternatives have also 2210 been explored, for example, T/TCP [Tou1998]. 2212 Persistent HTTP connections have a number of advantages: 2214 o By opening and closing fewer TCP connections, CPU time is saved in 2215 routers and hosts (clients, servers, proxies, gateways, tunnels, 2216 or caches), and memory used for TCP protocol control blocks can be 2217 saved in hosts. 2219 o HTTP requests and responses can be pipelined on a connection. 2220 Pipelining allows a client to make multiple requests without 2221 waiting for each response, allowing a single TCP connection to be 2222 used much more efficiently, with much lower elapsed time. 2224 o Network congestion is reduced by reducing the number of packets 2225 caused by TCP opens, and by allowing TCP sufficient time to 2226 determine the congestion state of the network. 2228 o Latency on subsequent requests is reduced since there is no time 2229 spent in TCP's connection opening handshake. 2231 o HTTP can evolve more gracefully, since errors can be reported 2232 without the penalty of closing the TCP connection. Clients using 2233 future versions of HTTP might optimistically try a new feature, 2234 but if communicating with an older server, retry with old 2235 semantics after an error is reported. 2237 HTTP implementations SHOULD implement persistent connections. 2239 8.1.2. Overall Operation 2241 A significant difference between HTTP/1.1 and earlier versions of 2242 HTTP is that persistent connections are the default behavior of any 2243 HTTP connection. That is, unless otherwise indicated, the client 2244 SHOULD assume that the server will maintain a persistent connection, 2245 even after error responses from the server. 2247 Persistent connections provide a mechanism by which a client and a 2248 server can signal the close of a TCP connection. This signaling 2249 takes place using the Connection header field (Section 14.10). Once 2250 a close has been signaled, the client MUST NOT send any more requests 2251 on that connection. 2253 8.1.2.1. Negotiation 2255 An HTTP/1.1 server MAY assume that a HTTP/1.1 client intends to 2256 maintain a persistent connection unless a Connection header including 2257 the connection-token "close" was sent in the request. If the server 2258 chooses to close the connection immediately after sending the 2259 response, it SHOULD send a Connection header including the 2260 connection-token close. 2262 An HTTP/1.1 client MAY expect a connection to remain open, but would 2263 decide to keep it open based on whether the response from a server 2264 contains a Connection header with the connection-token close. In 2265 case the client does not want to maintain a connection for more than 2266 that request, it SHOULD send a Connection header including the 2267 connection-token close. 2269 If either the client or the server sends the close token in the 2270 Connection header, that request becomes the last one for the 2271 connection. 2273 Clients and servers SHOULD NOT assume that a persistent connection is 2274 maintained for HTTP versions less than 1.1 unless it is explicitly 2275 signaled. See Appendix F.2 for more information on backward 2276 compatibility with HTTP/1.0 clients. 2278 In order to remain persistent, all messages on the connection MUST 2279 have a self-defined message length (i.e., one not defined by closure 2280 of the connection), as described in Section 4.4. 2282 8.1.2.2. Pipelining 2284 A client that supports persistent connections MAY "pipeline" its 2285 requests (i.e., send multiple requests without waiting for each 2286 response). A server MUST send its responses to those requests in the 2287 same order that the requests were received. 2289 Clients which assume persistent connections and pipeline immediately 2290 after connection establishment SHOULD be prepared to retry their 2291 connection if the first pipelined attempt fails. If a client does 2292 such a retry, it MUST NOT pipeline before it knows the connection is 2293 persistent. Clients MUST also be prepared to resend their requests 2294 if the server closes the connection before sending all of the 2295 corresponding responses. 2297 Clients SHOULD NOT pipeline requests using non-idempotent methods or 2298 non-idempotent sequences of methods (see Section 9.1.2). Otherwise, 2299 a premature termination of the transport connection could lead to 2300 indeterminate results. A client wishing to send a non-idempotent 2301 request SHOULD wait to send that request until it has received the 2302 response status for the previous request. 2304 8.1.3. Proxy Servers 2306 It is especially important that proxies correctly implement the 2307 properties of the Connection header field as specified in 2308 Section 14.10. 2310 The proxy server MUST signal persistent connections separately with 2311 its clients and the origin servers (or other proxy servers) that it 2312 connects to. Each persistent connection applies to only one 2313 transport link. 2315 A proxy server MUST NOT establish a HTTP/1.1 persistent connection 2316 with an HTTP/1.0 client (but see [RFC2068] for information and 2317 discussion of the problems with the Keep-Alive header implemented by 2318 many HTTP/1.0 clients). 2320 8.1.4. Practical Considerations 2322 Servers will usually have some time-out value beyond which they will 2323 no longer maintain an inactive connection. Proxy servers might make 2324 this a higher value since it is likely that the client will be making 2325 more connections through the same server. The use of persistent 2326 connections places no requirements on the length (or existence) of 2327 this time-out for either the client or the server. 2329 When a client or server wishes to time-out it SHOULD issue a graceful 2330 close on the transport connection. Clients and servers SHOULD both 2331 constantly watch for the other side of the transport close, and 2332 respond to it as appropriate. If a client or server does not detect 2333 the other side's close promptly it could cause unnecessary resource 2334 drain on the network. 2336 A client, server, or proxy MAY close the transport connection at any 2337 time. For example, a client might have started to send a new request 2338 at the same time that the server has decided to close the "idle" 2339 connection. From the server's point of view, the connection is being 2340 closed while it was idle, but from the client's point of view, a 2341 request is in progress. 2343 This means that clients, servers, and proxies MUST be able to recover 2344 from asynchronous close events. Client software SHOULD reopen the 2345 transport connection and retransmit the aborted sequence of requests 2346 without user interaction so long as the request sequence is 2347 idempotent (see Section 9.1.2). Non-idempotent methods or sequences 2348 MUST NOT be automatically retried, although user agents MAY offer a 2349 human operator the choice of retrying the request(s). Confirmation 2350 by user-agent software with semantic understanding of the application 2351 MAY substitute for user confirmation. The automatic retry SHOULD NOT 2352 be repeated if the second sequence of requests fails. 2354 Servers SHOULD always respond to at least one request per connection, 2355 if at all possible. Servers SHOULD NOT close a connection in the 2356 middle of transmitting a response, unless a network or client failure 2357 is suspected. 2359 Clients that use persistent connections SHOULD limit the number of 2360 simultaneous connections that they maintain to a given server. A 2361 single-user client SHOULD NOT maintain more than 2 connections with 2362 any server or proxy. A proxy SHOULD use up to 2*N connections to 2363 another server or proxy, where N is the number of simultaneously 2364 active users. These guidelines are intended to improve HTTP response 2365 times and avoid congestion. 2367 8.2. Message Transmission Requirements 2369 8.2.1. Persistent Connections and Flow Control 2371 HTTP/1.1 servers SHOULD maintain persistent connections and use TCP's 2372 flow control mechanisms to resolve temporary overloads, rather than 2373 terminating connections with the expectation that clients will retry. 2374 The latter technique can exacerbate network congestion. 2376 8.2.2. Monitoring Connections for Error Status Messages 2378 An HTTP/1.1 (or later) client sending a message-body SHOULD monitor 2379 the network connection for an error status while it is transmitting 2380 the request. If the client sees an error status, it SHOULD 2381 immediately cease transmitting the body. If the body is being sent 2382 using a "chunked" encoding (Section 3.6), a zero length chunk and 2383 empty trailer MAY be used to prematurely mark the end of the message. 2384 If the body was preceded by a Content-Length header, the client MUST 2385 close the connection. 2387 8.2.3. Use of the 100 (Continue) Status 2389 The purpose of the 100 (Continue) status (see Section 10.1.1) is to 2390 allow a client that is sending a request message with a request body 2391 to determine if the origin server is willing to accept the request 2392 (based on the request headers) before the client sends the request 2393 body. In some cases, it might either be inappropriate or highly 2394 inefficient for the client to send the body if the server will reject 2395 the message without looking at the body. 2397 Requirements for HTTP/1.1 clients: 2399 o If a client will wait for a 100 (Continue) response before sending 2400 the request body, it MUST send an Expect request-header field 2401 (Section 14.20) with the "100-continue" expectation. 2403 o A client MUST NOT send an Expect request-header field 2404 (Section 14.20) with the "100-continue" expectation if it does not 2405 intend to send a request body. 2407 Because of the presence of older implementations, the protocol allows 2408 ambiguous situations in which a client may send "Expect: 100- 2409 continue" without receiving either a 417 (Expectation Failed) status 2410 or a 100 (Continue) status. Therefore, when a client sends this 2411 header field to an origin server (possibly via a proxy) from which it 2412 has never seen a 100 (Continue) status, the client SHOULD NOT wait 2413 for an indefinite period before sending the request body. 2415 Requirements for HTTP/1.1 origin servers: 2417 o Upon receiving a request which includes an Expect request-header 2418 field with the "100-continue" expectation, an origin server MUST 2419 either respond with 100 (Continue) status and continue to read 2420 from the input stream, or respond with a final status code. The 2421 origin server MUST NOT wait for the request body before sending 2422 the 100 (Continue) response. If it responds with a final status 2423 code, it MAY close the transport connection or it MAY continue to 2424 read and discard the rest of the request. It MUST NOT perform the 2425 requested method if it returns a final status code. 2427 o An origin server SHOULD NOT send a 100 (Continue) response if the 2428 request message does not include an Expect request-header field 2429 with the "100-continue" expectation, and MUST NOT send a 100 2430 (Continue) response if such a request comes from an HTTP/1.0 (or 2431 earlier) client. There is an exception to this rule: for 2432 compatibility with RFC 2068, a server MAY send a 100 (Continue) 2433 status in response to an HTTP/1.1 PUT or POST request that does 2434 not include an Expect request-header field with the "100-continue" 2435 expectation. This exception, the purpose of which is to minimize 2436 any client processing delays associated with an undeclared wait 2437 for 100 (Continue) status, applies only to HTTP/1.1 requests, and 2438 not to requests with any other HTTP-version value. 2440 o An origin server MAY omit a 100 (Continue) response if it has 2441 already received some or all of the request body for the 2442 corresponding request. 2444 o An origin server that sends a 100 (Continue) response MUST 2445 ultimately send a final status code, once the request body is 2446 received and processed, unless it terminates the transport 2447 connection prematurely. 2449 o If an origin server receives a request that does not include an 2450 Expect request-header field with the "100-continue" expectation, 2451 the request includes a request body, and the server responds with 2452 a final status code before reading the entire request body from 2453 the transport connection, then the server SHOULD NOT close the 2454 transport connection until it has read the entire request, or 2455 until the client closes the connection. Otherwise, the client 2456 might not reliably receive the response message. However, this 2457 requirement is not be construed as preventing a server from 2458 defending itself against denial-of-service attacks, or from badly 2459 broken client implementations. 2461 Requirements for HTTP/1.1 proxies: 2463 o If a proxy receives a request that includes an Expect request- 2464 header field with the "100-continue" expectation, and the proxy 2465 either knows that the next-hop server complies with HTTP/1.1 or 2466 higher, or does not know the HTTP version of the next-hop server, 2467 it MUST forward the request, including the Expect header field. 2469 o If the proxy knows that the version of the next-hop server is 2470 HTTP/1.0 or lower, it MUST NOT forward the request, and it MUST 2471 respond with a 417 (Expectation Failed) status. 2473 o Proxies SHOULD maintain a cache recording the HTTP version numbers 2474 received from recently-referenced next-hop servers. 2476 o A proxy MUST NOT forward a 100 (Continue) response if the request 2477 message was received from an HTTP/1.0 (or earlier) client and did 2478 not include an Expect request-header field with the "100-continue" 2479 expectation. This requirement overrides the general rule for 2480 forwarding of 1xx responses (see Section 10.1). 2482 8.2.4. Client Behavior if Server Prematurely Closes Connection 2484 If an HTTP/1.1 client sends a request which includes a request body, 2485 but which does not include an Expect request-header field with the 2486 "100-continue" expectation, and if the client is not directly 2487 connected to an HTTP/1.1 origin server, and if the client sees the 2488 connection close before receiving any status from the server, the 2489 client SHOULD retry the request. If the client does retry this 2490 request, it MAY use the following "binary exponential backoff" 2491 algorithm to be assured of obtaining a reliable response: 2493 1. Initiate a new connection to the server 2495 2. Transmit the request-headers 2497 3. Initialize a variable R to the estimated round-trip time to the 2498 server (e.g., based on the time it took to establish the 2499 connection), or to a constant value of 5 seconds if the round- 2500 trip time is not available. 2502 4. Compute T = R * (2**N), where N is the number of previous retries 2503 of this request. 2505 5. Wait either for an error response from the server, or for T 2506 seconds (whichever comes first) 2508 6. If no error response is received, after T seconds transmit the 2509 body of the request. 2511 7. If client sees that the connection is closed prematurely, repeat 2512 from step 1 until the request is accepted, an error response is 2513 received, or the user becomes impatient and terminates the retry 2514 process. 2516 If at any point an error status is received, the client 2518 o SHOULD NOT continue and 2520 o SHOULD close the connection if it has not completed sending the 2521 request message. 2523 9. Method Definitions 2525 The set of common methods for HTTP/1.1 is defined below. Although 2526 this set can be expanded, additional methods cannot be assumed to 2527 share the same semantics for separately extended clients and servers. 2528 The Host request-header field (Section 14.23) MUST accompany all 2529 HTTP/1.1 requests. 2531 9.1. Safe and Idempotent Methods 2533 9.1.1. Safe Methods 2535 Implementors should be aware that the software represents the user in 2536 their interactions over the Internet, and should be careful to allow 2537 the user to be aware of any actions they might take which may have an 2538 unexpected significance to themselves or others. 2540 In particular, the convention has been established that the GET and 2541 HEAD methods SHOULD NOT have the significance of taking an action 2542 other than retrieval. These methods ought to be considered "safe". 2543 This allows user agents to represent other methods, such as POST, PUT 2544 and DELETE, in a special way, so that the user is made aware of the 2545 fact that a possibly unsafe action is being requested. 2547 Naturally, it is not possible to ensure that the server does not 2548 generate side-effects as a result of performing a GET request; in 2549 fact, some dynamic resources consider that a feature. The important 2550 distinction here is that the user did not request the side-effects, 2551 so therefore cannot be held accountable for them. 2553 9.1.2. Idempotent Methods 2555 Methods can also have the property of "idempotence" in that (aside 2556 from error or expiration issues) the side-effects of N > 0 identical 2557 requests is the same as for a single request. The methods GET, HEAD, 2558 PUT and DELETE share this property. Also, the methods OPTIONS and 2559 TRACE SHOULD NOT have side effects, and so are inherently idempotent. 2561 However, it is possible that a sequence of several requests is non- 2562 idempotent, even if all of the methods executed in that sequence are 2563 idempotent. (A sequence is idempotent if a single execution of the 2564 entire sequence always yields a result that is not changed by a 2565 reexecution of all, or part, of that sequence.) For example, a 2566 sequence is non-idempotent if its result depends on a value that is 2567 later modified in the same sequence. 2569 A sequence that never has side effects is idempotent, by definition 2570 (provided that no concurrent operations are being executed on the 2571 same set of resources). 2573 9.2. OPTIONS 2575 The OPTIONS method represents a request for information about the 2576 communication options available on the request/response chain 2577 identified by the Request-URI. This method allows the client to 2578 determine the options and/or requirements associated with a resource, 2579 or the capabilities of a server, without implying a resource action 2580 or initiating a resource retrieval. 2582 Responses to this method are not cacheable. 2584 If the OPTIONS request includes an entity-body (as indicated by the 2585 presence of Content-Length or Transfer-Encoding), then the media type 2586 MUST be indicated by a Content-Type field. Although this 2587 specification does not define any use for such a body, future 2588 extensions to HTTP might use the OPTIONS body to make more detailed 2589 queries on the server. A server that does not support such an 2590 extension MAY discard the request body. 2592 If the Request-URI is an asterisk ("*"), the OPTIONS request is 2593 intended to apply to the server in general rather than to a specific 2594 resource. Since a server's communication options typically depend on 2595 the resource, the "*" request is only useful as a "ping" or "no-op" 2596 type of method; it does nothing beyond allowing the client to test 2597 the capabilities of the server. For example, this can be used to 2598 test a proxy for HTTP/1.1 compliance (or lack thereof). 2600 If the Request-URI is not an asterisk, the OPTIONS request applies 2601 only to the options that are available when communicating with that 2602 resource. 2604 A 200 response SHOULD include any header fields that indicate 2605 optional features implemented by the server and applicable to that 2606 resource (e.g., Allow), possibly including extensions not defined by 2607 this specification. The response body, if any, SHOULD also include 2608 information about the communication options. The format for such a 2609 body is not defined by this specification, but might be defined by 2610 future extensions to HTTP. Content negotiation MAY be used to select 2611 the appropriate response format. If no response body is included, 2612 the response MUST include a Content-Length field with a field-value 2613 of "0". 2615 The Max-Forwards request-header field MAY be used to target a 2616 specific proxy in the request chain. When a proxy receives an 2617 OPTIONS request on an absoluteURI for which request forwarding is 2618 permitted, the proxy MUST check for a Max-Forwards field. If the 2619 Max-Forwards field-value is zero ("0"), the proxy MUST NOT forward 2620 the message; instead, the proxy SHOULD respond with its own 2621 communication options. If the Max-Forwards field-value is an integer 2622 greater than zero, the proxy MUST decrement the field-value when it 2623 forwards the request. If no Max-Forwards field is present in the 2624 request, then the forwarded request MUST NOT include a Max-Forwards 2625 field. 2627 9.3. GET 2629 The GET method means retrieve whatever information (in the form of an 2630 entity) is identified by the Request-URI. If the Request-URI refers 2631 to a data-producing process, it is the produced data which shall be 2632 returned as the entity in the response and not the source text of the 2633 process, unless that text happens to be the output of the process. 2635 The semantics of the GET method change to a "conditional GET" if the 2636 request message includes an If-Modified-Since, If-Unmodified-Since, 2637 If-Match, If-None-Match, or If-Range header field. A conditional GET 2638 method requests that the entity be transferred only under the 2639 circumstances described by the conditional header field(s). The 2640 conditional GET method is intended to reduce unnecessary network 2641 usage by allowing cached entities to be refreshed without requiring 2642 multiple requests or transferring data already held by the client. 2644 The semantics of the GET method change to a "partial GET" if the 2645 request message includes a Range header field. A partial GET 2646 requests that only part of the entity be transferred, as described in 2647 Section 14.35. The partial GET method is intended to reduce 2648 unnecessary network usage by allowing partially-retrieved entities to 2649 be completed without transferring data already held by the client. 2651 The response to a GET request is cacheable if and only if it meets 2652 the requirements for HTTP caching described in Section 13. 2654 See Section 15.1.3 for security considerations when used for forms. 2656 9.4. HEAD 2658 The HEAD method is identical to GET except that the server MUST NOT 2659 return a message-body in the response. The metainformation contained 2660 in the HTTP headers in response to a HEAD request SHOULD be identical 2661 to the information sent in response to a GET request. This method 2662 can be used for obtaining metainformation about the entity implied by 2663 the request without transferring the entity-body itself. This method 2664 is often used for testing hypertext links for validity, 2665 accessibility, and recent modification. 2667 The response to a HEAD request MAY be cacheable in the sense that the 2668 information contained in the response MAY be used to update a 2669 previously cached entity from that resource. If the new field values 2670 indicate that the cached entity differs from the current entity (as 2671 would be indicated by a change in Content-Length, Content-MD5, ETag 2672 or Last-Modified), then the cache MUST treat the cache entry as 2673 stale. 2675 9.5. POST 2677 The POST method is used to request that the origin server accept the 2678 entity enclosed in the request as data to be processed by the 2679 resource identified by the Request-URI in the Request-Line. POST is 2680 designed to allow a uniform method to cover the following functions: 2682 o Annotation of existing resources; 2684 o Posting a message to a bulletin board, newsgroup, mailing list, or 2685 similar group of articles; 2687 o Providing a block of data, such as the result of submitting a 2688 form, to a data-handling process; 2690 o Extending a database through an append operation. 2692 The actual function performed by the POST method is determined by the 2693 server and is usually dependent on the Request-URI. 2695 The action performed by the POST method might not result in a 2696 resource that can be identified by a URI. In this case, either 200 2697 (OK) or 204 (No Content) is the appropriate response status, 2698 depending on whether or not the response includes an entity that 2699 describes the result. 2701 If a resource has been created on the origin server, the response 2702 SHOULD be 201 (Created) and contain an entity which describes the 2703 status of the request and refers to the new resource, and a Location 2704 header (see Section 14.30). 2706 Responses to this method are not cacheable, unless the response 2707 includes appropriate Cache-Control or Expires header fields. 2708 However, the 303 (See Other) response can be used to direct the user 2709 agent to retrieve a cacheable resource. 2711 POST requests MUST obey the message transmission requirements set out 2712 in Section 8.2. 2714 See Section 15.1.3 for security considerations. 2716 9.6. PUT 2718 The PUT method requests that the enclosed entity be stored under the 2719 supplied Request-URI. If the Request-URI refers to an already 2720 existing resource, the enclosed entity SHOULD be considered as a 2721 modified version of the one residing on the origin server. If the 2722 Request-URI does not point to an existing resource, and that URI is 2723 capable of being defined as a new resource by the requesting user 2724 agent, the origin server can create the resource with that URI. If a 2725 new resource is created, the origin server MUST inform the user agent 2726 via the 201 (Created) response. If an existing resource is modified, 2727 either the 200 (OK) or 204 (No Content) response codes SHOULD be sent 2728 to indicate successful completion of the request. If the resource 2729 could not be created or modified with the Request-URI, an appropriate 2730 error response SHOULD be given that reflects the nature of the 2731 problem. The recipient of the entity MUST NOT ignore any Content-* 2732 (e.g. Content-Range) headers that it does not understand or 2733 implement and MUST return a 501 (Not Implemented) response in such 2734 cases. 2736 If the request passes through a cache and the Request-URI identifies 2737 one or more currently cached entities, those entries SHOULD be 2738 treated as stale. Responses to this method are not cacheable. 2740 The fundamental difference between the POST and PUT requests is 2741 reflected in the different meaning of the Request-URI. The URI in a 2742 POST request identifies the resource that will handle the enclosed 2743 entity. That resource might be a data-accepting process, a gateway 2744 to some other protocol, or a separate entity that accepts 2745 annotations. In contrast, the URI in a PUT request identifies the 2746 entity enclosed with the request -- the user agent knows what URI is 2747 intended and the server MUST NOT attempt to apply the request to some 2748 other resource. If the server desires that the request be applied to 2749 a different URI, it MUST send a 301 (Moved Permanently) response; the 2750 user agent MAY then make its own decision regarding whether or not to 2751 redirect the request. 2753 A single resource MAY be identified by many different URIs. For 2754 example, an article might have a URI for identifying "the current 2755 version" which is separate from the URI identifying each particular 2756 version. In this case, a PUT request on a general URI might result 2757 in several other URIs being defined by the origin server. 2759 HTTP/1.1 does not define how a PUT method affects the state of an 2760 origin server. 2762 PUT requests MUST obey the message transmission requirements set out 2763 in Section 8.2. 2765 Unless otherwise specified for a particular entity-header, the 2766 entity-headers in the PUT request SHOULD be applied to the resource 2767 created or modified by the PUT. 2769 9.7. DELETE 2771 The DELETE method requests that the origin server delete the resource 2772 identified by the Request-URI. This method MAY be overridden by 2773 human intervention (or other means) on the origin server. The client 2774 cannot be guaranteed that the operation has been carried out, even if 2775 the status code returned from the origin server indicates that the 2776 action has been completed successfully. However, the server SHOULD 2777 NOT indicate success unless, at the time the response is given, it 2778 intends to delete the resource or move it to an inaccessible 2779 location. 2781 A successful response SHOULD be 200 (OK) if the response includes an 2782 entity describing the status, 202 (Accepted) if the action has not 2783 yet been enacted, or 204 (No Content) if the action has been enacted 2784 but the response does not include an entity. 2786 If the request passes through a cache and the Request-URI identifies 2787 one or more currently cached entities, those entries SHOULD be 2788 treated as stale. Responses to this method are not cacheable. 2790 9.8. TRACE 2792 The TRACE method is used to invoke a remote, application-layer loop- 2793 back of the request message. The final recipient of the request 2794 SHOULD reflect the message received back to the client as the entity- 2795 body of a 200 (OK) response. The final recipient is either the 2796 origin server or the first proxy or gateway to receive a Max-Forwards 2797 value of zero (0) in the request (see Section 14.31). A TRACE 2798 request MUST NOT include an entity. 2800 TRACE allows the client to see what is being received at the other 2801 end of the request chain and use that data for testing or diagnostic 2802 information. The value of the Via header field (Section 14.45) is of 2803 particular interest, since it acts as a trace of the request chain. 2804 Use of the Max-Forwards header field allows the client to limit the 2805 length of the request chain, which is useful for testing a chain of 2806 proxies forwarding messages in an infinite loop. 2808 If the request is valid, the response SHOULD contain the entire 2809 request message in the entity-body, with a Content-Type of "message/ 2810 http". Responses to this method MUST NOT be cached. 2812 9.9. CONNECT 2814 This specification reserves the method name CONNECT for use with a 2815 proxy that can dynamically switch to being a tunnel (e.g. SSL 2816 tunneling [Luo1998]). 2818 10. Status Code Definitions 2820 Each Status-Code is described below, including a description of which 2821 method(s) it can follow and any metainformation required in the 2822 response. 2824 10.1. Informational 1xx 2826 This class of status code indicates a provisional response, 2827 consisting only of the Status-Line and optional headers, and is 2828 terminated by an empty line. There are no required headers for this 2829 class of status code. Since HTTP/1.0 did not define any 1xx status 2830 codes, servers MUST NOT send a 1xx response to an HTTP/1.0 client 2831 except under experimental conditions. 2833 A client MUST be prepared to accept one or more 1xx status responses 2834 prior to a regular response, even if the client does not expect a 100 2835 (Continue) status message. Unexpected 1xx status responses MAY be 2836 ignored by a user agent. 2838 Proxies MUST forward 1xx responses, unless the connection between the 2839 proxy and its client has been closed, or unless the proxy itself 2840 requested the generation of the 1xx response. (For example, if a 2841 proxy adds a "Expect: 100-continue" field when it forwards a request, 2842 then it need not forward the corresponding 100 (Continue) 2843 response(s).) 2845 10.1.1. 100 Continue 2847 The client SHOULD continue with its request. This interim response 2848 is used to inform the client that the initial part of the request has 2849 been received and has not yet been rejected by the server. The 2850 client SHOULD continue by sending the remainder of the request or, if 2851 the request has already been completed, ignore this response. The 2852 server MUST send a final response after the request has been 2853 completed. See Section 8.2.3 for detailed discussion of the use and 2854 handling of this status code. 2856 10.1.2. 101 Switching Protocols 2858 The server understands and is willing to comply with the client's 2859 request, via the Upgrade message header field (Section 14.42), for a 2860 change in the application protocol being used on this connection. 2861 The server will switch protocols to those defined by the response's 2862 Upgrade header field immediately after the empty line which 2863 terminates the 101 response. 2865 The protocol SHOULD be switched only when it is advantageous to do 2866 so. For example, switching to a newer version of HTTP is 2867 advantageous over older versions, and switching to a real-time, 2868 synchronous protocol might be advantageous when delivering resources 2869 that use such features. 2871 10.2. Successful 2xx 2873 This class of status code indicates that the client's request was 2874 successfully received, understood, and accepted. 2876 10.2.1. 200 OK 2878 The request has succeeded. The information returned with the 2879 response is dependent on the method used in the request, for example: 2881 GET an entity corresponding to the requested resource is sent in the 2882 response; 2884 HEAD the entity-header fields corresponding to the requested 2885 resource are sent in the response without any message-body; 2887 POST an entity describing or containing the result of the action; 2889 TRACE an entity containing the request message as received by the 2890 end server. 2892 10.2.2. 201 Created 2894 The request has been fulfilled and resulted in a new resource being 2895 created. The newly created resource can be referenced by the URI(s) 2896 returned in the entity of the response, with the most specific URI 2897 for the resource given by a Location header field. The response 2898 SHOULD include an entity containing a list of resource 2899 characteristics and location(s) from which the user or user agent can 2900 choose the one most appropriate. The entity format is specified by 2901 the media type given in the Content-Type header field. The origin 2902 server MUST create the resource before returning the 201 status code. 2903 If the action cannot be carried out immediately, the server SHOULD 2904 respond with 202 (Accepted) response instead. 2906 A 201 response MAY contain an ETag response header field indicating 2907 the current value of the entity tag for the requested variant just 2908 created, see Section 14.19. 2910 10.2.3. 202 Accepted 2912 The request has been accepted for processing, but the processing has 2913 not been completed. The request might or might not eventually be 2914 acted upon, as it might be disallowed when processing actually takes 2915 place. There is no facility for re-sending a status code from an 2916 asynchronous operation such as this. 2918 The 202 response is intentionally non-committal. Its purpose is to 2919 allow a server to accept a request for some other process (perhaps a 2920 batch-oriented process that is only run once per day) without 2921 requiring that the user agent's connection to the server persist 2922 until the process is completed. The entity returned with this 2923 response SHOULD include an indication of the request's current status 2924 and either a pointer to a status monitor or some estimate of when the 2925 user can expect the request to be fulfilled. 2927 10.2.4. 203 Non-Authoritative Information 2929 The returned metainformation in the entity-header is not the 2930 definitive set as available from the origin server, but is gathered 2931 from a local or a third-party copy. The set presented MAY be a 2932 subset or superset of the original version. For example, including 2933 local annotation information about the resource might result in a 2934 superset of the metainformation known by the origin server. Use of 2935 this response code is not required and is only appropriate when the 2936 response would otherwise be 200 (OK). 2938 10.2.5. 204 No Content 2940 The server has fulfilled the request but does not need to return an 2941 entity-body, and might want to return updated metainformation. The 2942 response MAY include new or updated metainformation in the form of 2943 entity-headers, which if present SHOULD be associated with the 2944 requested variant. 2946 If the client is a user agent, it SHOULD NOT change its document view 2947 from that which caused the request to be sent. This response is 2948 primarily intended to allow input for actions to take place without 2949 causing a change to the user agent's active document view, although 2950 any new or updated metainformation SHOULD be applied to the document 2951 currently in the user agent's active view. 2953 The 204 response MUST NOT include a message-body, and thus is always 2954 terminated by the first empty line after the header fields. 2956 10.2.6. 205 Reset Content 2958 The server has fulfilled the request and the user agent SHOULD reset 2959 the document view which caused the request to be sent. This response 2960 is primarily intended to allow input for actions to take place via 2961 user input, followed by a clearing of the form in which the input is 2962 given so that the user can easily initiate another input action. The 2963 response MUST NOT include an entity. 2965 10.2.7. 206 Partial Content 2967 The server has fulfilled the partial GET request for the resource. 2968 The request MUST have included a Range header field (Section 14.35) 2969 indicating the desired range, and MAY have included an If-Range 2970 header field (Section 14.27) to make the request conditional. 2972 The response MUST include the following header fields: 2974 o Either a Content-Range header field (Section 14.16) indicating the 2975 range included with this response, or a multipart/byteranges 2976 Content-Type including Content-Range fields for each part. If a 2977 Content-Length header field is present in the response, its value 2978 MUST match the actual number of OCTETs transmitted in the message- 2979 body. 2981 o Date 2983 o ETag and/or Content-Location, if the header would have been sent 2984 in a 200 response to the same request 2986 o Expires, Cache-Control, and/or Vary, if the field-value might 2987 differ from that sent in any previous response for the same 2988 variant 2990 If the 206 response is the result of an If-Range request, the 2991 response SHOULD NOT include other entity-headers. Otherwise, the 2992 response MUST include all of the entity-headers that would have been 2993 returned with a 200 (OK) response to the same request. 2995 A cache MUST NOT combine a 206 response with other previously cached 2996 content if the ETag or Last-Modified headers do not match exactly, 2997 see 13.5.4. 2999 A cache that does not support the Range and Content-Range headers 3000 MUST NOT cache 206 (Partial) responses. 3002 10.3. Redirection 3xx 3004 This class of status code indicates that further action needs to be 3005 taken by the user agent in order to fulfill the request. The action 3006 required MAY be carried out by the user agent without interaction 3007 with the user if and only if the method used in the second request is 3008 GET or HEAD. A client SHOULD detect infinite redirection loops, 3009 since such loops generate network traffic for each redirection. 3011 Note: previous versions of this specification recommended a 3012 maximum of five redirections. Content developers should be aware 3013 that there might be clients that implement such a fixed 3014 limitation. 3016 10.3.1. 300 Multiple Choices 3018 The requested resource corresponds to any one of a set of 3019 representations, each with its own specific location, and agent- 3020 driven negotiation information (Section 12) is being provided so that 3021 the user (or user agent) can select a preferred representation and 3022 redirect its request to that location. 3024 Unless it was a HEAD request, the response SHOULD include an entity 3025 containing a list of resource characteristics and location(s) from 3026 which the user or user agent can choose the one most appropriate. 3027 The entity format is specified by the media type given in the 3028 Content-Type header field. Depending upon the format and the 3029 capabilities of the user agent, selection of the most appropriate 3030 choice MAY be performed automatically. However, this specification 3031 does not define any standard for such automatic selection. 3033 If the server has a preferred choice of representation, it SHOULD 3034 include the specific URI for that representation in the Location 3035 field; user agents MAY use the Location field value for automatic 3036 redirection. This response is cacheable unless indicated otherwise. 3038 10.3.2. 301 Moved Permanently 3040 The requested resource has been assigned a new permanent URI and any 3041 future references to this resource SHOULD use one of the returned 3042 URIs. Clients with link editing capabilities ought to automatically 3043 re-link references to the Request-URI to one or more of the new 3044 references returned by the server, where possible. This response is 3045 cacheable unless indicated otherwise. 3047 The new permanent URI SHOULD be given by the Location field in the 3048 response. Unless the request method was HEAD, the entity of the 3049 response SHOULD contain a short hypertext note with a hyperlink to 3050 the new URI(s). 3052 If the 301 status code is received in response to a request method 3053 that is known to be "safe", as defined in Section 9.1.1, then the 3054 request MAY be automatically redirected by the user agent without 3055 confirmation. Otherwise, the user agent MUST NOT automatically 3056 redirect the request unless it can be confirmed by the user, since 3057 this might change the conditions under which the request was issued. 3059 Note: When automatically redirecting a POST request after 3060 receiving a 301 status code, some existing HTTP/1.0 user agents 3061 will erroneously change it into a GET request. 3063 10.3.3. 302 Found 3065 The requested resource resides temporarily under a different URI. 3066 Since the redirection might be altered on occasion, the client SHOULD 3067 continue to use the Request-URI for future requests. This response 3068 is only cacheable if indicated by a Cache-Control or Expires header 3069 field. 3071 The temporary URI SHOULD be given by the Location field in the 3072 response. Unless the request method was HEAD, the entity of the 3073 response SHOULD contain a short hypertext note with a hyperlink to 3074 the new URI(s). 3076 If the 302 status code is received in response to a request method 3077 that is known to be "safe", as defined in Section 9.1.1, then the 3078 request MAY be automatically redirected by the user agent without 3079 confirmation. Otherwise, the user agent MUST NOT automatically 3080 redirect the request unless it can be confirmed by the user, since 3081 this might change the conditions under which the request was issued. 3083 Note: RFC 1945 and RFC 2068 specify that the client is not allowed 3084 to change the method on the redirected request. However, most 3085 existing user agent implementations treat 302 as if it were a 303 3086 response, performing a GET on the Location field-value regardless 3087 of the original request method. The status codes 303 and 307 have 3088 been added for servers that wish to make unambiguously clear which 3089 kind of reaction is expected of the client. 3091 10.3.4. 303 See Other 3093 The response to the request can be found under a different URI and 3094 SHOULD be retrieved using a GET method on that resource. This method 3095 exists primarily to allow the output of a POST-activated script to 3096 redirect the user agent to a selected resource. The new URI is not a 3097 substitute reference for the originally requested resource. The 303 3098 response MUST NOT be cached, but the response to the second 3099 (redirected) request might be cacheable. 3101 The different URI SHOULD be given by the Location field in the 3102 response. Unless the request method was HEAD, the entity of the 3103 response SHOULD contain a short hypertext note with a hyperlink to 3104 the new URI(s). 3106 Note: Many pre-HTTP/1.1 user agents do not understand the 303 3107 status. When interoperability with such clients is a concern, the 3108 302 status code may be used instead, since most user agents react 3109 to a 302 response as described here for 303. 3111 10.3.5. 304 Not Modified 3113 If the client has performed a conditional GET request and access is 3114 allowed, but the document has not been modified, the server SHOULD 3115 respond with this status code. The 304 response MUST NOT contain a 3116 message-body, and thus is always terminated by the first empty line 3117 after the header fields. 3119 The response MUST include the following header fields: 3121 o Date, unless its omission is required by Section 14.18.1 3123 If a clockless origin server obeys these rules, and proxies and 3124 clients add their own Date to any response received without one (as 3125 already specified by [RFC2068], Section 14.19), caches will operate 3126 correctly. 3128 o ETag and/or Content-Location, if the header would have been sent 3129 in a 200 response to the same request 3131 o Expires, Cache-Control, and/or Vary, if the field-value might 3132 differ from that sent in any previous response for the same 3133 variant 3135 If the conditional GET used a strong cache validator (see 3136 Section 13.3.3), the response SHOULD NOT include other entity- 3137 headers. Otherwise (i.e., the conditional GET used a weak 3138 validator), the response MUST NOT include other entity-headers; this 3139 prevents inconsistencies between cached entity-bodies and updated 3140 headers. 3142 If a 304 response indicates an entity not currently cached, then the 3143 cache MUST disregard the response and repeat the request without the 3144 conditional. 3146 If a cache uses a received 304 response to update a cache entry, the 3147 cache MUST update the entry to reflect any new field values given in 3148 the response. 3150 10.3.6. 305 Use Proxy 3152 The requested resource MUST be accessed through the proxy given by 3153 the Location field. The Location field gives the URI of the proxy. 3155 The recipient is expected to repeat this single request via the 3156 proxy. 305 responses MUST only be generated by origin servers. 3158 Note: RFC 2068 was not clear that 305 was intended to redirect a 3159 single request, and to be generated by origin servers only. Not 3160 observing these limitations has significant security consequences. 3162 10.3.7. 306 (Unused) 3164 The 306 status code was used in a previous version of the 3165 specification, is no longer used, and the code is reserved. 3167 10.3.8. 307 Temporary Redirect 3169 The requested resource resides temporarily under a different URI. 3170 Since the redirection MAY be altered on occasion, the client SHOULD 3171 continue to use the Request-URI for future requests. This response 3172 is only cacheable if indicated by a Cache-Control or Expires header 3173 field. 3175 The temporary URI SHOULD be given by the Location field in the 3176 response. Unless the request method was HEAD, the entity of the 3177 response SHOULD contain a short hypertext note with a hyperlink to 3178 the new URI(s) , since many pre-HTTP/1.1 user agents do not 3179 understand the 307 status. Therefore, the note SHOULD contain the 3180 information necessary for a user to repeat the original request on 3181 the new URI. 3183 If the 307 status code is received in response to a request method 3184 that is known to be "safe", as defined in Section 9.1.1, then the 3185 request MAY be automatically redirected by the user agent without 3186 confirmation. Otherwise, the user agent MUST NOT automatically 3187 redirect the request unless it can be confirmed by the user, since 3188 this might change the conditions under which the request was issued. 3190 10.4. Client Error 4xx 3192 The 4xx class of status code is intended for cases in which the 3193 client seems to have erred. Except when responding to a HEAD 3194 request, the server SHOULD include an entity containing an 3195 explanation of the error situation, and whether it is a temporary or 3196 permanent condition. These status codes are applicable to any 3197 request method. User agents SHOULD display any included entity to 3198 the user. 3200 If the client is sending data, a server implementation using TCP 3201 SHOULD be careful to ensure that the client acknowledges receipt of 3202 the packet(s) containing the response, before the server closes the 3203 input connection. If the client continues sending data to the server 3204 after the close, the server's TCP stack will send a reset packet to 3205 the client, which may erase the client's unacknowledged input buffers 3206 before they can be read and interpreted by the HTTP application. 3208 10.4.1. 400 Bad Request 3210 The request could not be understood by the server due to malformed 3211 syntax. The client SHOULD NOT repeat the request without 3212 modifications. 3214 10.4.2. 401 Unauthorized 3216 The request requires user authentication. The response MUST include 3217 a WWW-Authenticate header field (Section 14.47) containing a 3218 challenge applicable to the requested resource. The client MAY 3219 repeat the request with a suitable Authorization header field 3220 (Section 14.8). If the request already included Authorization 3221 credentials, then the 401 response indicates that authorization has 3222 been refused for those credentials. If the 401 response contains the 3223 same challenge as the prior response, and the user agent has already 3224 attempted authentication at least once, then the user SHOULD be 3225 presented the entity that was given in the response, since that 3226 entity might include relevant diagnostic information. HTTP access 3227 authentication is explained in "HTTP Authentication: Basic and Digest 3228 Access Authentication" [RFC2617]. 3230 10.4.3. 402 Payment Required 3232 This code is reserved for future use. 3234 10.4.4. 403 Forbidden 3236 The server understood the request, but is refusing to fulfill it. 3237 Authorization will not help and the request SHOULD NOT be repeated. 3238 If the request method was not HEAD and the server wishes to make 3239 public why the request has not been fulfilled, it SHOULD describe the 3240 reason for the refusal in the entity. If the server does not wish to 3241 make this information available to the client, the status code 404 3242 (Not Found) can be used instead. 3244 10.4.5. 404 Not Found 3246 The server has not found anything matching the Request-URI. No 3247 indication is given of whether the condition is temporary or 3248 permanent. The 410 (Gone) status code SHOULD be used if the server 3249 knows, through some internally configurable mechanism, that an old 3250 resource is permanently unavailable and has no forwarding address. 3252 This status code is commonly used when the server does not wish to 3253 reveal exactly why the request has been refused, or when no other 3254 response is applicable. 3256 10.4.6. 405 Method Not Allowed 3258 The method specified in the Request-Line is not allowed for the 3259 resource identified by the Request-URI. The response MUST include an 3260 Allow header containing a list of valid methods for the requested 3261 resource. 3263 10.4.7. 406 Not Acceptable 3265 The resource identified by the request is only capable of generating 3266 response entities which have content characteristics not acceptable 3267 according to the accept headers sent in the request. 3269 Unless it was a HEAD request, the response SHOULD include an entity 3270 containing a list of available entity characteristics and location(s) 3271 from which the user or user agent can choose the one most 3272 appropriate. The entity format is specified by the media type given 3273 in the Content-Type header field. Depending upon the format and the 3274 capabilities of the user agent, selection of the most appropriate 3275 choice MAY be performed automatically. However, this specification 3276 does not define any standard for such automatic selection. 3278 Note: HTTP/1.1 servers are allowed to return responses which are 3279 not acceptable according to the accept headers sent in the 3280 request. In some cases, this may even be preferable to sending a 3281 406 response. User agents are encouraged to inspect the headers 3282 of an incoming response to determine if it is acceptable. 3284 If the response could be unacceptable, a user agent SHOULD 3285 temporarily stop receipt of more data and query the user for a 3286 decision on further actions. 3288 10.4.8. 407 Proxy Authentication Required 3290 This code is similar to 401 (Unauthorized), but indicates that the 3291 client must first authenticate itself with the proxy. The proxy MUST 3292 return a Proxy-Authenticate header field (Section 14.33) containing a 3293 challenge applicable to the proxy for the requested resource. The 3294 client MAY repeat the request with a suitable Proxy-Authorization 3295 header field (Section 14.34). HTTP access authentication is 3296 explained in "HTTP Authentication: Basic and Digest Access 3297 Authentication" [RFC2617]. 3299 10.4.9. 408 Request Timeout 3301 The client did not produce a request within the time that the server 3302 was prepared to wait. The client MAY repeat the request without 3303 modifications at any later time. 3305 10.4.10. 409 Conflict 3307 The request could not be completed due to a conflict with the current 3308 state of the resource. This code is only allowed in situations where 3309 it is expected that the user might be able to resolve the conflict 3310 and resubmit the request. The response body SHOULD include enough 3311 information for the user to recognize the source of the conflict. 3312 Ideally, the response entity would include enough information for the 3313 user or user agent to fix the problem; however, that might not be 3314 possible and is not required. 3316 Conflicts are most likely to occur in response to a PUT request. For 3317 example, if versioning were being used and the entity being PUT 3318 included changes to a resource which conflict with those made by an 3319 earlier (third-party) request, the server might use the 409 response 3320 to indicate that it can't complete the request. In this case, the 3321 response entity would likely contain a list of the differences 3322 between the two versions in a format defined by the response Content- 3323 Type. 3325 10.4.11. 410 Gone 3327 The requested resource is no longer available at the server and no 3328 forwarding address is known. This condition is expected to be 3329 considered permanent. Clients with link editing capabilities SHOULD 3330 delete references to the Request-URI after user approval. If the 3331 server does not know, or has no facility to determine, whether or not 3332 the condition is permanent, the status code 404 (Not Found) SHOULD be 3333 used instead. This response is cacheable unless indicated otherwise. 3335 The 410 response is primarily intended to assist the task of web 3336 maintenance by notifying the recipient that the resource is 3337 intentionally unavailable and that the server owners desire that 3338 remote links to that resource be removed. Such an event is common 3339 for limited-time, promotional services and for resources belonging to 3340 individuals no longer working at the server's site. It is not 3341 necessary to mark all permanently unavailable resources as "gone" or 3342 to keep the mark for any length of time -- that is left to the 3343 discretion of the server owner. 3345 10.4.12. 411 Length Required 3347 The server refuses to accept the request without a defined Content- 3348 Length. The client MAY repeat the request if it adds a valid 3349 Content-Length header field containing the length of the message-body 3350 in the request message. 3352 10.4.13. 412 Precondition Failed 3354 The precondition given in one or more of the request-header fields 3355 evaluated to false when it was tested on the server. This response 3356 code allows the client to place preconditions on the current resource 3357 metainformation (header field data) and thus prevent the requested 3358 method from being applied to a resource other than the one intended. 3360 10.4.14. 413 Request Entity Too Large 3362 The server is refusing to process a request because the request 3363 entity is larger than the server is willing or able to process. The 3364 server MAY close the connection to prevent the client from continuing 3365 the request. 3367 If the condition is temporary, the server SHOULD include a Retry- 3368 After header field to indicate that it is temporary and after what 3369 time the client MAY try again. 3371 10.4.15. 414 Request-URI Too Long 3373 The server is refusing to service the request because the Request-URI 3374 is longer than the server is willing to interpret. This rare 3375 condition is only likely to occur when a client has improperly 3376 converted a POST request to a GET request with long query 3377 information, when the client has descended into a URI "black hole" of 3378 redirection (e.g., a redirected URI prefix that points to a suffix of 3379 itself), or when the server is under attack by a client attempting to 3380 exploit security holes present in some servers using fixed-length 3381 buffers for reading or manipulating the Request-URI. 3383 10.4.16. 415 Unsupported Media Type 3385 The server is refusing to service the request because the entity of 3386 the request is in a format not supported by the requested resource 3387 for the requested method. 3389 10.4.17. 416 Requested Range Not Satisfiable 3391 A server SHOULD return a response with this status code if a request 3392 included a Range request-header field (Section 14.35), and none of 3393 the range-specifier values in this field overlap the current extent 3394 of the selected resource, and the request did not include an If-Range 3395 request-header field. (For byte-ranges, this means that the first- 3396 byte-pos of all of the byte-range-spec values were greater than the 3397 current length of the selected resource.) 3399 When this status code is returned for a byte-range request, the 3400 response SHOULD include a Content-Range entity-header field 3401 specifying the current length of the selected resource (see 3402 Section 14.16). This response MUST NOT use the multipart/byteranges 3403 content-type. 3405 10.4.18. 417 Expectation Failed 3407 The expectation given in an Expect request-header field (see 3408 Section 14.20) could not be met by this server, or, if the server is 3409 a proxy, the server has unambiguous evidence that the request could 3410 not be met by the next-hop server. 3412 10.5. Server Error 5xx 3414 Response status codes beginning with the digit "5" indicate cases in 3415 which the server is aware that it has erred or is incapable of 3416 performing the request. Except when responding to a HEAD request, 3417 the server SHOULD include an entity containing an explanation of the 3418 error situation, and whether it is a temporary or permanent 3419 condition. User agents SHOULD display any included entity to the 3420 user. These response codes are applicable to any request method. 3422 10.5.1. 500 Internal Server Error 3424 The server encountered an unexpected condition which prevented it 3425 from fulfilling the request. 3427 10.5.2. 501 Not Implemented 3429 The server does not support the functionality required to fulfill the 3430 request. This is the appropriate response when the server does not 3431 recognize the request method and is not capable of supporting it for 3432 any resource. 3434 10.5.3. 502 Bad Gateway 3436 The server, while acting as a gateway or proxy, received an invalid 3437 response from the upstream server it accessed in attempting to 3438 fulfill the request. 3440 10.5.4. 503 Service Unavailable 3442 The server is currently unable to handle the request due to a 3443 temporary overloading or maintenance of the server. The implication 3444 is that this is a temporary condition which will be alleviated after 3445 some delay. If known, the length of the delay MAY be indicated in a 3446 Retry-After header. If no Retry-After is given, the client SHOULD 3447 handle the response as it would for a 500 response. 3449 Note: The existence of the 503 status code does not imply that a 3450 server must use it when becoming overloaded. Some servers may 3451 wish to simply refuse the connection. 3453 10.5.5. 504 Gateway Timeout 3455 The server, while acting as a gateway or proxy, did not receive a 3456 timely response from the upstream server specified by the URI (e.g. 3457 HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed 3458 to access in attempting to complete the request. 3460 Note: Note to implementors: some deployed proxies are known to 3461 return 400 or 500 when DNS lookups time out. 3463 10.5.6. 505 HTTP Version Not Supported 3465 The server does not support, or refuses to support, the HTTP protocol 3466 version that was used in the request message. The server is 3467 indicating that it is unable or unwilling to complete the request 3468 using the same major version as the client, as described in 3469 Section 3.1, other than with this error message. The response SHOULD 3470 contain an entity describing why that version is not supported and 3471 what other protocols are supported by that server. 3473 11. Access Authentication 3475 HTTP provides several OPTIONAL challenge-response authentication 3476 mechanisms which can be used by a server to challenge a client 3477 request and by a client to provide authentication information. The 3478 general framework for access authentication, and the specification of 3479 "basic" and "digest" authentication, are specified in "HTTP 3480 Authentication: Basic and Digest Access Authentication" [RFC2617]. 3481 This specification adopts the definitions of "challenge" and 3482 "credentials" from that specification. 3484 12. Content Negotiation 3486 Most HTTP responses include an entity which contains information for 3487 interpretation by a human user. Naturally, it is desirable to supply 3488 the user with the "best available" entity corresponding to the 3489 request. Unfortunately for servers and caches, not all users have 3490 the same preferences for what is "best," and not all user agents are 3491 equally capable of rendering all entity types. For that reason, HTTP 3492 has provisions for several mechanisms for "content negotiation" -- 3493 the process of selecting the best representation for a given response 3494 when there are multiple representations available. 3496 Note: This is not called "format negotiation" because the 3497 alternate representations may be of the same media type, but use 3498 different capabilities of that type, be in different languages, 3499 etc. 3501 Any response containing an entity-body MAY be subject to negotiation, 3502 including error responses. 3504 There are two kinds of content negotiation which are possible in 3505 HTTP: server-driven and agent-driven negotiation. These two kinds of 3506 negotiation are orthogonal and thus may be used separately or in 3507 combination. One method of combination, referred to as transparent 3508 negotiation, occurs when a cache uses the agent-driven negotiation 3509 information provided by the origin server in order to provide server- 3510 driven negotiation for subsequent requests. 3512 12.1. Server-driven Negotiation 3514 If the selection of the best representation for a response is made by 3515 an algorithm located at the server, it is called server-driven 3516 negotiation. Selection is based on the available representations of 3517 the response (the dimensions over which it can vary; e.g. language, 3518 content-coding, etc.) and the contents of particular header fields in 3519 the request message or on other information pertaining to the request 3520 (such as the network address of the client). 3522 Server-driven negotiation is advantageous when the algorithm for 3523 selecting from among the available representations is difficult to 3524 describe to the user agent, or when the server desires to send its 3525 "best guess" to the client along with the first response (hoping to 3526 avoid the round-trip delay of a subsequent request if the "best 3527 guess" is good enough for the user). In order to improve the 3528 server's guess, the user agent MAY include request header fields 3529 (Accept, Accept-Language, Accept-Encoding, etc.) which describe its 3530 preferences for such a response. 3532 Server-driven negotiation has disadvantages: 3534 1. It is impossible for the server to accurately determine what 3535 might be "best" for any given user, since that would require 3536 complete knowledge of both the capabilities of the user agent and 3537 the intended use for the response (e.g., does the user want to 3538 view it on screen or print it on paper?). 3540 2. Having the user agent describe its capabilities in every request 3541 can be both very inefficient (given that only a small percentage 3542 of responses have multiple representations) and a potential 3543 violation of the user's privacy. 3545 3. It complicates the implementation of an origin server and the 3546 algorithms for generating responses to a request. 3548 4. It may limit a public cache's ability to use the same response 3549 for multiple user's requests. 3551 HTTP/1.1 includes the following request-header fields for enabling 3552 server-driven negotiation through description of user agent 3553 capabilities and user preferences: Accept (Section 14.1), Accept- 3554 Charset (Section 14.2), Accept-Encoding (Section 14.3), Accept- 3555 Language (Section 14.4), and User-Agent (Section 14.43). However, an 3556 origin server is not limited to these dimensions and MAY vary the 3557 response based on any aspect of the request, including information 3558 outside the request-header fields or within extension header fields 3559 not defined by this specification. 3561 The Vary header field can be used to express the parameters the 3562 server uses to select a representation that is subject to server- 3563 driven negotiation. See Section 13.6 for use of the Vary header 3564 field by caches and Section 14.44 for use of the Vary header field by 3565 servers. 3567 12.2. Agent-driven Negotiation 3569 With agent-driven negotiation, selection of the best representation 3570 for a response is performed by the user agent after receiving an 3571 initial response from the origin server. Selection is based on a 3572 list of the available representations of the response included within 3573 the header fields or entity-body of the initial response, with each 3574 representation identified by its own URI. Selection from among the 3575 representations may be performed automatically (if the user agent is 3576 capable of doing so) or manually by the user selecting from a 3577 generated (possibly hypertext) menu. 3579 Agent-driven negotiation is advantageous when the response would vary 3580 over commonly-used dimensions (such as type, language, or encoding), 3581 when the origin server is unable to determine a user agent's 3582 capabilities from examining the request, and generally when public 3583 caches are used to distribute server load and reduce network usage. 3585 Agent-driven negotiation suffers from the disadvantage of needing a 3586 second request to obtain the best alternate representation. This 3587 second request is only efficient when caching is used. In addition, 3588 this specification does not define any mechanism for supporting 3589 automatic selection, though it also does not prevent any such 3590 mechanism from being developed as an extension and used within 3591 HTTP/1.1. 3593 HTTP/1.1 defines the 300 (Multiple Choices) and 406 (Not Acceptable) 3594 status codes for enabling agent-driven negotiation when the server is 3595 unwilling or unable to provide a varying response using server-driven 3596 negotiation. 3598 12.3. Transparent Negotiation 3600 Transparent negotiation is a combination of both server-driven and 3601 agent-driven negotiation. When a cache is supplied with a form of 3602 the list of available representations of the response (as in agent- 3603 driven negotiation) and the dimensions of variance are completely 3604 understood by the cache, then the cache becomes capable of performing 3605 server-driven negotiation on behalf of the origin server for 3606 subsequent requests on that resource. 3608 Transparent negotiation has the advantage of distributing the 3609 negotiation work that would otherwise be required of the origin 3610 server and also removing the second request delay of agent-driven 3611 negotiation when the cache is able to correctly guess the right 3612 response. 3614 This specification does not define any mechanism for transparent 3615 negotiation, though it also does not prevent any such mechanism from 3616 being developed as an extension that could be used within HTTP/1.1. 3618 13. Caching in HTTP 3620 HTTP is typically used for distributed information systems, where 3621 performance can be improved by the use of response caches. The 3622 HTTP/1.1 protocol includes a number of elements intended to make 3623 caching work as well as possible. Because these elements are 3624 inextricable from other aspects of the protocol, and because they 3625 interact with each other, it is useful to describe the basic caching 3626 design of HTTP separately from the detailed descriptions of methods, 3627 headers, response codes, etc. 3629 Caching would be useless if it did not significantly improve 3630 performance. The goal of caching in HTTP/1.1 is to eliminate the 3631 need to send requests in many cases, and to eliminate the need to 3632 send full responses in many other cases. The former reduces the 3633 number of network round-trips required for many operations; we use an 3634 "expiration" mechanism for this purpose (see Section 13.2). The 3635 latter reduces network bandwidth requirements; we use a "validation" 3636 mechanism for this purpose (see Section 13.3). 3638 Requirements for performance, availability, and disconnected 3639 operation require us to be able to relax the goal of semantic 3640 transparency. The HTTP/1.1 protocol allows origin servers, caches, 3641 and clients to explicitly reduce transparency when necessary. 3642 However, because non-transparent operation may confuse non-expert 3643 users, and might be incompatible with certain server applications 3644 (such as those for ordering merchandise), the protocol requires that 3645 transparency be relaxed 3647 o only by an explicit protocol-level request when relaxed by client 3648 or origin server 3650 o only with an explicit warning to the end user when relaxed by 3651 cache or client 3653 Therefore, the HTTP/1.1 protocol provides these important elements: 3655 1. Protocol features that provide full semantic transparency when 3656 this is required by all parties. 3658 2. Protocol features that allow an origin server or user agent to 3659 explicitly request and control non-transparent operation. 3661 3. Protocol features that allow a cache to attach warnings to 3662 responses that do not preserve the requested approximation of 3663 semantic transparency. 3665 A basic principle is that it must be possible for the clients to 3666 detect any potential relaxation of semantic transparency. 3668 Note: The server, cache, or client implementor might be faced with 3669 design decisions not explicitly discussed in this specification. 3670 If a decision might affect semantic transparency, the implementor 3671 ought to err on the side of maintaining transparency unless a 3672 careful and complete analysis shows significant benefits in 3673 breaking transparency. 3675 13.1. 3677 13.1.1. Cache Correctness 3679 A correct cache MUST respond to a request with the most up-to-date 3680 response held by the cache that is appropriate to the request (see 3681 Sections 13.2.5, 13.2.6, and 13.12) which meets one of the following 3682 conditions: 3684 1. It has been checked for equivalence with what the origin server 3685 would have returned by revalidating the response with the origin 3686 server (Section 13.3); 3688 2. It is "fresh enough" (see Section 13.2). In the default case, 3689 this means it meets the least restrictive freshness requirement 3690 of the client, origin server, and cache (see Section 14.9); if 3691 the origin server so specifies, it is the freshness requirement 3692 of the origin server alone. If a stored response is not "fresh 3693 enough" by the most restrictive freshness requirement of both the 3694 client and the origin server, in carefully considered 3695 circumstances the cache MAY still return the response with the 3696 appropriate Warning header (see Section 13.1.5 and 14.46), unless 3697 such a response is prohibited (e.g., by a "no-store" cache- 3698 directive, or by a "no-cache" cache-request-directive; see 3699 Section 14.9). 3701 3. It is an appropriate 304 (Not Modified), 305 (Proxy Redirect), or 3702 error (4xx or 5xx) response message. 3704 If the cache can not communicate with the origin server, then a 3705 correct cache SHOULD respond as above if the response can be 3706 correctly served from the cache; if not it MUST return an error or 3707 warning indicating that there was a communication failure. 3709 If a cache receives a response (either an entire response, or a 304 3710 (Not Modified) response) that it would normally forward to the 3711 requesting client, and the received response is no longer fresh, the 3712 cache SHOULD forward it to the requesting client without adding a new 3713 Warning (but without removing any existing Warning headers). A cache 3714 SHOULD NOT attempt to revalidate a response simply because that 3715 response became stale in transit; this might lead to an infinite 3716 loop. A user agent that receives a stale response without a Warning 3717 MAY display a warning indication to the user. 3719 13.1.2. Warnings 3721 Whenever a cache returns a response that is neither first-hand nor 3722 "fresh enough" (in the sense of condition 2 in Section 13.1.1), it 3723 MUST attach a warning to that effect, using a Warning general-header. 3724 The Warning header and the currently defined warnings are described 3725 in Section 14.46. The warning allows clients to take appropriate 3726 action. 3728 Warnings MAY be used for other purposes, both cache-related and 3729 otherwise. The use of a warning, rather than an error status code, 3730 distinguish these responses from true failures. 3732 Warnings are assigned three digit warn-codes. The first digit 3733 indicates whether the Warning MUST or MUST NOT be deleted from a 3734 stored cache entry after a successful revalidation: 3736 1xx Warnings that describe the freshness or revalidation status of 3737 the response, and so MUST be deleted after a successful 3738 revalidation. 1XX warn-codes MAY be generated by a cache only when 3739 validating a cached entry. It MUST NOT be generated by clients. 3741 2xx Warnings that describe some aspect of the entity body or entity 3742 headers that is not rectified by a revalidation (for example, a 3743 lossy compression of the entity bodies) and which MUST NOT be 3744 deleted after a successful revalidation. 3746 See Section 14.46 for the definitions of the codes themselves. 3748 HTTP/1.0 caches will cache all Warnings in responses, without 3749 deleting the ones in the first category. Warnings in responses that 3750 are passed to HTTP/1.0 caches carry an extra warning-date field, 3751 which prevents a future HTTP/1.1 recipient from believing an 3752 erroneously cached Warning. 3754 Warnings also carry a warning text. The text MAY be in any 3755 appropriate natural language (perhaps based on the client's Accept 3756 headers), and include an OPTIONAL indication of what character set is 3757 used. 3759 Multiple warnings MAY be attached to a response (either by the origin 3760 server or by a cache), including multiple warnings with the same code 3761 number. For example, a server might provide the same warning with 3762 texts in both English and Basque. 3764 When multiple warnings are attached to a response, it might not be 3765 practical or reasonable to display all of them to the user. This 3766 version of HTTP does not specify strict priority rules for deciding 3767 which warnings to display and in what order, but does suggest some 3768 heuristics. 3770 13.1.3. Cache-control Mechanisms 3772 The basic cache mechanisms in HTTP/1.1 (server-specified expiration 3773 times and validators) are implicit directives to caches. In some 3774 cases, a server or client might need to provide explicit directives 3775 to the HTTP caches. We use the Cache-Control header for this 3776 purpose. 3778 The Cache-Control header allows a client or server to transmit a 3779 variety of directives in either requests or responses. These 3780 directives typically override the default caching algorithms. As a 3781 general rule, if there is any apparent conflict between header 3782 values, the most restrictive interpretation is applied (that is, the 3783 one that is most likely to preserve semantic transparency). However, 3784 in some cases, cache-control directives are explicitly specified as 3785 weakening the approximation of semantic transparency (for example, 3786 "max-stale" or "public"). 3788 The cache-control directives are described in detail in Section 14.9. 3790 13.1.4. Explicit User Agent Warnings 3792 Many user agents make it possible for users to override the basic 3793 caching mechanisms. For example, the user agent might allow the user 3794 to specify that cached entities (even explicitly stale ones) are 3795 never validated. Or the user agent might habitually add "Cache- 3796 Control: max-stale=3600" to every request. The user agent SHOULD NOT 3797 default to either non-transparent behavior, or behavior that results 3798 in abnormally ineffective caching, but MAY be explicitly configured 3799 to do so by an explicit action of the user. 3801 If the user has overridden the basic caching mechanisms, the user 3802 agent SHOULD explicitly indicate to the user whenever this results in 3803 the display of information that might not meet the server's 3804 transparency requirements (in particular, if the displayed entity is 3805 known to be stale). Since the protocol normally allows the user 3806 agent to determine if responses are stale or not, this indication 3807 need only be displayed when this actually happens. The indication 3808 need not be a dialog box; it could be an icon (for example, a picture 3809 of a rotting fish) or some other indicator. 3811 If the user has overridden the caching mechanisms in a way that would 3812 abnormally reduce the effectiveness of caches, the user agent SHOULD 3813 continually indicate this state to the user (for example, by a 3814 display of a picture of currency in flames) so that the user does not 3815 inadvertently consume excess resources or suffer from excessive 3816 latency. 3818 13.1.5. Exceptions to the Rules and Warnings 3820 In some cases, the operator of a cache MAY choose to configure it to 3821 return stale responses even when not requested by clients. This 3822 decision ought not be made lightly, but may be necessary for reasons 3823 of availability or performance, especially when the cache is poorly 3824 connected to the origin server. Whenever a cache returns a stale 3825 response, it MUST mark it as such (using a Warning header) enabling 3826 the client software to alert the user that there might be a potential 3827 problem. 3829 It also allows the user agent to take steps to obtain a first-hand or 3830 fresh response. For this reason, a cache SHOULD NOT return a stale 3831 response if the client explicitly requests a first-hand or fresh one, 3832 unless it is impossible to comply for technical or policy reasons. 3834 13.1.6. Client-controlled Behavior 3836 While the origin server (and to a lesser extent, intermediate caches, 3837 by their contribution to the age of a response) are the primary 3838 source of expiration information, in some cases the client might need 3839 to control a cache's decision about whether to return a cached 3840 response without validating it. Clients do this using several 3841 directives of the Cache-Control header. 3843 A client's request MAY specify the maximum age it is willing to 3844 accept of an unvalidated response; specifying a value of zero forces 3845 the cache(s) to revalidate all responses. A client MAY also specify 3846 the minimum time remaining before a response expires. Both of these 3847 options increase constraints on the behavior of caches, and so cannot 3848 further relax the cache's approximation of semantic transparency. 3850 A client MAY also specify that it will accept stale responses, up to 3851 some maximum amount of staleness. This loosens the constraints on 3852 the caches, and so might violate the origin server's specified 3853 constraints on semantic transparency, but might be necessary to 3854 support disconnected operation, or high availability in the face of 3855 poor connectivity. 3857 13.2. Expiration Model 3859 13.2.1. Server-Specified Expiration 3861 HTTP caching works best when caches can entirely avoid making 3862 requests to the origin server. The primary mechanism for avoiding 3863 requests is for an origin server to provide an explicit expiration 3864 time in the future, indicating that a response MAY be used to satisfy 3865 subsequent requests. In other words, a cache can return a fresh 3866 response without first contacting the server. 3868 Our expectation is that servers will assign future explicit 3869 expiration times to responses in the belief that the entity is not 3870 likely to change, in a semantically significant way, before the 3871 expiration time is reached. This normally preserves semantic 3872 transparency, as long as the server's expiration times are carefully 3873 chosen. 3875 The expiration mechanism applies only to responses taken from a cache 3876 and not to first-hand responses forwarded immediately to the 3877 requesting client. 3879 If an origin server wishes to force a semantically transparent cache 3880 to validate every request, it MAY assign an explicit expiration time 3881 in the past. This means that the response is always stale, and so 3882 the cache SHOULD validate it before using it for subsequent requests. 3883 See Section 14.9.4 for a more restrictive way to force revalidation. 3885 If an origin server wishes to force any HTTP/1.1 cache, no matter how 3886 it is configured, to validate every request, it SHOULD use the "must- 3887 revalidate" cache-control directive (see Section 14.9). 3889 Servers specify explicit expiration times using either the Expires 3890 header, or the max-age directive of the Cache-Control header. 3892 An expiration time cannot be used to force a user agent to refresh 3893 its display or reload a resource; its semantics apply only to caching 3894 mechanisms, and such mechanisms need only check a resource's 3895 expiration status when a new request for that resource is initiated. 3896 See Section 13.13 for an explanation of the difference between caches 3897 and history mechanisms. 3899 13.2.2. Heuristic Expiration 3901 Since origin servers do not always provide explicit expiration times, 3902 HTTP caches typically assign heuristic expiration times, employing 3903 algorithms that use other header values (such as the Last-Modified 3904 time) to estimate a plausible expiration time. The HTTP/1.1 3905 specification does not provide specific algorithms, but does impose 3906 worst-case constraints on their results. Since heuristic expiration 3907 times might compromise semantic transparency, they ought to used 3908 cautiously, and we encourage origin servers to provide explicit 3909 expiration times as much as possible. 3911 13.2.3. Age Calculations 3913 In order to know if a cached entry is fresh, a cache needs to know if 3914 its age exceeds its freshness lifetime. We discuss how to calculate 3915 the latter in Section 13.2.4; this section describes how to calculate 3916 the age of a response or cache entry. 3918 In this discussion, we use the term "now" to mean "the current value 3919 of the clock at the host performing the calculation." Hosts that use 3920 HTTP, but especially hosts running origin servers and caches, SHOULD 3921 use NTP [RFC1305] or some similar protocol to synchronize their 3922 clocks to a globally accurate time standard. 3924 HTTP/1.1 requires origin servers to send a Date header, if possible, 3925 with every response, giving the time at which the response was 3926 generated (see Section 14.18). We use the term "date_value" to 3927 denote the value of the Date header, in a form appropriate for 3928 arithmetic operations. 3930 HTTP/1.1 uses the Age response-header to convey the estimated age of 3931 the response message when obtained from a cache. The Age field value 3932 is the cache's estimate of the amount of time since the response was 3933 generated or revalidated by the origin server. 3935 In essence, the Age value is the sum of the time that the response 3936 has been resident in each of the caches along the path from the 3937 origin server, plus the amount of time it has been in transit along 3938 network paths. 3940 We use the term "age_value" to denote the value of the Age header, in 3941 a form appropriate for arithmetic operations. 3943 A response's age can be calculated in two entirely independent ways: 3945 1. now minus date_value, if the local clock is reasonably well 3946 synchronized to the origin server's clock. If the result is 3947 negative, the result is replaced by zero. 3949 2. age_value, if all of the caches along the response path implement 3950 HTTP/1.1. 3952 Given that we have two independent ways to compute the age of a 3953 response when it is received, we can combine these as 3955 corrected_received_age = max(now - date_value, age_value) 3957 and as long as we have either nearly synchronized clocks or all- 3958 HTTP/1.1 paths, one gets a reliable (conservative) result. 3960 Because of network-imposed delays, some significant interval might 3961 pass between the time that a server generates a response and the time 3962 it is received at the next outbound cache or client. If uncorrected, 3963 this delay could result in improperly low ages. 3965 Because the request that resulted in the returned Age value must have 3966 been initiated prior to that Age value's generation, we can correct 3967 for delays imposed by the network by recording the time at which the 3968 request was initiated. Then, when an Age value is received, it MUST 3969 be interpreted relative to the time the request was initiated, not 3970 the time that the response was received. This algorithm results in 3971 conservative behavior no matter how much delay is experienced. So, 3972 we compute: 3974 corrected_initial_age = corrected_received_age 3975 + (now - request_time) 3977 where "request_time" is the time (according to the local clock) when 3978 the request that elicited this response was sent. 3980 Summary of age calculation algorithm, when a cache receives a 3981 response: 3983 /* 3984 * age_value 3985 * is the value of Age: header received by the cache with 3986 * this response. 3987 * date_value 3988 * is the value of the origin server's Date: header 3989 * request_time 3990 * is the (local) time when the cache made the request 3991 * that resulted in this cached response 3992 * response_time 3993 * is the (local) time when the cache received the 3994 * response 3995 * now 3996 * is the current (local) time 3997 */ 3999 apparent_age = max(0, response_time - date_value); 4000 corrected_received_age = max(apparent_age, age_value); 4001 response_delay = response_time - request_time; 4002 corrected_initial_age = corrected_received_age + response_delay; 4003 resident_time = now - response_time; 4004 current_age = corrected_initial_age + resident_time; 4006 The current_age of a cache entry is calculated by adding the amount 4007 of time (in seconds) since the cache entry was last validated by the 4008 origin server to the corrected_initial_age. When a response is 4009 generated from a cache entry, the cache MUST include a single Age 4010 header field in the response with a value equal to the cache entry's 4011 current_age. 4013 The presence of an Age header field in a response implies that a 4014 response is not first-hand. However, the converse is not true, since 4015 the lack of an Age header field in a response does not imply that the 4016 response is first-hand unless all caches along the request path are 4017 compliant with HTTP/1.1 (i.e., older HTTP caches did not implement 4018 the Age header field). 4020 13.2.4. Expiration Calculations 4022 In order to decide whether a response is fresh or stale, we need to 4023 compare its freshness lifetime to its age. The age is calculated as 4024 described in Section 13.2.3; this section describes how to calculate 4025 the freshness lifetime, and to determine if a response has expired. 4026 In the discussion below, the values can be represented in any form 4027 appropriate for arithmetic operations. 4029 We use the term "expires_value" to denote the value of the Expires 4030 header. We use the term "max_age_value" to denote an appropriate 4031 value of the number of seconds carried by the "max-age" directive of 4032 the Cache-Control header in a response (see Section 14.9.3). 4034 The max-age directive takes priority over Expires, so if max-age is 4035 present in a response, the calculation is simply: 4037 freshness_lifetime = max_age_value 4039 Otherwise, if Expires is present in the response, the calculation is: 4041 freshness_lifetime = expires_value - date_value 4043 Note that neither of these calculations is vulnerable to clock skew, 4044 since all of the information comes from the origin server. 4046 If none of Expires, Cache-Control: max-age, or Cache-Control: 4047 s-maxage (see Section 14.9.3) appears in the response, and the 4048 response does not include other restrictions on caching, the cache 4049 MAY compute a freshness lifetime using a heuristic. The cache MUST 4050 attach Warning 113 to any response whose age is more than 24 hours if 4051 such warning has not already been added. 4053 Also, if the response does have a Last-Modified time, the heuristic 4054 expiration value SHOULD be no more than some fraction of the interval 4055 since that time. A typical setting of this fraction might be 10%. 4057 The calculation to determine if a response has expired is quite 4058 simple: 4060 response_is_fresh = (freshness_lifetime > current_age) 4062 13.2.5. Disambiguating Expiration Values 4064 Because expiration values are assigned optimistically, it is possible 4065 for two caches to contain fresh values for the same resource that are 4066 different. 4068 If a client performing a retrieval receives a non-first-hand response 4069 for a request that was already fresh in its own cache, and the Date 4070 header in its existing cache entry is newer than the Date on the new 4071 response, then the client MAY ignore the response. If so, it MAY 4072 retry the request with a "Cache-Control: max-age=0" directive (see 4073 Section 14.9), to force a check with the origin server. 4075 If a cache has two fresh responses for the same representation with 4076 different validators, it MUST use the one with the more recent Date 4077 header. This situation might arise because the cache is pooling 4078 responses from other caches, or because a client has asked for a 4079 reload or a revalidation of an apparently fresh cache entry. 4081 13.2.6. Disambiguating Multiple Responses 4083 Because a client might be receiving responses via multiple paths, so 4084 that some responses flow through one set of caches and other 4085 responses flow through a different set of caches, a client might 4086 receive responses in an order different from that in which the origin 4087 server sent them. We would like the client to use the most recently 4088 generated response, even if older responses are still apparently 4089 fresh. 4091 Neither the entity tag nor the expiration value can impose an 4092 ordering on responses, since it is possible that a later response 4093 intentionally carries an earlier expiration time. The Date values 4094 are ordered to a granularity of one second. 4096 When a client tries to revalidate a cache entry, and the response it 4097 receives contains a Date header that appears to be older than the one 4098 for the existing entry, then the client SHOULD repeat the request 4099 unconditionally, and include 4101 Cache-Control: max-age=0 4103 to force any intermediate caches to validate their copies directly 4104 with the origin server, or 4106 Cache-Control: no-cache 4108 to force any intermediate caches to obtain a new copy from the origin 4109 server. 4111 If the Date values are equal, then the client MAY use either response 4112 (or MAY, if it is being extremely prudent, request a new response). 4113 Servers MUST NOT depend on clients being able to choose 4114 deterministically between responses generated during the same second, 4115 if their expiration times overlap. 4117 13.3. Validation Model 4119 When a cache has a stale entry that it would like to use as a 4120 response to a client's request, it first has to check with the origin 4121 server (or possibly an intermediate cache with a fresh response) to 4122 see if its cached entry is still usable. We call this "validating" 4123 the cache entry. Since we do not want to have to pay the overhead of 4124 retransmitting the full response if the cached entry is good, and we 4125 do not want to pay the overhead of an extra round trip if the cached 4126 entry is invalid, the HTTP/1.1 protocol supports the use of 4127 conditional methods. 4129 The key protocol features for supporting conditional methods are 4130 those concerned with "cache validators." When an origin server 4131 generates a full response, it attaches some sort of validator to it, 4132 which is kept with the cache entry. When a client (user agent or 4133 proxy cache) makes a conditional request for a resource for which it 4134 has a cache entry, it includes the associated validator in the 4135 request. 4137 The server then checks that validator against the current validator 4138 for the entity, and, if they match (see Section 13.3.3), it responds 4139 with a special status code (usually, 304 (Not Modified)) and no 4140 entity-body. Otherwise, it returns a full response (including 4141 entity-body). Thus, we avoid transmitting the full response if the 4142 validator matches, and we avoid an extra round trip if it does not 4143 match. 4145 In HTTP/1.1, a conditional request looks exactly the same as a normal 4146 request for the same resource, except that it carries a special 4147 header (which includes the validator) that implicitly turns the 4148 method (usually, GET) into a conditional. 4150 The protocol includes both positive and negative senses of cache- 4151 validating conditions. That is, it is possible to request either 4152 that a method be performed if and only if a validator matches or if 4153 and only if no validators match. 4155 Note: a response that lacks a validator may still be cached, and 4156 served from cache until it expires, unless this is explicitly 4157 prohibited by a cache-control directive. However, a cache cannot 4158 do a conditional retrieval if it does not have a validator for the 4159 entity, which means it will not be refreshable after it expires. 4161 13.3.1. Last-Modified Dates 4163 The Last-Modified entity-header field value is often used as a cache 4164 validator. In simple terms, a cache entry is considered to be valid 4165 if the entity has not been modified since the Last-Modified value. 4167 13.3.2. Entity Tag Cache Validators 4169 The ETag response-header field value, an entity tag, provides for an 4170 "opaque" cache validator. This might allow more reliable validation 4171 in situations where it is inconvenient to store modification dates, 4172 where the one-second resolution of HTTP date values is not 4173 sufficient, or where the origin server wishes to avoid certain 4174 paradoxes that might arise from the use of modification dates. 4176 Entity Tags are described in Section 3.11. The headers used with 4177 entity tags are described in Sections 14.19, 14.24, 14.26 and 14.44. 4179 13.3.3. Weak and Strong Validators 4181 Since both origin servers and caches will compare two validators to 4182 decide if they represent the same or different entities, one normally 4183 would expect that if the entity (the entity-body or any entity- 4184 headers) changes in any way, then the associated validator would 4185 change as well. If this is true, then we call this validator a 4186 "strong validator." 4188 However, there might be cases when a server prefers to change the 4189 validator only on semantically significant changes, and not when 4190 insignificant aspects of the entity change. A validator that does 4191 not always change when the resource changes is a "weak validator." 4193 Entity tags are normally "strong validators," but the protocol 4194 provides a mechanism to tag an entity tag as "weak." One can think 4195 of a strong validator as one that changes whenever the bits of an 4196 entity changes, while a weak value changes whenever the meaning of an 4197 entity changes. Alternatively, one can think of a strong validator 4198 as part of an identifier for a specific entity, while a weak 4199 validator is part of an identifier for a set of semantically 4200 equivalent entities. 4202 Note: One example of a strong validator is an integer that is 4203 incremented in stable storage every time an entity is changed. 4205 An entity's modification time, if represented with one-second 4206 resolution, could be a weak validator, since it is possible that 4207 the resource might be modified twice during a single second. 4209 Support for weak validators is optional. However, weak validators 4210 allow for more efficient caching of equivalent objects; for 4211 example, a hit counter on a site is probably good enough if it is 4212 updated every few days or weeks, and any value during that period 4213 is likely "good enough" to be equivalent. 4215 A "use" of a validator is either when a client generates a request 4216 and includes the validator in a validating header field, or when a 4217 server compares two validators. 4219 Strong validators are usable in any context. Weak validators are 4220 only usable in contexts that do not depend on exact equality of an 4221 entity. For example, either kind is usable for a conditional GET of 4222 a full entity. However, only a strong validator is usable for a sub- 4223 range retrieval, since otherwise the client might end up with an 4224 internally inconsistent entity. 4226 Clients MAY issue simple (non-subrange) GET requests with either weak 4227 validators or strong validators. Clients MUST NOT use weak 4228 validators in other forms of request. 4230 The only function that the HTTP/1.1 protocol defines on validators is 4231 comparison. There are two validator comparison functions, depending 4232 on whether the comparison context allows the use of weak validators 4233 or not: 4235 o The strong comparison function: in order to be considered equal, 4236 both validators MUST be identical in every way, and both MUST NOT 4237 be weak. 4239 o The weak comparison function: in order to be considered equal, 4240 both validators MUST be identical in every way, but either or both 4241 of them MAY be tagged as "weak" without affecting the result. 4243 An entity tag is strong unless it is explicitly tagged as weak. 4244 Section 3.11 gives the syntax for entity tags. 4246 A Last-Modified time, when used as a validator in a request, is 4247 implicitly weak unless it is possible to deduce that it is strong, 4248 using the following rules: 4250 o The validator is being compared by an origin server to the actual 4251 current validator for the entity and, 4253 o That origin server reliably knows that the associated entity did 4254 not change twice during the second covered by the presented 4255 validator. 4257 or 4259 o The validator is about to be used by a client in an If-Modified- 4260 Since or If-Unmodified-Since header, because the client has a 4261 cache entry for the associated entity, and 4263 o That cache entry includes a Date value, which gives the time when 4264 the origin server sent the original response, and 4266 o The presented Last-Modified time is at least 60 seconds before the 4267 Date value. 4269 or 4270 o The validator is being compared by an intermediate cache to the 4271 validator stored in its cache entry for the entity, and 4273 o That cache entry includes a Date value, which gives the time when 4274 the origin server sent the original response, and 4276 o The presented Last-Modified time is at least 60 seconds before the 4277 Date value. 4279 This method relies on the fact that if two different responses were 4280 sent by the origin server during the same second, but both had the 4281 same Last-Modified time, then at least one of those responses would 4282 have a Date value equal to its Last-Modified time. The arbitrary 60- 4283 second limit guards against the possibility that the Date and Last- 4284 Modified values are generated from different clocks, or at somewhat 4285 different times during the preparation of the response. An 4286 implementation MAY use a value larger than 60 seconds, if it is 4287 believed that 60 seconds is too short. 4289 If a client wishes to perform a sub-range retrieval on a value for 4290 which it has only a Last-Modified time and no opaque validator, it 4291 MAY do this only if the Last-Modified time is strong in the sense 4292 described here. 4294 A cache or origin server receiving a conditional request, other than 4295 a full-body GET request, MUST use the strong comparison function to 4296 evaluate the condition. 4298 These rules allow HTTP/1.1 caches and clients to safely perform sub- 4299 range retrievals on values that have been obtained from HTTP/1.0 4300 servers. 4302 13.3.4. Rules for When to Use Entity Tags and Last-Modified Dates 4304 We adopt a set of rules and recommendations for origin servers, 4305 clients, and caches regarding when various validator types ought to 4306 be used, and for what purposes. 4308 HTTP/1.1 origin servers: 4310 o SHOULD send an entity tag validator unless it is not feasible to 4311 generate one. 4313 o MAY send a weak entity tag instead of a strong entity tag, if 4314 performance considerations support the use of weak entity tags, or 4315 if it is unfeasible to send a strong entity tag. 4317 o SHOULD send a Last-Modified value if it is feasible to send one, 4318 unless the risk of a breakdown in semantic transparency that could 4319 result from using this date in an If-Modified-Since header would 4320 lead to serious problems. 4322 In other words, the preferred behavior for an HTTP/1.1 origin server 4323 is to send both a strong entity tag and a Last-Modified value. 4325 In order to be legal, a strong entity tag MUST change whenever the 4326 associated entity value changes in any way. A weak entity tag SHOULD 4327 change whenever the associated entity changes in a semantically 4328 significant way. 4330 Note: in order to provide semantically transparent caching, an 4331 origin server must avoid reusing a specific strong entity tag 4332 value for two different entities, or reusing a specific weak 4333 entity tag value for two semantically different entities. Cache 4334 entries might persist for arbitrarily long periods, regardless of 4335 expiration times, so it might be inappropriate to expect that a 4336 cache will never again attempt to validate an entry using a 4337 validator that it obtained at some point in the past. 4339 HTTP/1.1 clients: 4341 o If an entity tag has been provided by the origin server, MUST use 4342 that entity tag in any cache-conditional request (using If-Match 4343 or If-None-Match). 4345 o If only a Last-Modified value has been provided by the origin 4346 server, SHOULD use that value in non-subrange cache-conditional 4347 requests (using If-Modified-Since). 4349 o If only a Last-Modified value has been provided by an HTTP/1.0 4350 origin server, MAY use that value in subrange cache-conditional 4351 requests (using If-Unmodified-Since:). The user agent SHOULD 4352 provide a way to disable this, in case of difficulty. 4354 o If both an entity tag and a Last-Modified value have been provided 4355 by the origin server, SHOULD use both validators in cache- 4356 conditional requests. This allows both HTTP/1.0 and HTTP/1.1 4357 caches to respond appropriately. 4359 An HTTP/1.1 origin server, upon receiving a conditional request that 4360 includes both a Last-Modified date (e.g., in an If-Modified-Since or 4361 If-Unmodified-Since header field) and one or more entity tags (e.g., 4362 in an If-Match, If-None-Match, or If-Range header field) as cache 4363 validators, MUST NOT return a response status of 304 (Not Modified) 4364 unless doing so is consistent with all of the conditional header 4365 fields in the request. 4367 An HTTP/1.1 caching proxy, upon receiving a conditional request that 4368 includes both a Last-Modified date and one or more entity tags as 4369 cache validators, MUST NOT return a locally cached response to the 4370 client unless that cached response is consistent with all of the 4371 conditional header fields in the request. 4373 Note: The general principle behind these rules is that HTTP/1.1 4374 servers and clients should transmit as much non-redundant 4375 information as is available in their responses and requests. 4376 HTTP/1.1 systems receiving this information will make the most 4377 conservative assumptions about the validators they receive. 4379 HTTP/1.0 clients and caches will ignore entity tags. Generally, 4380 last-modified values received or used by these systems will 4381 support transparent and efficient caching, and so HTTP/1.1 origin 4382 servers should provide Last-Modified values. In those rare cases 4383 where the use of a Last-Modified value as a validator by an 4384 HTTP/1.0 system could result in a serious problem, then HTTP/1.1 4385 origin servers should not provide one. 4387 13.3.5. Non-validating Conditionals 4389 The principle behind entity tags is that only the service author 4390 knows the semantics of a resource well enough to select an 4391 appropriate cache validation mechanism, and the specification of any 4392 validator comparison function more complex than byte-equality would 4393 open up a can of worms. Thus, comparisons of any other headers 4394 (except Last-Modified, for compatibility with HTTP/1.0) are never 4395 used for purposes of validating a cache entry. 4397 13.4. Response Cacheability 4399 Unless specifically constrained by a cache-control (Section 14.9) 4400 directive, a caching system MAY always store a successful response 4401 (see Section 13.8) as a cache entry, MAY return it without validation 4402 if it is fresh, and MAY return it after successful validation. If 4403 there is neither a cache validator nor an explicit expiration time 4404 associated with a response, we do not expect it to be cached, but 4405 certain caches MAY violate this expectation (for example, when little 4406 or no network connectivity is available). A client can usually 4407 detect that such a response was taken from a cache by comparing the 4408 Date header to the current time. 4410 Note: some HTTP/1.0 caches are known to violate this expectation 4411 without providing any Warning. 4413 However, in some cases it might be inappropriate for a cache to 4414 retain an entity, or to return it in response to a subsequent 4415 request. This might be because absolute semantic transparency is 4416 deemed necessary by the service author, or because of security or 4417 privacy considerations. Certain cache-control directives are 4418 therefore provided so that the server can indicate that certain 4419 resource entities, or portions thereof, are not to be cached 4420 regardless of other considerations. 4422 Note that Section 14.8 normally prevents a shared cache from saving 4423 and returning a response to a previous request if that request 4424 included an Authorization header. 4426 A response received with a status code of 200, 203, 206, 300, 301 or 4427 410 MAY be stored by a cache and used in reply to a subsequent 4428 request, subject to the expiration mechanism, unless a cache-control 4429 directive prohibits caching. However, a cache that does not support 4430 the Range and Content-Range headers MUST NOT cache 206 (Partial 4431 Content) responses. 4433 A response received with any other status code (e.g. status codes 302 4434 and 307) MUST NOT be returned in a reply to a subsequent request 4435 unless there are cache-control directives or another header(s) that 4436 explicitly allow it. For example, these include the following: an 4437 Expires header (Section 14.21); a "max-age", "s-maxage", "must- 4438 revalidate", "proxy-revalidate", "public" or "private" cache-control 4439 directive (Section 14.9). 4441 13.5. Constructing Responses From Caches 4443 The purpose of an HTTP cache is to store information received in 4444 response to requests for use in responding to future requests. In 4445 many cases, a cache simply returns the appropriate parts of a 4446 response to the requester. However, if the cache holds a cache entry 4447 based on a previous response, it might have to combine parts of a new 4448 response with what is held in the cache entry. 4450 13.5.1. End-to-end and Hop-by-hop Headers 4452 For the purpose of defining the behavior of caches and non-caching 4453 proxies, we divide HTTP headers into two categories: 4455 o End-to-end headers, which are transmitted to the ultimate 4456 recipient of a request or response. End-to-end headers in 4457 responses MUST be stored as part of a cache entry and MUST be 4458 transmitted in any response formed from a cache entry. 4460 o Hop-by-hop headers, which are meaningful only for a single 4461 transport-level connection, and are not stored by caches or 4462 forwarded by proxies. 4464 The following HTTP/1.1 headers are hop-by-hop headers: 4466 o Connection 4468 o Keep-Alive 4470 o Proxy-Authenticate 4472 o Proxy-Authorization 4474 o TE 4476 o Trailer 4478 o Transfer-Encoding 4480 o Upgrade 4482 All other headers defined by HTTP/1.1 are end-to-end headers. 4484 Other hop-by-hop headers MUST be listed in a Connection header, 4485 (Section 14.10) to be introduced into HTTP/1.1 (or later). 4487 13.5.2. Non-modifiable Headers 4489 Some features of the HTTP/1.1 protocol, such as Digest 4490 Authentication, depend on the value of certain end-to-end headers. A 4491 transparent proxy SHOULD NOT modify an end-to-end header unless the 4492 definition of that header requires or specifically allows that. 4494 A transparent proxy MUST NOT modify any of the following fields in a 4495 request or response, and it MUST NOT add any of these fields if not 4496 already present: 4498 o Content-Location 4500 o Content-MD5 4502 o ETag 4504 o Last-Modified 4506 A transparent proxy MUST NOT modify any of the following fields in a 4507 response: 4509 o Expires 4511 but it MAY add any of these fields if not already present. If an 4512 Expires header is added, it MUST be given a field-value identical to 4513 that of the Date header in that response. 4515 A proxy MUST NOT modify or add any of the following fields in a 4516 message that contains the no-transform cache-control directive, or in 4517 any request: 4519 o Content-Encoding 4521 o Content-Range 4523 o Content-Type 4525 A non-transparent proxy MAY modify or add these fields to a message 4526 that does not include no-transform, but if it does so, it MUST add a 4527 Warning 214 (Transformation applied) if one does not already appear 4528 in the message (see Section 14.46). 4530 Warning: unnecessary modification of end-to-end headers might 4531 cause authentication failures if stronger authentication 4532 mechanisms are introduced in later versions of HTTP. Such 4533 authentication mechanisms MAY rely on the values of header fields 4534 not listed here. 4536 The Content-Length field of a request or response is added or deleted 4537 according to the rules in Section 4.4. A transparent proxy MUST 4538 preserve the entity-length (Section 7.2.2) of the entity-body, 4539 although it MAY change the transfer-length (Section 4.4). 4541 13.5.3. Combining Headers 4543 When a cache makes a validating request to a server, and the server 4544 provides a 304 (Not Modified) response or a 206 (Partial Content) 4545 response, the cache then constructs a response to send to the 4546 requesting client. 4548 If the status code is 304 (Not Modified), the cache uses the entity- 4549 body stored in the cache entry as the entity-body of this outgoing 4550 response. If the status code is 206 (Partial Content) and the ETag 4551 or Last-Modified headers match exactly, the cache MAY combine the 4552 contents stored in the cache entry with the new contents received in 4553 the response and use the result as the entity-body of this outgoing 4554 response, (see 13.5.4). 4556 The end-to-end headers stored in the cache entry are used for the 4557 constructed response, except that 4559 o any stored Warning headers with warn-code 1xx (see Section 14.46) 4560 MUST be deleted from the cache entry and the forwarded response. 4562 o any stored Warning headers with warn-code 2xx MUST be retained in 4563 the cache entry and the forwarded response. 4565 o any end-to-end headers provided in the 304 or 206 response MUST 4566 replace the corresponding headers from the cache entry. 4568 Unless the cache decides to remove the cache entry, it MUST also 4569 replace the end-to-end headers stored with the cache entry with 4570 corresponding headers received in the incoming response, except for 4571 Warning headers as described immediately above. If a header field- 4572 name in the incoming response matches more than one header in the 4573 cache entry, all such old headers MUST be replaced. 4575 In other words, the set of end-to-end headers received in the 4576 incoming response overrides all corresponding end-to-end headers 4577 stored with the cache entry (except for stored Warning headers with 4578 warn-code 1xx, which are deleted even if not overridden). 4580 Note: this rule allows an origin server to use a 304 (Not 4581 Modified) or a 206 (Partial Content) response to update any header 4582 associated with a previous response for the same entity or sub- 4583 ranges thereof, although it might not always be meaningful or 4584 correct to do so. This rule does not allow an origin server to 4585 use a 304 (Not Modified) or a 206 (Partial Content) response to 4586 entirely delete a header that it had provided with a previous 4587 response. 4589 13.5.4. Combining Byte Ranges 4591 A response might transfer only a subrange of the bytes of an entity- 4592 body, either because the request included one or more Range 4593 specifications, or because a connection was broken prematurely. 4594 After several such transfers, a cache might have received several 4595 ranges of the same entity-body. 4597 If a cache has a stored non-empty set of subranges for an entity, and 4598 an incoming response transfers another subrange, the cache MAY 4599 combine the new subrange with the existing set if both the following 4600 conditions are met: 4602 o Both the incoming response and the cache entry have a cache 4603 validator. 4605 o The two cache validators match using the strong comparison 4606 function (see Section 13.3.3). 4608 If either requirement is not met, the cache MUST use only the most 4609 recent partial response (based on the Date values transmitted with 4610 every response, and using the incoming response if these values are 4611 equal or missing), and MUST discard the other partial information. 4613 13.6. Caching Negotiated Responses 4615 Use of server-driven content negotiation (Section 12.1), as indicated 4616 by the presence of a Vary header field in a response, alters the 4617 conditions and procedure by which a cache can use the response for 4618 subsequent requests. See Section 14.44 for use of the Vary header 4619 field by servers. 4621 A server SHOULD use the Vary header field to inform a cache of what 4622 request-header fields were used to select among multiple 4623 representations of a cacheable response subject to server-driven 4624 negotiation. The set of header fields named by the Vary field value 4625 is known as the "selecting" request-headers. 4627 When the cache receives a subsequent request whose Request-URI 4628 specifies one or more cache entries including a Vary header field, 4629 the cache MUST NOT use such a cache entry to construct a response to 4630 the new request unless all of the selecting request-headers present 4631 in the new request match the corresponding stored request-headers in 4632 the original request. 4634 The selecting request-headers from two requests are defined to match 4635 if and only if the selecting request-headers in the first request can 4636 be transformed to the selecting request-headers in the second request 4637 by adding or removing linear white space (LWS) at places where this 4638 is allowed by the corresponding BNF, and/or combining multiple 4639 message-header fields with the same field name following the rules 4640 about message headers in Section 4.2. 4642 A Vary header field-value of "*" always fails to match and subsequent 4643 requests on that resource can only be properly interpreted by the 4644 origin server. 4646 If the selecting request header fields for the cached entry do not 4647 match the selecting request header fields of the new request, then 4648 the cache MUST NOT use a cached entry to satisfy the request unless 4649 it first relays the new request to the origin server in a conditional 4650 request and the server responds with 304 (Not Modified), including an 4651 entity tag or Content-Location that indicates the entity to be used. 4653 If an entity tag was assigned to a cached representation, the 4654 forwarded request SHOULD be conditional and include the entity tags 4655 in an If-None-Match header field from all its cache entries for the 4656 resource. This conveys to the server the set of entities currently 4657 held by the cache, so that if any one of these entities matches the 4658 requested entity, the server can use the ETag header field in its 304 4659 (Not Modified) response to tell the cache which entry is appropriate. 4660 If the entity-tag of the new response matches that of an existing 4661 entry, the new response SHOULD be used to update the header fields of 4662 the existing entry, and the result MUST be returned to the client. 4664 If any of the existing cache entries contains only partial content 4665 for the associated entity, its entity-tag SHOULD NOT be included in 4666 the If-None-Match header field unless the request is for a range that 4667 would be fully satisfied by that entry. 4669 If a cache receives a successful response whose Content-Location 4670 field matches that of an existing cache entry for the same Request- 4671 URI, whose entity-tag differs from that of the existing entry, and 4672 whose Date is more recent than that of the existing entry, the 4673 existing entry SHOULD NOT be returned in response to future requests 4674 and SHOULD be deleted from the cache. 4676 13.7. Shared and Non-Shared Caches 4678 For reasons of security and privacy, it is necessary to make a 4679 distinction between "shared" and "non-shared" caches. A non-shared 4680 cache is one that is accessible only to a single user. Accessibility 4681 in this case SHOULD be enforced by appropriate security mechanisms. 4682 All other caches are considered to be "shared." Other sections of 4683 this specification place certain constraints on the operation of 4684 shared caches in order to prevent loss of privacy or failure of 4685 access controls. 4687 13.8. Errors or Incomplete Response Cache Behavior 4689 A cache that receives an incomplete response (for example, with fewer 4690 bytes of data than specified in a Content-Length header) MAY store 4691 the response. However, the cache MUST treat this as a partial 4692 response. Partial responses MAY be combined as described in 4693 Section 13.5.4; the result might be a full response or might still be 4694 partial. A cache MUST NOT return a partial response to a client 4695 without explicitly marking it as such, using the 206 (Partial 4696 Content) status code. A cache MUST NOT return a partial response 4697 using a status code of 200 (OK). 4699 If a cache receives a 5xx response while attempting to revalidate an 4700 entry, it MAY either forward this response to the requesting client, 4701 or act as if the server failed to respond. In the latter case, it 4702 MAY return a previously received response unless the cached entry 4703 includes the "must-revalidate" cache-control directive (see 4704 Section 14.9). 4706 13.9. Side Effects of GET and HEAD 4708 Unless the origin server explicitly prohibits the caching of their 4709 responses, the application of GET and HEAD methods to any resources 4710 SHOULD NOT have side effects that would lead to erroneous behavior if 4711 these responses are taken from a cache. They MAY still have side 4712 effects, but a cache is not required to consider such side effects in 4713 its caching decisions. Caches are always expected to observe an 4714 origin server's explicit restrictions on caching. 4716 We note one exception to this rule: since some applications have 4717 traditionally used GETs and HEADs with query URLs (those containing a 4718 "?" in the rel_path part) to perform operations with significant side 4719 effects, caches MUST NOT treat responses to such URIs as fresh unless 4720 the server provides an explicit expiration time. This specifically 4721 means that responses from HTTP/1.0 servers for such URIs SHOULD NOT 4722 be taken from a cache. See Section 9.1.1 for related information. 4724 13.10. Invalidation After Updates or Deletions 4726 The effect of certain methods performed on a resource at the origin 4727 server might cause one or more existing cache entries to become non- 4728 transparently invalid. That is, although they might continue to be 4729 "fresh," they do not accurately reflect what the origin server would 4730 return for a new request on that resource. 4732 There is no way for the HTTP protocol to guarantee that all such 4733 cache entries are marked invalid. For example, the request that 4734 caused the change at the origin server might not have gone through 4735 the proxy where a cache entry is stored. However, several rules help 4736 reduce the likelihood of erroneous behavior. 4738 In this section, the phrase "invalidate an entity" means that the 4739 cache will either remove all instances of that entity from its 4740 storage, or will mark these as "invalid" and in need of a mandatory 4741 revalidation before they can be returned in response to a subsequent 4742 request. 4744 Some HTTP methods MUST cause a cache to invalidate an entity. This 4745 is either the entity referred to by the Request-URI, or by the 4746 Location or Content-Location headers (if present). These methods 4747 are: 4749 o PUT 4751 o DELETE 4753 o POST 4755 An invalidation based on the URI in a Location or Content-Location 4756 header MUST NOT be performed if the host part of that URI differs 4757 from the host part in the Request-URI. This helps prevent denial of 4758 service attacks. 4760 A cache that passes through requests for methods it does not 4761 understand SHOULD invalidate any entities referred to by the Request- 4762 URI. 4764 13.11. Write-Through Mandatory 4766 All methods that might be expected to cause modifications to the 4767 origin server's resources MUST be written through to the origin 4768 server. This currently includes all methods except for GET and HEAD. 4769 A cache MUST NOT reply to such a request from a client before having 4770 transmitted the request to the inbound server, and having received a 4771 corresponding response from the inbound server. This does not 4772 prevent a proxy cache from sending a 100 (Continue) response before 4773 the inbound server has sent its final reply. 4775 The alternative (known as "write-back" or "copy-back" caching) is not 4776 allowed in HTTP/1.1, due to the difficulty of providing consistent 4777 updates and the problems arising from server, cache, or network 4778 failure prior to write-back. 4780 13.12. Cache Replacement 4782 If a new cacheable (see Sections 14.9.2, 13.2.5, 13.2.6 and 13.8) 4783 response is received from a resource while any existing responses for 4784 the same resource are cached, the cache SHOULD use the new response 4785 to reply to the current request. It MAY insert it into cache storage 4786 and MAY, if it meets all other requirements, use it to respond to any 4787 future requests that would previously have caused the old response to 4788 be returned. If it inserts the new response into cache storage the 4789 rules in Section 13.5.3 apply. 4791 Note: a new response that has an older Date header value than 4792 existing cached responses is not cacheable. 4794 13.13. History Lists 4796 User agents often have history mechanisms, such as "Back" buttons and 4797 history lists, which can be used to redisplay an entity retrieved 4798 earlier in a session. 4800 History mechanisms and caches are different. In particular history 4801 mechanisms SHOULD NOT try to show a semantically transparent view of 4802 the current state of a resource. Rather, a history mechanism is 4803 meant to show exactly what the user saw at the time when the resource 4804 was retrieved. 4806 By default, an expiration time does not apply to history mechanisms. 4807 If the entity is still in storage, a history mechanism SHOULD display 4808 it even if the entity has expired, unless the user has specifically 4809 configured the agent to refresh expired history documents. 4811 This is not to be construed to prohibit the history mechanism from 4812 telling the user that a view might be stale. 4814 Note: if history list mechanisms unnecessarily prevent users from 4815 viewing stale resources, this will tend to force service authors 4816 to avoid using HTTP expiration controls and cache controls when 4817 they would otherwise like to. Service authors may consider it 4818 important that users not be presented with error messages or 4819 warning messages when they use navigation controls (such as BACK) 4820 to view previously fetched resources. Even though sometimes such 4821 resources ought not to cached, or ought to expire quickly, user 4822 interface considerations may force service authors to resort to 4823 other means of preventing caching (e.g. "once-only" URLs) in order 4824 not to suffer the effects of improperly functioning history 4825 mechanisms. 4827 14. Header Field Definitions 4829 This section defines the syntax and semantics of all standard 4830 HTTP/1.1 header fields. For entity-header fields, both sender and 4831 recipient refer to either the client or the server, depending on who 4832 sends and who receives the entity. 4834 14.1. Accept 4836 The Accept request-header field can be used to specify certain media 4837 types which are acceptable for the response. Accept headers can be 4838 used to indicate that the request is specifically limited to a small 4839 set of desired types, as in the case of a request for an in-line 4840 image. 4842 Accept = "Accept" ":" 4843 #( media-range [ accept-params ] ) 4845 media-range = ( "*/*" 4846 | ( type "/" "*" ) 4847 | ( type "/" subtype ) 4848 ) *( ";" parameter ) 4849 accept-params = ";" "q" "=" qvalue *( accept-extension ) 4850 accept-extension = ";" token [ "=" ( token | quoted-string ) ] 4852 The asterisk "*" character is used to group media types into ranges, 4853 with "*/*" indicating all media types and "type/*" indicating all 4854 subtypes of that type. The media-range MAY include media type 4855 parameters that are applicable to that range. 4857 Each media-range MAY be followed by one or more accept-params, 4858 beginning with the "q" parameter for indicating a relative quality 4859 factor. The first "q" parameter (if any) separates the media-range 4860 parameter(s) from the accept-params. Quality factors allow the user 4861 or user agent to indicate the relative degree of preference for that 4862 media-range, using the qvalue scale from 0 to 1 (Section 3.9). The 4863 default value is q=1. 4865 Note: Use of the "q" parameter name to separate media type 4866 parameters from Accept extension parameters is due to historical 4867 practice. Although this prevents any media type parameter named 4868 "q" from being used with a media range, such an event is believed 4869 to be unlikely given the lack of any "q" parameters in the IANA 4870 media type registry and the rare usage of any media type 4871 parameters in Accept. Future media types are discouraged from 4872 registering any parameter named "q". 4874 The example 4875 Accept: audio/*; q=0.2, audio/basic 4877 SHOULD be interpreted as "I prefer audio/basic, but send me any audio 4878 type if it is the best available after an 80% mark-down in quality." 4880 If no Accept header field is present, then it is assumed that the 4881 client accepts all media types. If an Accept header field is 4882 present, and if the server cannot send a response which is acceptable 4883 according to the combined Accept field value, then the server SHOULD 4884 send a 406 (not acceptable) response. 4886 A more elaborate example is 4888 Accept: text/plain; q=0.5, text/html, 4889 text/x-dvi; q=0.8, text/x-c 4891 Verbally, this would be interpreted as "text/html and text/x-c are 4892 the preferred media types, but if they do not exist, then send the 4893 text/x-dvi entity, and if that does not exist, send the text/plain 4894 entity." 4896 Media ranges can be overridden by more specific media ranges or 4897 specific media types. If more than one media range applies to a 4898 given type, the most specific reference has precedence. For example, 4900 Accept: text/*, text/html, text/html;level=1, */* 4902 have the following precedence: 4904 1) text/html;level=1 4905 2) text/html 4906 3) text/* 4907 4) */* 4909 The media type quality factor associated with a given type is 4910 determined by finding the media range with the highest precedence 4911 which matches that type. For example, 4913 Accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1, 4914 text/html;level=2;q=0.4, */*;q=0.5 4916 would cause the following values to be associated: 4918 text/html;level=1 = 1 4919 text/html = 0.7 4920 text/plain = 0.3 4921 image/jpeg = 0.5 4922 text/html;level=2 = 0.4 4923 text/html;level=3 = 0.7 4925 Note: A user agent might be provided with a default set of quality 4926 values for certain media ranges. However, unless the user agent is a 4927 closed system which cannot interact with other rendering agents, this 4928 default set ought to be configurable by the user. 4930 14.2. Accept-Charset 4932 The Accept-Charset request-header field can be used to indicate what 4933 character sets are acceptable for the response. This field allows 4934 clients capable of understanding more comprehensive or special- 4935 purpose character sets to signal that capability to a server which is 4936 capable of representing documents in those character sets. 4938 Accept-Charset = "Accept-Charset" ":" 4939 1#( ( charset | "*" )[ ";" "q" "=" qvalue ] ) 4941 Character set values are described in Section 3.4. Each charset MAY 4942 be given an associated quality value which represents the user's 4943 preference for that charset. The default value is q=1. An example 4944 is 4946 Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 4948 The special value "*", if present in the Accept-Charset field, 4949 matches every character set (including ISO-8859-1) which is not 4950 mentioned elsewhere in the Accept-Charset field. If no "*" is 4951 present in an Accept-Charset field, then all character sets not 4952 explicitly mentioned get a quality value of 0, except for ISO-8859-1, 4953 which gets a quality value of 1 if not explicitly mentioned. 4955 If no Accept-Charset header is present, the default is that any 4956 character set is acceptable. If an Accept-Charset header is present, 4957 and if the server cannot send a response which is acceptable 4958 according to the Accept-Charset header, then the server SHOULD send 4959 an error response with the 406 (not acceptable) status code, though 4960 the sending of an unacceptable response is also allowed. 4962 14.3. Accept-Encoding 4964 The Accept-Encoding request-header field is similar to Accept, but 4965 restricts the content-codings (Section 3.5) that are acceptable in 4966 the response. 4968 Accept-Encoding = "Accept-Encoding" ":" 4969 1#( codings [ ";" "q" "=" qvalue ] ) 4970 codings = ( content-coding | "*" ) 4972 Examples of its use are: 4974 Accept-Encoding: compress, gzip 4975 Accept-Encoding: 4976 Accept-Encoding: * 4977 Accept-Encoding: compress;q=0.5, gzip;q=1.0 4978 Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0 4980 A server tests whether a content-coding is acceptable, according to 4981 an Accept-Encoding field, using these rules: 4983 1. If the content-coding is one of the content-codings listed in the 4984 Accept-Encoding field, then it is acceptable, unless it is 4985 accompanied by a qvalue of 0. (As defined in Section 3.9, a 4986 qvalue of 0 means "not acceptable.") 4988 2. The special "*" symbol in an Accept-Encoding field matches any 4989 available content-coding not explicitly listed in the header 4990 field. 4992 3. If multiple content-codings are acceptable, then the acceptable 4993 content-coding with the highest non-zero qvalue is preferred. 4995 4. The "identity" content-coding is always acceptable, unless 4996 specifically refused because the Accept-Encoding field includes 4997 "identity;q=0", or because the field includes "*;q=0" and does 4998 not explicitly include the "identity" content-coding. If the 4999 Accept-Encoding field-value is empty, then only the "identity" 5000 encoding is acceptable. 5002 If an Accept-Encoding field is present in a request, and if the 5003 server cannot send a response which is acceptable according to the 5004 Accept-Encoding header, then the server SHOULD send an error response 5005 with the 406 (Not Acceptable) status code. 5007 If no Accept-Encoding field is present in a request, the server MAY 5008 assume that the client will accept any content coding. In this case, 5009 if "identity" is one of the available content-codings, then the 5010 server SHOULD use the "identity" content-coding, unless it has 5011 additional information that a different content-coding is meaningful 5012 to the client. 5014 Note: If the request does not include an Accept-Encoding field, 5015 and if the "identity" content-coding is unavailable, then content- 5016 codings commonly understood by HTTP/1.0 clients (i.e., "gzip" and 5017 "compress") are preferred; some older clients improperly display 5018 messages sent with other content-codings. The server might also 5019 make this decision based on information about the particular user- 5020 agent or client. 5022 Note: Most HTTP/1.0 applications do not recognize or obey qvalues 5023 associated with content-codings. This means that qvalues will not 5024 work and are not permitted with x-gzip or x-compress. 5026 14.4. Accept-Language 5028 The Accept-Language request-header field is similar to Accept, but 5029 restricts the set of natural languages that are preferred as a 5030 response to the request. Language tags are defined in Section 3.10. 5032 Accept-Language = "Accept-Language" ":" 5033 1#( language-range [ ";" "q" "=" qvalue ] ) 5034 language-range = ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" ) 5036 Each language-range MAY be given an associated quality value which 5037 represents an estimate of the user's preference for the languages 5038 specified by that range. The quality value defaults to "q=1". For 5039 example, 5041 Accept-Language: da, en-gb;q=0.8, en;q=0.7 5043 would mean: "I prefer Danish, but will accept British English and 5044 other types of English." A language-range matches a language-tag if 5045 it exactly equals the tag, or if it exactly equals a prefix of the 5046 tag such that the first tag character following the prefix is "-". 5047 The special range "*", if present in the Accept-Language field, 5048 matches every tag not matched by any other range present in the 5049 Accept-Language field. 5051 Note: This use of a prefix matching rule does not imply that 5052 language tags are assigned to languages in such a way that it is 5053 always true that if a user understands a language with a certain 5054 tag, then this user will also understand all languages with tags 5055 for which this tag is a prefix. The prefix rule simply allows the 5056 use of prefix tags if this is the case. 5058 The language quality factor assigned to a language-tag by the Accept- 5059 Language field is the quality value of the longest language-range in 5060 the field that matches the language-tag. If no language-range in the 5061 field matches the tag, the language quality factor assigned is 0. If 5062 no Accept-Language header is present in the request, the server 5063 SHOULD assume that all languages are equally acceptable. If an 5064 Accept-Language header is present, then all languages which are 5065 assigned a quality factor greater than 0 are acceptable. 5067 It might be contrary to the privacy expectations of the user to send 5068 an Accept-Language header with the complete linguistic preferences of 5069 the user in every request. For a discussion of this issue, see 5070 Section 15.1.4. 5072 As intelligibility is highly dependent on the individual user, it is 5073 recommended that client applications make the choice of linguistic 5074 preference available to the user. If the choice is not made 5075 available, then the Accept-Language header field MUST NOT be given in 5076 the request. 5078 Note: When making the choice of linguistic preference available to 5079 the user, we remind implementors of the fact that users are not 5080 familiar with the details of language matching as described above, 5081 and should provide appropriate guidance. As an example, users 5082 might assume that on selecting "en-gb", they will be served any 5083 kind of English document if British English is not available. A 5084 user agent might suggest in such a case to add "en" to get the 5085 best matching behavior. 5087 14.5. Accept-Ranges 5089 The Accept-Ranges response-header field allows the server to indicate 5090 its acceptance of range requests for a resource: 5092 Accept-Ranges = "Accept-Ranges" ":" acceptable-ranges 5093 acceptable-ranges = 1#range-unit | "none" 5095 Origin servers that accept byte-range requests MAY send 5097 Accept-Ranges: bytes 5099 but are not required to do so. Clients MAY generate byte-range 5100 requests without having received this header for the resource 5101 involved. Range units are defined in Section 3.12. 5103 Servers that do not accept any kind of range request for a resource 5104 MAY send 5106 Accept-Ranges: none 5108 to advise the client not to attempt a range request. 5110 14.6. Age 5112 The Age response-header field conveys the sender's estimate of the 5113 amount of time since the response (or its revalidation) was generated 5114 at the origin server. A cached response is "fresh" if its age does 5115 not exceed its freshness lifetime. Age values are calculated as 5116 specified in Section 13.2.3. 5118 Age = "Age" ":" age-value 5119 age-value = delta-seconds 5121 Age values are non-negative decimal integers, representing time in 5122 seconds. 5124 If a cache receives a value larger than the largest positive integer 5125 it can represent, or if any of its age calculations overflows, it 5126 MUST transmit an Age header with a value of 2147483648 (2^31). An 5127 HTTP/1.1 server that includes a cache MUST include an Age header 5128 field in every response generated from its own cache. Caches SHOULD 5129 use an arithmetic type of at least 31 bits of range. 5131 14.7. Allow 5133 The Allow entity-header field lists the set of methods supported by 5134 the resource identified by the Request-URI. The purpose of this 5135 field is strictly to inform the recipient of valid methods associated 5136 with the resource. An Allow header field MUST be present in a 405 5137 (Method Not Allowed) response. 5139 Allow = "Allow" ":" #Method 5141 Example of use: 5143 Allow: GET, HEAD, PUT 5145 This field cannot prevent a client from trying other methods. 5146 However, the indications given by the Allow header field value SHOULD 5147 be followed. The actual set of allowed methods is defined by the 5148 origin server at the time of each request. 5150 The Allow header field MAY be provided with a PUT request to 5151 recommend the methods to be supported by the new or modified 5152 resource. The server is not required to support these methods and 5153 SHOULD include an Allow header in the response giving the actual 5154 supported methods. 5156 A proxy MUST NOT modify the Allow header field even if it does not 5157 understand all the methods specified, since the user agent might have 5158 other means of communicating with the origin server. 5160 14.8. Authorization 5162 A user agent that wishes to authenticate itself with a server-- 5163 usually, but not necessarily, after receiving a 401 response--does so 5164 by including an Authorization request-header field with the request. 5165 The Authorization field value consists of credentials containing the 5166 authentication information of the user agent for the realm of the 5167 resource being requested. 5169 Authorization = "Authorization" ":" credentials 5171 HTTP access authentication is described in "HTTP Authentication: 5172 Basic and Digest Access Authentication" [RFC2617]. If a request is 5173 authenticated and a realm specified, the same credentials SHOULD be 5174 valid for all other requests within this realm (assuming that the 5175 authentication scheme itself does not require otherwise, such as 5176 credentials that vary according to a challenge value or using 5177 synchronized clocks). 5179 When a shared cache (see Section 13.7) receives a request containing 5180 an Authorization field, it MUST NOT return the corresponding response 5181 as a reply to any other request, unless one of the following specific 5182 exceptions holds: 5184 1. If the response includes the "s-maxage" cache-control directive, 5185 the cache MAY use that response in replying to a subsequent 5186 request. But (if the specified maximum age has passed) a proxy 5187 cache MUST first revalidate it with the origin server, using the 5188 request-headers from the new request to allow the origin server 5189 to authenticate the new request. (This is the defined behavior 5190 for s-maxage.) If the response includes "s-maxage=0", the proxy 5191 MUST always revalidate it before re-using it. 5193 2. If the response includes the "must-revalidate" cache-control 5194 directive, the cache MAY use that response in replying to a 5195 subsequent request. But if the response is stale, all caches 5196 MUST first revalidate it with the origin server, using the 5197 request-headers from the new request to allow the origin server 5198 to authenticate the new request. 5200 3. If the response includes the "public" cache-control directive, it 5201 MAY be returned in reply to any subsequent request. 5203 14.9. Cache-Control 5205 The Cache-Control general-header field is used to specify directives 5206 that MUST be obeyed by all caching mechanisms along the request/ 5207 response chain. The directives specify behavior intended to prevent 5208 caches from adversely interfering with the request or response. 5209 These directives typically override the default caching algorithms. 5210 Cache directives are unidirectional in that the presence of a 5211 directive in a request does not imply that the same directive is to 5212 be given in the response. 5214 Note that HTTP/1.0 caches might not implement Cache-Control and 5215 might only implement Pragma: no-cache (see Section 14.32). 5217 Cache directives MUST be passed through by a proxy or gateway 5218 application, regardless of their significance to that application, 5219 since the directives might be applicable to all recipients along the 5220 request/response chain. It is not possible to specify a cache- 5221 directive for a specific cache. 5223 Cache-Control = "Cache-Control" ":" 1#cache-directive 5225 cache-directive = cache-request-directive 5226 | cache-response-directive 5228 cache-request-directive = 5229 "no-cache" ; Section 14.9.1 5230 | "no-store" ; Section 14.9.2 5231 | "max-age" "=" delta-seconds ; Section 14.9.3, 14.9.4 5232 | "max-stale" [ "=" delta-seconds ] ; Section 14.9.3 5233 | "min-fresh" "=" delta-seconds ; Section 14.9.3 5234 | "no-transform" ; Section 14.9.5 5235 | "only-if-cached" ; Section 14.9.4 5236 | cache-extension ; Section 14.9.6 5238 cache-response-directive = 5239 "public" ; Section 14.9.1 5240 | "private" [ "=" <"> 1#field-name <"> ] ; Section 14.9.1 5241 | "no-cache" [ "=" <"> 1#field-name <"> ]; Section 14.9.1 5242 | "no-store" ; Section 14.9.2 5243 | "no-transform" ; Section 14.9.5 5244 | "must-revalidate" ; Section 14.9.4 5245 | "proxy-revalidate" ; Section 14.9.4 5246 | "max-age" "=" delta-seconds ; Section 14.9.3 5247 | "s-maxage" "=" delta-seconds ; Section 14.9.3 5248 | cache-extension ; Section 14.9.6 5250 cache-extension = token [ "=" ( token | quoted-string ) ] 5252 When a directive appears without any 1#field-name parameter, the 5253 directive applies to the entire request or response. When such a 5254 directive appears with a 1#field-name parameter, it applies only to 5255 the named field or fields, and not to the rest of the request or 5256 response. This mechanism supports extensibility; implementations of 5257 future versions of the HTTP protocol might apply these directives to 5258 header fields not defined in HTTP/1.1. 5260 The cache-control directives can be broken down into these general 5261 categories: 5263 o Restrictions on what are cacheable; these may only be imposed by 5264 the origin server. 5266 o Restrictions on what may be stored by a cache; these may be 5267 imposed by either the origin server or the user agent. 5269 o Modifications of the basic expiration mechanism; these may be 5270 imposed by either the origin server or the user agent. 5272 o Controls over cache revalidation and reload; these may only be 5273 imposed by a user agent. 5275 o Control over transformation of entities. 5277 o Extensions to the caching system. 5279 14.9.1. What is Cacheable 5281 By default, a response is cacheable if the requirements of the 5282 request method, request header fields, and the response status 5283 indicate that it is cacheable. Section 13.4 summarizes these 5284 defaults for cacheability. The following Cache-Control response 5285 directives allow an origin server to override the default 5286 cacheability of a response: 5288 public 5290 Indicates that the response MAY be cached by any cache, even if it 5291 would normally be non-cacheable or cacheable only within a non- 5292 shared cache. (See also Authorization, Section 14.8, for 5293 additional details.) 5295 private 5297 Indicates that all or part of the response message is intended for 5298 a single user and MUST NOT be cached by a shared cache. This 5299 allows an origin server to state that the specified parts of the 5300 response are intended for only one user and are not a valid 5301 response for requests by other users. A private (non-shared) 5302 cache MAY cache the response. 5304 Note: This usage of the word private only controls where the 5305 response may be cached, and cannot ensure the privacy of the 5306 message content. 5308 no-cache 5310 If the no-cache directive does not specify a field-name, then a 5311 cache MUST NOT use the response to satisfy a subsequent request 5312 without successful revalidation with the origin server. This 5313 allows an origin server to prevent caching even by caches that 5314 have been configured to return stale responses to client requests. 5316 If the no-cache directive does specify one or more field-names, 5317 then a cache MAY use the response to satisfy a subsequent request, 5318 subject to any other restrictions on caching. However, the 5319 specified field-name(s) MUST NOT be sent in the response to a 5320 subsequent request without successful revalidation with the origin 5321 server. This allows an origin server to prevent the re-use of 5322 certain header fields in a response, while still allowing caching 5323 of the rest of the response. 5325 Note: Most HTTP/1.0 caches will not recognize or obey this 5326 directive. 5328 14.9.2. What May be Stored by Caches 5330 no-store 5332 The purpose of the no-store directive is to prevent the 5333 inadvertent release or retention of sensitive information (for 5334 example, on backup tapes). The no-store directive applies to the 5335 entire message, and MAY be sent either in a response or in a 5336 request. If sent in a request, a cache MUST NOT store any part of 5337 either this request or any response to it. If sent in a response, 5338 a cache MUST NOT store any part of either this response or the 5339 request that elicited it. This directive applies to both non- 5340 shared and shared caches. "MUST NOT store" in this context means 5341 that the cache MUST NOT intentionally store the information in 5342 non-volatile storage, and MUST make a best-effort attempt to 5343 remove the information from volatile storage as promptly as 5344 possible after forwarding it. 5346 Even when this directive is associated with a response, users 5347 might explicitly store such a response outside of the caching 5348 system (e.g., with a "Save As" dialog). History buffers MAY store 5349 such responses as part of their normal operation. 5351 The purpose of this directive is to meet the stated requirements 5352 of certain users and service authors who are concerned about 5353 accidental releases of information via unanticipated accesses to 5354 cache data structures. While the use of this directive might 5355 improve privacy in some cases, we caution that it is NOT in any 5356 way a reliable or sufficient mechanism for ensuring privacy. In 5357 particular, malicious or compromised caches might not recognize or 5358 obey this directive, and communications networks might be 5359 vulnerable to eavesdropping. 5361 14.9.3. Modifications of the Basic Expiration Mechanism 5363 The expiration time of an entity MAY be specified by the origin 5364 server using the Expires header (see Section 14.21). Alternatively, 5365 it MAY be specified using the max-age directive in a response. When 5366 the max-age cache-control directive is present in a cached response, 5367 the response is stale if its current age is greater than the age 5368 value given (in seconds) at the time of a new request for that 5369 resource. The max-age directive on a response implies that the 5370 response is cacheable (i.e., "public") unless some other, more 5371 restrictive cache directive is also present. 5373 If a response includes both an Expires header and a max-age 5374 directive, the max-age directive overrides the Expires header, even 5375 if the Expires header is more restrictive. This rule allows an 5376 origin server to provide, for a given response, a longer expiration 5377 time to an HTTP/1.1 (or later) cache than to an HTTP/1.0 cache. This 5378 might be useful if certain HTTP/1.0 caches improperly calculate ages 5379 or expiration times, perhaps due to desynchronized clocks. 5381 Many HTTP/1.0 cache implementations will treat an Expires value that 5382 is less than or equal to the response Date value as being equivalent 5383 to the Cache-Control response directive "no-cache". If an HTTP/1.1 5384 cache receives such a response, and the response does not include a 5385 Cache-Control header field, it SHOULD consider the response to be 5386 non-cacheable in order to retain compatibility with HTTP/1.0 servers. 5388 Note: An origin server might wish to use a relatively new HTTP 5389 cache control feature, such as the "private" directive, on a 5390 network including older caches that do not understand that 5391 feature. The origin server will need to combine the new feature 5392 with an Expires field whose value is less than or equal to the 5393 Date value. This will prevent older caches from improperly 5394 caching the response. 5396 s-maxage 5398 If a response includes an s-maxage directive, then for a shared 5399 cache (but not for a private cache), the maximum age specified by 5400 this directive overrides the maximum age specified by either the 5401 max-age directive or the Expires header. The s-maxage directive 5402 also implies the semantics of the proxy-revalidate directive (see 5403 Section 14.9.4), i.e., that the shared cache must not use the 5404 entry after it becomes stale to respond to a subsequent request 5405 without first revalidating it with the origin server. The 5406 s-maxage directive is always ignored by a private cache. 5408 Note that most older caches, not compliant with this specification, 5409 do not implement any cache-control directives. An origin server 5410 wishing to use a cache-control directive that restricts, but does not 5411 prevent, caching by an HTTP/1.1-compliant cache MAY exploit the 5412 requirement that the max-age directive overrides the Expires header, 5413 and the fact that pre-HTTP/1.1-compliant caches do not observe the 5414 max-age directive. 5416 Other directives allow a user agent to modify the basic expiration 5417 mechanism. These directives MAY be specified on a request: 5419 max-age 5421 Indicates that the client is willing to accept a response whose 5422 age is no greater than the specified time in seconds. Unless max- 5423 stale directive is also included, the client is not willing to 5424 accept a stale response. 5426 min-fresh 5428 Indicates that the client is willing to accept a response whose 5429 freshness lifetime is no less than its current age plus the 5430 specified time in seconds. That is, the client wants a response 5431 that will still be fresh for at least the specified number of 5432 seconds. 5434 max-stale 5436 Indicates that the client is willing to accept a response that has 5437 exceeded its expiration time. If max-stale is assigned a value, 5438 then the client is willing to accept a response that has exceeded 5439 its expiration time by no more than the specified number of 5440 seconds. If no value is assigned to max-stale, then the client is 5441 willing to accept a stale response of any age. 5443 If a cache returns a stale response, either because of a max-stale 5444 directive on a request, or because the cache is configured to 5445 override the expiration time of a response, the cache MUST attach a 5446 Warning header to the stale response, using Warning 110 (Response is 5447 stale). 5449 A cache MAY be configured to return stale responses without 5450 validation, but only if this does not conflict with any "MUST"-level 5451 requirements concerning cache validation (e.g., a "must-revalidate" 5452 cache-control directive). 5454 If both the new request and the cached entry include "max-age" 5455 directives, then the lesser of the two values is used for determining 5456 the freshness of the cached entry for that request. 5458 14.9.4. Cache Revalidation and Reload Controls 5460 Sometimes a user agent might want or need to insist that a cache 5461 revalidate its cache entry with the origin server (and not just with 5462 the next cache along the path to the origin server), or to reload its 5463 cache entry from the origin server. End-to-end revalidation might be 5464 necessary if either the cache or the origin server has overestimated 5465 the expiration time of the cached response. End-to-end reload may be 5466 necessary if the cache entry has become corrupted for some reason. 5468 End-to-end revalidation may be requested either when the client does 5469 not have its own local cached copy, in which case we call it 5470 "unspecified end-to-end revalidation", or when the client does have a 5471 local cached copy, in which case we call it "specific end-to-end 5472 revalidation." 5474 The client can specify these three kinds of action using Cache- 5475 Control request directives: 5477 End-to-end reload 5479 The request includes a "no-cache" cache-control directive or, for 5480 compatibility with HTTP/1.0 clients, "Pragma: no-cache". Field 5481 names MUST NOT be included with the no-cache directive in a 5482 request. The server MUST NOT use a cached copy when responding to 5483 such a request. 5485 Specific end-to-end revalidation 5487 The request includes a "max-age=0" cache-control directive, which 5488 forces each cache along the path to the origin server to 5489 revalidate its own entry, if any, with the next cache or server. 5490 The initial request includes a cache-validating conditional with 5491 the client's current validator. 5493 Unspecified end-to-end revalidation 5495 The request includes "max-age=0" cache-control directive, which 5496 forces each cache along the path to the origin server to 5497 revalidate its own entry, if any, with the next cache or server. 5498 The initial request does not include a cache-validating 5499 conditional; the first cache along the path (if any) that holds a 5500 cache entry for this resource includes a cache-validating 5501 conditional with its current validator. 5503 max-age 5505 When an intermediate cache is forced, by means of a max-age=0 5506 directive, to revalidate its own cache entry, and the client has 5507 supplied its own validator in the request, the supplied validator 5508 might differ from the validator currently stored with the cache 5509 entry. In this case, the cache MAY use either validator in making 5510 its own request without affecting semantic transparency. 5512 However, the choice of validator might affect performance. The 5513 best approach is for the intermediate cache to use its own 5514 validator when making its request. If the server replies with 304 5515 (Not Modified), then the cache can return its now validated copy 5516 to the client with a 200 (OK) response. If the server replies 5517 with a new entity and cache validator, however, the intermediate 5518 cache can compare the returned validator with the one provided in 5519 the client's request, using the strong comparison function. If 5520 the client's validator is equal to the origin server's, then the 5521 intermediate cache simply returns 304 (Not Modified). Otherwise, 5522 it returns the new entity with a 200 (OK) response. 5524 If a request includes the no-cache directive, it SHOULD NOT 5525 include min-fresh, max-stale, or max-age. 5527 only-if-cached 5529 In some cases, such as times of extremely poor network 5530 connectivity, a client may want a cache to return only those 5531 responses that it currently has stored, and not to reload or 5532 revalidate with the origin server. To do this, the client may 5533 include the only-if-cached directive in a request. If it receives 5534 this directive, a cache SHOULD either respond using a cached entry 5535 that is consistent with the other constraints of the request, or 5536 respond with a 504 (Gateway Timeout) status. However, if a group 5537 of caches is being operated as a unified system with good internal 5538 connectivity, such a request MAY be forwarded within that group of 5539 caches. 5541 must-revalidate 5543 Because a cache MAY be configured to ignore a server's specified 5544 expiration time, and because a client request MAY include a max- 5545 stale directive (which has a similar effect), the protocol also 5546 includes a mechanism for the origin server to require revalidation 5547 of a cache entry on any subsequent use. When the must-revalidate 5548 directive is present in a response received by a cache, that cache 5549 MUST NOT use the entry after it becomes stale to respond to a 5550 subsequent request without first revalidating it with the origin 5551 server. (I.e., the cache MUST do an end-to-end revalidation every 5552 time, if, based solely on the origin server's Expires or max-age 5553 value, the cached response is stale.) 5555 The must-revalidate directive is necessary to support reliable 5556 operation for certain protocol features. In all circumstances an 5557 HTTP/1.1 cache MUST obey the must-revalidate directive; in 5558 particular, if the cache cannot reach the origin server for any 5559 reason, it MUST generate a 504 (Gateway Timeout) response. 5561 Servers SHOULD send the must-revalidate directive if and only if 5562 failure to revalidate a request on the entity could result in 5563 incorrect operation, such as a silently unexecuted financial 5564 transaction. Recipients MUST NOT take any automated action that 5565 violates this directive, and MUST NOT automatically provide an 5566 unvalidated copy of the entity if revalidation fails. 5568 Although this is not recommended, user agents operating under 5569 severe connectivity constraints MAY violate this directive but, if 5570 so, MUST explicitly warn the user that an unvalidated response has 5571 been provided. The warning MUST be provided on each unvalidated 5572 access, and SHOULD require explicit user confirmation. 5574 proxy-revalidate 5576 The proxy-revalidate directive has the same meaning as the must- 5577 revalidate directive, except that it does not apply to non-shared 5578 user agent caches. It can be used on a response to an 5579 authenticated request to permit the user's cache to store and 5580 later return the response without needing to revalidate it (since 5581 it has already been authenticated once by that user), while still 5582 requiring proxies that service many users to revalidate each time 5583 (in order to make sure that each user has been authenticated). 5584 Note that such authenticated responses also need the public cache 5585 control directive in order to allow them to be cached at all. 5587 14.9.5. No-Transform Directive 5589 no-transform 5591 Implementors of intermediate caches (proxies) have found it useful 5592 to convert the media type of certain entity bodies. A non- 5593 transparent proxy might, for example, convert between image 5594 formats in order to save cache space or to reduce the amount of 5595 traffic on a slow link. 5597 Serious operational problems occur, however, when these 5598 transformations are applied to entity bodies intended for certain 5599 kinds of applications. For example, applications for medical 5600 imaging, scientific data analysis and those using end-to-end 5601 authentication, all depend on receiving an entity body that is bit 5602 for bit identical to the original entity-body. 5604 Therefore, if a message includes the no-transform directive, an 5605 intermediate cache or proxy MUST NOT change those headers that are 5606 listed in Section 13.5.2 as being subject to the no-transform 5607 directive. This implies that the cache or proxy MUST NOT change 5608 any aspect of the entity-body that is specified by these headers, 5609 including the value of the entity-body itself. 5611 14.9.6. Cache Control Extensions 5613 The Cache-Control header field can be extended through the use of one 5614 or more cache-extension tokens, each with an optional assigned value. 5615 Informational extensions (those which do not require a change in 5616 cache behavior) MAY be added without changing the semantics of other 5617 directives. Behavioral extensions are designed to work by acting as 5618 modifiers to the existing base of cache directives. Both the new 5619 directive and the standard directive are supplied, such that 5620 applications which do not understand the new directive will default 5621 to the behavior specified by the standard directive, and those that 5622 understand the new directive will recognize it as modifying the 5623 requirements associated with the standard directive. In this way, 5624 extensions to the cache-control directives can be made without 5625 requiring changes to the base protocol. 5627 This extension mechanism depends on an HTTP cache obeying all of the 5628 cache-control directives defined for its native HTTP-version, obeying 5629 certain extensions, and ignoring all directives that it does not 5630 understand. 5632 For example, consider a hypothetical new response directive called 5633 community which acts as a modifier to the private directive. We 5634 define this new directive to mean that, in addition to any non-shared 5635 cache, any cache which is shared only by members of the community 5636 named within its value may cache the response. An origin server 5637 wishing to allow the UCI community to use an otherwise private 5638 response in their shared cache(s) could do so by including 5640 Cache-Control: private, community="UCI" 5642 A cache seeing this header field will act correctly even if the cache 5643 does not understand the community cache-extension, since it will also 5644 see and understand the private directive and thus default to the safe 5645 behavior. 5647 Unrecognized cache-directives MUST be ignored; it is assumed that any 5648 cache-directive likely to be unrecognized by an HTTP/1.1 cache will 5649 be combined with standard directives (or the response's default 5650 cacheability) such that the cache behavior will remain minimally 5651 correct even if the cache does not understand the extension(s). 5653 14.10. Connection 5655 The Connection general-header field allows the sender to specify 5656 options that are desired for that particular connection and MUST NOT 5657 be communicated by proxies over further connections. 5659 The Connection header has the following grammar: 5661 Connection = "Connection" ":" 1#(connection-token) 5662 connection-token = token 5664 HTTP/1.1 proxies MUST parse the Connection header field before a 5665 message is forwarded and, for each connection-token in this field, 5666 remove any header field(s) from the message with the same name as the 5667 connection-token. Connection options are signaled by the presence of 5668 a connection-token in the Connection header field, not by any 5669 corresponding additional header field(s), since the additional header 5670 field may not be sent if there are no parameters associated with that 5671 connection option. 5673 Message headers listed in the Connection header MUST NOT include end- 5674 to-end headers, such as Cache-Control. 5676 HTTP/1.1 defines the "close" connection option for the sender to 5677 signal that the connection will be closed after completion of the 5678 response. For example, 5680 Connection: close 5682 in either the request or the response header fields indicates that 5683 the connection SHOULD NOT be considered `persistent' (Section 8.1) 5684 after the current request/response is complete. 5686 An HTTP/1.1 client that does not support persistent connections MUST 5687 include the "close" connection option in every request message. 5689 An HTTP/1.1 server that does not support persistent connections MUST 5690 include the "close" connection option in every response message that 5691 does not have a 1xx (informational) status code. 5693 A system receiving an HTTP/1.0 (or lower-version) message that 5694 includes a Connection header MUST, for each connection-token in this 5695 field, remove and ignore any header field(s) from the message with 5696 the same name as the connection-token. This protects against 5697 mistaken forwarding of such header fields by pre-HTTP/1.1 proxies. 5698 See Appendix F.2. 5700 14.11. Content-Encoding 5702 The Content-Encoding entity-header field is used as a modifier to the 5703 media-type. When present, its value indicates what additional 5704 content codings have been applied to the entity-body, and thus what 5705 decoding mechanisms must be applied in order to obtain the media-type 5706 referenced by the Content-Type header field. Content-Encoding is 5707 primarily used to allow a document to be compressed without losing 5708 the identity of its underlying media type. 5710 Content-Encoding = "Content-Encoding" ":" 1#content-coding 5712 Content codings are defined in Section 3.5. An example of its use is 5714 Content-Encoding: gzip 5716 The content-coding is a characteristic of the entity identified by 5717 the Request-URI. Typically, the entity-body is stored with this 5718 encoding and is only decoded before rendering or analogous usage. 5719 However, a non-transparent proxy MAY modify the content-coding if the 5720 new coding is known to be acceptable to the recipient, unless the 5721 "no-transform" cache-control directive is present in the message. 5723 If the content-coding of an entity is not "identity", then the 5724 response MUST include a Content-Encoding entity-header 5725 (Section 14.11) that lists the non-identity content-coding(s) used. 5727 If the content-coding of an entity in a request message is not 5728 acceptable to the origin server, the server SHOULD respond with a 5729 status code of 415 (Unsupported Media Type). 5731 If multiple encodings have been applied to an entity, the content 5732 codings MUST be listed in the order in which they were applied. 5733 Additional information about the encoding parameters MAY be provided 5734 by other entity-header fields not defined by this specification. 5736 14.12. Content-Language 5738 The Content-Language entity-header field describes the natural 5739 language(s) of the intended audience for the enclosed entity. Note 5740 that this might not be equivalent to all the languages used within 5741 the entity-body. 5743 Content-Language = "Content-Language" ":" 1#language-tag 5745 Language tags are defined in Section 3.10. The primary purpose of 5746 Content-Language is to allow a user to identify and differentiate 5747 entities according to the user's own preferred language. Thus, if 5748 the body content is intended only for a Danish-literate audience, the 5749 appropriate field is 5751 Content-Language: da 5753 If no Content-Language is specified, the default is that the content 5754 is intended for all language audiences. This might mean that the 5755 sender does not consider it to be specific to any natural language, 5756 or that the sender does not know for which language it is intended. 5758 Multiple languages MAY be listed for content that is intended for 5759 multiple audiences. For example, a rendition of the "Treaty of 5760 Waitangi," presented simultaneously in the original Maori and English 5761 versions, would call for 5763 Content-Language: mi, en 5765 However, just because multiple languages are present within an entity 5766 does not mean that it is intended for multiple linguistic audiences. 5767 An example would be a beginner's language primer, such as "A First 5768 Lesson in Latin," which is clearly intended to be used by an English- 5769 literate audience. In this case, the Content-Language would properly 5770 only include "en". 5772 Content-Language MAY be applied to any media type -- it is not 5773 limited to textual documents. 5775 14.13. Content-Length 5777 The Content-Length entity-header field indicates the size of the 5778 entity-body, in decimal number of OCTETs, sent to the recipient or, 5779 in the case of the HEAD method, the size of the entity-body that 5780 would have been sent had the request been a GET. 5782 Content-Length = "Content-Length" ":" 1*DIGIT 5784 An example is 5786 Content-Length: 3495 5788 Applications SHOULD use this field to indicate the transfer-length of 5789 the message-body, unless this is prohibited by the rules in 5790 Section 4.4. 5792 Any Content-Length greater than or equal to zero is a valid value. 5793 Section 4.4 describes how to determine the length of a message-body 5794 if a Content-Length is not given. 5796 Note that the meaning of this field is significantly different from 5797 the corresponding definition in MIME, where it is an optional field 5798 used within the "message/external-body" content-type. In HTTP, it 5799 SHOULD be sent whenever the message's length can be determined prior 5800 to being transferred, unless this is prohibited by the rules in 5801 Section 4.4. 5803 14.14. Content-Location 5805 The Content-Location entity-header field MAY be used to supply the 5806 resource location for the entity enclosed in the message when that 5807 entity is accessible from a location separate from the requested 5808 resource's URI. A server SHOULD provide a Content-Location for the 5809 variant corresponding to the response entity; especially in the case 5810 where a resource has multiple entities associated with it, and those 5811 entities actually have separate locations by which they might be 5812 individually accessed, the server SHOULD provide a Content-Location 5813 for the particular variant which is returned. 5815 Content-Location = "Content-Location" ":" 5816 ( absoluteURI | relativeURI ) 5818 The value of Content-Location also defines the base URI for the 5819 entity. 5821 The Content-Location value is not a replacement for the original 5822 requested URI; it is only a statement of the location of the resource 5823 corresponding to this particular entity at the time of the request. 5824 Future requests MAY specify the Content-Location URI as the request- 5825 URI if the desire is to identify the source of that particular 5826 entity. 5828 A cache cannot assume that an entity with a Content-Location 5829 different from the URI used to retrieve it can be used to respond to 5830 later requests on that Content-Location URI. However, the Content- 5831 Location can be used to differentiate between multiple entities 5832 retrieved from a single requested resource, as described in 5833 Section 13.6. 5835 If the Content-Location is a relative URI, the relative URI is 5836 interpreted relative to the Request-URI. 5838 The meaning of the Content-Location header in PUT or POST requests is 5839 undefined; servers are free to ignore it in those cases. 5841 14.15. Content-MD5 5843 The Content-MD5 entity-header field, as defined in [RFC1864], is an 5844 MD5 digest of the entity-body for the purpose of providing an end-to- 5845 end message integrity check (MIC) of the entity-body. (Note: a MIC 5846 is good for detecting accidental modification of the entity-body in 5847 transit, but is not proof against malicious attacks.) 5849 Content-MD5 = "Content-MD5" ":" md5-digest 5850 md5-digest = 5852 The Content-MD5 header field MAY be generated by an origin server or 5853 client to function as an integrity check of the entity-body. Only 5854 origin servers or clients MAY generate the Content-MD5 header field; 5855 proxies and gateways MUST NOT generate it, as this would defeat its 5856 value as an end-to-end integrity check. Any recipient of the entity- 5857 body, including gateways and proxies, MAY check that the digest value 5858 in this header field matches that of the entity-body as received. 5860 The MD5 digest is computed based on the content of the entity-body, 5861 including any content-coding that has been applied, but not including 5862 any transfer-encoding applied to the message-body. If the message is 5863 received with a transfer-encoding, that encoding MUST be removed 5864 prior to checking the Content-MD5 value against the received entity. 5866 This has the result that the digest is computed on the octets of the 5867 entity-body exactly as, and in the order that, they would be sent if 5868 no transfer-encoding were being applied. 5870 HTTP extends RFC 1864 to permit the digest to be computed for MIME 5871 composite media-types (e.g., multipart/* and message/rfc822), but 5872 this does not change how the digest is computed as defined in the 5873 preceding paragraph. 5875 There are several consequences of this. The entity-body for 5876 composite types MAY contain many body-parts, each with its own MIME 5877 and HTTP headers (including Content-MD5, Content-Transfer-Encoding, 5878 and Content-Encoding headers). If a body-part has a Content- 5879 Transfer-Encoding or Content-Encoding header, it is assumed that the 5880 content of the body-part has had the encoding applied, and the body- 5881 part is included in the Content-MD5 digest as is -- i.e., after the 5882 application. The Transfer-Encoding header field is not allowed 5883 within body-parts. 5885 Conversion of all line breaks to CRLF MUST NOT be done before 5886 computing or checking the digest: the line break convention used in 5887 the text actually transmitted MUST be left unaltered when computing 5888 the digest. 5890 Note: while the definition of Content-MD5 is exactly the same for 5891 HTTP as in RFC 1864 for MIME entity-bodies, there are several ways 5892 in which the application of Content-MD5 to HTTP entity-bodies 5893 differs from its application to MIME entity-bodies. One is that 5894 HTTP, unlike MIME, does not use Content-Transfer-Encoding, and 5895 does use Transfer