idnits 2.17.1 draft-ietf-http-v11-spec-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-23) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 2 longer pages, the longest (page 95) being 60 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** 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 separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 3 instances of too long lines in the document, the longest one being 3 characters in excess of 72. == There are 5 instances of lines with non-RFC2606-compliant FQDNs in the document. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 382: '...the MUST requirements for the protocol...' RFC 2119 keyword, line 383: '...atisfies all the MUST and all the SHOU...' RFC 2119 keyword, line 385: '...all the MUST requirements but not all ...' RFC 2119 keyword, line 756: '...ecial characters MUST be in a quoted s...' RFC 2119 keyword, line 807: '...nd minor numbers MUST be treated as se...' (498 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 1166 has weird spacing: '...a Types in th...' -- The exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Persistent connections provide a mechanism by which a client and a server can signal the close of a TCP connection. This signaling takes place using the Connection header field. Once a close has been signaled, the client MUST not send any more requests on that connection. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: The DELETE method requests that the origin server delete the resource identified by the Request-URI. This method MAY be overridden by human intervention (or other means) on the origin server. The client cannot be guaranteed that the operation has been carried out, even if the status code returned from the origin server indicates that the action has been completed successfully. However, the server SHOULD not indicate success unless, at the time the response is given, it intends to delete the resource or move it to an inaccessible location. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: The request has been accepted for processing, but the processing has not been completed. The request MAY or MAY NOT eventually be acted upon, as it MAY be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: Note: The client SHOULD not send the From header field without the user's approval, as it may conflict with the user's privacy interests or their site's security policy. It is strongly recommended that the user be able to disable, enable, and modify the value of this field at any time prior to a request. -- 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 (July 4, 1996) is 10155 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) -- Looks like a reference, but probably isn't: 'CRLF' on line 740 == Unused Reference: '5' is defined on line 6657, but no explicit reference was found in the text == Unused Reference: '12' is defined on line 6685, but no explicit reference was found in the text ** Obsolete normative reference: RFC 1766 (ref. '1') (Obsoleted by RFC 3066, RFC 3282) ** Downref: Normative reference to an Informational RFC: RFC 1436 (ref. '2') ** Downref: Normative reference to an Informational RFC: RFC 1630 (ref. '3') ** Obsolete normative reference: RFC 1738 (ref. '4') (Obsoleted by RFC 4248, RFC 4266) ** Obsolete normative reference: RFC 1866 (ref. '5') (Obsoleted by RFC 2854) ** Downref: Normative reference to an Informational RFC: RFC 1945 (ref. '6') ** Obsolete normative reference: RFC 1521 (ref. '7') (Obsoleted by RFC 2045, RFC 2046, RFC 2047, RFC 2048, RFC 2049) ** Obsolete normative reference: RFC 822 (ref. '9') (Obsoleted by RFC 2822) -- Possible downref: Non-RFC (?) normative reference: ref. '10' ** Obsolete normative reference: RFC 1808 (ref. '11') (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 850 (ref. '12') (Obsoleted by RFC 1036) ** Obsolete normative reference: RFC 977 (ref. '13') (Obsoleted by RFC 3977) ** Obsolete normative reference: RFC 1522 (ref. '14') (Obsoleted by RFC 2045, RFC 2046, RFC 2047, RFC 2048, RFC 2049) ** Obsolete normative reference: RFC 1867 (ref. '15') (Obsoleted by RFC 2854) ** Obsolete normative reference: RFC 821 (ref. '16') (Obsoleted by RFC 2821) ** Obsolete normative reference: RFC 1590 (ref. '17') (Obsoleted by RFC 2045, RFC 2046, RFC 2047, RFC 2048, RFC 2049) ** Obsolete normative reference: RFC 1700 (ref. '19') (Obsoleted by RFC 3232) ** Downref: Normative reference to an Informational RFC: RFC 1737 (ref. '20') -- Possible downref: Non-RFC (?) normative reference: ref. '21' -- Possible downref: Non-RFC (?) normative reference: ref. '22' ** Downref: Normative reference to an Informational RFC: RFC 1900 (ref. '24') ** Downref: Normative reference to an Informational RFC: RFC 1952 (ref. '25') -- Possible downref: Non-RFC (?) normative reference: ref. '26' ** Obsolete normative reference: RFC 1305 (ref. '28') (Obsoleted by RFC 5905) ** Downref: Normative reference to an Informational RFC: RFC 1951 (ref. '29') -- Possible downref: Non-RFC (?) normative reference: ref. '30' ** Downref: Normative reference to an Informational RFC: RFC 1950 (ref. '31') -- Possible downref: Non-RFC (?) normative reference: ref. '32' Summary: 32 errors (**), 0 flaws (~~), 11 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 HTTP Working Group R. Fielding, UC Irvine 2 INTERNET-DRAFT J. Gettys, DEC 3 J. C. Mogul, DEC 4 H. Frystyk, MIT/LCS 5 T. Berners-Lee, MIT/LCS 6 Expires January 4, 1996 July 4, 1996 8 Hypertext Transfer Protocol -- HTTP/1.1 10 Status of this Memo 12 This document is an Internet-Draft. Internet-Drafts are working 13 documents of the Internet Engineering Task Force (IETF), its areas, and 14 its working groups. Note that other groups may also distribute working 15 documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six months 18 and may be updated, replaced, or made obsolete by other documents at any 19 time. It is inappropriate to use Internet-Drafts as reference material 20 or to cite them other than as "work in progress". 22 To learn the current status of any Internet-Draft, please check the 23 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 24 Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 25 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 26 ftp.isi.edu (US West Coast). 28 Distribution of this document is unlimited. Please send comments to the 29 HTTP working group at . Discussions of the 30 working group are archived at 31 . General discussions about 32 HTTP and the applications which use HTTP should take place on the mailing list. 35 Abstract 37 The Hypertext Transfer Protocol (HTTP) is an application-level protocol 38 for distributed, collaborative, hypermedia information systems. It is a 39 generic, stateless, object-oriented protocol which can be used for many 40 tasks, such as name servers and distributed object management systems, 41 through extension of its request methods. A feature of HTTP is the 42 typing and negotiation of data representation, allowing systems to be 43 built independently of the data being transferred. 45 HTTP has been in use by the World-Wide Web global information initiative 46 since 1990. This specification defines the protocol referred to as 47 "HTTP/1.1". 49 Table of Contents 51 HYPERTEXT TRANSFER PROTOCOL -- HTTP/1.1....................1 53 Status of this Memo........................................1 55 Abstract...................................................1 57 Table of Contents..........................................2 59 1 Introduction.............................................8 60 1.1 Purpose ..............................................8 61 1.2 Requirements .........................................8 62 1.3 Terminology ..........................................9 63 1.4 Overall Operation ...................................12 65 2 Notational Conventions and Generic Grammar..............14 66 2.1 Augmented BNF .......................................14 67 2.2 Basic Rules .........................................15 69 3 Protocol Parameters.....................................17 70 3.1 HTTP Version ........................................17 71 3.2 Uniform Resource Identifiers ........................18 72 3.2.1 General Syntax ...................................18 73 3.2.2 http URL .........................................19 74 3.2.3 URI Comparison ...................................20 75 3.3 Date/Time Formats ...................................20 76 3.3.1 Full Date ........................................20 77 3.3.2 Delta Seconds ....................................21 78 3.4 Character Sets ......................................22 79 3.5 Content Codings .....................................22 80 3.6 Transfer Codings ....................................23 81 3.7 Media Types .........................................25 82 3.7.1 Canonicalization and Text Defaults ...............25 83 3.7.2 Multipart Types ..................................26 84 3.8 Product Tokens ......................................27 85 3.9 Quality Values ......................................27 86 3.10 Language Tags ......................................28 87 3.11 Entity Tags ........................................28 88 3.12 Range Units ........................................29 90 4 HTTP Message............................................29 91 4.1 Message Types .......................................29 92 4.2 Message Headers .....................................30 93 4.3 Message Body ........................................31 94 4.4 Message Length ......................................31 95 4.5 General Header Fields ...............................32 96 5 Request.................................................33 97 5.1 Request-Line ........................................33 98 5.1.1 Method ...........................................33 99 5.1.2 Request-URI ......................................34 100 5.2 The Resource Identified by a Request ................35 101 5.3 Request Header Fields ...............................36 103 6 Response................................................37 104 6.1 Status-Line .........................................37 105 6.1.1 Status Code and Reason Phrase ....................37 106 6.2 Response Header Fields ..............................39 108 7 Entity..................................................39 109 7.1 Entity Header Fields ................................40 110 7.2 Entity Body .........................................40 111 7.2.1 Type .............................................40 112 7.2.2 Length ...........................................41 114 8 Connections.............................................41 115 8.1 Persistent Connections ..............................41 116 8.1.1 Purpose ..........................................41 117 8.1.2 Overall Operation ................................42 118 8.1.3 Proxy Servers ....................................43 119 8.1.4 Practical Considerations .........................43 120 8.2 Message Transmission Requirements ...................44 122 9 Method Definitions......................................46 123 9.1 Safe and Idempotent Methods .........................46 124 9.1.1 Safe Methods .....................................46 125 9.1.2 Idempotent Methods ...............................46 126 9.2 OPTIONS .............................................47 127 9.3 GET .................................................47 128 9.4 HEAD ................................................48 129 9.5 POST ................................................48 130 9.6 PUT .................................................49 131 9.7 DELETE ..............................................50 132 9.8 TRACE ...............................................50 134 10 Status Code Definitions................................51 135 10.1 Informational 1xx ..................................51 136 10.1.1 100 Continue ....................................51 137 10.1.2 101 Switching Protocols .........................51 138 10.2 Successful 2xx .....................................52 139 10.2.1 200 OK ..........................................52 140 10.2.2 201 Created .....................................52 141 10.2.3 202 Accepted ....................................52 142 10.2.4 203 Non-Authoritative Information ...............53 143 10.2.5 204 No Content ..................................53 144 10.2.6 205 Reset Content ...............................53 145 10.2.7 206 Partial Content .............................53 146 10.3 Redirection 3xx ....................................54 147 10.3.1 300 Multiple Choices ............................54 148 10.3.2 301 Moved Permanently ...........................54 149 10.3.3 302 Moved Temporarily ...........................55 150 10.3.4 303 See Other ...................................55 151 10.3.5 304 Not Modified ................................56 152 10.3.6 305 Use Proxy ...................................56 153 10.4 Client Error 4xx ...................................56 154 10.4.1 400 Bad Request .................................57 155 10.4.2 401 Unauthorized ................................57 156 10.4.3 402 Payment Required ............................57 157 10.4.4 403 Forbidden ...................................57 158 10.4.5 404 Not Found ...................................57 159 10.4.6 405 Method Not Allowed ..........................58 160 10.4.7 406 Not Acceptable ..............................58 161 10.4.8 407 Proxy Authentication Required ...............58 162 10.4.9 408 Request Timeout .............................59 163 10.4.10 409 Conflict ...................................59 164 10.4.11 410 Gone .......................................59 165 10.4.12 411 Length Required ............................59 166 10.4.13 412 Precondition Failed ........................60 167 10.4.14 413 Request Entity Too Large ...................60 168 10.4.15 414 Request-URI Too Long .......................60 169 10.4.16 415 Unsupported Media Type .....................60 170 10.5 Server Error 5xx ...................................60 171 10.5.1 500 Internal Server Error .......................61 172 10.5.2 501 Not Implemented .............................61 173 10.5.3 502 Bad Gateway .................................61 174 10.5.4 503 Service Unavailable .........................61 175 10.5.5 504 Gateway Timeout .............................61 176 10.5.6 505 HTTP Version Not Supported ..................61 178 11 Access Authentication..................................62 179 11.1 Basic Authentication Scheme ........................63 180 11.2 Digest Authentication Scheme .......................64 182 12 Content Negotiation....................................64 183 12.1 Server-driven Negotiation ..........................65 184 12.2 Agent-driven Negotiation ...........................66 185 12.3 Transparent Negotiation ............................66 187 13 Caching in HTTP........................................67 188 13.1.1 Cache Correctness ...............................68 189 13.1.2 Warnings ........................................69 190 13.1.3 Cache-control Mechanisms ........................70 191 13.1.4 Explicit User Agent Warnings ....................70 192 13.1.5 Exceptions to the Rules and Warnings ............70 193 13.1.6 Client-controlled Behavior ......................71 194 13.2 Expiration Model ...................................71 195 13.2.1 Server-Specified Expiration .....................71 196 13.2.2 Heuristic Expiration ............................72 197 13.2.3 Age Calculations ................................72 198 13.2.4 Expiration Calculations .........................75 199 13.2.5 Disambiguating Expiration Values ................75 200 13.2.6 Disambiguating Multiple Responses ...............76 201 13.3 Validation Model ...................................77 202 13.3.1 Last-modified Dates .............................77 203 13.3.2 Entity Tag Cache Validators .....................78 204 13.3.3 Weak and Strong Validators ......................78 205 13.3.4 Rules for When to Use Entity Tags and Last-modified Dates 206 .......................................................80 207 13.3.5 Non-validating Conditionals .....................81 208 13.4 Response Cachability ...............................82 209 13.5 Constructing Responses From Caches .................82 210 13.5.1 End-to-end and Hop-by-hop Headers ...............83 211 13.5.2 Non-modifiable Headers ..........................83 212 13.5.3 Combining Headers ...............................84 213 13.5.4 Combining Byte Ranges ...........................84 214 13.6 Caching Negotiated Responses .......................85 215 13.7 Shared and Non-Shared Caches .......................86 216 13.8 Errors or Incomplete Response Cache Behavior .......86 217 13.9 Side Effects of GET and HEAD .......................86 218 13.10 Invalidation After Updates or Deletions ...........87 219 13.11 Write-Through Mandatory ...........................87 220 13.12 Cache Replacement .................................88 221 13.13 History Lists .....................................88 223 14 Header Field Definitions...............................89 224 14.1 Accept .............................................89 225 14.2 Accept-Charset .....................................91 226 14.3 Accept-Encoding ....................................91 227 14.4 Accept-Language ....................................92 228 14.5 Accept-Ranges ......................................93 229 14.6 Age ................................................93 230 14.7 Allow ..............................................94 231 14.8 Authorization ......................................94 232 14.9 Cache-Control ......................................95 233 14.9.1What is Cachable .................................96 234 14.9.1 What May be Stored by Caches ....................97 235 14.9.2 Modifications of the Basic Expiration Mechanism .98 236 14.9.3 Cache Revalidation and Reload Controls ..........99 237 14.9.4 No-Transform Directive .........................101 238 14.9.5 Cache Control Extensions .......................101 239 14.10 Connection .......................................102 240 14.11 Content-Base .....................................103 241 14.12 Content-Encoding .................................103 242 14.13 Content-Language .................................104 243 14.14 Content-Length ...................................104 244 14.15 Content-Location .................................105 245 14.16 Content-MD5 ......................................106 246 14.17 Content-Range ....................................107 247 14.18 Content-Type .....................................108 248 14.19 Date .............................................109 249 14.20 ETag .............................................109 250 14.21 Expires ..........................................110 251 14.22 From .............................................111 252 14.23 Host .............................................111 253 14.24 If-Modified-Since ................................112 254 14.25 If-Match .........................................113 255 14.26 If-None-Match ....................................114 256 14.27 If-Range .........................................115 257 14.28 If-Unmodified-Since ..............................116 258 14.29 Last-Modified ....................................116 259 14.30 Location .........................................117 260 14.31 Max-Forwards .....................................117 261 14.32 Pragma ...........................................118 262 14.33 Proxy-Authenticate ...............................118 263 14.34 Proxy-Authorization ..............................119 264 14.35 Public ...........................................119 265 14.36 Range ............................................120 266 14.36.1 Byte Ranges ...................................120 267 14.36.2 Range Retrieval Requests ......................121 268 14.37 Referer ..........................................122 269 14.38 Retry-After ......................................123 270 14.39 Server ...........................................123 271 14.40 Transfer-Encoding ................................124 272 14.41 Upgrade ..........................................124 273 14.42 User-Agent .......................................125 274 14.43 Vary .............................................125 275 14.44 Via ..............................................127 276 14.45 Warning ..........................................128 277 14.46 WWW-Authenticate .................................130 279 15 Security Considerations...............................130 280 15.1 Authentication of Clients .........................130 281 15.2 Offering a Choice of Authentication Schemes .......131 282 15.3 Abuse of Server Log Information ...................132 283 15.4 Transfer of Sensitive Information .................132 284 15.5 Attacks Based On File and Path Names ..............133 285 15.6 Personal Information ..............................133 286 15.7 Privacy Issues Connected to Accept Headers ........134 287 15.8 DNS Spoofing ......................................134 288 15.9 Location Headers and Spoofing .....................135 290 16 Acknowledgments.......................................135 292 17 References............................................136 294 18 Authors' Addresses....................................140 296 19 Appendices............................................141 297 19.1 Internet Media Type message/http ..................141 298 19.2 Internet Media Type multipart/byteranges ..........141 299 19.3 Tolerant Applications .............................142 300 19.4 Differences Between HTTP Entities and RFC 1521 Entities 143 301 19.4.1 Conversion to Canonical Form ...................143 302 19.4.2 Conversion of Date Formats .....................144 303 19.4.3 Introduction of Content-Encoding ...............144 304 19.4.4 No Content-Transfer-Encoding ...................144 305 19.4.5 HTTP Header Fields in Multipart Body-Parts .....144 306 19.4.6 Introduction of Transfer-Encoding ..............144 307 19.4.7 MIME-Version ...................................145 308 19.5 Changes from HTTP/1.0 .............................145 309 19.5.1 Changes to Simplify Multi-homed Web Servers and Conserve IP 310 Addresses .............................................145 311 19.6 Additional Features ...............................146 312 19.6.1 Additional Request Methods .....................146 313 19.6.2 Additional Header Field Definitions ............148 314 19.7 Compatibility with Previous Versions ..............150 315 19.7.1 Compatibility with HTTP/1.0 Persistent Connections151 316 19.8 Notes to the RFC Editor and IANA ..................152 317 19.8.1 Charset Registry ...............................152 318 19.8.2 Content-coding Values ..........................153 319 19.8.3 New Media Types Registered .....................153 320 19.8.4 Possible Merge With Digest Authentication Draft 153 321 1 Introduction 323 1.1 Purpose 325 The Hypertext Transfer Protocol (HTTP) is an application-level protocol 326 for distributed, collaborative, hypermedia information systems. HTTP has 327 been in use by the World-Wide Web global information initiative since 328 1990. The first version of HTTP, referred to as HTTP/0.9, was a simple 329 protocol for raw data transfer across the Internet. HTTP/1.0, as defined 330 by RFC 1945 [6], improved the protocol by allowing messages to be in the 331 format of MIME-like messages, containing metainformation about the data 332 transferred and modifiers on the request/response semantics. However, 333 HTTP/1.0 does not sufficiently take into consideration the effects of 334 hierarchical proxies, caching, the need for persistent connections, and 335 virtual hosts. In addition, the proliferation of incompletely- 336 implemented applications calling themselves "HTTP/1.0" has necessitated 337 a protocol version change in order for two communicating applications to 338 determine each other's true capabilities. 340 This specification defines the protocol referred to as "HTTP/1.1". This 341 protocol includes more stringent requirements than HTTP/1.0 in order to 342 ensure reliable implementation of its features. 344 Practical information systems require more functionality than simple 345 retrieval, including search, front-end update, and annotation. HTTP 346 allows an open-ended set of methods that indicate the purpose of a 347 request. It builds on the discipline of reference provided by the 348 Uniform Resource Identifier (URI) [3][20], as a location (URL) [4] or 349 name (URN) , for indicating the resource to which a method is to be 350 applied. Messages are passed in a format similar to that used by 351 Internet mail as defined by the Multipurpose Internet Mail Extensions 352 (MIME). 354 HTTP is also used as a generic protocol for communication between user 355 agents and proxies/gateways to other Internet systems, including those 356 supported by the SMTP [16], NNTP [13], FTP [18], Gopher [2], and WAIS 357 [10] protocols. In this way, HTTP allows basic hypermedia access to 358 resources available from diverse applications. 360 1.2 Requirements 362 This specification uses the same words as RFC 1123 [8] for defining the 363 significance of each particular requirement. These words are: 365 MUST 366 This word or the adjective "required" means that the item is an 367 absolute requirement of the specification. 369 SHOULD 370 This word or the adjective "recommended" means that there may exist 371 valid reasons in particular circumstances to ignore this item, but 372 the full implications should be understood and the case carefully 373 weighed before choosing a different course. 375 MAY 376 This word or the adjective "optional" means that this item is truly 377 optional. One vendor may choose to include the item because a 378 particular marketplace requires it or because it enhances the 379 product, for example; another vendor may omit the same item. 381 An implementation is not compliant if it fails to satisfy one or more of 382 the MUST requirements for the protocols it implements. An implementation 383 that satisfies all the MUST and all the SHOULD requirements for its 384 protocols is said to be "unconditionally compliant"; one that satisfies 385 all the MUST requirements but not all the SHOULD requirements for its 386 protocols is said to be "conditionally compliant." 388 1.3 Terminology 390 This specification uses a number of terms to refer to the roles played 391 by participants in, and objects of, the HTTP communication. 393 connection 394 A transport layer virtual circuit established between two programs 395 for the purpose of communication. 397 message 398 The basic unit of HTTP communication, consisting of a structured 399 sequence of octets matching the syntax defined in section 4 and 400 transmitted via the connection. 402 request 403 An HTTP request message, as defined in section 5. 405 response 406 An HTTP response message, as defined in section 6. 408 resource 409 A network data object or service that can be identified by a URI, as 410 defined in section 3.2. Resources may be available in multiple 411 representations (e.g. multiple languages, data formats, size, 412 resolutions) or vary in other ways. 414 entity 415 The information transferred as the payload of a request or response. 416 An entity consists of metainformation in the form of entity-header 417 fields and content in the form of an entity-body, as described in 418 section 7. 420 representation 421 An entity included with a response that is subject to content 422 negotiation, as described in section 12. There may exist multiple 423 representations associated with a particular response status. 425 content negotiation 426 The mechanism for selecting the appropriate representation when 427 servicing a request, as described in section 12. The representation 428 of entities in any response can be negotiated (including error 429 responses). 431 variant 432 A resource may have one, or more than one, representation(s) 433 associated with it at any given instant. Each of these 434 representations is termed a `variant.' Use of the term `variant' does 435 not necessarily imply that the resource is subject to content 436 negotiation. 438 client 439 A program that establishes connections for the purpose of sending 440 requests. 442 user agent 443 The client which initiates a request. These are often browsers, 444 editors, spiders (web-traversing robots), or other end user tools. 446 server 447 An application program that accepts connections in order to service 448 requests by sending back responses. Any given program may be capable 449 of being both a client and a server; our use of these terms refers 450 only to the role being performed by the program for a particular 451 connection, rather than to the program's capabilities in general. 452 Likewise, any server may act as an origin server, proxy, gateway, or 453 tunnel, switching behavior based on the nature of each request. 455 origin server 456 The server on which a given resource resides or is to be created. 458 proxy 459 An intermediary program which acts as both a server and a client for 460 the purpose of making requests on behalf of other clients. Requests 461 are serviced internally or by passing them on, with possible 462 translation, to other servers. A proxy must implement both the client 463 and server requirements of this specification. 465 gateway 466 A server which acts as an intermediary for some other server. Unlike 467 a proxy, a gateway receives requests as if it were the origin server 468 for the requested resource; the requesting client may not be aware 469 that it is communicating with a gateway. 471 tunnel 472 An intermediary program which is acting as a blind relay between two 473 connections. Once active, a tunnel is not considered a party to the 474 HTTP communication, though the tunnel may have been initiated by an 475 HTTP request. The tunnel ceases to exist when both ends of the 476 relayed connections are closed. 478 cache 479 A program's local store of response messages and the subsystem that 480 controls its message storage, retrieval, and deletion. A cache stores 481 cachable responses in order to reduce the response time and network 482 bandwidth consumption on future, equivalent requests. Any client or 483 server may include a cache, though a cache cannot be used by a server 484 that is acting as a tunnel. 486 cachable 487 A response is cachable if a cache is allowed to store a copy of the 488 response message for use in answering subsequent requests. The rules 489 for determining the cachability of HTTP responses are defined in 490 section 13. Even if a resource is cachable, there may be additional 491 constraints on whether a cache can use the cached copy for a 492 particular request. 494 first-hand 495 A response is first-hand if it comes directly and without unnecessary 496 delay from the origin server, perhaps via one or more proxies. A 497 response is also first-hand if its validity has just been checked 498 directly with the origin server. 500 explicit expiration time 501 The time at which the origin server intends that an entity should no 502 longer be returned by a cache without further validation. 504 heuristic expiration time 505 An expiration time assigned by a cache when no explicit expiration 506 time is available. 508 age 509 The age of a response is the time since it was sent by, or 510 successfully validated with, the origin server. 512 freshness lifetime 513 The length of time between the generation of a response and its 514 expiration time. 516 fresh 517 A response is fresh if its age has not yet exceeded its freshness 518 lifetime. 520 stale 521 A response is stale if its age has passed its freshness lifetime. 523 semantically transparent 524 A cache behaves in a "semantically transparent" manner, with respect 525 to a particular response, when its use affects neither the requesting 526 client nor the origin server, except to improve performance. When a 527 cache is semantically transparent, the client receives exactly the 528 same response (except for hop-by-hop headers) that it would have 529 received had its request been handled directly by the origin server. 531 validator 532 A protocol element (e.g., an entity tag or a Last-Modified time) that 533 is used to find out whether a cache entry is an equivalent copy of an 534 entity. 536 1.4 Overall Operation 538 The HTTP protocol is a request/response protocol. A client sends a 539 request to the server in the form of a request method, URI, and protocol 540 version, followed by a MIME-like message containing request modifiers, 541 client information, and possible body content over a connection with a 542 server. The server responds with a status line, including the message's 543 protocol version and a success or error code, followed by a MIME-like 544 message containing server information, entity metainformation, and 545 possible entity-body content. The relationship between HTTP and MIME is 546 described in appendix 19.4. 548 Most HTTP communication is initiated by a user agent and consists of a 549 request to be applied to a resource on some origin server. In the 550 simplest case, this may be accomplished via a single connection (v) 551 between the user agent (UA) and the origin server (O). 553 request chain ------------------------> 554 UA -------------------v------------------- O 555 <----------------------- response chain 557 A more complicated situation occurs when one or more intermediaries are 558 present in the request/response chain. There are three common forms of 559 intermediary: proxy, gateway, and tunnel. A proxy is a forwarding agent, 560 receiving requests for a URI in its absolute form, rewriting all or part 561 of the message, and forwarding the reformatted request toward the server 562 identified by the URI. A gateway is a receiving agent, acting as a layer 563 above some other server(s) and, if necessary, translating the requests 564 to the underlying server's protocol. A tunnel acts as a relay point 565 between two connections without changing the messages; tunnels are used 566 when the communication needs to pass through an intermediary (such as a 567 firewall) even when the intermediary cannot understand the contents of 568 the messages. 570 request chain --------------------------------------> 571 UA -----v----- A -----v----- B -----v----- C -----v----- O 572 <------------------------------------- response chain 573 The figure above shows three intermediaries (A, B, and C) between the 574 user agent and origin server. A request or response message that travels 575 the whole chain will pass through four separate connections. This 576 distinction is important because some HTTP communication options may 577 apply only to the connection with the nearest, non-tunnel neighbor, only 578 to the end-points of the chain, or to all connections along the chain. 579 Although the diagram is linear, each participant may be engaged in 580 multiple, simultaneous communications. For example, B may be receiving 581 requests from many clients other than A, and/or forwarding requests to 582 servers other than C, at the same time that it is handling A's request. 584 Any party to the communication which is not acting as a tunnel may 585 employ an internal cache for handling requests. The effect of a cache is 586 that the request/response chain is shortened if one of the participants 587 along the chain has a cached response applicable to that request. The 588 following illustrates the resulting chain if B has a cached copy of an 589 earlier response from O (via C) for a request which has not been cached 590 by UA or A. 592 request chain ----------> 593 UA -----v----- A -----v----- B - - - - - - C - - - - - - O 594 <--------- response chain 596 Not all responses are usefully cachable, and some requests may contain 597 modifiers which place special requirements on cache behavior. HTTP 598 requirements for cache behavior and cachable responses are defined in 599 section 13. 601 In fact, there are a wide variety of architectures and configurations of 602 caches and proxies currently being experimented with or deployed across 603 the World Wide Web; these systems include national hierarchies of proxy 604 caches to save transoceanic bandwidth, systems that broadcast or 605 multicast cache entries, organizations that distribute subsets of cached 606 data via CD-ROM, and so on. HTTP systems are used in corporate intranets 607 over high-bandwidth links, and for access via PDAs with low-power radio 608 links and intermittent connectivity. The goal of HTTP/1.1 is to support 609 the wide diversity of configurations already deployed while introducing 610 protocol constructs that meet the needs of those who build web 611 applications that require high reliability and, failing that, at least 612 reliable indications of failure. 614 HTTP communication usually takes place over TCP/IP connections. The 615 default port is TCP 80, but other ports can be used. This does not 616 preclude HTTP from being implemented on top of any other protocol on the 617 Internet, or on other networks. HTTP only presumes a reliable transport; 618 any protocol that provides such guarantees can be used; the mapping of 619 the HTTP/1.1 request and response structures onto the transport data 620 units of the protocol in question is outside the scope of this 621 specification. 623 In HTTP/1.0, most implementations used a new connection for each 624 request/response exchange. In HTTP/1.1, a connection may be used for one 625 or more request/response exchanges, although connections may be closed 626 for a variety of reasons (see section 8.1). 628 2 Notational Conventions and Generic Grammar 630 2.1 Augmented BNF 632 All of the mechanisms specified in this document are described in both 633 prose and an augmented Backus-Naur Form (BNF) similar to that used by 634 RFC 822 [9]. Implementers will need to be familiar with the notation in 635 order to understand this specification. The augmented BNF includes the 636 following constructs: 638 name = definition 639 The name of a rule is simply the name itself (without any enclosing 640 "<" and ">") and is separated from its definition by the equal "=" 641 character. Whitespace is only significant in that indentation of 642 continuation lines is used to indicate a rule definition that spans 643 more than one line. Certain basic rules are in uppercase, such as 644 SP, LWS, HT, CRLF, DIGIT, ALPHA, etc. Angle brackets are used 645 within definitions whenever their presence will facilitate 646 discerning the use of rule names. 648 "literal" 649 Quotation marks surround literal text. Unless stated otherwise, the 650 text is case-insensitive. 652 rule1 | rule2 653 Elements separated by a bar ("|") are alternatives, e.g., 654 "yes | no" will accept yes or no. 656 (rule1 rule2) 657 Elements enclosed in parentheses are treated as a single element. 658 Thus, "(elem (foo | bar) elem)" allows the token sequences 659 "elem foo elem" and "elem bar elem". 661 *rule 662 The character "*" preceding an element indicates repetition. The 663 full form is "*element" indicating at least and at most 664 occurrences of element. Default values are 0 and infinity so 665 that "*(element)" allows any number, including zero; "1*element" 666 requires at least one; and "1*2element" allows one or two. 668 [rule] 669 Square brackets enclose optional elements; "[foo bar]" is 670 equivalent to "*1(foo bar)". 672 N rule 673 Specific repetition: "(element)" is equivalent to 674 "*(element)"; that is, exactly occurrences of (element). 675 Thus 2DIGIT is a 2-digit number, and 3ALPHA is a string of three 676 alphabetic characters. 678 #rule 679 A construct "#" is defined, similar to "*", for defining lists of 680 elements. The full form is "#element " indicating at least 681 and at most elements, each separated by one or more commas 682 (",") and optional linear whitespace (LWS). This makes the usual 683 form of lists very easy; a rule such as 684 "( *LWS element *( *LWS "," *LWS element )) " can be shown as 685 "1#element". Wherever this construct is used, null elements are 686 allowed, but do not contribute to the count of elements present. 687 That is, "(element), , (element) " is permitted, but counts as only 688 two elements. Therefore, where at least one element is required, at 689 least one non-null element must be present. Default values are 0 690 and infinity so that "#element" allows any number, including zero; 691 "1#element" requires at least one; and "1#2element" allows one or 692 two. 694 ; comment 695 A semi-colon, set off some distance to the right of rule text, 696 starts a comment that continues to the end of line. This is a 697 simple way of including useful notes in parallel with the 698 specifications. 700 implied *LWS 701 The grammar described by this specification is word-based. Except 702 where noted otherwise, linear whitespace (LWS) can be included 703 between any two adjacent words (token or quoted-string), and 704 between adjacent tokens and delimiters (tspecials), without 705 changing the interpretation of a field. At least one delimiter 706 (tspecials) must exist between any two tokens, since they would 707 otherwise be interpreted as a single token. 709 2.2 Basic Rules 711 The following rules are used throughout this specification to describe 712 basic parsing constructs. The US-ASCII coded character set is defined by 713 ANSI X3.4-1986 [21]. 715 OCTET = 716 CHAR = 717 UPALPHA = 718 LOALPHA = 719 ALPHA = UPALPHA | LOALPHA 720 DIGIT = 721 CTL = 723 CR = 724 LF = 725 SP = 726 HT = 727 <"> = 729 HTTP/1.1 defines the sequence CR LF as the end-of-line marker for all 730 protocol elements except the entity-body (see appendix 19.3 for tolerant 731 applications). The end-of-line marker within an entity-body is defined 732 by its associated media type, as described in section 3.7. 734 CRLF = CR LF 736 HTTP/1.1 headers can be folded onto multiple lines if the continuation 737 line begins with a space or horizontal tab. All linear white space, 738 including folding, has the same semantics as SP. 740 LWS = [CRLF] 1*( SP | HT ) 742 The TEXT rule is only used for descriptive field contents and values 743 that are not intended to be interpreted by the message parser. Words of 744 *TEXT may contain characters from character sets other than ISO 8859-1 745 [22] only when encoded according to the rules of RFC 1522 [14]. 747 TEXT = 750 Hexadecimal numeric characters are used in several protocol elements. 752 HEX = "A" | "B" | "C" | "D" | "E" | "F" 753 | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT 755 Many HTTP/1.1 header field values consist of words separated by LWS or 756 special characters. These special characters MUST be in a quoted string 757 to be used within a parameter value. 759 token = 1* 761 tspecials = "(" | ")" | "<" | ">" | "@" 762 | "," | ";" | ":" | "\" | <"> 763 | "/" | "[" | "]" | "?" | "=" 764 | "{" | "}" | SP | HT 766 Comments can be included in some HTTP header fields by surrounding the 767 comment text with parentheses. Comments are only allowed in fields 768 containing "comment" as part of their field value definition. In all 769 other fields, parentheses are considered part of the field value. 771 comment = "(" *( ctext | comment ) ")" 772 ctext = 773 A string of text is parsed as a single word if it is quoted using 774 double-quote marks. 776 quoted-string = ( <"> *(qdtext) <"> ) 778 qdtext = > 780 The backslash character ("\") may be used as a single-character quoting 781 mechanism only within quoted-string and comment constructs. 783 quoted-pair = "\" CHAR 785 3 Protocol Parameters 787 3.1 HTTP Version 789 HTTP uses a "." numbering scheme to indicate versions of 790 the protocol. The protocol versioning policy is intended to allow the 791 sender to indicate the format of a message and its capacity for 792 understanding further HTTP communication, rather than the features 793 obtained via that communication. No change is made to the version number 794 for the addition of message components which do not affect communication 795 behavior or which only add to extensible field values. The 796 number is incremented when the changes made to the protocol add features 797 which do not change the general message parsing algorithm, but which may 798 add to the message semantics and imply additional capabilities of the 799 sender. The number is incremented when the format of a message 800 within the protocol is changed. 802 The version of an HTTP message is indicated by an HTTP-Version field in 803 the first line of the message. 805 HTTP-Version = "HTTP" "/" 1*DIGIT "." 1*DIGIT 807 Note that the major and minor numbers MUST be treated as separate 808 integers and that each may be incremented higher than a single digit. 809 Thus, HTTP/2.4 is a lower version than HTTP/2.13, which in turn is lower 810 than HTTP/12.3. Leading zeros MUST be ignored by recipients and MUST NOT 811 be sent. 813 Applications sending Request or Response messages, as defined by this 814 specification, MUST include an HTTP-Version of "HTTP/1.1". Use of this 815 version number indicates that the sending application is at least 816 conditionally compliant with this specification. 818 The HTTP version of an application is the highest HTTP version for which 819 the application is at least conditionally compliant. 821 Proxy and gateway applications must be careful when forwarding messages 822 in protocol versions different from that of the application. Since the 823 protocol version indicates the protocol capability of the sender, a 824 proxy/gateway MUST never send a message with a version indicator which 825 is greater than its actual version; if a higher version request is 826 received, the proxy/gateway MUST either downgrade the request version, 827 respond with an error, or switch to tunnel behavior. Requests with a 828 version lower than that of the proxy/gateway's version MAY be upgraded 829 before being forwarded; the proxy/gateway's response to that request 830 MUST be in the same major version as the request. 832 Note: Converting between versions of HTTP may involve modification 833 of header fields required or forbidden by the versions involved. 835 3.2 Uniform Resource Identifiers 837 URIs have been known by many names: WWW addresses, Universal Document 838 Identifiers, Universal Resource Identifiers , and finally the 839 combination of Uniform Resource Locators (URL) and Names (URN). As far 840 as HTTP is concerned, Uniform Resource Identifiers are simply formatted 841 strings which identify--via name, location, or any other characteristic- 842 -a resource. 844 3.2.1 General Syntax 846 URIs in HTTP can be represented in absolute form or relative to some 847 known base URI, depending upon the context of their use. The two forms 848 are differentiated by the fact that absolute URIs always begin with a 849 scheme name followed by a colon. 851 URI = ( absoluteURI | relativeURI ) [ "#" fragment ] 853 absoluteURI = scheme ":" *( uchar | reserved ) 855 relativeURI = net_path | abs_path | rel_path 857 net_path = "//" net_loc [ abs_path ] 858 abs_path = "/" rel_path 859 rel_path = [ path ] [ ";" params ] [ "?" query ] 861 path = fsegment *( "/" segment ) 862 fsegment = 1*pchar 863 segment = *pchar 865 params = param *( ";" param ) 866 param = *( pchar | "/" ) 868 scheme = 1*( ALPHA | DIGIT | "+" | "-" | "." ) 869 net_loc = *( pchar | ";" | "?" ) 870 query = *( uchar | reserved ) 871 fragment = *( uchar | reserved ) 873 pchar = uchar | ":" | "@" | "&" | "=" | "+" 874 uchar = unreserved | escape 875 unreserved = ALPHA | DIGIT | safe | extra | national 877 escape = "%" HEX HEX 878 reserved = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" 879 extra = "!" | "*" | "'" | "(" | ")" | "," 880 safe = "$" | "-" | "_" | "." 881 unsafe = CTL | SP | <"> | "#" | "%" | "<" | ">" 882 national = 885 For definitive information on URL syntax and semantics, see RFC 1738 [4] 886 and RFC 1808 [11]. The BNF above includes national characters not 887 allowed in valid URLs as specified by RFC 1738, since HTTP servers are 888 not restricted in the set of unreserved characters allowed to represent 889 the rel_path part of addresses, and HTTP proxies may receive requests 890 for URIs not defined by RFC 1738. 892 The HTTP protocol does not place any a priori limit on the length of a 893 URI. Servers MUST be able to handle the URI of any resource they serve, 894 and SHOULD be able to handle URIs of unbounded length if they provide 895 GET-based forms that could generate such URIs. A server SHOULD return 896 414 (Request-URI Too Long) status if a URI is longer than the server can 897 handle (see section 10.4.15). 899 Note: Servers should be cautious about depending on URI lengths 900 above 255 bytes, because some older client or proxy implementations 901 may not properly support these lengths. 903 3.2.2 http URL 905 The "http" scheme is used to locate network resources via the HTTP 906 protocol. This section defines the scheme-specific syntax and semantics 907 for http URLs. 909 http_URL = "http:" "//" host [ ":" port ] [ abs_path ] 911 host = 915 port = *DIGIT 917 If the port is empty or not given, port 80 is assumed. The semantics are 918 that the identified resource is located at the server listening for TCP 919 connections on that port of that host, and the Request-URI for the 920 resource is abs_path. The use of IP addresses in URL's SHOULD be avoided 921 whenever possible (see RFC 1900 [24]). If the abs_path is not present in 922 the URL, it MUST be given as "/" when used as a Request-URI for a 923 resource (section 5.1.2). 925 3.2.3 URI Comparison 927 When comparing two URIs to decide if they match or not, a client SHOULD 928 use a case-sensitive octet-by-octet comparison of the entire URIs, with 929 these exceptions: 931 o A port that is empty or not given is equivalent to the default port 932 for that URI; 934 o Comparisons of host names MUST be case-insensitive; 936 o Comparisons of scheme names MUST be case-insensitive; 938 o An empty abs_path is equivalent to an abs_path of "/". 940 Characters other than those in the "reserved" and "unsafe" sets (see 941 section 3.2) are equivalent to their ""%" HEX HEX" encodings. 943 For example, the following three URIs are equivalent: 945 http://abc.com:80/~smith/home.html 946 http://ABC.com/%7Esmith/home.html 947 http://ABC.com:/%7esmith/home.html 949 3.3 Date/Time Formats 951 3.3.1 Full Date 953 HTTP applications have historically allowed three different formats for 954 the representation of date/time stamps: 956 Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123 957 Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036 958 Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format 960 The first format is preferred as an Internet standard and represents a 961 fixed-length subset of that defined by RFC 1123 (an update to RFC 822). 962 The second format is in common use, but is based on the obsolete RFC 963 850 date format and lacks a four-digit year. HTTP/1.1 clients and 964 servers that parse the date value MUST accept all three formats (for 965 compatibility with HTTP/1.0), though they MUST only generate the RFC 966 1123 format for representing HTTP-date values in header fields. 968 Note: Recipients of date values are encouraged to be robust in 969 accepting date values that may have been sent by non-HTTP 970 applications, as is sometimes the case when retrieving or posting 971 messages via proxies/gateways to SMTP or NNTP. 973 All HTTP date/time stamps MUST be represented in Greenwich Mean Time 974 (GMT), without exception. This is indicated in the first two formats by 975 the inclusion of "GMT" as the three-letter abbreviation for time zone, 976 and MUST be assumed when reading the asctime format. 978 HTTP-date = rfc1123-date | rfc850-date | asctime-date 980 rfc1123-date = wkday "," SP date1 SP time SP "GMT" 981 rfc850-date = weekday "," SP date2 SP time SP "GMT" 982 asctime-date = wkday SP date3 SP time SP 4DIGIT 984 date1 = 2DIGIT SP month SP 4DIGIT 985 ; day month year (e.g., 02 Jun 1982) 986 date2 = 2DIGIT "-" month "-" 2DIGIT 987 ; day-month-year (e.g., 02-Jun-82) 988 date3 = month SP ( 2DIGIT | ( SP 1DIGIT )) 989 ; month day (e.g., Jun 2) 991 time = 2DIGIT ":" 2DIGIT ":" 2DIGIT 992 ; 00:00:00 - 23:59:59 994 wkday = "Mon" | "Tue" | "Wed" 995 | "Thu" | "Fri" | "Sat" | "Sun" 997 weekday = "Monday" | "Tuesday" | "Wednesday" 998 | "Thursday" | "Friday" | "Saturday" | "Sunday" 1000 month = "Jan" | "Feb" | "Mar" | "Apr" 1001 | "May" | "Jun" | "Jul" | "Aug" 1002 | "Sep" | "Oct" | "Nov" | "Dec" 1004 Note: HTTP requirements for the date/time stamp format apply only 1005 to their usage within the protocol stream. Clients and servers are 1006 not required to use these formats for user presentation, request 1007 logging, etc. 1009 3.3.2 Delta Seconds 1011 Some HTTP header fields allow a time value to be specified as an integer 1012 number of seconds, represented in decimal, after the time that the 1013 message was received. 1015 delta-seconds = 1*DIGIT 1016 3.4 Character Sets 1018 HTTP uses the same definition of the term "character set" as that 1019 described for MIME: 1021 The term "character set" is used in this document to refer to a 1022 method used with one or more tables to convert a sequence of octets 1023 into a sequence of characters. Note that unconditional conversion 1024 in the other direction is not required, in that not all characters 1025 may be available in a given character set and a character set may 1026 provide more than one sequence of octets to represent a particular 1027 character. This definition is intended to allow various kinds of 1028 character encodings, from simple single-table mappings such as US- 1029 ASCII to complex table switching methods such as those that use ISO 1030 2022's techniques. However, the definition associated with a MIME 1031 character set name MUST fully specify the mapping to be performed 1032 from octets to characters. In particular, use of external profiling 1033 information to determine the exact mapping is not permitted. 1035 Note: This use of the term "character set" is more commonly 1036 referred to as a "character encoding." However, since HTTP and MIME 1037 share the same registry, it is important that the terminology also 1038 be shared. 1040 HTTP character sets are identified by case-insensitive tokens. The 1041 complete set of tokens is defined by the IANA Character Set registry 1042 [19]. 1044 charset = token 1046 Although HTTP allows an arbitrary token to be used as a charset value, 1047 any token that has a predefined value within the IANA Character Set 1048 registry MUST represent the character set defined by that registry. 1049 Applications SHOULD limit their use of character sets to those defined 1050 by the IANA registry. 1052 3.5 Content Codings 1054 Content coding values indicate an encoding transformation that has been 1055 or can be applied to an entity. Content codings are primarily used to 1056 allow a document to be compressed or otherwise usefully transformed 1057 without losing the identity of its underlying media type and without 1058 loss of information. Frequently, the entity is stored in coded form, 1059 transmitted directly, and only decoded by the recipient. 1061 content-coding = token 1063 All content-coding values are case-insensitive. HTTP/1.1 uses content- 1064 coding values in the Accept-Encoding (section 14.3) and Content-Encoding 1065 (section 14.12) header fields. Although the value describes the content- 1066 coding, what is more important is that it indicates what decoding 1067 mechanism will be required to remove the encoding. 1069 The Internet Assigned Numbers Authority (IANA) acts as a registry for 1070 content-coding value tokens. Initially, the registry contains the 1071 following tokens: 1073 gzip An encoding format produced by the file compression program "gzip" 1074 (GNU zip) as described in RFC 1952 [25]. This format is a Lempel- 1075 Ziv coding (LZ77) with a 32 bit CRC. 1077 compress 1078 The encoding format produced by the common UNIX file compression 1079 program "compress". This format is an adaptive Lempel-Ziv-Welch 1080 coding (LZW). 1082 Note: Use of program names for the identification of encoding 1083 formats is not desirable and should be discouraged for future 1084 encodings. Their use here is representative of historical practice, 1085 not good design. For compatibility with previous implementations of 1086 HTTP, applications should consider "x-gzip" and "x-compress" to be 1087 equivalent to "gzip" and "compress" respectively. 1089 deflate The "zlib" format defined in RFC 1950[31] in combination with 1090 the "deflate" compression mechanism described in RFC 1951[29]. 1092 New content-coding value tokens should be registered; to allow 1093 interoperability between clients and servers, specifications of the 1094 content coding algorithms needed to implement a new value should be 1095 publicly available and adequate for independent implementation, and 1096 conform to the purpose of content coding defined in this section. 1098 3.6 Transfer Codings 1100 Transfer coding values are used to indicate an encoding transformation 1101 that has been, can be, or may need to be applied to an entity-body in 1102 order to ensure "safe transport" through the network. This differs from 1103 a content coding in that the transfer coding is a property of the 1104 message, not of the original entity. 1106 transfer-coding = "chunked" | transfer-extension 1108 transfer-extension = token 1110 All transfer-coding values are case-insensitive. HTTP/1.1 uses transfer 1111 coding values in the Transfer-Encoding header field (section 14.40). 1113 Transfer codings are analogous to the Content-Transfer-Encoding values 1114 of MIME , which were designed to enable safe transport of binary data 1115 over a 7-bit transport service. However, safe transport has a different 1116 focus for an 8bit-clean transfer protocol. In HTTP, the only unsafe 1117 characteristic of message-bodies is the difficulty in determining the 1118 exact body length (section 7.2.2), or the desire to encrypt data over a 1119 shared transport. 1121 The chunked encoding modifies the body of a message in order to transfer 1122 it as a series of chunks, each with its own size indicator, followed by 1123 an optional footer containing entity-header fields. This allows 1124 dynamically-produced content to be transferred along with the 1125 information necessary for the recipient to verify that it has received 1126 the full message. 1128 Chunked-Body = *chunk 1129 "0" CRLF 1130 footer 1131 CRLF 1133 chunk = chunk-size [ chunk-ext ] CRLF 1134 chunk-data CRLF 1136 hex-no-zero = 1138 chunk-size = hex-no-zero *HEX 1139 chunk-ext = *( ";" chunk-ext-name [ "=" chunk-ext-value ] ) 1140 chunk-ext-name = token 1141 chunk-ext-val = token | quoted-string 1142 chunk-data = chunk-size(OCTET) 1144 footer = *entity-header 1146 The chunked encoding is ended by a zero-sized chunk followed by the 1147 footer, which is terminated by an empty line. The purpose of the footer 1148 is to provide an efficient way to supply information about an entity 1149 that is generated dynamically; applications MUST NOT send header fields 1150 in the footer which are not explicitly defined as being appropriate for 1151 the footer, such as Content-MD5 or future extensions to HTTP for digital 1152 signatures or other facilities. 1154 An example process for decoding a Chunked-Body is presented in appendix 1155 19.4.6. 1157 All HTTP/1.1 applications MUST be able to receive and decode the 1158 "chunked" transfer coding, and MUST ignore transfer coding extensions 1159 they do not understand. A server which receives an entity-body with a 1160 transfer-coding it does not understand SHOULD return 501 1161 (Unimplemented), and close the connection. A server MUST NOT send 1162 transfer-codings to an HTTP/1.0 client. 1164 3.7 Media Types 1166 HTTP uses Internet Media Types in the Content-Type (section 14.18) and 1167 Accept (section 14.1) header fields in order to provide open and 1168 extensible data typing and type negotiation. 1170 media-type = type "/" subtype *( ";" parameter ) 1171 type = token 1172 subtype = token 1174 Parameters may follow the type/subtype in the form of attribute/value 1175 pairs. 1177 parameter = attribute "=" value 1178 attribute = token 1179 value = token | quoted-string 1181 The type, subtype, and parameter attribute names are case-insensitive. 1182 Parameter values may or may not be case-sensitive, depending on the 1183 semantics of the parameter name. Linear white space (LWS) MUST NOT be 1184 used between the type and subtype, nor between an attribute and its 1185 value. User agents that recognize the media-type MUST process (or 1186 arrange to be processed by any external applications used to process 1187 that type/subtype by the user agent) the parameters for that MIME type 1188 as described by that type/subtype definition to the and inform the user 1189 of any problems discovered. 1191 Note: some older HTTP applications do not recognize media type 1192 parameters. When sending data to older HTTP applications, 1193 implementations should only use media type parameters when they are 1194 required by that type/subtype definition. 1196 Media-type values are registered with the Internet Assigned Number 1197 Authority (IANA). The media type registration process is outlined in RFC 1198 1590 [17]. Use of non-registered media types is discouraged. 1200 3.7.1 Canonicalization and Text Defaults 1202 Internet media types are registered with a canonical form. In general, 1203 an entity-body transferred via HTTP messages MUST be represented in the 1204 appropriate canonical form prior to its transmission; the exception is 1205 "text" types, as defined in the next paragraph. 1207 When in canonical form, media subtypes of the "text" type use CRLF as 1208 the text line break. HTTP relaxes this requirement and allows the 1209 transport of text media with plain CR or LF alone representing a line 1210 break when it is done consistently for an entire entity-body. HTTP 1211 applications MUST accept CRLF, bare CR, and bare LF as being 1212 representative of a line break in text media received via HTTP. In 1213 addition, if the text is represented in a character set that does not 1214 use octets 13 and 10 for CR and LF respectively, as is the case for some 1215 multi-byte character sets, HTTP allows the use of whatever octet 1216 sequences are defined by that character set to represent the equivalent 1217 of CR and LF for line breaks. This flexibility regarding line breaks 1218 applies only to text media in the entity-body; a bare CR or LF MUST NOT 1219 be substituted for CRLF within any of the HTTP control structures (such 1220 as header fields and multipart boundaries). 1222 If an entity-body is encoded with a Content-Encoding, the underlying 1223 data MUST be in a form defined above prior to being encoded. 1225 The "charset" parameter is used with some media types to define the 1226 character set (section 3.4) of the data. When no explicit charset 1227 parameter is provided by the sender, media subtypes of the "text" type 1228 are defined to have a default charset value of "ISO-8859-1" when 1229 received via HTTP. Data in character sets other than "ISO-8859-1" or its 1230 subsets MUST be labeled with an appropriate charset value. 1232 Some HTTP/1.0 software has interpreted a Content-Type header without 1233 charset parameter incorrectly to mean "recipient should guess." Senders 1234 wishing to defeat this behavior MAY include a charset parameter even 1235 when the charset is ISO-8859-1 and SHOULD do so when it is known that it 1236 will not confuse the recipient. 1238 Unfortunately, some older HTTP/1.0 clients did not deal properly with an 1239 explicit charset parameter. HTTP/1.1 recipients MUST respect the charset 1240 label provided by the sender; and those user agents that have a 1241 provision to "guess" a charset MUST use the charset from the content- 1242 type field if they support that charset, rather than the recipient's 1243 preference, when initially displaying a document. 1245 3.7.2 Multipart Types 1247 MIME provides for a number of "multipart" types -- encapsulations of one 1248 or more entities within a single message-body. All multipart types share 1249 a common syntax, as defined in section 7.2.1 of RFC 1521 [7], and MUST 1250 include a boundary parameter as part of the media type value. The 1251 message body is itself a protocol element and MUST therefore use only 1252 CRLF to represent line breaks between body-parts. Unlike in RFC 1521, 1253 the epilogue of any multipart message MUST be empty; HTTP applications 1254 MUST NOT transmit the epilogue (even if the original multipart contains 1255 an epilogue). 1257 In HTTP, multipart body-parts MAY contain header fields which are 1258 significant to the meaning of that part. A Content-Location header field 1259 (section 14.15) SHOULD be included in the body-part of each enclosed 1260 entity that can be identified by a URL. 1262 In general, an HTTP user agent SHOULD follow the same or similar 1263 behavior as a MIME user agent would upon receipt of a multipart type. If 1264 an application receives an unrecognized multipart subtype, the 1265 application MUST treat it as being equivalent to "multipart/mixed". 1267 Note: The "multipart/form-data" type has been specifically defined 1268 for carrying form data suitable for processing via the POST request 1269 method, as described in RFC 1867 [15]. 1271 3.8 Product Tokens 1273 Product tokens are used to allow communicating applications to identify 1274 themselves by software name and version. Most fields using product 1275 tokens also allow sub-products which form a significant part of the 1276 application to be listed, separated by whitespace. By convention, the 1277 products are listed in order of their significance for identifying the 1278 application. 1280 product = token ["/" product-version] 1281 product-version = token 1283 Examples: 1285 User-Agent: CERN-LineMode/2.15 libwww/2.17b3 1286 Server: Apache/0.8.4 1288 Product tokens should be short and to the point -- use of them for 1289 advertising or other non-essential information is explicitly forbidden. 1290 Although any token character may appear in a product-version, this token 1291 SHOULD only be used for a version identifier (i.e., successive versions 1292 of the same product SHOULD only differ in the product-version portion of 1293 the product value). 1295 3.9 Quality Values 1297 HTTP content negotiation (section 12) uses short "floating point" 1298 numbers to indicate the relative importance ("weight") of various 1299 negotiable parameters. A weight is normalized to a real number in the 1300 range 0 through 1, where 0 is the minimum and 1 the maximum value. 1301 HTTP/1.1 applications MUST NOT generate more than three digits after the 1302 decimal point. User configuration of these values SHOULD also be limited 1303 in this fashion. 1305 qvalue = ( "0" [ "." 0*3DIGIT ] ) 1306 | ( "1" [ "." 0*3("0") ] ) 1308 "Quality values" is a misnomer, since these values merely represent 1309 relative degradation in desired quality. 1311 3.10 Language Tags 1313 A language tag identifies a natural language spoken, written, or 1314 otherwise conveyed by human beings for communication of information to 1315 other human beings. Computer languages are explicitly excluded. HTTP 1316 uses language tags within the Accept-Language and Content-Language 1317 fields. 1319 The syntax and registry of HTTP language tags is the same as that 1320 defined by RFC 1766 [1]. In summary, a language tag is composed of 1 or 1321 more parts: A primary language tag and a possibly empty series of 1322 subtags: 1324 language-tag = primary-tag *( "-" subtag ) 1326 primary-tag = 1*8ALPHA 1327 subtag = 1*8ALPHA 1329 Whitespace is not allowed within the tag and all tags are case- 1330 insensitive. The name space of language tags is administered by the 1331 IANA. Example tags include: 1333 en, en-US, en-cockney, i-cherokee, x-pig-latin 1335 where any two-letter primary-tag is an ISO 639 language abbreviation and 1336 any two-letter initial subtag is an ISO 3166 country code. (The last 1337 three tags above are not registered tags; all but the last are examples 1338 of tags which could be registered in future.) 1340 3.11 Entity Tags 1342 Entity tags are used for comparing two or more entities from the same 1343 requested resource. HTTP/1.1 uses entity tags in the ETag (section 1344 14.20), If-Match (section 14.25), If-None-Match (section 14.26), and If- 1345 Range (section 14.27) header fields. The definition of how they are used 1346 and compared as cache validators is in section 13.3.3. An entity tag 1347 consists of an opaque quoted string, possibly prefixed by a weakness 1348 indicator. 1350 entity-tag = [ weak ] opaque-tag 1352 weak = "W/" 1353 opaque-tag = quoted-string 1355 A "strong entity tag" may be shared by two entities of a resource only 1356 if they are equivalent by octet equality. 1358 A "weak entity tag," indicated by the "W/" prefix, may be shared by two 1359 entities of a resource only if the entities are equivalent and could be 1360 substituted for each other with no significant change in semantics. A 1361 weak entity tag can only be used for weak comparison. 1363 An entity tag MUST be unique across all versions of all entities 1364 associated with a particular resource. A given entity tag value may be 1365 used for entities obtained by requests on different URIs without 1366 implying anything about the equivalence of those entities. 1368 3.12 Range Units 1370 HTTP/1.1 allows a client to request that only part (a range of) the 1371 response entity be included within the response. HTTP/1.1 uses range 1372 units in the Range (section 14.36) and Content-Range (section 14.17) 1373 header fields. An entity may be broken down into subranges according to 1374 various structural units. 1376 range-unit = bytes-unit | other-range-unit 1378 bytes-unit = "bytes" 1379 other-range-unit = token 1381 The only range unit defined by HTTP/1.1 is "bytes". HTTP/1.1 1382 implementations may ignore ranges specified using other units. HTTP/1.1 1383 has been designed to allow implementations of applications that do not 1384 depend on knowledge of ranges. 1386 4 HTTP Message 1388 4.1 Message Types 1390 HTTP messages consist of requests from client to server and responses 1391 from server to client. 1393 HTTP-message = Request | Response ; HTTP/1.1 messages 1395 Request (section 5) and Response (section 6) messages use the generic 1396 message format of RFC 822 [9] for transferring entities (the payload of 1397 the message). Both types of message consist of a start-line, one or more 1398 header fields (also known as "headers"), an empty line (i.e., a line 1399 with nothing preceding the CRLF) indicating the end of the header 1400 fields, and an optional message-body. 1402 generic-message = start-line 1403 *message-header 1404 CRLF 1405 [ message-body ] 1407 start-line = Request-Line | Status-Line 1408 In the interest of robustness, servers SHOULD ignore any empty line(s) 1409 received where a Request-Line is expected. In other words, if the server 1410 is reading the protocol stream at the beginning of a message and 1411 receives a CRLF first, it should ignore the CRLF. 1413 Note: certain buggy HTTP/1.0 client implementations generate an 1414 extra CRLF's after a POST request. To restate what is explicitly 1415 forbidden by the BNF, an HTTP/1.1 client must not preface or follow 1416 a request with an extra CRLF. 1418 4.2 Message Headers 1420 HTTP header fields, which include general-header (section 4.5), request- 1421 header (section 5.3), response-header (section 6.2), and entity-header 1422 (section 7.1) fields, follow the same generic format as that given in 1423 Section 3.1 of RFC 822 [9]. Each header field consists of a name 1424 followed by a colon (":") and the field value. Field names are case- 1425 insensitive. The field value may be preceded by any amount of LWS, 1426 though a single SP is preferred. Header fields can be extended over 1427 multiple lines by preceding each extra line with at least one SP or HT. 1428 Applications SHOULD follow "common form" when generating HTTP 1429 constructs, since there might exist some implementations that fail to 1430 accept anything beyond the common forms. 1432 message-header = field-name ":" [ field-value ] CRLF 1434 field-name = token 1435 field-value = *( field-content | LWS ) 1437 field-content = 1441 The order in which header fields with differing field names are received 1442 is not significant. However, it is "good practice" to send general- 1443 header fields first, followed by request-header or response-header 1444 fields, and ending with the entity-header fields. 1446 Multiple message-header fields with the same field-name may be present 1447 in a message if and only if the entire field-value for that header field 1448 is defined as a comma-separated list [i.e., #(values)]. It MUST be 1449 possible to combine the multiple header fields into one "field-name: 1450 field-value" pair, without changing the semantics of the message, by 1451 appending each subsequent field-value to the first, each separated by a 1452 comma. The order in which header fields with the same field-name are 1453 received is therefore significant to the interpretation of the combined 1454 field value, and thus a proxy MUST NOT change the order of these field 1455 values when a message is forwarded. 1457 4.3 Message Body 1459 The message-body (if any) of an HTTP message is used to carry the 1460 entity-body associated with the request or response. The message-body 1461 differs from the entity-body only when a transfer coding has been 1462 applied, as indicated by the Transfer-Encoding header field (section 1463 14.40). 1465 message-body = entity-body 1466 | 1468 Transfer-Encoding MUST be used to indicate any transfer codings applied 1469 by an application to ensure safe and proper transfer of the message. 1470 Transfer-Encoding is a property of the message, not of the entity, and 1471 thus can be added or removed by any application along the 1472 request/response chain. 1474 The rules for when a message-body is allowed in a message differ for 1475 requests and responses. 1477 The presence of a message-body in a request is signaled by the inclusion 1478 of a Content-Length or Transfer-Encoding header field in the request's 1479 message-headers. A message-body MAY be included in a request only when 1480 the request method (section 5.1.1) allows an entity-body. 1482 For response messages, whether or not a message-body is included with a 1483 message is dependent on both the request method and the response status 1484 code (section 6.1.1). All responses to the HEAD request method MUST NOT 1485 include a message-body, even though the presence of entity-header fields 1486 might lead one to believe they do. All 1xx (informational), 204 (no 1487 content), and 304 (not modified) responses MUST NOT include a message- 1488 body. All other responses do include a message-body, although it may be 1489 of zero length. 1491 4.4 Message Length 1493 When a message-body is included with a message, the length of that body 1494 is determined by one of the following (in order of precedence): 1496 1. Any response message which MUST NOT include a message-body (such as 1497 the 1xx, 204, and 304 responses and any response to a HEAD request) 1498 is always terminated by the first empty line after the header fields, 1499 regardless of the entity-header fields present in the message. 1501 2. If a Transfer-Encoding header field (section 14.40) is present and 1502 indicates that the "chunked" transfer coding has been applied, then 1503 the length is defined by the chunked encoding (section 3.6). 1505 3. If a Content-Length header field (section 14.14) is present, its 1506 value in bytes represents the length of the message-body. 1508 4. If the message uses the media type "multipart/byteranges", which is 1509 self-delimiting, then that defines the length. This media type MUST 1510 NOT be used unless the sender knows that the recipient can parse it; 1511 the presence in a request of a Range header with multiple byte-range 1512 specifiers implies that the client can parse multipart/byteranges 1513 responses. 1515 5. By the server closing the connection. (Closing the connection cannot 1516 be used to indicate the end of a request body, since that would leave 1517 no possibility for the server to send back a response.) 1519 For compatibility with HTTP/1.0 applications, HTTP/1.1 requests 1520 containing a message-body MUST include a valid Content-Length header 1521 field unless the server is known to be HTTP/1.1 compliant. If a request 1522 contains a message-body and a Content-Length is not given, the server 1523 SHOULD respond with 400 (bad request) if it cannot determine the length 1524 of the message, or with 411 (length required) if it wishes to insist on 1525 receiving a valid Content-Length. 1527 All HTTP/1.1 applications that receive entities MUST accept the 1528 "chunked" transfer coding (section 3.6), thus allowing this mechanism to 1529 be used for messages when the message length cannot be determined in 1530 advance. 1532 Messages MUST NOT include both a Content-Length header field and the 1533 "chunked" transfer coding. If both are received, the Content-Length MUST 1534 be ignored. 1536 When a Content-Length is given in a message where a message-body is 1537 allowed, its field value MUST exactly match the number of OCTETs in the 1538 message-body. HTTP/1.1 user agents MUST notify the user when an invalid 1539 length is received and detected. 1541 4.5 General Header Fields 1543 There are a few header fields which have general applicability for both 1544 request and response messages, but which do not apply to the entity 1545 being transferred. These header fields apply only to the message being 1546 transmitted. 1548 general-header = Cache-Control ; Section 14.9 1549 | Connection ; Section 14.10 1550 | Date ; Section 14.19 1551 | Pragma ; Section 14.32 1552 | Transfer-Encoding ; Section 14.40 1553 | Upgrade ; Section 14.41 1554 | Via ; Section 14.44 1556 General-header field names can be extended reliably only in combination 1557 with a change in the protocol version. However, new or experimental 1558 header fields may be given the semantics of general header fields if all 1559 parties in the communication recognize them to be general-header fields. 1560 Unrecognized header fields are treated as entity-header fields. 1562 5 Request 1564 A request message from a client to a server includes, within the first 1565 line of that message, the method to be applied to the resource, the 1566 identifier of the resource, and the protocol version in use. 1568 Request = Request-Line ; Section 5.1 1569 *( general-header ; Section 4.5 1570 | request-header ; Section 5.3 1571 | entity-header ) ; Section 7.1 1572 CRLF 1573 [ message-body ] ; Section 7.2 1575 5.1 Request-Line 1577 The Request-Line begins with a method token, followed by the Request-URI 1578 and the protocol version, and ending with CRLF. The elements are 1579 separated by SP characters. No CR or LF are allowed except in the final 1580 CRLF sequence. 1582 Request-Line = Method SP Request-URI SP HTTP-Version CRLF 1584 5.1.1 Method 1586 The Method token indicates the method to be performed on the resource 1587 identified by the Request-URI. The method is case-sensitive. 1589 Method = "OPTIONS" ; Section 9.2 1590 | "GET" ; Section 9.3 1591 | "HEAD" ; Section 9.4 1592 | "POST" ; Section 9.5 1593 | "PUT" ; Section 9.6 1594 | "DELETE" ; Section 9.7 1595 | "TRACE" ; Section 9.8 1596 | extension-method 1598 extension-method = token 1600 The list of methods allowed by a resource can be specified in an Allow 1601 header field (section 14.7). The return code of the response always 1602 notifies the client whether a method is currently allowed on a resource, 1603 since the set of allowed methods can change dynamically. Servers SHOULD 1604 return the status code 405 (Method Not Allowed) if the method is known 1605 by the server but not allowed for the requested resource, and 501 (Not 1606 Implemented) if the method is unrecognized or not implemented by the 1607 server. The list of methods known by a server can be listed in a Public 1608 response-header field (section 14.35). 1610 The methods GET and HEAD MUST be supported by all general-purpose 1611 servers. All other methods are optional; however, if the above methods 1612 are implemented, they MUST be implemented with the same semantics as 1613 those specified in section 9. 1615 5.1.2 Request-URI 1617 The Request-URI is a Uniform Resource Identifier (section 3.2) and 1618 identifies the resource upon which to apply the request. 1620 Request-URI = "*" | absoluteURI | abs_path 1622 The three options for Request-URI are dependent on the nature of the 1623 request. The asterisk "*" means that the request does not apply to a 1624 particular resource, but to the server itself, and is only allowed when 1625 the method used does not necessarily apply to a resource. One example 1626 would be 1628 OPTIONS * HTTP/1.1 1630 The absoluteURI form is required when the request is being made to a 1631 proxy. The proxy is requested to forward the request or service it from 1632 a valid cache, and return the response. Note that the proxy MAY forward 1633 the request on to another proxy or directly to the server specified by 1634 the absoluteURI. In order to avoid request loops, a proxy MUST be able 1635 to recognize all of its server names, including any aliases, local 1636 variations, and the numeric IP address. An example Request-Line would 1637 be: 1639 GET http://www.w3.org/pub/WWW/TheProject.html HTTP/1.1 1641 To allow for transition to absoluteURIs in all requests in future 1642 versions of HTTP, all HTTP/1.1 servers MUST accept the absoluteURI form 1643 in requests, even though HTTP/1.1 clients will only generate them in 1644 requests to proxies. 1646 The most common form of Request-URI is that used to identify a resource 1647 on an origin server or gateway. In this case the absolute path of the 1648 URI MUST be transmitted (see section 3.2.1, abs_path) as the Request- 1649 URI, and the network location of the URI (net_loc) MUST be transmitted 1650 in a Host header field. For example, a client wishing to retrieve the 1651 resource above directly from the origin server would create a TCP 1652 connection to port 80 of the host "www.w3.org" and send the lines: 1654 GET /pub/WWW/TheProject.html HTTP/1.1 1655 Host: www.w3.org 1656 followed by the remainder of the Request. Note that the absolute path 1657 cannot be empty; if none is present in the original URI, it MUST be 1658 given as "/" (the server root). 1660 If a proxy receives a request without any path in the Request-URI and 1661 the method specified is capable of supporting the asterisk form of 1662 request, then the last proxy on the request chain MUST forward the 1663 request with "*" as the final Request-URI. For example, the request 1665 OPTIONS http://www.ics.uci.edu:8001 HTTP/1.1 1667 would be forwarded by the proxy as 1669 OPTIONS * HTTP/1.1 1670 Host: www.ics.uci.edu:8001 1672 after connecting to port 8001 of host "www.ics.uci.edu". 1674 The Request-URI is transmitted in the format specified in section 3.2.1. 1675 The origin server MUST decode the Request-URI in order to properly 1676 interpret the request. Servers SHOULD respond to invalid Request-URIs 1677 with an appropriate status code. 1679 In requests that they forward, proxies MUST NOT rewrite the "abs_path" 1680 part of a Request-URI in any way except as noted above to replace a null 1681 abs_path with "*", no matter what the proxy does in its internal 1682 implementation. 1684 Note: The "no rewrite" rule prevents the proxy from changing the 1685 meaning of the request when the origin server is improperly using a 1686 non-reserved URL character for a reserved purpose. Implementers 1687 should be aware that some pre-HTTP/1.1 proxies have been known to 1688 rewrite the Request-URI. 1690 5.2 The Resource Identified by a Request 1692 HTTP/1.1 origin servers SHOULD be aware that the exact resource 1693 identified by an Internet request is determined by examining both the 1694 Request-URI and the Host header field. 1696 An origin server that does not allow resources to differ by the 1697 requested host MAY ignore the Host header field value. (But see section 1698 19.5.1 for other requirements on Host support in HTTP/1.1.) 1700 An origin server that does differentiate resources based on the host 1701 requested (sometimes referred to as virtual hosts or vanity hostnames) 1702 MUST use the following rules for determining the requested resource on 1703 an HTTP/1.1 request: 1705 1. If Request-URI is an absoluteURI, the host is part of the Request- 1706 URI. Any Host header field value in the request MUST be ignored. 1708 2. If the Request-URI is not an absoluteURI, and the request includes 1709 a Host header field, the host is determined by the Host header 1710 field value. 1712 3. If the host as determined by rule 1 or 2 is not a valid host on the 1713 server, the response MUST be a 400 (Bad Request) error message. 1715 Recipients of an HTTP/1.0 request that lacks a Host header field MAY 1716 attempt to use heuristics (e.g., examination of the URI path for 1717 something unique to a particular host) in order to determine what exact 1718 resource is being requested. 1720 5.3 Request Header Fields 1722 The request-header fields allow the client to pass additional 1723 information about the request, and about the client itself, to the 1724 server. These fields act as request modifiers, with semantics equivalent 1725 to the parameters on a programming language method invocation. 1727 request-header = Accept ; Section 14.1 1728 | Accept-Charset ; Section 14.2 1729 | Accept-Encoding ; Section 14.3 1730 | Accept-Language ; Section 14.4 1731 | Authorization ; Section 14.8 1732 | From ; Section 14.22 1733 | Host ; Section 14.23 1734 | If-Modified-Since ; Section 14.24 1735 | If-Match ; Section 14.25 1736 | If-None-Match ; Section 14.26 1737 | If-Range ; Section 14.27 1738 | If-Unmodified-Since ; Section 14.28 1739 | Max-Forwards ; Section 14.31 1740 | Proxy-Authorization ; Section 14.34 1741 | Range ; Section 14.36 1742 | Referer ; Section 14.37 1743 | User-Agent ; Section 14.42 1745 Request-header field names can be extended reliably only in combination 1746 with a change in the protocol version. However, new or experimental 1747 header fields MAY be given the semantics of request-header fields if all 1748 parties in the communication recognize them to be request-header fields. 1749 Unrecognized header fields are treated as entity-header fields. 1751 6 Response 1753 After receiving and interpreting a request message, a server responds 1754 with an HTTP response message. 1756 Response = Status-Line ; Section 6.1 1757 *( general-header ; Section 4.5 1758 | response-header ; Section 6.2 1759 | entity-header ) ; Section 7.1 1760 CRLF 1761 [ message-body ] ; Section 7.2 1763 6.1 Status-Line 1765 The first line of a Response message is the Status-Line, consisting of 1766 the protocol version followed by a numeric status code and its 1767 associated textual phrase, with each element separated by SP characters. 1768 No CR or LF is allowed except in the final CRLF sequence. 1770 Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF 1772 6.1.1 Status Code and Reason Phrase 1774 The Status-Code element is a 3-digit integer result code of the attempt 1775 to understand and satisfy the request. These codes are fully defined in 1776 section 10. The Reason-Phrase is intended to give a short textual 1777 description of the Status-Code. The Status-Code is intended for use by 1778 automata and the Reason-Phrase is intended for the human user. The 1779 client is not required to examine or display the Reason-Phrase. 1781 The first digit of the Status-Code defines the class of response. The 1782 last two digits do not have any categorization role. There are 5 values 1783 for the first digit: 1785 o 1xx: Informational - Request received, continuing process 1787 o 2xx: Success - The action was successfully received, understood, 1788 and accepted 1790 o 3xx: Redirection - Further action must be taken in order to 1791 complete the request 1793 o 4xx: Client Error - The request contains bad syntax or cannot be 1794 fulfilled 1796 o 5xx: Server Error - The server failed to fulfill an apparently 1797 valid request 1798 The individual values of the numeric status codes defined for HTTP/1.1, 1799 and an example set of corresponding Reason-Phrase's, are presented 1800 below. The reason phrases listed here are only recommended -- they may 1801 be replaced by local equivalents without affecting the protocol. 1803 Status-Code = "100" ; Continue 1804 | "101" ; Switching Protocols 1805 | "200" ; OK 1806 | "201" ; Created 1807 | "202" ; Accepted 1808 | "203" ; Non-Authoritative Information 1809 | "204" ; No Content 1810 | "205" ; Reset Content 1811 | "206" ; Partial Content 1812 | "300" ; Multiple Choices 1813 | "301" ; Moved Permanently 1814 | "302" ; Moved Temporarily 1815 | "303" ; See Other 1816 | "304" ; Not Modified 1817 | "305" ; Use Proxy 1818 | "400" ; Bad Request 1819 | "401" ; Unauthorized 1820 | "402" ; Payment Required 1821 | "403" ; Forbidden 1822 | "404" ; Not Found 1823 | "405" ; Method Not Allowed 1824 | "406" ; Not Acceptable 1825 | "407" ; Proxy Authentication Required 1826 | "408" ; Request Time-out 1827 | "409" ; Conflict 1828 | "410" ; Gone 1829 | "411" ; Length Required 1830 | "412" ; Precondition Failed 1831 | "413" ; Request Entity Too Large 1832 | "414" ; Request-URI Too Large 1833 | "415" ; Unsupported Media Type 1834 | "500" ; Internal Server Error 1835 | "501" ; Not Implemented 1836 | "502" ; Bad Gateway 1837 | "503" ; Service Unavailable 1838 | "504" ; Gateway Time-out 1839 | "505" ; HTTP Version not supported 1840 | extension-code 1842 extension-code = 3DIGIT 1844 Reason-Phrase = * 1846 HTTP status codes are extensible. HTTP applications are not required to 1847 understand the meaning of all registered status codes, though such 1848 understanding is obviously desirable. However, applications MUST 1849 understand the class of any status code, as indicated by the first 1850 digit, and treat any unrecognized response as being equivalent to the 1851 x00 status code of that class, with the exception that an unrecognized 1852 response MUST NOT be cached. For example, if an unrecognized status code 1853 of 431 is received by the client, it can safely assume that there was 1854 something wrong with its request and treat the response as if it had 1855 received a 400 status code. In such cases, user agents SHOULD present to 1856 the user the entity returned with the response, since that entity is 1857 likely to include human-readable information which will explain the 1858 unusual status. 1860 6.2 Response Header Fields 1862 The response-header fields allow the server to pass additional 1863 information about the response which cannot be placed in the Status- 1864 Line. These header fields give information about the server and about 1865 further access to the resource identified by the Request-URI. 1867 response-header = Age ; Section 14.6 1868 | Location ; Section 14.30 1869 | Proxy-Authenticate ; Section 14.33 1870 | Public ; Section 14.35 1871 | Retry-After ; Section 14.38 1872 | Server ; Section 14.39 1873 | Vary ; Section 14.43 1874 | Warning ; Section 14.45 1875 | WWW-Authenticate ; Section 14.46 1877 Response-header field names can be extended reliably only in combination 1878 with a change in the protocol version. However, new or experimental 1879 header fields MAY be given the semantics of response-header fields if 1880 all parties in the communication recognize them to be response-header 1881 fields. Unrecognized header fields are treated as entity-header fields. 1883 7 Entity 1885 Request and Response messages MAY transfer an entity if not otherwise 1886 restricted by the request method or response status code. An entity 1887 consists of entity-header fields and an entity-body, although some 1888 responses will only include the entity-headers. 1890 In this section, both sender and recipient refer to either the client or 1891 the server, depending on who sends and who receives the entity. 1893 7.1 Entity Header Fields 1895 Entity-header fields define optional metainformation about the entity- 1896 body or, if no body is present, about the resource identified by the 1897 request. 1899 entity-header = Allow ; Section 14.7 1900 | Content-Base ; Section 14.11 1901 | Content-Encoding ; Section 14.12 1902 | Content-Language ; Section 14.13 1903 | Content-Length ; Section 14.14 1904 | Content-Location ; Section 14.15 1905 | Content-MD5 ; Section 14.16 1906 | Content-Range ; Section 14.17 1907 | Content-Type ; Section 14.18 1908 | ETag ; Section 14.20 1909 | Expires ; Section 14.21 1910 | Last-Modified ; Section 14.29 1911 | extension-header 1913 extension-header = message-header 1915 The extension-header mechanism allows additional entity-header fields to 1916 be defined without changing the protocol, but these fields cannot be 1917 assumed to be recognizable by the recipient. Unrecognized header fields 1918 SHOULD be ignored by the recipient and forwarded by proxies. 1920 7.2 Entity Body 1922 The entity-body (if any) sent with an HTTP request or response is in a 1923 format and encoding defined by the entity-header fields. 1925 entity-body = *OCTET 1927 An entity-body is only present in a message when a message-body is 1928 present, as described in section 4.3. The entity-body is obtained from 1929 the message-body by decoding any Transfer-Encoding that may have been 1930 applied to ensure safe and proper transfer of the message. 1932 7.2.1 Type 1934 When an entity-body is included with a message, the data type of that 1935 body is determined via the header fields Content-Type and Content- 1936 Encoding. These define a two-layer, ordered encoding model: 1938 entity-body := Content-Encoding( Content-Type( data ) ) 1940 Content-Type specifies the media type of the underlying data. Content- 1941 Encoding may be used to indicate any additional content codings applied 1942 to the data, usually for the purpose of data compression, that are a 1943 property of the requested resource. There is no default encoding. 1945 Any HTTP/1.1 message containing an entity-body SHOULD include a Content- 1946 Type header field defining the media type of that body. If and only if 1947 the media type is not given by a Content-Type field, the recipient MAY 1948 attempt to guess the media type via inspection of its content and/or the 1949 name extension(s) of the URL used to identify the resource. If the media 1950 type remains unknown, the recipient SHOULD treat it as type 1951 "application/octet-stream". 1953 7.2.2 Length 1955 The length of an entity-body is the length of the message-body after any 1956 transfer codings have been removed. Section 4.4 defines how the length 1957 of a message-body is determined. 1959 8 Connections 1961 8.1 Persistent Connections 1963 8.1.1 Purpose 1965 Prior to persistent connections, a separate TCP connection was 1966 established to fetch each URL, increasing the load on HTTP servers and 1967 causing congestion on the Internet. The use of inline images and other 1968 associated data often requires a client to make multiple requests of the 1969 same server in a short amount of time. Analyses of these performance 1970 problems are available [30]; analysis and results from a prototype 1971 implementation are in [26]. 1973 Persistent HTTP connections have a number of advantages: 1975 o By opening and closing fewer TCP connections, CPU time is saved, 1976 and memory used for TCP protocol control blocks is also saved. 1977 o HTTP requests and responses can be pipelined on a connection. 1978 Pipelining allows a client to make multiple requests without 1979 waiting for each response, allowing a single TCP connection to be 1980 used much more efficiently, with much lower elapsed time. 1981 o Network congestion is reduced by reducing the number of packets 1982 caused by TCP opens, and by allowing TCP sufficient time to 1983 determine the congestion state of the network. 1984 o HTTP can evolve more gracefully; since errors can be reported 1985 without the penalty of closing the TCP connection. Clients using 1986 future versions of HTTP might optimistically try a new feature, but 1987 if communicating with an older server, retry with old semantics 1988 after an error is reported. 1990 HTTP implementations SHOULD implement persistent connections. 1992 8.1.2 Overall Operation 1994 A significant difference between HTTP/1.1 and earlier versions of HTTP 1995 is that persistent connections are the default behavior of any HTTP 1996 connection. That is, unless otherwise indicated, the client may assume 1997 that the server will maintain a persistent connection. 1999 Persistent connections provide a mechanism by which a client and a 2000 server can signal the close of a TCP connection. This signaling takes 2001 place using the Connection header field. Once a close has been signaled, 2002 the client MUST not send any more requests on that connection. 2004 8.1.2.1 Negotiation 2006 An HTTP/1.1 server MAY assume that a HTTP/1.1 client intends to maintain 2007 a persistent connection unless a Connection header including the 2008 connection-token "close" was sent in the request. If the server chooses 2009 to close the connection immediately after sending the response, it 2010 SHOULD send a Connection header including the connection-token close. 2012 An HTTP/1.1 client MAY expect a connection to remain open, but would 2013 decide to keep it open based on whether the response from a server 2014 contains a Connection header with the connection-token close. In case 2015 the client does not want to maintain a connection for more than that 2016 request, it SHOULD send a Connection header including the connection- 2017 token close. 2019 If either the client or the server sends the close token in the 2020 Connection header, that request becomes the last one for the connection. 2022 Clients and servers SHOULD NOT assume that a persistent connection is 2023 maintained for HTTP versions less than 1.1 unless it is explicitly 2024 signaled. See section 19.7.1 for more information on backwards 2025 compatibility with HTTP/1.0 clients. 2027 In order to remain persistent, all messages on the connection must have 2028 a self-defined message length (i.e., one not defined by closure of the 2029 connection), as described in section 4.4. 2031 8.1.2.2 Pipelining 2033 A client that supports persistent connections MAY "pipeline" its 2034 requests (i.e., send multiple requests without waiting for each 2035 response). A server MUST send its responses to those requests in the 2036 same order that the requests were received. 2038 Clients which assume persistent connections and pipeline immediately 2039 after connection establishment SHOULD be prepared to retry their 2040 connection if the first pipelined attempt fails. If a client does such a 2041 retry, it MUST NOT pipeline before it knows the connection is 2042 persistent. Clients MUST also be prepared to resend their requests if 2043 the server closes the connection before sending all of the corresponding 2044 responses. 2046 8.1.3 Proxy Servers 2048 It is especially important that proxies correctly implement the 2049 properties of the Connection header field as specified in 14.2.1. 2051 The proxy server MUST signal persistent connections separately with its 2052 clients and the origin servers (or other proxy servers) that it connects 2053 to. Each persistent connection applies to only one transport link. 2055 A proxy server MUST NOT establish a persistent connection with an 2056 HTTP/1.0 client. 2058 8.1.4 Practical Considerations 2060 Servers will usually have some time-out value beyond which they will no 2061 longer maintain an inactive connection. Proxy servers might make this a 2062 higher value since it is likely that the client will be making more 2063 connections through the same server. The use of persistent connections 2064 places no requirements on the length of this time-out for either the 2065 client or the server. 2067 When a client or server wishes to time-out it SHOULD issue a graceful 2068 close on the transport connection. Clients and servers SHOULD both 2069 constantly watch for the other side of the transport close, and respond 2070 to it as appropriate. If a client or server does not detect the other 2071 side's close promptly it could cause unnecessary resource drain on the 2072 network. 2074 A client, server, or proxy MAY close the transport connection at any 2075 time. For example, a client MAY have started to send a new request at 2076 the same time that the server has decided to close the "idle" 2077 connection. From the server's point of view, the connection is being 2078 closed while it was idle, but from the client's point of view, a request 2079 is in progress. 2081 This means that clients, servers, and proxies MUST be able to recover 2082 from asynchronous close events. Client software SHOULD reopen the 2083 transport connection and retransmit the aborted request without user 2084 interaction so long as the request method is idempotent (see section 2085 9.1.2); other methods MUST NOT be automatically retried, although user 2086 agents MAY offer a human operator the choice of retrying the request. 2088 However, this automatic retry SHOULD NOT be repeated if the second 2089 request fails. 2091 Servers SHOULD always respond to at least one request per connection, if 2092 at all possible. Servers SHOULD NOT close a connection in the middle of 2093 transmitting a response, unless a network or client failure is 2094 suspected. 2096 Clients that use persistent connections SHOULD limit the number of 2097 simultaneous connections that they maintain to a given server. A single- 2098 user client SHOULD maintain AT MOST 2 connections with any server or 2099 proxy. A proxy SHOULD use up to 2*N connections to another server or 2100 proxy, where N is the number of simultaneously active users. These 2101 guidelines are intended to improve HTTP response times and avoid 2102 congestion of the Internet or other networks. 2104 8.2 Message Transmission Requirements 2106 General requirements: 2108 o HTTP/1.1 servers SHOULD maintain persistent connections and use 2109 TCP's flow control mechanisms to resolve temporary overloads, 2110 rather than terminating connections with the expectation that 2111 clients will retry. The latter technique can exacerbate network 2112 congestion. 2114 o An HTTP/1.1 (or later) client sending a message-body SHOULD monitor 2115 the network connection for an error status while it is transmitting 2116 the request. If the client sees an error status, it SHOULD 2117 immediately cease transmitting the body. If the body is being sent 2118 using a "chunked" encoding (section 3.6), a zero length chunk and 2119 empty footer MAY be used to prematurely mark the end of the 2120 message. If the body was preceded by a Content-Length header, the 2121 client MUST close the connection. 2123 o An HTTP/1.1 (or later) client MUST be prepared to accept a 100 2124 (Continue) status followed by a regular response. 2126 o An HTTP/1.1 (or later) server that receives a request from a 2127 HTTP/1.0 (or earlier) client MUST NOT transmit the 100 (continue) 2128 response; it SHOULD either wait for the request to be completed 2129 normally (thus avoiding an interrupted request) or close the 2130 connection prematurely. 2132 Upon receiving a method subject to these requirements from an HTTP/1.1 2133 (or later) client, an HTTP/1.1 (or later) server MUST either respond 2134 with 100 (Continue) status and continue to read from the input stream, 2135 or respond with an error status. If it responds with an error status, it 2136 MAY close the transport (TCP) connection or it MAY continue to read and 2137 discard the rest of the request. It MUST NOT perform the requested 2138 method if it returns an error status. 2140 Clients SHOULD remember the version number of at least the most recently 2141 used server; if an HTTP/1.1 client has seen an HTTP/1.1 or later 2142 response from the server, and it sees the connection close before 2143 receiving any status from the server, the client SHOULD retry the 2144 request without user interaction so long as the request method is 2145 idempotent (see section 9.1.2); other methods MUST NOT be automatically 2146 retried, although user agents MAY offer a human operator the choice of 2147 retrying the request.. If the client does retry the request, the client 2149 o MUST first send the request header fields, and then 2151 o MUST wait for the server to respond with either a 100 (Continue) 2152 response, in which case the client should continue, or with an 2153 error status. 2155 If an HTTP/1.1 client has not seen an HTTP/1.1 or later response from 2156 the server, it should assume that the server implements HTTP/1.0 or 2157 older and will not use the 100 (Continue) response. If in this case the 2158 client sees the connection close before receiving any status from the 2159 server, the client SHOULD retry the request. If the client does retry 2160 the request, it should use the following "binary exponential backoff" 2161 algorithm to be assured of obtaining a reliable response: 2163 1. Initiate a new connection to the server 2165 2. Transmit the request-headers 2167 3. Initialize a variable R to the estimated round-trip time to the 2168 server (e.g., based on the time it took to establish the 2169 connection), or to a constant value of 5 seconds if the round-trip 2170 time is not available. 2172 4. Compute T = R * (2**N), where N is the number of previous retries 2173 of this request. 2175 5. Wait either for an error response from the server, or for T seconds 2176 (whichever comes first) 2178 6. If no error response is received, after T seconds transmit the body 2179 of the request. 2181 7. If client sees that the connection is closed prematurely, repeat 2182 from step 1 until the request is accepted, an error response is 2183 received, or the user becomes impatient and terminates the retry 2184 process. 2186 No matter what the server version, if an error status is received, the 2187 client 2188 o MUST NOT continue and 2190 o MUST close the connection if it has not completed sending the 2191 message. 2193 An HTTP/1.1 (or later) client that sees the connection close after 2194 receiving a 100 (Continue) but before receiving any other status SHOULD 2195 retry the request, and need not wait for 100 (Continue) response (but 2196 MAY do so if this simplifies the implementation). 2198 9 Method Definitions 2200 The set of common methods for HTTP/1.1 is defined below. Although this 2201 set can be expanded, additional methods cannot be assumed to share the 2202 same semantics for separately extended clients and servers. 2204 The Host request-header field (section 14.23) MUST accompany all 2205 HTTP/1.1 requests. 2207 9.1 Safe and Idempotent Methods 2209 9.1.1 Safe Methods 2211 Implementers should be aware that the software represents the user in 2212 their interactions over the Internet, and should be careful to allow the 2213 user to be aware of any actions they may take which may have an 2214 unexpected significance to themselves or others. 2216 In particular, the convention has been established that the GET and HEAD 2217 methods should never have the significance of taking an action other 2218 than retrieval. These methods should be considered "safe." This allows 2219 user agents to represent other methods, such as POST, PUT and DELETE, in 2220 a special way, so that the user is made aware of the fact that a 2221 possibly unsafe action is being requested. 2223 Naturally, it is not possible to ensure that the server does not 2224 generate side-effects as a result of performing a GET request; in fact, 2225 some dynamic resources consider that a feature. The important 2226 distinction here is that the user did not request the side-effects, so 2227 therefore cannot be held accountable for them. 2229 9.1.2 Idempotent Methods 2231 Methods may also have the property of "idempotence" in that (aside from 2232 error or expiration issues) the side-effects of N > 0 identical 2233 requests is the same as for a single request. The methods GET, HEAD, PUT 2234 and DELETE share this property. 2236 9.2 OPTIONS 2238 The OPTIONS method represents a request for information about the 2239 communication options available on the request/response chain identified 2240 by the Request-URI. This method allows the client to determine the 2241 options and/or requirements associated with a resource, or the 2242 capabilities of a server, without implying a resource action or 2243 initiating a resource retrieval. 2245 Unless the server's response is an error, the response MUST NOT include 2246 entity information other than what can be considered as communication 2247 options (e.g., Allow is appropriate, but Content-Type is not). Responses 2248 to this method are not cachable. 2250 If the Request-URI is an asterisk ("*"), the OPTIONS request is intended 2251 to apply to the server as a whole. A 200 response SHOULD include any 2252 header fields which indicate optional features implemented by the server 2253 (e.g., Public), including any extensions not defined by this 2254 specification, in addition to any applicable general or response-header 2255 fields. As described in section 5.1.2, an "OPTIONS *" request can be 2256 applied through a proxy by specifying the destination server in the 2257 Request-URI without any path information. 2259 If the Request-URI is not an asterisk, the OPTIONS request applies only 2260 to the options that are available when communicating with that resource. 2261 A 200 response SHOULD include any header fields which indicate optional 2262 features implemented by the server and applicable to that resource 2263 (e.g., Allow), including any extensions not defined by this 2264 specification, in addition to any applicable general or response-header 2265 fields. If the OPTIONS request passes through a proxy, the proxy MUST 2266 edit the response to exclude those options which apply to a proxy's 2267 capabilities and which are known to be unavailable through that proxy. 2269 9.3 GET 2271 The GET method means retrieve whatever information (in the form of an 2272 entity) is identified by the Request-URI. If the Request-URI refers to a 2273 data-producing process, it is the produced data which shall be returned 2274 as the entity in the response and not the source text of the process, 2275 unless that text happens to be the output of the process. 2277 The semantics of the GET method change to a "conditional GET" if the 2278 request message includes an If-Modified-Since, If-Unmodified-Since, If- 2279 Match, If-None-Match, or If-Range header field. A conditional GET method 2280 requests that the entity be transferred only under the circumstances 2281 described by the conditional header field(s). The conditional GET method 2282 is intended to reduce unnecessary network usage by allowing cached 2283 entities to be refreshed without requiring multiple requests or 2284 transferring data already held by the client. 2286 The semantics of the GET method change to a "partial GET" if the request 2287 message includes a Range header field. A partial GET requests that only 2288 part of the entity be transferred, as described in section 14.36. The 2289 partial GET method is intended to reduce unnecessary network usage by 2290 allowing partially-retrieved entities to be completed without 2291 transferring data already held by the client. 2293 The response to a GET request is cachable if and only if it meets the 2294 requirements for HTTP caching described in section 13. 2296 9.4 HEAD 2298 The HEAD method is identical to GET except that the server MUST NOT 2299 return a message-body in the response. The metainformation contained in 2300 the HTTP headers in response to a HEAD request SHOULD be identical to 2301 the information sent in response to a GET request. This method can be 2302 used for obtaining metainformation about the entity implied by the 2303 request without transferring the entity-body itself. This method is 2304 often used for testing hypertext links for validity, accessibility, and 2305 recent modification. 2307 The response to a HEAD request may be cachable in the sense that the 2308 information contained in the response may be used to update a previously 2309 cached entity from that resource. If the new field values indicate that 2310 the cached entity differs from the current entity (as would be indicated 2311 by a change in Content-Length, Content-MD5, ETag or Last-Modified), then 2312 the cache MUST treat the cache entry as stale. 2314 9.5 POST 2316 The POST method is used to request that the destination server accept 2317 the entity enclosed in the request as a new subordinate of the resource 2318 identified by the Request-URI in the Request-Line. POST is designed to 2319 allow a uniform method to cover the following functions: 2321 o Annotation of existing resources; 2323 o Posting a message to a bulletin board, newsgroup, mailing list, or 2324 similar group of articles; 2326 o Providing a block of data, such as the result of submitting a form, 2327 to a data-handling process; 2329 o Extending a database through an append operation. 2331 The actual function performed by the POST method is determined by the 2332 server and is usually dependent on the Request-URI. The posted entity is 2333 subordinate to that URI in the same way that a file is subordinate to a 2334 directory containing it, a news article is subordinate to a newsgroup to 2335 which it is posted, or a record is subordinate to a database. 2337 The action performed by the POST method might not result in a resource 2338 that can be identified by a URI. In this case, either 200 (OK) or 204 2339 (No Content) is the appropriate response status, depending on whether or 2340 not the response includes an entity that describes the result. 2342 If a resource has been created on the origin server, the response SHOULD 2343 be 201 (Created) and contain an entity which describes the status of the 2344 request and refers to the new resource, and a Location header (see 2345 section 14.30). 2347 Responses to this method are not cachable, unless the response includes 2348 appropriate Cache-Control or Expires header fields. However, the 303 2349 (See Other) response can be used to direct the user agent to retrieve a 2350 cachable resource. 2352 POST requests must obey the message transmission requirements set out in 2353 section 8.2. 2355 9.6 PUT 2357 The PUT method requests that the enclosed entity be stored under the 2358 supplied Request-URI. If the Request-URI refers to an already existing 2359 resource, the enclosed entity SHOULD be considered as a modified version 2360 of the one residing on the origin server. If the Request-URI does not 2361 point to an existing resource, and that URI is capable of being defined 2362 as a new resource by the requesting user agent, the origin server can 2363 create the resource with that URI. If a new resource is created, the 2364 origin server MUST inform the user agent via the 201 (Created) response. 2365 If an existing resource is modified, either the 200 (OK) or 204 (No 2366 Content) response codes SHOULD be sent to indicate successful completion 2367 of the request. If the resource could not be created or modified with 2368 the Request-URI, an appropriate error response SHOULD be given that 2369 reflects the nature of the problem. The recipient of the entity MUST NOT 2370 ignore any Content-* (e.g. Content-Range) headers that it does not 2371 understand or implement and MUST return a 501 (Not Implemented) response 2372 in such cases. 2374 If the request passes through a cache and the Request-URI identifies one 2375 or more currently cached entities, those entries should be treated as 2376 stale. Responses to this method are not cachable. 2378 The fundamental difference between the POST and PUT requests is 2379 reflected in the different meaning of the Request-URI. The URI in a POST 2380 request identifies the resource that will handle the enclosed entity. 2381 That resource may be a data-accepting process, a gateway to some other 2382 protocol, or a separate entity that accepts annotations. In contrast, 2383 the URI in a PUT request identifies the entity enclosed with the request 2384 -- the user agent knows what URI is intended and the server MUST NOT 2385 attempt to apply the request to some other resource. If the server 2386 desires that the request be applied to a different URI, it MUST send a 2387 301 (Moved Permanently) response; the user agent MAY then make its own 2388 decision regarding whether or not to redirect the request. 2390 A single resource MAY be identified by many different URIs. For example, 2391 an article may have a URI for identifying "the current version" which is 2392 separate from the URI identifying each particular version. In this case, 2393 a PUT request on a general URI may result in several other URIs being 2394 defined by the origin server. 2396 HTTP/1.1 does not define how a PUT method affects the state of an origin 2397 server. 2399 PUT requests must obey the message transmission requirements set out in 2400 section 8.2. 2402 9.7 DELETE 2404 The DELETE method requests that the origin server delete the resource 2405 identified by the Request-URI. This method MAY be overridden by human 2406 intervention (or other means) on the origin server. The client cannot be 2407 guaranteed that the operation has been carried out, even if the status 2408 code returned from the origin server indicates that the action has been 2409 completed successfully. However, the server SHOULD not indicate success 2410 unless, at the time the response is given, it intends to delete the 2411 resource or move it to an inaccessible location. 2413 A successful response SHOULD be 200 (OK) if the response includes an 2414 entity describing the status, 202 (Accepted) if the action has not yet 2415 been enacted, or 204 (No Content) if the response is OK but does not 2416 include an entity. 2418 If the request passes through a cache and the Request-URI identifies one 2419 or more currently cached entities, those entries should be treated as 2420 stale. Responses to this method are not cachable. 2422 9.8 TRACE 2424 The TRACE method is used to invoke a remote, application-layer loop-back 2425 of the request message. The final recipient of the request SHOULD 2426 reflect the message received back to the client as the entity-body of a 2427 200 (OK) response. The final recipient is either the origin server or 2428 the first proxy or gateway to receive a Max-Forwards value of zero (0) 2429 in the request (see section 14.31). A TRACE request MUST NOT include an 2430 entity. 2432 TRACE allows the client to see what is being received at the other end 2433 of the request chain and use that data for testing or diagnostic 2434 information. The value of the Via header field (section 14.44) is of 2435 particular interest, since it acts as a trace of the request chain. Use 2436 of the Max-Forwards header field allows the client to limit the length 2437 of the request chain, which is useful for testing a chain of proxies 2438 forwarding messages in an infinite loop. 2440 If successful, the response SHOULD contain the entire request message in 2441 the entity-body, with a Content-Type of "message/http". Responses to 2442 this method MUST NOT be cached. 2444 10 Status Code Definitions 2446 Each Status-Code is described below, including a description of which 2447 method(s) it can follow and any metainformation required in the 2448 response. 2450 10.1 Informational 1xx 2452 This class of status code indicates a provisional response, consisting 2453 only of the Status-Line and optional headers, and is terminated by an 2454 empty line. Since HTTP/1.0 did not define any 1xx status codes, servers 2455 MUST NOT send a 1xx response to an HTTP/1.0 client except under 2456 experimental conditions. 2458 10.1.1 100 Continue 2460 The client may continue with its request. This interim response is used 2461 to inform the client that the initial part of the request has been 2462 received and has not yet been rejected by the server. The client SHOULD 2463 continue by sending the remainder of the request or, if the request has 2464 already been completed, ignore this response. The server MUST send a 2465 final response after the request has been completed. 2467 10.1.2 101 Switching Protocols 2469 The server understands and is willing to comply with the client's 2470 request, via the Upgrade message header field (section 14.41), for a 2471 change in the application protocol being used on this connection. The 2472 server will switch protocols to those defined by the response's Upgrade 2473 header field immediately after the empty line which terminates the 101 2474 response. 2476 The protocol should only be switched when it is advantageous to do so. 2477 For example, switching to a newer version of HTTP is advantageous over 2478 older versions, and switching to a real-time, synchronous protocol may 2479 be advantageous when delivering resources that use such features. 2481 10.2 Successful 2xx 2483 This class of status code indicates that the client's request was 2484 successfully received, understood, and accepted. 2486 10.2.1 200 OK 2488 The request has succeeded. The information returned with the response is 2489 dependent on the method used in the request, for example: 2491 GET an entity corresponding to the requested resource is sent in the 2492 response; 2494 HEAD the entity-header fields corresponding to the requested resource 2495 are sent in the response without any message-body; 2497 POST an entity describing or containing the result of the action; 2499 TRACE an entity containing the request message as received by the end 2500 server. 2502 10.2.2 201 Created 2504 The request has been fulfilled and resulted in a new resource being 2505 created. The newly created resource can be referenced by the URI(s) 2506 returned in the entity of the response, with the most specific URL for 2507 the resource given by a Location header field. The origin server MUST 2508 create the resource before returning the 201 status code. If the action 2509 cannot be carried out immediately, the server should respond with 202 2510 (Accepted) response instead. 2512 10.2.3 202 Accepted 2514 The request has been accepted for processing, but the processing has not 2515 been completed. The request MAY or MAY NOT eventually be acted upon, as 2516 it MAY be disallowed when processing actually takes place. There is no 2517 facility for re-sending a status code from an asynchronous operation 2518 such as this. 2520 The 202 response is intentionally non-committal. Its purpose is to allow 2521 a server to accept a request for some other process (perhaps a batch- 2522 oriented process that is only run once per day) without requiring that 2523 the user agent's connection to the server persist until the process is 2524 completed. The entity returned with this response SHOULD include an 2525 indication of the request's current status and either a pointer to a 2526 status monitor or some estimate of when the user can expect the request 2527 to be fulfilled. 2529 10.2.4 203 Non-Authoritative Information 2531 The returned metainformation in the entity-header is not the definitive 2532 set as available from the origin server, but is gathered from a local or 2533 a third-party copy. The set presented MAY be a subset or superset of the 2534 original version. For example, including local annotation information 2535 about the resource MAY result in a superset of the metainformation known 2536 by the origin server. Use of this response code is not required and is 2537 only appropriate when the response would otherwise be 200 (OK). 2539 10.2.5 204 No Content 2541 The server has fulfilled the request but there is no new information to 2542 send back. If the client is a user agent, it SHOULD NOT change its 2543 document view from that which caused the request to be sent. This 2544 response is primarily intended to allow input for actions to take place 2545 without causing a change to the user agent's active document view. The 2546 response MAY include new metainformation in the form of entity-headers, 2547 which SHOULD apply to the document currently in the user agent's active 2548 view. 2550 The 204 response MUST NOT include a message-body, and thus is always 2551 terminated by the first empty line after the header fields. 2553 10.2.6 205 Reset Content 2555 The server has fulfilled the request and the user agent SHOULD reset the 2556 document view which caused the request to be sent. This response is 2557 primarily intended to allow input for actions to take place via user 2558 input, followed by a clearing of the form in which the input is given so 2559 that the user can easily initiate another input action. The response 2560 MUST NOT include an entity. 2562 10.2.7 206 Partial Content 2564 The server has fulfilled the partial GET request for the resource. The 2565 request must have included a Range header field (section 14.36) 2566 indicating the desired range. The response MUST include either a 2567 Content-Range header field (section 14.17) indicating the range included 2568 with this response, or a multipart/byteranges Content-Type including 2569 Content-Range fields for each part. If multipart/byteranges is not used, 2570 the Content-Length header field in the response MUST match the actual 2571 number of OCTETs transmitted in the message-body. 2573 A cache that does not support the Range and Content-Range headers MUST 2574 NOT cache 206 (Partial) responses. 2576 10.3 Redirection 3xx 2578 This class of status code indicates that further action needs to be 2579 taken by the user agent in order to fulfill the request. The action 2580 required MAY be carried out by the user agent without interaction with 2581 the user if and only if the method used in the second request is GET or 2582 HEAD. A user agent SHOULD NOT automatically redirect a request more than 2583 5 times, since such redirections usually indicate an infinite loop. 2585 10.3.1 300 Multiple Choices 2587 The requested resource corresponds to any one of a set of 2588 representations, each with its own specific location, and agent-driven 2589 negotiation information (section 12) is being provided so that the user 2590 (or user agent) can select a preferred representation and redirect its 2591 request to that location. 2593 Unless it was a HEAD request, the response SHOULD include an entity 2594 containing a list of resource characteristics and location(s) from which 2595 the user or user agent can choose the one most appropriate. The entity 2596 format is specified by the media type given in the Content-Type header 2597 field. Depending upon the format and the capabilities of the user agent, 2598 selection of the most appropriate choice may be performed automatically. 2599 However, this specification does not define any standard for such 2600 automatic selection. 2602 If the server has a preferred choice of representation, it SHOULD 2603 include the specific URL for that representation in the Location field; 2604 user agents MAY use the Location field value for automatic redirection. 2605 This response is cachable unless indicated otherwise. 2607 10.3.2 301 Moved Permanently 2609 The requested resource has been assigned a new permanent URI and any 2610 future references to this resource SHOULD be done using one of the 2611 returned URIs. Clients with link editing capabilities SHOULD 2612 automatically re-link references to the Request-URI to one or more of 2613 the new references returned by the server, where possible. This response 2614 is cachable unless indicated otherwise. 2616 If the new URI is a location, its URL SHOULD be given by the Location 2617 field in the response. Unless the request method was HEAD, the entity of 2618 the response SHOULD contain a short hypertext note with a hyperlink to 2619 the new URI(s). 2621 If the 301 status code is received in response to a request other than 2622 GET or HEAD, the user agent MUST NOT automatically redirect the request 2623 unless it can be confirmed by the user, since this might change the 2624 conditions under which the request was issued. 2626 Note: When automatically redirecting a POST request after receiving 2627 a 301 status code, some existing HTTP/1.0 user agents will 2628 erroneously change it into a GET request. 2630 10.3.3 302 Moved Temporarily 2632 The requested resource resides temporarily under a different URI. Since 2633 the redirection may be altered on occasion, the client SHOULD continue 2634 to use the Request-URI for future requests. This response is only 2635 cachable if indicated by a Cache-Control or Expires header field. 2637 If the new URI is a location, its URL SHOULD be given by the Location 2638 field in the response. Unless the request method was HEAD, the entity of 2639 the response SHOULD contain a short hypertext note with a hyperlink to 2640 the new URI(s). 2642 If the 302 status code is received in response to a request other than 2643 GET or HEAD, the user agent MUST NOT automatically redirect the request 2644 unless it can be confirmed by the user, since this might change the 2645 conditions under which the request was issued. 2647 Note: When automatically redirecting a POST request after receiving 2648 a 302 status code, some existing HTTP/1.0 user agents will 2649 erroneously change it into a GET request. 2651 10.3.4 303 See Other 2653 The response to the request can be found under a different URI and 2654 SHOULD be retrieved using a GET method on that resource. This method 2655 exists primarily to allow the output of a POST-activated script to 2656 redirect the user agent to a selected resource. The new URI is not a 2657 substitute reference for the originally requested resource. The 303 2658 response is not cachable, but the response to the second (redirected) 2659 request MAY be cachable. 2661 If the new URI is a location, its URL SHOULD be given by the Location 2662 field in the response. Unless the request method was HEAD, the entity of 2663 the response SHOULD contain a short hypertext note with a hyperlink to 2664 the new URI(s). 2666 10.3.5 304 Not Modified 2668 If the client has performed a conditional GET request and access is 2669 allowed, but the document has not been modified, the server SHOULD 2670 respond with this status code. The response MUST NOT contain a message- 2671 body. 2673 The response MUST include the following header fields: 2675 o Date 2677 o ETag and/or Content-Location, if the header would have been sent in 2678 a 200 response to the same request 2680 o Expires, Cache-Control, and/or Vary, if the field-value might 2681 differ from that sent in any previous response for the same variant 2683 If the conditional GET used a strong cache validator (see section 2684 13.3.3), the response SHOULD NOT include other entity-headers. Otherwise 2685 (i.e., the conditional GET used a weak validator), the response MUST NOT 2686 include other entity-headers; this prevents inconsistencies between 2687 cached entity-bodies and updated headers. 2689 If a 304 response indicates an entity not currently cached, then the 2690 cache MUST disregard the response and repeat the request without the 2691 conditional. 2693 If a cache uses a received 304 response to update a cache entry, the 2694 cache MUST update the entry to reflect any new field values given in the 2695 response. 2697 The 304 response MUST NOT include a message-body, and thus is always 2698 terminated by the first empty line after the header fields. 2700 10.3.6 305 Use Proxy 2702 The requested resource MUST be accessed through the proxy given by the 2703 Location field. The Location field gives the URL of the proxy. The 2704 recipient is expected to repeat the request via the proxy. 2706 10.4 Client Error 4xx 2708 The 4xx class of status code is intended for cases in which the client 2709 seems to have erred. Except when responding to a HEAD request, the 2710 server SHOULD include an entity containing an explanation of the error 2711 situation, and whether it is a temporary or permanent condition. These 2712 status codes are applicable to any request method. User agents SHOULD 2713 display any included entity to the user. 2715 Note: If the client is sending data, a server implementation using 2716 TCP should be careful to ensure that the client acknowledges 2717 receipt of the packet(s) containing the response, before the server 2718 closes the input connection. If the client continues sending data 2719 to the server after the close, the server's TCP stack will send a 2720 reset packet to the client, which may erase the client's 2721 unacknowledged input buffers before they can be read and 2722 interpreted by the HTTP application. 2724 10.4.1 400 Bad Request 2726 The request could not be understood by the server due to malformed 2727 syntax. The client SHOULD NOT repeat the request without modifications. 2729 10.4.2 401 Unauthorized 2731 The request requires user authentication. The response MUST include a 2732 WWW-Authenticate header field (section 14.46) containing a challenge 2733 applicable to the requested resource. The client MAY repeat the request 2734 with a suitable Authorization header field (section 14.8). If the 2735 request already included Authorization credentials, then the 401 2736 response indicates that authorization has been refused for those 2737 credentials. If the 401 response contains the same challenge as the 2738 prior response, and the user agent has already attempted authentication 2739 at least once, then the user SHOULD be presented the entity that was 2740 given in the response, since that entity MAY include relevant diagnostic 2741 information. HTTP access authentication is explained in section 11. 2743 10.4.3 402 Payment Required 2745 This code is reserved for future use. 2747 10.4.4 403 Forbidden 2749 The server understood the request, but is refusing to fulfill it. 2750 Authorization will not help and the request SHOULD NOT be repeated. If 2751 the request method was not HEAD and the server wishes to make public why 2752 the request has not been fulfilled, it SHOULD describe the reason for 2753 the refusal in the entity. This status code is commonly used when the 2754 server does not wish to reveal exactly why the request has been refused, 2755 or when no other response is applicable. 2757 10.4.5 404 Not Found 2759 The server has not found anything matching the Request-URI. No 2760 indication is given of whether the condition is temporary or permanent. 2762 If the server does not wish to make this information available to the 2763 client, the status code 403 (Forbidden) can be used instead. The 410 2764 (Gone) status code SHOULD be used if the server knows, through some 2765 internally configurable mechanism, that an old resource is permanently 2766 unavailable and has no forwarding address. 2768 10.4.6 405 Method Not Allowed 2770 The method specified in the Request-Line is not allowed for the resource 2771 identified by the Request-URI. The response MUST include an Allow header 2772 containing a list of valid methods for the requested resource. 2774 10.4.7 406 Not Acceptable 2776 The resource identified by the request is only capable of generating 2777 response entities which have content characteristics not acceptable 2778 according to the accept headers sent in the request. 2780 Unless it was a HEAD request, the response SHOULD include an entity 2781 containing a list of available entity characteristics and location(s) 2782 from which the user or user agent can choose the one most appropriate. 2783 The entity format is specified by the media type given in the Content- 2784 Type header field. Depending upon the format and the capabilities of the 2785 user agent, selection of the most appropriate choice may be performed 2786 automatically. However, this specification does not define any standard 2787 for such automatic selection. 2789 Note: HTTP/1.1 servers are allowed to return responses which are 2790 not acceptable according to the accept headers sent in the request. 2791 In some cases, this may even be preferable to sending a 406 2792 response. User agents are encouraged to inspect the headers of an 2793 incoming response to determine if it is acceptable. If the response 2794 could be unacceptable, a user agent SHOULD temporarily stop receipt 2795 of more data and query the user for a decision on further actions. 2797 10.4.8 407 Proxy Authentication Required 2799 This code is similar to 401 (Unauthorized), but indicates that the 2800 client MUST first authenticate itself with the proxy. The proxy MUST 2801 return a Proxy-Authenticate header field (section 14.33) containing a 2802 challenge applicable to the proxy for the requested resource. The client 2803 MAY repeat the request with a suitable Proxy-Authorization header field 2804 (section 14.34). HTTP access authentication is explained in section 11. 2806 10.4.9 408 Request Timeout 2808 The client did not produce a request within the time that the server was 2809 prepared to wait. The client MAY repeat the request without 2810 modifications at any later time. 2812 10.4.10 409 Conflict 2814 The request could not be completed due to a conflict with the current 2815 state of the resource. This code is only allowed in situations where it 2816 is expected that the user might be able to resolve the conflict and 2817 resubmit the request. The response body SHOULD include enough 2818 information for the user to recognize the source of the conflict. 2819 Ideally, the response entity would include enough information for the 2820 user or user agent to fix the problem; however, that may not be possible 2821 and is not required. 2823 Conflicts are most likely to occur in response to a PUT request. If 2824 versioning is being used and the entity being PUT includes changes to a 2825 resource which conflict with those made by an earlier (third-party) 2826 request, the server MAY use the 409 response to indicate that it can't 2827 complete the request. In this case, the response entity SHOULD contain a 2828 list of the differences between the two versions in a format defined by 2829 the response Content-Type. 2831 10.4.11 410 Gone 2833 The requested resource is no longer available at the server and no 2834 forwarding address is known. This condition SHOULD be considered 2835 permanent. Clients with link editing capabilities SHOULD delete 2836 references to the Request-URI after user approval. If the server does 2837 not know, or has no facility to determine, whether or not the condition 2838 is permanent, the status code 404 (Not Found) SHOULD be used instead. 2839 This response is cachable unless indicated otherwise. 2841 The 410 response is primarily intended to assist the task of web 2842 maintenance by notifying the recipient that the resource is 2843 intentionally unavailable and that the server owners desire that remote 2844 links to that resource be removed. Such an event is common for limited- 2845 time, promotional services and for resources belonging to individuals no 2846 longer working at the server's site. It is not necessary to mark all 2847 permanently unavailable resources as "gone" or to keep the mark for any 2848 length of time -- that is left to the discretion of the server owner. 2850 10.4.12 411 Length Required 2852 The server refuses to accept the request without a defined Content- 2853 Length. The client MAY repeat the request if it adds a valid Content- 2854 Length header field containing the length of the message-body in the 2855 request message. 2857 10.4.13 412 Precondition Failed 2859 The precondition given in one or more of the request-header fields 2860 evaluated to false when it was tested on the server. This response code 2861 allows the client to place preconditions on the current resource 2862 metainformation (header field data) and thus prevent the requested 2863 method from being applied to a resource other than the one intended. 2865 10.4.14 413 Request Entity Too Large 2867 The server is refusing to process a request because the request entity 2868 is larger than the server is willing or able to process. The server may 2869 close the connection to prevent the client from continuing the request. 2871 If the condition is temporary, the server SHOULD include a Retry-After 2872 header field to indicate that it is temporary and after what time the 2873 client may try again. 2875 10.4.15 414 Request-URI Too Long 2877 The server is refusing to service the request because the Request-URI is 2878 longer than the server is willing to interpret. This rare condition is 2879 only likely to occur when a client has improperly converted a POST 2880 request to a GET request with long query information, when the client 2881 has descended into a URL "black hole" of redirection (e.g., a redirected 2882 URL prefix that points to a suffix of itself), or when the server is 2883 under attack by a client attempting to exploit security holes present in 2884 some servers using fixed-length buffers for reading or manipulating the 2885 Request-URI. 2887 10.4.16 415 Unsupported Media Type 2889 The server is refusing to service the request because the entity of the 2890 request is in a format not supported by the requested resource for the 2891 requested method. 2893 10.5 Server Error 5xx 2895 Response status codes beginning with the digit "5" indicate cases in 2896 which the server is aware that it has erred or is incapable of 2897 performing the request. Except when responding to a HEAD request, the 2898 server SHOULD include an entity containing an explanation of the error 2899 situation, and whether it is a temporary or permanent condition. User 2900 agents SHOULD display any included entity to the user. These response 2901 codes are applicable to any request method. 2903 10.5.1 500 Internal Server Error 2905 The server encountered an unexpected condition which prevented it from 2906 fulfilling the request. 2908 10.5.2 501 Not Implemented 2910 The server does not support the functionality required to fulfill the 2911 request. This is the appropriate response when the server does not 2912 recognize the request method and is not capable of supporting it for any 2913 resource. 2915 10.5.3 502 Bad Gateway 2917 The server, while acting as a gateway or proxy, received an invalid 2918 response from the upstream server it accessed in attempting to fulfill 2919 the request. 2921 10.5.4 503 Service Unavailable 2923 The server is currently unable to handle the request due to a temporary 2924 overloading or maintenance of the server. The implication is that this 2925 is a temporary condition which will be alleviated after some delay. If 2926 known, the length of the delay may be indicated in a Retry-After header. 2927 If no Retry-After is given, the client SHOULD handle the response as it 2928 would for a 500 response. 2930 Note: The existence of the 503 status code does not imply that a 2931 server must use it when becoming overloaded. Some servers may wish 2932 to simply refuse the connection. 2934 10.5.5 504 Gateway Timeout 2936 The server, while acting as a gateway or proxy, did not receive a timely 2937 response from the upstream server it accessed in attempting to complete 2938 the request. 2940 10.5.6 505 HTTP Version Not Supported 2942 The server does not support, or refuses to support, the HTTP protocol 2943 version that was used in the request message. The server is indicating 2944 that it is unable or unwilling to complete the request using the same 2945 major version as the client, as described in section 3.1, other than 2946 with this error message. The response SHOULD contain an entity 2947 describing why that version is not supported and what other protocols 2948 are supported by that server. 2950 11 Access Authentication 2952 HTTP provides a simple challenge-response authentication mechanism which 2953 MAY be used by a server to challenge a client request and by a client to 2954 provide authentication information. It uses an extensible, case- 2955 insensitive token to identify the authentication scheme, followed by a 2956 comma-separated list of attribute-value pairs which carry the parameters 2957 necessary for achieving authentication via that scheme. 2959 auth-scheme = token 2961 auth-param = token "=" quoted-string 2963 The 401 (Unauthorized) response message is used by an origin server to 2964 challenge the authorization of a user agent. This response MUST include 2965 a WWW-Authenticate header field containing at least one challenge 2966 applicable to the requested resource. 2968 challenge = auth-scheme 1*SP realm *( "," auth-param ) 2970 realm = "realm" "=" realm-value 2971 realm-value = quoted-string 2973 The realm attribute (case-insensitive) is required for all 2974 authentication schemes which issue a challenge. The realm value (case- 2975 sensitive), in combination with the canonical root URL (see section 2976 5.1.2) of the server being accessed, defines the protection space. These 2977 realms allow the protected resources on a server to be partitioned into 2978 a set of protection spaces, each with its own authentication scheme 2979 and/or authorization database. The realm value is a string, generally 2980 assigned by the origin server, which may have additional semantics 2981 specific to the authentication scheme. 2983 A user agent that wishes to authenticate itself with a server--usually, 2984 but not necessarily, after receiving a 401 or 411 response--MAY do so by 2985 including an Authorization header field with the request. The 2986 Authorization field value consists of credentials containing the 2987 authentication information of the user agent for the realm of the 2988 resource being requested. 2990 credentials = basic-credentials 2991 | auth-scheme #auth-param 2993 The domain over which credentials can be automatically applied by a user 2994 agent is determined by the protection space. If a prior request has been 2995 authorized, the same credentials MAY be reused for all other requests 2996 within that protection space for a period of time determined by the 2997 authentication scheme, parameters, and/or user preference. Unless 2998 otherwise defined by the authentication scheme, a single protection 2999 space cannot extend outside the scope of its server. 3001 If the server does not wish to accept the credentials sent with a 3002 request, it SHOULD return a 401 (Unauthorized) response. The response 3003 MUST include a WWW-Authenticate header field containing the (possibly 3004 new) challenge applicable to the requested resource and an entity 3005 explaining the refusal. 3007 The HTTP protocol does not restrict applications to this simple 3008 challenge-response mechanism for access authentication. Additional 3009 mechanisms MAY be used, such as encryption at the transport level or via 3010 message encapsulation, and with additional header fields specifying 3011 authentication information. However, these additional mechanisms are not 3012 defined by this specification. 3014 Proxies MUST be completely transparent regarding user agent 3015 authentication. That is, they MUST forward the WWW-Authenticate and 3016 Authorization headers untouched, and follow the rules found in section 3017 14.8. 3019 HTTP/1.1 allows a client to pass authentication information to and from 3020 a proxy via the Proxy-Authenticate and Proxy-Authorization headers. 3022 11.1 Basic Authentication Scheme 3024 The "basic" authentication scheme is based on the model that the user 3025 agent must authenticate itself with a user-ID and a password for each 3026 realm. The realm value should be considered an opaque string which can 3027 only be compared for equality with other realms on that server. The 3028 server will service the request only if it can validate the user-ID and 3029 password for the protection space of the Request-URI. There are no 3030 optional authentication parameters. 3032 Upon receipt of an unauthorized request for a URI within the protection 3033 space, the server MAY respond with a challenge like the following: 3035 WWW-Authenticate: Basic realm="WallyWorld" 3037 where "WallyWorld" is the string assigned by the server to identify the 3038 protection space of the Request-URI. 3040 To receive authorization, the client sends the userid and password, 3041 separated by a single colon (":") character, within a base64 encoded 3042 string in the credentials. 3044 basic-credentials = "Basic" SP basic-cookie 3045 basic-cookie = 3048 user-pass = userid ":" password 3050 userid = * 3052 password = *TEXT 3054 Userids might be case sensitive. 3056 If the user agent wishes to send the userid "Aladdin" and password "open 3057 sesame", it would use the following header field: 3059 Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 3061 See section 15 for security considerations associated with Basic 3062 authentication. 3064 11.2 Digest Authentication Scheme 3066 Note for the RFC editor: This section is reserved for including the 3067 Digest Authentication specification, or if the RFC editor chooses to 3068 issue a single RFC rather than two RFC's, this section should be 3069 deleted. 3071 12 Content Negotiation 3073 Most HTTP responses include an entity which contains information for 3074 interpretation by a human user. Naturally, it is desirable to supply the 3075 user with the "best available" entity corresponding to the request. 3076 Unfortunately for servers and caches, not all users have the same 3077 preferences for what is "best," and not all user agents are equally 3078 capable of rendering all entity types. For that reason, HTTP has 3079 provisions for several mechanisms for "content negotiation" -- the 3080 process of selecting the best representation for a given response when 3081 there are multiple representations available. 3083 Note: This is not called "format negotiation" because the alternate 3084 representations may be of the same media type, but use different 3085 capabilities of that type, be in different languages, etc. 3087 Any response containing an entity-body MAY be subject to negotiation, 3088 including error responses. 3090 There are two kinds of content negotiation which are possible in HTTP: 3091 server-driven and agent-driven negotiation. These two kinds of 3092 negotiation are orthogonal and thus may be used separately or in 3093 combination. One method of combination, referred to as transparent 3094 negotiation, occurs when a cache uses the agent-driven negotiation 3095 information provided by the origin server in order to provide server- 3096 driven negotiation for subsequent requests. 3098 12.1 Server-driven Negotiation 3100 If the selection of the best representation for a response is made by an 3101 algorithm located at the server, it is called server-driven negotiation. 3102 Selection is based on the available representations of the response (the 3103 dimensions over which it can vary; e.g. language, content-coding, etc.) 3104 and the contents of particular header fields in the request message or 3105 on other information pertaining to the request (such as the network 3106 address of the client). 3108 Server-driven negotiation is advantageous when the algorithm for 3109 selecting from among the available representations is difficult to 3110 describe to the user agent, or when the server desires to send its "best 3111 guess" to the client along with the first response (hoping to avoid the 3112 round-trip delay of a subsequent request if the "best guess" is good 3113 enough for the user). In order to improve the server's guess, the user 3114 agent MAY include request header fields (Accept, Accept-Language, 3115 Accept-Encoding, etc.) which describe its preferences for such a 3116 response. 3118 Server-driven negotiation has disadvantages: 3120 1. It is impossible for the server to accurately determine what might be 3121 "best" for any given user, since that would require complete 3122 knowledge of both the capabilities of the user agent and the intended 3123 use for the response (e.g., does the user want to view it on screen 3124 or print it on paper?). 3126 2. Having the user agent describe its capabilities in every request can 3127 be both very inefficient (given that only a small percentage of 3128 responses have multiple representations) and a potential violation of 3129 the user's privacy. 3131 3. It complicates the implementation of an origin server and the 3132 algorithms for generating responses to a request. 3134 4. It may limit a public cache's ability to use the same response for 3135 multiple user's requests. 3137 HTTP/1.1 includes the following request-header fields for enabling 3138 server-driven negotiation through description of user agent capabilities 3139 and user preferences: Accept (section 14.1), Accept-Charset (section 3140 14.2), Accept-Encoding (section 14.3), Accept-Language (section 14.4), 3141 and User-Agent (section 14.42). However, an origin server is not limited 3142 to these dimensions and MAY vary the response based on any aspect of the 3143 request, including information outside the request-header fields or 3144 within extension header fields not defined by this specification. 3146 HTTP/1.1 origin servers MUST include an appropriate Vary header field 3147 (section 14.43) in any cachable response based on server-driven 3148 negotiation. The Vary header field describes the dimensions over which 3149 the response might vary (i.e. the dimensions over which the origin 3150 server picks its "best guess" response from multiple representations). 3152 HTTP/1.1 public caches MUST recognize the Vary header field when it is 3153 included in a response and obey the requirements described in section 3154 13.6 that describes the interactions between caching and content 3155 negotiation. 3157 12.2 Agent-driven Negotiation 3159 With agent-driven negotiation, selection of the best representation for 3160 a response is performed by the user agent after receiving an initial 3161 response from the origin server. Selection is based on a list of the 3162 available representations of the response included within the header 3163 fields (this specification reserves the field-name Alternates, as 3164 described in appendix 19.6.2.1) or entity-body of the initial response, 3165 with each representation identified by its own URI. Selection from among 3166 the representations may be performed automatically (if the user agent is 3167 capable of doing so) or manually by the user selecting from a generated 3168 (possibly hypertext) menu. 3170 Agent-driven negotiation is advantageous when the response would vary 3171 over commonly-used dimensions (such as type, language, or encoding), 3172 when the origin server is unable to determine a user agent's 3173 capabilities from examining the request, and generally when public 3174 caches are used to distribute server load and reduce network usage. 3176 Agent-driven negotiation suffers from the disadvantage of needing a 3177 second request to obtain the best alternate representation. This second 3178 request is only efficient when caching is used. In addition, this 3179 specification does not define any mechanism for supporting automatic 3180 selection, though it also does not prevent any such mechanism from being 3181 developed as an extension and used within HTTP/1.1. 3183 HTTP/1.1 defines the 300 (Multiple Choices) and 406 (Not Acceptable) 3184 status codes for enabling agent-driven negotiation when the server is 3185 unwilling or unable to provide a varying response using server-driven 3186 negotiation. 3188 12.3 Transparent Negotiation 3190 Transparent negotiation is a combination of both server-driven and 3191 agent-driven negotiation. When a cache is supplied with a form of the 3192 list of available representations of the response (as in agent-driven 3193 negotiation) and the dimensions of variance are completely understood by 3194 the cache, then the cache becomes capable of performing server-driven 3195 negotiation on behalf of the origin server for subsequent requests on 3196 that resource. 3198 Transparent negotiation has the advantage of distributing the 3199 negotiation work that would otherwise be required of the origin server 3200 and also removing the second request delay of agent-driven negotiation 3201 when the cache is able to correctly guess the right response. 3203 This specification does not define any mechanism for transparent 3204 negotiation, though it also does not prevent any such mechanism from 3205 being developed as an extension and used within HTTP/1.1. An HTTP/1.1 3206 cache performing transparent negotiation MUST include a Vary header 3207 field in the response (defining the dimensions of its variance) if it is 3208 cachable to ensure correct interoperation with all HTTP/1.1 clients. The 3209 agent-driven negotiation information supplied by the origin server 3210 SHOULD be included with the transparently negotiated response. 3212 13 Caching in HTTP 3214 HTTP is typically used for distributed information systems, where 3215 performance can be improved by the use of response caches. The HTTP/1.1 3216 protocol includes a number of elements intended to make caching work as 3217 well as possible. Because these elements are inextricable from other 3218 aspects of the protocol, and because they interact with each other, it 3219 is useful to describe the basic caching design of HTTP separately from 3220 the detailed descriptions of methods, headers, response codes, etc. 3222 Caching would be useless if it did not significantly improve 3223 performance. The goal of caching in HTTP/1.1 is to eliminate the need to 3224 send requests in many cases, and to eliminate the need to send full 3225 responses in many other cases. The former reduces the number of network 3226 round-trips required for many operations; we use an "expiration" 3227 mechanism for this purpose (see section 13.2). The latter reduces 3228 network bandwidth requirements; we use a "validation" mechanism for this 3229 purpose (see section 13.3). 3231 Requirements for performance, availability, and disconnected operation 3232 require us to be able to relax the goal of semantic transparency. The 3233 HTTP/1.1 protocol allows origin servers, caches, and clients to 3234 explicitly reduce transparency when necessary. However, because non- 3235 transparent operation may confuse non-expert users, and may be 3236 incompatible with certain server applications (such as those for 3237 ordering merchandise), the protocol requires that transparency be 3238 relaxed 3240 o only by an explicit protocol-level request when relaxed by client 3241 or origin server 3242 o only with an explicit warning to the end user when relaxed by cache 3243 or client 3244 Therefore, the HTTP/1.1 protocol provides these important elements: 3246 1. Protocol features that provide full semantic transparency when this 3247 is required by all parties. 3249 2. Protocol features that allow an origin server or user agent to 3250 explicitly request and control non-transparent operation. 3252 3. Protocol features that allow a cache to attach warnings to 3253 responses that do not preserve the requested approximation of 3254 semantic transparency. 3256 A basic principle is that it must be possible for the clients to detect 3257 any potential relaxation of semantic transparency. 3259 Note: The server, cache, or client implementer may be faced with 3260 design decisions not explicitly discussed in this specification. If 3261 a decision may affect semantic transparency, the implementer ought 3262 to err on the side of maintaining transparency unless a careful and 3263 complete analysis shows significant benefits in breaking 3264 transparency. 3266 13.1.1 Cache Correctness 3268 A correct cache MUST respond to a request with the most up-to-date 3269 response held by the cache that is appropriate to the request (see 3270 sections 13.2.5, 13.2.6, and 13.12) which meets one of the following 3271 conditions: 3273 1. It has been checked for equivalence with what the origin server 3274 would have returned by revalidating the response with the origin 3275 server (section 13.3); 3277 2. It is "fresh enough" (see section 13.2). In the default case, this 3278 means it meets the least restrictive freshness requirement of the 3279 client, server, and cache (see section 14.9); if the origin server 3280 so specifies, it is the freshness requirement of the origin server 3281 alone. 3283 3. It includes a warning if the freshness demand of the client or the 3284 origin server is violated (see section 13.1.5 and 14.45). 3286 4. It is an appropriate 304 (Not Modified), 305 (Proxy Redirect), or 3287 error (4xx or 5xx) response message. 3289 If the cache can not communicate with the origin server, then a correct 3290 cache SHOULD respond as above if the response can be correctly served 3291 from the cache; if not it MUST return an error or warning indicating 3292 that there was a communication failure. 3294 If a cache receives a response (either an entire response, or a 304 (Not 3295 Modified) response) that it would normally forward to the requesting 3296 client, and the received response is no longer fresh, the cache SHOULD 3297 forward it to the requesting client without adding a new Warning (but 3298 without removing any existing Warning headers). A cache SHOULD NOT 3299 attempt to revalidate a response simply because that response became 3300 stale in transit; this might lead to an infinite loop. An user agent 3301 that receives a stale response without a Warning MAY display a warning 3302 indication to the user. 3304 13.1.2 Warnings 3306 Whenever a cache returns a response that is neither first-hand nor 3307 "fresh enough" (in the sense of condition 2 in section 13.1.1), it must 3308 attach a warning to that effect, using a Warning response-header. This 3309 warning allows clients to take appropriate action. 3311 Warnings may be used for other purposes, both cache-related and 3312 otherwise. The use of a warning, rather than an error status code, 3313 distinguish these responses from true failures. 3315 Warnings are always cachable, because they never weaken the transparency 3316 of a response. This means that warnings can be passed to HTTP/1.0 caches 3317 without danger; such caches will simply pass the warning along as an 3318 entity-header in the response. 3320 Warnings are assigned numbers between 0 and 99. This specification 3321 defines the code numbers and meanings of each currently assigned 3322 warnings, allowing a client or cache to take automated action in some 3323 (but not all) cases. 3325 Warnings also carry a warning text. The text may be in any appropriate 3326 natural language (perhaps based on the client's Accept headers), and 3327 include an optional indication of what character set is used. 3329 Multiple warnings may be attached to a response (either by the origin 3330 server or by a cache), including multiple warnings with the same code 3331 number. For example, a server may provide the same warning with texts in 3332 both English and Basque. 3334 When multiple warnings are attached to a response, it may not be 3335 practical or reasonable to display all of them to the user. This version 3336 of HTTP does not specify strict priority rules for deciding which 3337 warnings to display and in what order, but does suggest some heuristics. 3339 The Warning header and the currently defined warnings are described in 3340 section 14.45. 3342 13.1.3 Cache-control Mechanisms 3344 The basic cache mechanisms in HTTP/1.1 (server-specified expiration 3345 times and validators) are implicit directives to caches. In some cases, 3346 a server or client may need to provide explicit directives to the HTTP 3347 caches. We use the Cache-Control header for this purpose. 3349 The Cache-Control header allows a client or server to transmit a variety 3350 of directives in either requests or responses. These directives 3351 typically override the default caching algorithms. As a general rule, if 3352 there is any apparent conflict between header values, the most 3353 restrictive interpretation should be applied (that is, the one that is 3354 most likely to preserve semantic transparency). However, in some cases, 3355 Cache-Control directives are explicitly specified as weakening the 3356 approximation of semantic transparency (for example, "max-stale" or 3357 "public"). 3359 The Cache-Control directives are described in detail in section 14.9. 3361 13.1.4 Explicit User Agent Warnings 3363 Many user agents make it possible for users to override the basic 3364 caching mechanisms. For example, the user agent may allow the user to 3365 specify that cached entities (even explicitly stale ones) are never 3366 validated. Or the user agent might habitually add "Cache-Control: max- 3367 stale=3600" or "Cache-Control: reload" to every request. The user should 3368 have to explicitly request either non-transparent behavior, or behavior 3369 that results in abnormally ineffective caching. 3371 If the user has overridden the basic caching mechanisms, the user agent 3372 should explicitly indicate to the user whenever this results in the 3373 display of information that might not meet the server's transparency 3374 requirements (in particular, if the displayed entity is known to be 3375 stale). Since the protocol normally allows the user agent to determine 3376 if responses are stale or not, this indication need only be displayed 3377 when this actually happens. The indication need not be a dialog box; it 3378 could be an icon (for example, a picture of a rotting fish) or some 3379 other visual indicator. 3381 If the user has overridden the caching mechanisms in a way that would 3382 abnormally reduce the effectiveness of caches, the user agent should 3383 continually display an indication (for example, a picture of currency in 3384 flames) so that the user does not inadvertently consume excess resources 3385 or suffer from excessive latency. 3387 13.1.5 Exceptions to the Rules and Warnings 3389 In some cases, the operator of a cache may choose to configure it to 3390 return stale responses even when not requested by clients. This decision 3391 should not be made lightly, but may be necessary for reasons of 3392 availability or performance, especially when the cache is poorly 3393 connected to the origin server. Whenever a cache returns a stale 3394 response, it MUST mark it as such (using a Warning header). This allows 3395 the client software to alert the user that there may be a potential 3396 problem. 3398 It also allows the user agent to take steps to obtain a first-hand or 3399 fresh response. For this reason, a cache SHOULD NOT return a stale 3400 response if the client explicitly requests a first-hand or fresh one, 3401 unless it is impossible to comply for technical or policy reasons. 3403 13.1.6 Client-controlled Behavior 3405 While the origin server (and to a lesser extent, intermediate caches, by 3406 their contribution to the age of a response) are the primary source of 3407 expiration information, in some cases the client may need to control a 3408 cache's decision about whether to return a cached response without 3409 validating it. Clients do this using several directives of the Cache- 3410 Control header. 3412 A client's request may specify the maximum age it is willing to accept 3413 of an unvalidated response; specifying a value of zero forces the 3414 cache(s) to revalidate all responses. A client may also specify the 3415 minimum time remaining before a response expires. Both of these options 3416 increase constraints on the behavior of caches, and so cannot further 3417 relax the cache's approximation of semantic transparency. 3419 A client may also specify that it will accept stale responses, up to 3420 some maximum amount of staleness. This loosens the constraints on the 3421 caches, and so may violate the origin server's specified constraints on 3422 semantic transparency, but may be necessary to support disconnected 3423 operation, or high availability in the face of poor connectivity. 3425 13.2 Expiration Model 3427 13.2.1 Server-Specified Expiration 3429 HTTP caching works best when caches can entirely avoid making requests 3430 to the origin server. The primary mechanism for avoiding requests is for 3431 an origin server to provide an explicit expiration time in the future, 3432 indicating that a response may be used to satisfy subsequent requests. 3433 In other words, a cache can return a fresh response without first 3434 contacting the server. 3436 Our expectation is that servers will assign future explicit expiration 3437 times to responses in the belief that the entity is not likely to 3438 change, in a semantically significant way, before the expiration time is 3439 reached. This normally preserves semantic transparency, as long as the 3440 server's expiration times are carefully chosen. 3442 The expiration mechanism applies only to responses taken from a cache 3443 and not to first-hand responses forwarded immediately to the requesting 3444 client. 3446 If an origin server wishes to force a semantically transparent cache to 3447 validate every request, it may assign an explicit expiration time in the 3448 past. This means that the response is always stale, and so the cache 3449 SHOULD validate it before using it for subsequent requests. See section 3450 14.9.4 for a more restrictive way to force revalidation. 3452 If an origin server wishes to force any HTTP/1.1 cache, no matter how it 3453 is configured, to validate every request, it should use the "must- 3454 revalidate" Cache-Control directive (see section 14.9). 3456 Servers specify explicit expiration times using either the Expires 3457 header, or the max-age directive of the Cache-Control header. 3459 An expiration time cannot be used to force a user agent to refresh its 3460 display or reload a resource; its semantics apply only to caching 3461 mechanisms, and such mechanisms need only check a resource's expiration 3462 status when a new request for that resource is initiated. See section 3463 13.13 for explanation of the difference between caches and history 3464 mechanisms. 3466 13.2.2 Heuristic Expiration 3468 Since origin servers do not always provide explicit expiration times, 3469 HTTP caches typically assign heuristic expiration times, employing 3470 algorithms that use other header values (such as the Last-Modified time) 3471 to estimate a plausible expiration time. The HTTP/1.1 specification does 3472 not provide specific algorithms, but does impose worst-case constraints 3473 on their results. Since heuristic expiration times may compromise 3474 semantic transparency, they should be used cautiously, and we encourage 3475 origin servers to provide explicit expiration times as much as possible. 3477 13.2.3 Age Calculations 3479 In order to know if a cached entry is fresh, a cache needs to know if 3480 its age exceeds its freshness lifetime. We discuss how to calculate the 3481 latter in section 13.2.4; this section describes how to calculate the 3482 age of a response or cache entry. 3484 In this discussion, we use the term "now" to mean "the current value of 3485 the clock at the host performing the calculation." Hosts that use HTTP, 3486 but especially hosts running origin servers and caches, should use NTP 3487 [28] or some similar protocol to synchronize their clocks to a globally 3488 accurate time standard. 3490 Also note that HTTP/1.1 requires origin servers to send a Date header 3491 with every response, giving the time at which the response was 3492 generated. We use the term "date_value" to denote the value of the Date 3493 header, in a form appropriate for arithmetic operations. 3495 HTTP/1.1 uses the Age response-header to help convey age information 3496 between caches. The Age header value is the sender's estimate of the 3497 amount of time since the response was generated at the origin server. In 3498 the case of a cached response that has been revalidated with the origin 3499 server, the Age value is based on the time of revalidation, not of the 3500 original response. 3502 In essence, the Age value is the sum of the time that the response has 3503 been resident in each of the caches along the path from the origin 3504 server, plus the amount of time it has been in transit along network 3505 paths. 3507 We use the term "age_value" to denote the value of the Age header, in a 3508 form appropriate for arithmetic operations. 3510 A response's age can be calculated in two entirely independent ways: 3512 1. now minus date_value, if the local clock is reasonably well 3513 synchronized to the origin server's clock. If the result is 3514 negative, the result is replaced by zero. 3516 2. age_value, if all of the caches along the response path implement 3517 HTTP/1.1. 3519 Given that we have two independent ways to compute the age of a response 3520 when it is received, we can combine these as 3522 corrected_received_age = max(now - date_value, age_value) 3524 and as long as we have either nearly synchronized clocks or all-HTTP/1.1 3525 paths, one gets a reliable (conservative) result. 3527 Note that this correction is applied at each HTTP/1.1 cache along the 3528 path, so that if there is an HTTP/1.0 cache in the path, the correct 3529 received age is computed as long as the receiving cache's clock is 3530 nearly in sync. We don't need end-to-end clock synchronization (although 3531 it is good to have), and there is no explicit clock synchronization 3532 step. 3534 Because of network-imposed delays, some significant interval may pass 3535 from the time that a server generates a response and the time it is 3536 received at the next outbound cache or client. If uncorrected, this 3537 delay could result in improperly low ages. 3539 Because the request that resulted in the returned Age value must have 3540 been initiated prior to that Age value's generation, we can correct for 3541 delays imposed by the network by recording the time at which the request 3542 was initiated. Then, when an Age value is received, it MUST be 3543 interpreted relative to the time the request was initiated, not the time 3544 that the response was received. This algorithm results in conservative 3545 behavior no matter how much delay is experienced. So, we compute: 3547 corrected_initial_age = corrected_received_age 3548 + (now - request_time) 3550 where "request_time" is the time (according to the local clock) when the 3551 request that elicited this response was sent. 3553 Summary of age calculation algorithm, when a cache receives a response: 3555 /* 3556 * age_value 3557 * is the value of Age: header received by the cache with 3558 * this response. 3559 * date_value 3560 * is the value of the origin server's Date: header 3561 * request_time 3562 * is the (local) time when the cache made the request 3563 * that resulted in this cached response 3564 * response_time 3565 * is the (local) time when the cache received the 3566 * response 3567 * now 3568 * is the current (local) time 3569 */ 3570 apparent_age = max(0, response_time - date_value); 3571 corrected_received_age = max(apparent_age, age_value); 3572 response_delay = response_time - request_time; 3573 corrected_initial_age = corrected_received_age + response_delay; 3574 resident_time = now - response_time; 3575 current_age = corrected_initial_age + resident_time; 3577 When a cache sends a response, it must add to the corrected_initial_age 3578 the amount of time that the response was resident locally. It must then 3579 transmit this total age, using the Age header, to the next recipient 3580 cache. 3582 Note that a client cannot reliably tell that a response is first- 3583 hand, but the presence of an Age header indicates that a response 3584 is definitely not first-hand. Also, if the Date in a response is 3585 earlier than the client's local request time, the response is 3586 probably not first-hand (in the absence of serious clock skew). 3588 13.2.4 Expiration Calculations 3590 In order to decide whether a response is fresh or stale, we need to 3591 compare its freshness lifetime to its age. The age is calculated as 3592 described in section 13.2.3; this section describes how to calculate the 3593 freshness lifetime, and to determine if a response has expired. In the 3594 discussion below, the values can be represented in any form appropriate 3595 for arithmetic operations. 3597 We use the term "expires_value" to denote the value of the Expires 3598 header. We use the term "max_age_value" to denote an appropriate value 3599 of the number of seconds carried by the max-age directive of the Cache- 3600 Control header in a response (see section 14.10. 3602 The max-age directive takes priority over Expires, so if max-age is 3603 present in a response, the calculation is simply: 3605 freshness_lifetime = max_age_value 3607 Otherwise, if Expires is present in the response, the calculation is: 3609 freshness_lifetime = expires_value - date_value 3611 Note that neither of these calculations is vulnerable to clock skew, 3612 since all of the information comes from the origin server. 3614 If neither Expires nor Cache-Control: max-age appears in the response, 3615 and the response does not include other restrictions on caching, the 3616 cache MAY compute a freshness lifetime using a heuristic. If the value 3617 is greater than 24 hours, the cache must attach Warning 13 to any 3618 response whose age is more than 24 hours if such warning has not already 3619 been added. 3621 Also, if the response does have a Last-Modified time, the heuristic 3622 expiration value SHOULD be no more than some fraction of the interval 3623 since that time. A typical setting of this fraction might be 10%. 3625 The calculation to determine if a response has expired is quite simple: 3627 response_is_fresh = (freshness_lifetime > current_age) 3629 13.2.5 Disambiguating Expiration Values 3631 Because expiration values are assigned optimistically, it is possible 3632 for two caches to contain fresh values for the same resource that are 3633 different. 3635 If a client performing a retrieval receives a non-first-hand response 3636 for a request that was already fresh in its own cache, and the Date 3637 header in its existing cache entry is newer than the Date on the new 3638 response, then the client MAY ignore the response. If so, it MAY retry 3639 the request with a "Cache-Control: max-age=0" directive (see section 3640 14.9), to force a check with the origin server. 3642 If a cache has two fresh responses for the same representation with 3643 different validators, it MUST use the one with the more recent Date 3644 header. This situation may arise because the cache is pooling responses 3645 from other caches, or because a client has asked for a reload or a 3646 revalidation of an apparently fresh cache entry. 3648 13.2.6 Disambiguating Multiple Responses 3650 Because a client may be receiving responses via multiple paths, so that 3651 some responses flow through one set of caches and other responses flow 3652 through a different set of caches, a client may receive responses in an 3653 order different from that in which the origin server sent them. We would 3654 like the client to use the most recently generated response, even if 3655 older responses are still apparently fresh. 3657 Neither the entity tag nor the expiration value can impose an ordering 3658 on responses, since it is possible that a later response intentionally 3659 carries an earlier expiration time. However, the HTTP/1.1 specification 3660 requires the transmission of Date headers on every response, and the 3661 Date values are ordered to a granularity of one second. 3663 When a client tries to revalidate a cache entry, and the response it 3664 receives contains a Date header that appears to be older than the one 3665 for the existing entry, then the client SHOULD repeat the request 3666 unconditionally, and include 3668 Cache-Control: max-age=0 3670 to force any intermediate caches to validate their copies directly with 3671 the origin server, or 3673 Cache-Control: no-cache 3675 to force any intermediate caches to obtain a new copy from the origin 3676 server. 3678 If the Date values are equal, then the client may use either response 3679 (or may, if it is being extremely prudent, request a new response). 3680 Servers MUST NOT depend on clients being able to choose 3681 deterministically between responses generated during the same second, if 3682 their expiration times overlap. 3684 13.3 Validation Model 3686 When a cache has a stale entry that it would like to use as a response 3687 to a client's request, it first has to check with the origin server (or 3688 possibly an intermediate cache with a fresh response) to see if its 3689 cached entry is still usable. We call this "validating" the cache entry. 3690 Since we do not want to have to pay the overhead of retransmitting the 3691 full response if the cached entry is good, and we do not want to pay the 3692 overhead of an extra round trip if the cached entry is invalid, the 3693 HTTP/1.1 protocol supports the use of conditional methods. 3695 The key protocol features for supporting conditional methods are those 3696 concerned with "cache validators." When an origin server generates a 3697 full response, it attaches some sort of validator to it, which is kept 3698 with the cache entry. When a client (user agent or proxy cache) makes a 3699 conditional request for a resource for which it has a cache entry, it 3700 includes the associated validator in the request. 3702 The server then checks that validator against the current validator for 3703 the entity, and, if they match, it responds with a special status code 3704 (usually, 304 (Not Modified)) and no entity-body. Otherwise, it returns 3705 a full response (including entity-body). Thus, we avoid transmitting the 3706 full response if the validator matches, and we avoid an extra round trip 3707 if it does not match. 3709 Note: the comparison functions used to decide if validators match 3710 are defined in section 13.3.3. 3712 In HTTP/1.1, a conditional request looks exactly the same as a normal 3713 request for the same resource, except that it carries a special header 3714 (which includes the validator) that implicitly turns the method 3715 (usually, GET) into a conditional. 3717 The protocol includes both positive and negative senses of cache- 3718 validating conditions. That is, it is possible to request either that a 3719 method be performed if and only if a validator matches or if and only if 3720 no validators match. 3722 Note: a response that lacks a validator may still be cached, and 3723 served from cache until it expires, unless this is explicitly 3724 prohibited by a Cache-Control directive. However, a cache cannot do 3725 a conditional retrieval if it does not have a validator for the 3726 entity, which means it will not be refreshable after it expires. 3728 13.3.1 Last-modified Dates 3730 The Last-Modified entity-header field value is often used as a cache 3731 validator. In simple terms, a cache entry is considered to be valid if 3732 the entity has not been modified since the Last-Modified value. 3734 13.3.2 Entity Tag Cache Validators 3736 The ETag entity-header field value, an entity tag, provides for an 3737 "opaque" cache validator. This may allow more reliable validation in 3738 situations where it is inconvenient to store modification dates, where 3739 the one-second resolution of HTTP date values is not sufficient, or 3740 where the origin server wishes to avoid certain paradoxes that may arise 3741 from the use of modification dates. 3743 Entity Tags are described in section 3.11. The headers used with entity 3744 tags are described in sections 14.20, 14.25, 14.26 and 14.43. 3746 13.3.3 Weak and Strong Validators 3748 Since both origin servers and caches will compare two validators to 3749 decide if they represent the same or different entities, one normally 3750 would expect that if the entity (the entity-body or any entity-headers) 3751 changes in any way, then the associated validator would change as well. 3752 If this is true, then we call this validator a "strong validator." 3754 However, there may be cases when a server prefers to change the 3755 validator only on semantically significant changes, and not when 3756 insignificant aspects of the entity change. A validator that does not 3757 always change when the resource changes is a "weak validator." 3759 Entity tags are normally "strong validators," but the protocol provides 3760 a mechanism to tag an entity tag as "weak." One can think of a strong 3761 validator as one that changes whenever the bits of an entity changes, 3762 while a weak value changes whenever the meaning of an entity changes. 3763 Alternatively, one can think of a strong validator as part of an 3764 identifier for a specific entity, while a weak validator is part of an 3765 identifier for a set of semantically equivalent entities. 3767 Note: One example of a strong validator is an integer that is 3768 incremented in stable storage every time an entity is changed. 3770 An entity's modification time, if represented with one-second 3771 resolution, could be a weak validator, since it is possible that 3772 the resource may be modified twice during a single second. 3774 Support for weak validators is optional; however, weak validators 3775 allow for more efficient caching of equivalent objects; for 3776 example, a hit counter on a site is probably good enough if it is 3777 updated every few days or weeks, and any value during that period 3778 is likely "good enough" to be equivalent. 3780 A "use" of a validator is either when a client generates a request and 3781 includes the validator in a validating header field, or when a server 3782 compares two validators. 3784 Strong validators are usable in any context. Weak validators are only 3785 usable in contexts that do not depend on exact equality of an entity. 3786 For example, either kind is usable for a conditional GET of a full 3787 entity. However, only a strong validator is usable for a sub-range 3788 retrieval, since otherwise the client may end up with an internally 3789 inconsistent entity. 3791 The only function that the HTTP/1.1 protocol defines on validators is 3792 comparison. There are two validator comparison functions, depending on 3793 whether the comparison context allows the use of weak validators or not: 3795 o The strong comparison function: in order to be considered equal, 3796 both validators must be identical in every way, and neither may be 3797 weak. 3798 o The weak comparison function: in order to be considered equal, both 3799 validators must be identical in every way, but either or both of 3800 them may be tagged as "weak" without affecting the result. 3802 The weak comparison function MAY be used for simple (non-subrange) GET 3803 requests. The strong comparison function MUST be used in all other 3804 cases. 3806 An entity tag is strong unless it is explicitly tagged as weak. Section 3807 3.11 gives the syntax for entity tags. 3809 A Last-Modified time, when used as a validator in a request, is 3810 implicitly weak unless it is possible to deduce that it is strong, using 3811 the following rules: 3813 o The validator is being compared by an origin server to the actual 3814 current validator for the entity and, 3815 o That origin server reliably knows that the associated entity did 3816 not change twice during the second covered by the presented 3817 validator. 3818 or 3820 o The validator is about to be used by a client in an If-Modified- 3821 Since or If-Unmodified-Since header, because the client has a cache 3822 entry for the associated entity, and 3823 o That cache entry includes a Date value, which gives the time when 3824 the origin server sent the original response, and 3825 o The presented Last-Modified time is at least 60 seconds before the 3826 Date value. 3827 or 3829 o The validator is being compared by an intermediate cache to the 3830 validator stored in its cache entry for the entity, and 3831 o That cache entry includes a Date value, which gives the time when 3832 the origin server sent the original response, and 3833 o The presented Last-Modified time is at least 60 seconds before the 3834 Date value. 3836 This method relies on the fact that if two different responses were sent 3837 by the origin server during the same second, but both had the same Last- 3838 Modified time, then at least one of those responses would have a Date 3839 value equal to its Last-Modified time. The arbitrary 60-second limit 3840 guards against the possibility that the Date and Last-Modified values 3841 are generated from different clocks, or at somewhat different times 3842 during the preparation of the response. An implementation may use a 3843 value larger than 60 seconds, if it is believed that 60 seconds is too 3844 short. 3846 If a client wishes to perform a sub-range retrieval on a value for which 3847 it has only a Last-Modified time and no opaque validator, it may do this 3848 only if the Last-Modified time is strong in the sense described here. 3850 A cache or origin server receiving a cache-conditional request, other 3851 than a full-body GET request, MUST use the strong comparison function to 3852 evaluate the condition. 3854 These rules allow HTTP/1.1 caches and clients to safely perform sub- 3855 range retrievals on values that have been obtained from HTTP/1.0 3856 servers. 3858 13.3.4 Rules for When to Use Entity Tags and Last-modified Dates 3860 We adopt a set of rules and recommendations for origin servers, clients, 3861 and caches regarding when various validator types should be used, and 3862 for what purposes. 3864 HTTP/1.1 origin servers: 3866 o SHOULD send an entity tag validator unless it is not feasible to 3867 generate one. 3868 o MAY send a weak entity tag instead of a strong entity tag, if 3869 performance considerations support the use of weak entity tags, or 3870 if it is unfeasible to send a strong entity tag. 3871 o SHOULD send a Last-Modified value if it is feasible to send one, 3872 unless the risk of a breakdown in semantic transparency that could 3873 result from using this date in an If-Modified-Since header would 3874 lead to serious problems. 3876 In other words, the preferred behavior for an HTTP/1.1 origin server is 3877 to send both a strong entity tag and a Last-Modified value. 3879 In order to be legal, a strong entity tag MUST change whenever the 3880 associated entity value changes in any way. A weak entity tag SHOULD 3881 change whenever the associated entity changes in a semantically 3882 significant way. 3884 Note: in order to provide semantically transparent caching, an 3885 origin server must avoid reusing a specific strong entity tag value 3886 for two different entities, or reusing a specific weak entity tag 3887 value for two semantically different entities. Cache entries may 3888 persist for arbitrarily long periods, regardless of expiration 3889 times, so it may be inappropriate to expect that a cache will never 3890 again attempt to validate an entry using a validator that it 3891 obtained at some point in the past. 3893 HTTP/1.1 clients: 3895 o If an entity tag has been provided by the origin server, MUST use 3896 that entity tag in any cache-conditional request (using If-Match or 3897 If-None-Match). 3898 o If only a Last-Modified value has been provided by the origin 3899 server, SHOULD use that value in non-subrange cache-conditional 3900 requests (using If-Modified-Since). 3901 o If only a Last-Modified value has been provided by an HTTP/1.0 3902 origin server, MAY use that value in subrange cache-conditional 3903 requests (using If-Unmodified-Since:). The user agent should 3904 provide a way to disable this, in case of difficulty. 3905 o If both an entity tag and a Last-Modified value have been provided 3906 by the origin server, SHOULD use both validators in cache- 3907 conditional requests. This allows both HTTP/1.0 and HTTP/1.1 caches 3908 to respond appropriately. 3910 An HTTP/1.1 cache, upon receiving a request, MUST use the most 3911 restrictive validator when deciding whether the client's cache entry 3912 matches the cache's own cache entry. This is only an issue when the 3913 request contains both an entity tag and a last-modified-date validator 3914 (If-Modified-Since or If-Unmodified-Since). 3916 A note on rationale: The general principle behind these rules is 3917 that HTTP/1.1 servers and clients should transmit as much non- 3918 redundant information as is available in their responses and 3919 requests. HTTP/1.1 systems receiving this information will make the 3920 most conservative assumptions about the validators they receive. 3922 HTTP/1.0 clients and caches will ignore entity tags. Generally, 3923 last-modified values received or used by these systems will support 3924 transparent and efficient caching, and so HTTP/1.1 origin servers 3925 should provide Last-Modified values. In those rare cases where the 3926 use of a Last-Modified value as a validator by an HTTP/1.0 system 3927 could result in a serious problem, then HTTP/1.1 origin servers 3928 should not provide one. 3930 13.3.5 Non-validating Conditionals 3932 The principle behind entity tags is that only the service author knows 3933 the semantics of a resource well enough to select an appropriate cache 3934 validation mechanism, and the specification of any validator comparison 3935 function more complex than byte-equality would open up a can of worms. 3936 Thus, comparisons of any other headers (except Last-Modified, for 3937 compatibility with HTTP/1.0) are never used for purposes of validating a 3938 cache entry. 3940 13.4 Response Cachability 3942 Unless specifically constrained by a Cache-Control (section 14.9) 3943 directive, a caching system may always store a successful response (see 3944 section 13.8) as a cache entry, may return it without validation if it 3945 is fresh, and may return it after successful validation. If there is 3946 neither a cache validator nor an explicit expiration time associated 3947 with a response, we do not expect it to be cached, but certain caches 3948 may violate this expectation (for example, when little or no network 3949 connectivity is available). A client can usually detect that such a 3950 response was taken from a cache by comparing the Date header to the 3951 current time. 3953 Note that some HTTP/1.0 caches are known to violate this 3954 expectation without providing any Warning. 3956 However, in some cases it may be inappropriate for a cache to retain an 3957 entity, or to return it in response to a subsequent request. This may be 3958 because absolute semantic transparency is deemed necessary by the 3959 service author, or because of security or privacy considerations. 3960 Certain Cache-Control directives are therefore provided so that the 3961 server can indicate that certain resource entities, or portions thereof, 3962 may not be cached regardless of other considerations. 3964 Note that section 14.8 normally prevents a shared cache from saving and 3965 returning a response to a previous request if that request included an 3966 Authorization header. 3968 A response received with a status code of 200, 203, 206, 300, 301 or 410 3969 may be stored by a cache and used in reply to a subsequent request, 3970 subject to the expiration mechanism, unless a Cache-Control directive 3971 prohibits caching. However, a cache that does not support the Range and 3972 Content-Range headers MUST NOT cache 206 (Partial Content) responses. 3974 A response received with any other status code MUST NOT be returned in a 3975 reply to a subsequent request unless there are Cache-Control directives 3976 or another header(s) that explicitly allow it. For example, these 3977 include the following: an Expires header (section 14.21); a "max-age", 3978 "must-revalidate", "proxy-revalidate", "public" or "private" Cache- 3979 Control directive (section 14.9). 3981 13.5 Constructing Responses From Caches 3983 The purpose of an HTTP cache is to store information received in 3984 response to requests, for use in responding to future requests. In many 3985 cases, a cache simply returns the appropriate parts of a response to the 3986 requester. However, if the cache holds a cache entry based on a previous 3987 response, it may have to combine parts of a new response with what is 3988 held in the cache entry. 3990 13.5.1 End-to-end and Hop-by-hop Headers 3992 For the purpose of defining the behavior of caches and non-caching 3993 proxies, we divide HTTP headers into two categories: 3995 o End-to-end headers, which must be transmitted to the ultimate 3996 recipient of a request or response. End-to-end headers in responses 3997 must be stored as part of a cache entry and transmitted in any 3998 response formed from a cache entry. 3999 o Hop-by-hop headers, which are meaningful only for a single 4000 transport-level connection, and are not stored by caches or 4001 forwarded by proxies. 4003 The following HTTP/1.1 headers are hop-by-hop headers: 4005 o Connection 4006 o Keep-Alive 4007 o Public 4008 o Proxy-Authenticate 4009 o Transfer-Encoding 4010 o Upgrade 4012 All other headers defined by HTTP/1.1 are end-to-end headers. 4014 Hop-by-hop headers introduced in future versions of HTTP MUST be listed 4015 in a Connection header, as described in section 14.10. 4017 13.5.2 Non-modifiable Headers 4019 Some features of the HTTP/1.1 protocol, such as Digest Authentication, 4020 depend on the value of certain end-to-end headers. A cache or non- 4021 caching proxy SHOULD NOT modify an end-to-end header unless the 4022 definition of that header requires or specifically allows that. 4024 A cache or non-caching proxy MUST NOT modify any of the following fields 4025 in a request or response, nor may it add any of these fields if not 4026 already present: 4028 o Content-Location 4029 o ETag 4030 o Expires 4031 o Last-Modified 4033 A cache or non-caching proxy MUST NOT modify or add any of the following 4034 fields in a response that contains the no-transform Cache-Control 4035 directive, or in any request: 4037 o Content-Encoding 4038 o Content-Length 4039 o Content-Range 4040 o Content-Type 4042 A cache or non-caching proxy MAY modify or add these fields in a 4043 response that does not include no-transform, but if it does so, it MUST 4044 add a Warning 14 (Transformation applied) if one does not already appear 4045 in the response. 4047 Warning: unnecessary modification of end-to-end headers may cause 4048 authentication failures if stronger authentication mechanisms are 4049 introduced in later versions of HTTP. Such authentication 4050 mechanisms may rely on the values of header fields not listed here. 4052 13.5.3 Combining Headers 4054 When a cache makes a validating request to a server, and the server 4055 provides a 304 (Not Modified) response, the cache must construct a 4056 response to send to the requesting client. The cache uses the entity- 4057 body stored in the cache entry as the entity-body of this outgoing 4058 response. The end-to-end headers stored in the cache entry are used for 4059 the constructed response, except that any end-to-end headers provided in 4060 the 304 response MUST replace the corresponding headers from the cache 4061 entry. Unless the cache decides to remove the cache entry, it MUST also 4062 replace the end-to-end headers stored with the cache entry with 4063 corresponding headers received in the incoming response. 4065 In other words, the set of end-to-end headers received in the incoming 4066 response overrides all corresponding end-to-end headers stored with the 4067 cache entry. The cache may add Warning headers (see section 14.45) to 4068 this set. 4070 If a header field-name in the incoming response matches more than one 4071 header in the cache entry, all such old headers are replaced. 4073 Note: this rule allows an origin server to use a 304 (Not Modified) 4074 response to update any header associated with a previous response 4075 for the same entity, although it might not always be meaningful or 4076 correct to do so. This rule does not allow an origin server to use 4077 a 304 (not Modified) response to entirely delete a header that it 4078 had provided with a previous response. 4080 13.5.4 Combining Byte Ranges 4082 A response may transfer only a subrange of the bytes of an entity-body, 4083 either because the request included one or more Range specifications, or 4084 because a connection was broken prematurely. After several such 4085 transfers, a cache may have received several ranges of the same entity- 4086 body. 4088 If a cache has a stored non-empty set of subranges for an entity, and an 4089 incoming response transfers another subrange, the cache MAY combine the 4090 new subrange with the existing set if both the following conditions are 4091 met: 4093 o Both the incoming response and the cache entry must have a cache 4094 validator. 4095 o The two cache validators must match using the strong comparison 4096 function (see section 13.3.3). 4098 If either requirement is not meant, the cache must use only the most 4099 recent partial response (based on the Date values transmitted with every 4100 response, and using the incoming response if these values are equal or 4101 missing), and must discard the other partial information. 4103 13.6 Caching Negotiated Responses 4105 Use of server-driven content negotiation (section 12), as indicated by 4106 the presence of a Vary header field in a response, alters the conditions 4107 and procedure by which a cache can use the response for subsequent 4108 requests. 4110 A server MUST use the Vary header field (section 14.43) to inform a 4111 cache of what header field dimensions are used to select among multiple 4112 representations of a cachable response. A cache may use the selected 4113 representation (the entity included with that particular response) for 4114 replying to subsequent requests on that resource only when the 4115 subsequent requests have the same or equivalent values for all header 4116 fields specified in the Vary response-header. Requests with a different 4117 value for one or more of those header fields would be forwarded toward 4118 the origin server. 4120 If an entity tag was assigned to the representation, the forwarded 4121 request SHOULD be conditional and include the entity tags in an If-None- 4122 Match header field from all its cache entries for the Request-URI. This 4123 conveys to the server the set of entities currently held by the cache, 4124 so that if any one of these entities matches the requested entity, the 4125 server can use the ETag header in its 304 (Not Modified) response to 4126 tell the cache which entry is appropriate. If the entity-tag of the new 4127 response matches that of an existing entry, the new response SHOULD be 4128 used to update the header fields of the existing entry, and the result 4129 MUST be returned to the client. 4131 The Vary header field may also inform the cache that the representation 4132 was selected using criteria not limited to the request-headers; in this 4133 case, a cache MUST NOT use the response in a reply to a subsequent 4134 request unless the cache relays the new request to the origin server in 4135 a conditional request and the server responds with 304 (Not Modified), 4136 including an entity tag or Content-Location that indicates which entity 4137 should be used. 4139 If any of the existing cache entries contains only partial content for 4140 the associated entity, its entity-tag SHOULD NOT be included in the If- 4141 None-Match header unless the request is for a range that would be fully 4142 satisfied by that entry. 4144 If a cache receives a successful response whose Content-Location field 4145 matches that of an existing cache entry for the same Request-URI, whose 4146 entity-tag differs from that of the existing entry, and whose Date is 4147 more recent than that of the existing entry, the existing entry SHOULD 4148 NOT be returned in response to future requests, and should be deleted 4149 from the cache. 4151 13.7 Shared and Non-Shared Caches 4153 For reasons of security and privacy, it is necessary to make a 4154 distinction between "shared" and "non-shared" caches. A non-shared cache 4155 is one that is accessible only to a single user. Accessibility in this 4156 case SHOULD be enforced by appropriate security mechanisms. All other 4157 caches are considered to be "shared." Other sections of this 4158 specification place certain constraints on the operation of shared 4159 caches in order to prevent loss of privacy or failure of access 4160 controls. 4162 13.8 Errors or Incomplete Response Cache Behavior 4164 A cache that receives an incomplete response (for example, with fewer 4165 bytes of data than specified in a Content-Length header) may store the 4166 response. However, the cache MUST treat this as a partial response. 4167 Partial responses may be combined as described in section 13.5.4; the 4168 result might be a full response or might still be partial. A cache MUST 4169 NOT return a partial response to a client without explicitly marking it 4170 as such, using the 206 (Partial Content) status code. A cache MUST NOT 4171 return a partial response using a status code of 200 (OK). 4173 If a cache receives a 5xx response while attempting to revalidate an 4174 entry, it may either forward this response to the requesting client, or 4175 act as if the server failed to respond. In the latter case, it MAY 4176 return a previously received response unless the cached entry includes 4177 the "must-revalidate" Cache-Control directive (see section 14.9). 4179 13.9 Side Effects of GET and HEAD 4181 Unless the origin server explicitly prohibits the caching of their 4182 responses, the application of GET and HEAD methods to any resources 4183 SHOULD NOT have side effects that would lead to erroneous behavior if 4184 these responses are taken from a cache. They may still have side 4185 effects, but a cache is not required to consider such side effects in 4186 its caching decisions. Caches are always expected to observe an origin 4187 server's explicit restrictions on caching. 4189 We note one exception to this rule: since some applications have 4190 traditionally used GETs and HEADs with query URLs (those containing a 4191 "?" in the rel_path part) to perform operations with significant side 4192 effects, caches MUST NOT treat responses to such URLs as fresh unless 4193 the server provides an explicit expiration time. This specifically means 4194 that responses from HTTP/1.0 servers for such URIs should not be taken 4195 from a cache. See section 9.1.1 for related information. 4197 13.10 Invalidation After Updates or Deletions 4199 The effect of certain methods at the origin server may cause one or more 4200 existing cache entries to become non-transparently invalid. That is, 4201 although they may continue to be "fresh," they do not accurately reflect 4202 what the origin server would return for a new request. 4204 There is no way for the HTTP protocol to guarantee that all such cache 4205 entries are marked invalid. For example, the request that caused the 4206 change at the origin server may not have gone through the proxy where a 4207 cache entry is stored. However, several rules help reduce the likelihood 4208 of erroneous behavior. 4210 In this section, the phrase "invalidate an entity" means that the cache 4211 should either remove all instances of that entity from its storage, or 4212 should mark these as "invalid" and in need of a mandatory revalidation 4213 before they can be returned in response to a subsequent request. 4215 Some HTTP methods may invalidate an entity. This is either the entity 4216 referred to by the Request-URI, or by the Location or Content-Location 4217 response-headers (if present). These methods are: 4219 o PUT 4220 o DELETE 4221 o POST 4223 In order to prevent denial of service attacks, an invalidation based on 4224 the URI in a Location or Content-Location header MUST only be performed 4225 if the host part is the same as in the Request-URI. 4227 13.11 Write-Through Mandatory 4229 All methods that may be expected to cause modifications to the origin 4230 server's resources MUST be written through to the origin server. This 4231 currently includes all methods except for GET and HEAD. A cache MUST NOT 4232 reply to such a request from a client before having transmitted the 4233 request to the inbound server, and having received a corresponding 4234 response from the inbound server. This does not prevent a cache from 4235 sending a 100 (Continue) response before the inbound server has replied. 4237 The alternative (known as "write-back" or "copy-back" caching) is not 4238 allowed in HTTP/1.1, due to the difficulty of providing consistent 4239 updates and the problems arising from server, cache, or network failure 4240 prior to write-back. 4242 13.12 Cache Replacement 4244 If a new cachable (see sections 14.9.2, 13.2.5, 13.2.6 and 13.8) 4245 response is received from a resource while any existing responses for 4246 the same resource are cached, the cache SHOULD use the new response to 4247 reply to the current request. It may insert it into cache storage and 4248 may, if it meets all other requirements, use it to respond to any future 4249 requests that would previously have caused the old response to be 4250 returned. If it inserts the new response into cache storage it should 4251 follow the rules in section 13.5.3. 4253 Note: a new response that has an older Date header value than 4254 existing cached responses is not cachable. 4256 13.13 History Lists 4258 User agents often have history mechanisms, such as "Back" buttons and 4259 history lists, which can be used to redisplay an entity retrieved 4260 earlier in a session. 4262 History mechanisms and caches are different. In particular history 4263 mechanisms SHOULD NOT try to show a semantically transparent view of the 4264 current state of a resource. Rather, a history mechanism is meant to 4265 show exactly what the user saw at the time when the resource was 4266 retrieved. 4268 By default, an expiration time does not apply to history mechanisms. If 4269 the entity is still in storage, a history mechanism should display it 4270 even if the entity has expired, unless the user has specifically 4271 configured the agent to refresh expired history documents. 4273 This should not be construed to prohibit the history mechanism from 4274 telling the user that a view may be stale. 4276 Note: if history list mechanisms unnecessarily prevent users from 4277 viewing stale resources, this will tend to force service authors to 4278 avoid using HTTP expiration controls and cache controls when they 4279 would otherwise like to. Service authors may consider it important 4280 that users not be presented with error messages or warning messages 4281 when they use navigation controls (such as BACK) to view previously 4282 fetched resources. Even though sometimes such resources ought not 4283 to cached, or ought to expire quickly, user interface 4284 considerations may force service authors to resort to other means 4285 of preventing caching (e.g. "once-only" URLs) in order not to 4286 suffer the effects of improperly functioning history mechanisms. 4288 14 Header Field Definitions 4290 This section defines the syntax and semantics of all standard HTTP/1.1 4291 header fields. For entity-header fields, both sender and recipient refer 4292 to either the client or the server, depending on who sends and who 4293 receives the entity. 4295 14.1 Accept 4297 The Accept request-header field can be used to specify certain media 4298 types which are acceptable for the response. Accept headers can be used 4299 to indicate that the request is specifically limited to a small set of 4300 desired types, as in the case of a request for an in-line image. 4302 Accept = "Accept" ":" 4303 #( media-range [ accept-params ] ) 4305 media-range = ( "*/*" 4306 | ( type "/" "*" ) 4307 | ( type "/" subtype ) 4308 ) *( ";" parameter ) 4310 accept-params = ";" "q" "=" qvalue *( accept-extension ) 4312 accept-extension = ";" token [ "=" ( token | quoted-string ) ] 4314 The asterisk "*" character is used to group media types into ranges, 4315 with "*/*" indicating all media types and "type/*" indicating all 4316 subtypes of that type. The media-range MAY include media type parameters 4317 that are applicable to that range. 4319 Each media-range MAY be followed by one or more accept-params, beginning 4320 with the "q" parameter for indicating a relative quality factor. The 4321 first "q" parameter (if any) separates the media-range parameter(s) from 4322 the accept-params. Quality factors allow the user or user agent to 4323 indicate the relative degree of preference for that media-range, using 4324 the qvalue scale from 0 to 1 (section 3.9). The default value is q=1. 4326 Note: Use of the "q" parameter name to separate media type 4327 parameters from Accept extension parameters is due to historical 4328 practice. Although this prevents any media type parameter named 4329 "q" from being used with a media range, such an event is believed 4330 to be unlikely given the lack of any "q" parameters in the IANA 4331 media type registry and the rare usage of any media type parameters 4332 in Accept. Future media types should be discouraged from 4333 registering any parameter named "q". 4335 The example 4337 Accept: audio/*; q=0.2, audio/basic 4339 SHOULD be interpreted as "I prefer audio/basic, but send me any audio 4340 type if it is the best available after an 80% mark-down in quality." 4342 If no Accept header field is present, then it is assumed that the client 4343 accepts all media types. If an Accept header field is present, and if 4344 the server cannot send a response which is acceptable according to the 4345 combined Accept field value, then the server SHOULD send a 406 (not 4346 acceptable) response. 4348 A more elaborate example is 4350 Accept: text/plain; q=0.5, text/html, 4351 text/x-dvi; q=0.8, text/x-c 4353 Verbally, this would be interpreted as "text/html and text/x-c are the 4354 preferred media types, but if they do not exist, then send the text/x- 4355 dvi entity, and if that does not exist, send the text/plain entity." 4357 Media ranges can be overridden by more specific media ranges or specific 4358 media types. If more than one media range applies to a given type, the 4359 most specific reference has precedence. For example, 4361 Accept: text/*, text/html, text/html;level=1, */* 4363 have the following precedence: 4365 1) text/html;level=1 4366 2) text/html 4367 3) text/* 4368 4) */* 4370 The media type quality factor associated with a given type is determined 4371 by finding the media range with the highest precedence which matches 4372 that type. For example, 4374 Accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1, 4375 text/html;level=2;q=0.4, */*;q=0.5 4377 would cause the following values to be associated: 4379 text/html;level=1 = 1 4380 text/html = 0.7 4381 text/plain = 0.3 4382 image/jpeg = 0.5 4383 text/html;level=2 = 0.4 4384 text/html;level=3 = 0.7 4386 Note: A user agent may be provided with a default set of quality 4387 values for certain media ranges. However, unless the user agent is 4388 a closed system which cannot interact with other rendering agents, 4389 this default set should be configurable by the user. 4391 14.2 Accept-Charset 4393 The Accept-Charset request-header field can be used to indicate what 4394 character sets are acceptable for the response. This field allows 4395 clients capable of understanding more comprehensive or special-purpose 4396 character sets to signal that capability to a server which is capable of 4397 representing documents in those character sets. The ISO-8859-1 character 4398 set can be assumed to be acceptable to all user agents. 4400 Accept-Charset = "Accept-Charset" ":" 4401 1#( charset [ ";" "q" "=" qvalue ] ) 4403 Character set values are described in section 3.4. Each charset may be 4404 given an associated quality value which represents the user's preference 4405 for that charset. The default value is q=1. An example is 4407 Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 4409 If no Accept-Charset header is present, the default is that any 4410 character set is acceptable. If an Accept-Charset header is present, and 4411 if the server cannot send a response which is acceptable according to 4412 the Accept-Charset header, then the server SHOULD send an error response 4413 with the 406 (not acceptable) status code, though the sending of an 4414 unacceptable response is also allowed. 4416 14.3 Accept-Encoding 4418 The Accept-Encoding request-header field is similar to Accept, but 4419 restricts the content-coding values (section 14.12) which are acceptable 4420 in the response. 4422 Accept-Encoding = "Accept-Encoding" ":" 4423 #( content-coding ) 4425 An example of its use is 4427 Accept-Encoding: compress, gzip 4428 If no Accept-Encoding header is present in a request, the server MAY 4429 assume that the client will accept any content coding. If an Accept- 4430 Encoding header is present, and if the server cannot send a response 4431 which is acceptable according to the Accept-Encoding header, then the 4432 server SHOULD send an error response with the 406 (Not Acceptable) 4433 status code. 4435 An empty Accept-Encoding value indicates none are acceptable. 4437 14.4 Accept-Language 4439 The Accept-Language request-header field is similar to Accept, but 4440 restricts the set of natural languages that are preferred as a response 4441 to the request. 4443 Accept-Language = "Accept-Language" ":" 4444 1#( language-range [ ";" "q" "=" qvalue ] ) 4446 language-range = ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" ) 4448 Each language-range MAY be given an associated quality value which 4449 represents an estimate of the user's preference for the languages 4450 specified by that range. The quality value defaults to "q=1". For 4451 example, 4453 Accept-Language: da, en-gb;q=0.8, en;q=0.7 4455 would mean: "I prefer Danish, but will accept British English and other 4456 types of English." A language-range matches a language-tag if it exactly 4457 equals the tag, or if it exactly equals a prefix of the tag such that 4458 the first tag character following the prefix is "-". The special range 4459 "*", if present in the Accept-Language field, matches every tag not 4460 matched by any other range present in the Accept-Language field. 4462 Note: This use of a prefix matching rule does not imply that 4463 language tags are assigned to languages in such a way that it is 4464 always true that if a user understands a language with a certain 4465 tag, then this user will also understand all languages with tags 4466 for which this tag is a prefix. The prefix rule simply allows the 4467 use of prefix tags if this is the case. 4469 The language quality factor assigned to a language-tag by the Accept- 4470 Language field is the quality value of the longest language-range in the 4471 field that matches the language-tag. If no language-range in the field 4472 matches the tag, the language quality factor assigned is 0. If no 4473 Accept-Language header is present in the request, the server SHOULD 4474 assume that all languages are equally acceptable. If an Accept-Language 4475 header is present, then all languages which are assigned a quality 4476 factor greater than 0 are acceptable. 4478 It may be contrary to the privacy expectations of the user to send an 4479 Accept-Language header with the complete linguistic preferences of the 4480 user in every request. For a discussion of this issue, see section 15.7. 4482 Note: As intelligibility is highly dependent on the individual 4483 user, it is recommended that client applications make the choice of 4484 linguistic preference available to the user. If the choice is not 4485 made available, then the Accept-Language header field must not be 4486 given in the request. 4488 14.5 Accept-Ranges 4490 The Accept-Ranges response-header field allows the server to indicate 4491 its acceptance of range requests for a resource: 4493 Accept-Ranges = "Accept-Ranges" ":" acceptable-ranges 4495 acceptable-ranges = 1#range-unit | "none" 4497 Origin servers that accept byte-range requests MAY send 4499 Accept-Ranges: bytes 4501 but are not required to do so. Clients MAY generate byte-range requests 4502 without having received this header for the resource involved. 4504 Servers that do not accept any kind of range request for a resource MAY 4505 send 4507 Accept-Ranges: none 4509 to advise the client not to attempt a range request. 4511 14.6 Age 4513 The Age response-header field conveys the sender's estimate of the 4514 amount of time since the response (or its revalidation) was generated at 4515 the origin server. A cached response is "fresh" if its age does not 4516 exceed its freshness lifetime. Age values are calculated as specified in 4517 section 13.2.3. 4519 Age = "Age" ":" age-value 4521 age-value = delta-seconds 4523 Age values are non-negative decimal integers, representing time in 4524 seconds. 4526 If a cache receives a value larger than the largest positive integer it 4527 can represent, or if any of its age calculations overflows, it MUST 4528 transmit an Age header with a value of 2147483648 (2^31). HTTP/1.1 4529 caches MUST send an Age header in every response. Caches SHOULD use an 4530 arithmetic type of at least 31 bits of range. 4532 14.7 Allow 4534 The Allow entity-header field lists the set of methods supported by the 4535 resource identified by the Request-URI. The purpose of this field is 4536 strictly to inform the recipient of valid methods associated with the 4537 resource. An Allow header field MUST be present in a 405 (Method Not 4538 Allowed) response. 4540 Allow = "Allow" ":" 1#method 4542 Example of use: 4544 Allow: GET, HEAD, PUT 4546 This field cannot prevent a client from trying other methods. However, 4547 the indications given by the Allow header field value SHOULD be 4548 followed. The actual set of allowed methods is defined by the origin 4549 server at the time of each request. 4551 The Allow header field MAY be provided with a PUT request to recommend 4552 the methods to be supported by the new or modified resource. The server 4553 is not required to support these methods and SHOULD include an Allow 4554 header in the response giving the actual supported methods. 4556 A proxy MUST NOT modify the Allow header field even if it does not 4557 understand all the methods specified, since the user agent MAY have 4558 other means of communicating with the origin server. 4560 The Allow header field does not indicate what methods are implemented at 4561 the server level. Servers MAY use the Public response-header field 4562 (section 14.35) to describe what methods are implemented on the server 4563 as a whole. 4565 14.8 Authorization 4567 A user agent that wishes to authenticate itself with a server--usually, 4568 but not necessarily, after receiving a 401 response--MAY do so by 4569 including an Authorization request-header field with the request. The 4570 Authorization field value consists of credentials containing the 4571 authentication information of the user agent for the realm of the 4572 resource being requested. 4574 Authorization = "Authorization" ":" credentials 4575 HTTP access authentication is described in section 11. If a request is 4576 authenticated and a realm specified, the same credentials SHOULD be 4577 valid for all other requests within this realm. 4579 When a shared cache (see section 13.7) receives a request containing an 4580 Authorization field, it MUST NOT return the corresponding response as a 4581 reply to any other request, unless one of the following specific 4582 exceptions holds: 4584 1. If the response includes the "proxy-revalidate" Cache-Control 4585 directive, the cache MAY use that response in replying to a 4586 subsequent request, but a proxy cache MUST first revalidate it with 4587 the origin server, using the request-headers from the new request 4588 to allow the origin server to authenticate the new request. 4589 2. If the response includes the "must-revalidate" Cache-Control 4590 directive, the cache MAY use that response in replying to a 4591 subsequent request, but all caches MUST first revalidate it with 4592 the origin server, using the request-headers from the new request 4593 to allow the origin server to authenticate the new request. 4594 3. If the response includes the "public" Cache-Control directive, it 4595 may be returned in reply to any subsequent request. 4597 14.9 Cache-Control 4599 The Cache-Control general-header field is used to specify directives 4600 that MUST be obeyed by all caching mechanisms along the request/response 4601 chain. The directives specify behavior intended to prevent caches from 4602 adversely interfering with the request or response. These directives 4603 typically override the default caching algorithms. Cache directives are 4604 unidirectional in that the presence of a directive in a request does not 4605 imply that the same directive should be given in the response. 4607 Note that HTTP/1.0 caches may not implement Cache-Control and may 4608 only implement Pragma: no-cache (see section 14.32). 4610 Cache directives must be passed through by a proxy or gateway 4611 application, regardless of their significance to that application, since 4612 the directives may be applicable to all recipients along the 4613 request/response chain. It is not possible to specify a cache-directive 4614 for a specific cache. 4616 Cache-Control = "Cache-Control" ":" 1#cache-directive 4618 cache-directive = cache-request-directive 4619 | cache-response-directive 4621 cache-request-directive = 4622 | "no-cache" [ "=" <"> 1#field-name <"> ] 4623 | "no-store" 4624 | "max-age" "=" delta-seconds 4625 | "max-stale" "=" [ delta-seconds ] 4626 | "min-fresh" "=" delta-seconds 4627 | "only-if-cached" 4628 | cache-extension 4629 cache-response-directive = 4630 "public" 4631 | "private" [ "=" <"> 1#field-name <"> ] 4632 | "no-cache" [ "=" <"> 1#field-name <"> ] 4633 | "no-store" 4634 | "no-transform" 4635 | "must-revalidate" 4636 | "proxy-revalidate" 4637 | "max-age" "=" delta-seconds 4638 | cache-extension 4640 cache-extension = token [ "=" ( token | quoted-string ) ] 4642 When a directive appears without any 1#field-name parameter, the 4643 directive applies to the entire request or response. When such a 4644 directive appears with a 1#field-name parameter, it applies only to the 4645 named field or fields, and not to the rest of the request or response. 4646 This mechanism supports extensibility; implementations of future 4647 versions of the HTTP protocol may apply these directives to header 4648 fields not defined in HTTP/1.1. 4650 The cache-control directives can be broken down into these general 4651 categories: 4653 o Restrictions on what is cachable; these may only be imposed by the 4654 origin server. 4655 o Restrictions on what may be stored by a cache; these may be imposed 4656 by either the origin server or the user agent. 4657 o Modifications of the basic expiration mechanism; these may be 4658 imposed by either the origin server or the user agent. 4659 o Controls over cache revalidation and reload; these may only be 4660 imposed by a user agent. 4661 o Control over transformation of entities. 4662 o Extensions to the caching system. 4664 14.9.1 What is Cachable 4666 By default, a response is cachable if the requirements of the request 4667 method, request header fields, and the response status indicate that it 4668 is cachable. Section 13.4 summarizes these defaults for cachability. The 4669 following Cache-Control response directives allow an origin server to 4670 override the default cachability of a response: 4672 public 4673 Indicates that the response is cachable by any cache, even if it 4674 would normally be non-cachable or cachable only within a non-shared 4675 cache. (See also Authorization, section 14.8, for additional 4676 details.) 4678 private 4679 Indicates that all or part of the response message is intended for a 4680 single user and MUST NOT be cached by a shared cache. This allows an 4681 origin server to state that the specified parts of the response are 4682 intended for only one user and are not a valid response for requests 4683 by other users. A private (non-shared) cache may cache the response. 4685 Note: This usage of the word private only controls where the 4686 response may be cached, and cannot ensure the privacy of the 4687 message content. 4689 no-cache 4690 Indicates that all or part of the response message MUST NOT be cached 4691 anywhere. This allows an origin server to prevent caching even by 4692 caches that have been configured to return stale responses to client 4693 requests. 4695 Note: Most HTTP/1.0 caches will not recognize or obey this 4696 directive. 4698 14.9.2 What May be Stored by Caches 4700 The purpose of the no-store directive is to prevent the inadvertent 4701 release or retention of sensitive information (for example, on backup 4702 tapes). The no-store directive applies to the entire message, and may be 4703 sent either in a response or in a request. If sent in a request, a cache 4704 MUST NOT store any part of either this request or any response to it. If 4705 sent in a response, a cache MUST NOT store any part of either this 4706 response or the request that elicited it. This directive applies to both 4707 non-shared and shared caches. "MUST NOT store" in this context means 4708 that the cache MUST NOT intentionally store the information in non- 4709 volatile storage, and MUST make a best-effort attempt to remove the 4710 information from volatile storage as promptly as possible after 4711 forwarding it. 4713 Even when this directive is associated with a response, users may 4714 explicitly store such a response outside of the caching system (e.g., 4715 with a "Save As" dialog). History buffers may store such responses as 4716 part of their normal operation. 4718 The purpose of this directive is to meet the stated requirements of 4719 certain users and service authors who are concerned about accidental 4720 releases of information via unanticipated accesses to cache data 4721 structures. While the use of this directive may improve privacy in some 4722 cases, we caution that it is NOT in any way a reliable or sufficient 4723 mechanism for ensuring privacy. In particular, malicious or compromised 4724 caches may not recognize or obey this directive; and communications 4725 networks may be vulnerable to eavesdropping. 4727 14.9.3 Modifications of the Basic Expiration Mechanism 4729 The expiration time of an entity may be specified by the origin server 4730 using the Expires header (see section 14.21). Alternatively, it may be 4731 specified using the max-age directive in a response. 4733 If a response includes both an Expires header and a max-age directive, 4734 the max-age directive overrides the Expires header, even if the Expires 4735 header is more restrictive. This rule allows an origin server to 4736 provide, for a given response, a longer expiration time to an HTTP/1.1 4737 (or later) cache than to an HTTP/1.0 cache. This may be useful if 4738 certain HTTP/1.0 caches improperly calculate ages or expiration times, 4739 perhaps due to desynchronized clocks. 4741 Note: most older caches, not compliant with this specification, do 4742 not implement any Cache-Control directives. An origin server 4743 wishing to use a Cache-Control directive that restricts, but does 4744 not prevent, caching by an HTTP/1.1-compliant cache may exploit the 4745 requirement that the max-age directive overrides the Expires 4746 header, and the fact that non-HTTP/1.1-compliant caches do not 4747 observe the max-age directive. 4749 Other directives allow an user agent to modify the basic expiration 4750 mechanism. These directives may be specified on a request: 4752 max-age 4753 Indicates that the client is willing to accept a response whose age 4754 is no greater than the specified time in seconds. Unless max-stale 4755 directive is also included, the client is not willing to accept a 4756 stale response. 4758 min-fresh 4759 Indicates that the client is willing to accept a response whose 4760 freshness lifetime is no less than its current age plus the specified 4761 time in seconds. That is, the client wants a response that will still 4762 be fresh for at least the specified number of seconds. 4764 max-stale 4765 Indicates that the client is willing to accept a response that has 4766 exceeded its expiration time. If max-stale is assigned a value, then 4767 the client is willing to accept a response that has exceeded its 4768 expiration time by no more than the specified number of seconds. If 4769 no value is assigned to max-stale, then the client is willing to 4770 accept a stale response of any age. 4772 If a cache returns a stale response, either because of a max-stale 4773 directive on a request, or because the cache is configured to override 4774 the expiration time of a response, the cache MUST attach a Warning 4775 header to the stale response, using Warning 10 (Response is stale). 4777 14.9.4 Cache Revalidation and Reload Controls 4779 Sometimes an user agent may want or need to insist that a cache 4780 revalidate its cache entry with the origin server (and not just with the 4781 next cache along the path to the origin server), or to reload its cache 4782 entry from the origin server. End-to-end revalidation may be necessary 4783 if either the cache or the origin server has overestimated the 4784 expiration time of the cached response. End-to-end reload may be 4785 necessary if the cache entry has become corrupted for some reason. 4787 End-to-end revalidation may be requested either when the client does not 4788 have its own local cached copy, in which case we call it "unspecified 4789 end-to-end revalidation", or when the client does have a local cached 4790 copy, in which case we call it "specific end-to-end revalidation." 4792 The client can specify these three kinds of action using Cache-Control 4793 request directives: 4795 End-to-end reload 4796 The request includes a "no-cache" Cache-Control directive or, for 4797 compatibility with HTTP/1.0 clients, "Pragma: no-cache". No field 4798 names may be included with the no-cache directive in a request. The 4799 server MUST NOT use a cached copy when responding to such a request. 4801 Specific end-to-end revalidation 4802 The request includes a "max-age=0" Cache-Control directive, which 4803 forces each cache along the path to the origin server to revalidate 4804 its own entry, if any, with the next cache or server. The initial 4805 request includes a cache-validating conditional with the client's 4806 current validator. 4808 Unspecified end-to-end revalidation 4809 The request includes "max-age=0" Cache-Control directive, which 4810 forces each cache along the path to the origin server to revalidate 4811 its own entry, if any, with the next cache or server. The initial 4812 request does not include a cache-validating conditional; the first 4813 cache along the path (if any) that holds a cache entry for this 4814 resource includes a cache-validating conditional with its current 4815 validator. 4817 When an intermediate cache is forced, by means of a max-age=0 directive, 4818 to revalidate its own cache entry, and the client has supplied its own 4819 validator in the request, the supplied validator may differ from the 4820 validator currently stored with the cache entry. In this case, the cache 4821 may use either validator in making its own request without affecting 4822 semantic transparency. 4824 However, the choice of validator may affect performance. The best 4825 approach is for the intermediate cache to use its own validator when 4826 making its request. If the server replies with 304 (Not Modified), then 4827 the cache should return its now validated copy to the client with a 200 4828 (OK) response. If the server replies with a new entity and cache 4829 validator, however, the intermediate cache should compare the returned 4830 validator with the one provided in the client's request, using the 4831 strong comparison function. If the client's validator is equal to the 4832 origin server's, then the intermediate cache simply returns 304 (Not 4833 Modified). Otherwise, it returns the new entity with a 200 (OK) 4834 response. 4836 If a request includes the no-cache directive, it should not include min- 4837 fresh, max-stale, or max-age. 4839 In some cases, such as times of extremely poor network connectivity, a 4840 client may want a cache to return only those responses that it currently 4841 has stored, and not to reload or revalidate with the origin server. To 4842 do this, the client may include the only-if-cached directive in a 4843 request. If it receives this directive, a cache SHOULD either respond 4844 using a cached entry that is consistent with the other constraints of 4845 the request, or respond with a 504 (Gateway Timeout) status. However, if 4846 a group of caches is being operated as a unified system with good 4847 internal connectivity, such a request MAY be forwarded within that group 4848 of caches. 4850 Because a cache may be configured to ignore a server's specified 4851 expiration time, and because a client request may include a max-stale 4852 directive (which has a similar effect), the protocol also includes a 4853 mechanism for the origin server to require revalidation of a cache entry 4854 on any subsequent use. When the must-revalidate directive is present in 4855 a response received by a cache, that cache MUST NOT use the entry after 4856 it becomes stale to respond to a subsequent request without first 4857 revalidating it with the origin server. (I.e., the cache must do an end- 4858 to-end revalidation every time, if, based solely on the origin server's 4859 Expires or max-age value, the cached response is stale.) 4861 The must-revalidate directive is necessary to support reliable operation 4862 for certain protocol features. In all circumstances an HTTP/1.1 cache 4863 MUST obey the must-revalidate directive; in particular, if the cache 4864 cannot reach the origin server for any reason, it MUST generate a 504 4865 (Gateway Timeout) response. 4867 Servers should send the must-revalidate directive if and only if failure 4868 to revalidate a request on the entity could result in incorrect 4869 operation, such as a silently unexecuted financial transaction. 4870 Recipients MUST NOT take any automated action that violates this 4871 directive, and MUST NOT automatically provide an unvalidated copy of the 4872 entity if revalidation fails. 4874 Although this is not recommended, user agents operating under severe 4875 connectivity constraints may violate this directive but, if so, MUST 4876 explicitly warn the user that an unvalidated response has been provided. 4877 The warning MUST be provided on each unvalidated access, and SHOULD 4878 require explicit user confirmation. 4880 The proxy-revalidate directive has the same meaning as the must- 4881 revalidate directive, except that it does not apply to non-shared user 4882 agent caches. It can be used on a response to an authenticated request 4883 to permit the user's cache to store and later return the response 4884 without needing to revalidate it (since it has already been 4885 authenticated once by that user), while still requiring proxies that 4886 service many users to revalidate each time (in order to make sure that 4887 each user has been authenticated). Note that such authenticated 4888 responses also need the public cache control directive in order to allow 4889 them to be cached at all. 4891 14.9.5 No-Transform Directive 4893 Implementers of intermediate caches (proxies) have found it useful to 4894 convert the media type of certain entity bodies. A proxy might, for 4895 example, convert between image formats in order to save cache space or 4896 to reduce the amount of traffic on a slow link. HTTP has to date been 4897 silent on these transformations. 4899 Serious operational problems have already occurred, however, when these 4900 transformations have been applied to entity bodies intended for certain 4901 kinds of applications. For example, applications for medical imaging, 4902 scientific data analysis and those using end-to-end authentication, all 4903 depend on receiving an entity body that is bit for bit identical to the 4904 original entity-body. 4906 Therefore, if a response includes the no-transform directive, an 4907 intermediate cache or proxy MUST NOT change those headers that are 4908 listed in section 13.5.2 as being subject to the no-transform directive. 4909 This implies that the cache or proxy must not change any aspect of the 4910 entity-body that is specified by these headers. 4912 14.9.6 Cache Control Extensions 4914 The Cache-Control header field can be extended through the use of one or 4915 more cache-extension tokens, each with an optional assigned value. 4916 Informational extensions (those which do not require a change in cache 4917 behavior) may be added without changing the semantics of other 4918 directives. Behavioral extensions are designed to work by acting as 4919 modifiers to the existing base of cache directives. Both the new 4920 directive and the standard directive are supplied, such that 4921 applications which do not understand the new directive will default to 4922 the behavior specified by the standard directive, and those that 4923 understand the new directive will recognize it as modifying the 4924 requirements associated with the standard directive. In this way, 4925 extensions to the Cache-Control directives can be made without requiring 4926 changes to the base protocol. 4928 This extension mechanism depends on a HTTP cache obeying all of the 4929 cache-control directives defined for its native HTTP-version, obeying 4930 certain extensions, and ignoring all directives that it does not 4931 understand. 4933 For example, consider a hypothetical new response directive called 4934 "community" which acts as a modifier to the "private" directive. We 4935 define this new directive to mean that, in addition to any non-shared 4936 cache, any cache which is shared only by members of the community named 4937 within its value may cache the response. An origin server wishing to 4938 allow the "UCI" community to use an otherwise private response in their 4939 shared cache(s) may do so by including 4941 Cache-Control: private, community="UCI" 4943 A cache seeing this header field will act correctly even if the cache 4944 does not understand the "community" cache-extension, since it will also 4945 see and understand the "private" directive and thus default to the safe 4946 behavior. 4948 Unrecognized cache-directives MUST be ignored; it is assumed that any 4949 cache-directive likely to be unrecognized by an HTTP/1.1 cache will be 4950 combined with standard directives (or the response's default 4951 cachability) such that the cache behavior will remain minimally correct 4952 even if the cache does not understand the extension(s). 4954 14.10 Connection 4956 The Connection general-header field allows the sender to specify options 4957 that are desired for that particular connection and MUST NOT be 4958 communicated by proxies over further connections. 4960 The Connection header has the following grammar: 4962 Connection-header = "Connection" ":" 1#(connection-token) 4963 connection-token = token 4965 HTTP/1.1 proxies MUST parse the Connection header field before a message 4966 is forwarded and, for each connection-token in this field, remove any 4967 header field(s) from the message with the same name as the connection- 4968 token. Connection options are signaled by the presence of a connection- 4969 token in the Connection header field, not by any corresponding 4970 additional header field(s), since the additional header field may not be 4971 sent if there are no parameters associated with that connection option. 4973 HTTP/1.1 defines the "close" connection option for the sender to signal 4974 that the connection will be closed after completion of the response. For 4975 example, 4977 Connection: close 4979 in either the request or the response header fields indicates that the 4980 connection should not be considered `persistent' (section 8.1) after the 4981 current request/response is complete. 4983 HTTP/1.1 applications that do not support persistent connections MUST 4984 include the "close" connection option in every message. 4986 14.11 Content-Base 4988 The Content-Base entity-header field may be used to specify the base URI 4989 for resolving relative URLs within the entity. This header field is 4990 described as Base in RFC 1808, which is expected to be revised. 4992 Content-Base = "Content-Base" ":" absoluteURI 4994 If no Content-Base field is present, the base URI of an entity is 4995 defined either by its Content-Location (if that Content-Location URI is 4996 an absolute URI) or the URI used to initiate the request, in that order 4997 of precedence. Note, however, that the base URI of the contents within 4998 the entity-body may be redefined within that entity-body. 5000 14.12 Content-Encoding 5002 The Content-Encoding entity-header field is used as a modifier to the 5003 media-type. When present, its value indicates what additional content 5004 codings have been applied to the entity-body, and thus what decoding 5005 mechanisms MUST be applied in order to obtain the media-type referenced 5006 by the Content-Type header field. Content-Encoding is primarily used to 5007 allow a document to be compressed without losing the identity of its 5008 underlying media type. 5010 Content-Encoding = "Content-Encoding" ":" 1#content-coding 5012 Content codings are defined in section 3.5. An example of its use is 5014 Content-Encoding: gzip 5016 The Content-Encoding is a characteristic of the entity identified by the 5017 Request-URI. Typically, the entity-body is stored with this encoding and 5018 is only decoded before rendering or analogous usage. 5020 If multiple encodings have been applied to an entity, the content 5021 codings MUST be listed in the order in which they were applied. 5023 Additional information about the encoding parameters MAY be provided by 5024 other entity-header fields not defined by this specification. 5026 14.13 Content-Language 5028 The Content-Language entity-header field describes the natural 5029 language(s) of the intended audience for the enclosed entity. Note that 5030 this may not be equivalent to all the languages used within the entity- 5031 body. 5033 Content-Language = "Content-Language" ":" 1#language-tag 5035 Language tags are defined in section 3.10. The primary purpose of 5036 Content-Language is to allow a user to identify and differentiate 5037 entities according to the user's own preferred language. Thus, if the 5038 body content is intended only for a Danish-literate audience, the 5039 appropriate field is 5041 Content-Language: da 5043 If no Content-Language is specified, the default is that the content is 5044 intended for all language audiences. This may mean that the sender does 5045 not consider it to be specific to any natural language, or that the 5046 sender does not know for which language it is intended. 5048 Multiple languages MAY be listed for content that is intended for 5049 multiple audiences. For example, a rendition of the "Treaty of 5050 Waitangi," presented simultaneously in the original Maori and English 5051 versions, would call for 5053 Content-Language: mi, en 5055 However, just because multiple languages are present within an entity 5056 does not mean that it is intended for multiple linguistic audiences. An 5057 example would be a beginner's language primer, such as "A First Lesson 5058 in Latin," which is clearly intended to be used by an English-literate 5059 audience. In this case, the Content-Language should only include "en". 5061 Content-Language may be applied to any media type -- it is not limited 5062 to textual documents. 5064 14.14 Content-Length 5066 The Content-Length entity-header field indicates the size of the 5067 message-body, in decimal number of octets, sent to the recipient or, in 5068 the case of the HEAD method, the size of the entity-body that would have 5069 been sent had the request been a GET. 5071 Content-Length = "Content-Length" ":" 1*DIGIT 5072 An example is 5074 Content-Length: 3495 5076 Applications SHOULD use this field to indicate the size of the message- 5077 body to be transferred, regardless of the media type of the entity. It 5078 must be possible for the recipient to reliably determine the end of 5079 HTTP/1.1 requests containing an entity-body, e.g., because the request 5080 has a valid Content-Length field, uses Transfer-Encoding: chunked or a 5081 multipart body. 5083 Any Content-Length greater than or equal to zero is a valid value. 5084 Section 4.4 describes how to determine the length of a message-body if a 5085 Content-Length is not given. 5087 Note: The meaning of this field is significantly different from the 5088 corresponding definition in MIME, where it is an optional field 5089 used within the "message/external-body" content-type. In HTTP, it 5090 SHOULD be sent whenever the message's length can be determined 5091 prior to being transferred. 5093 14.15 Content-Location 5095 The Content-Location entity-header field may be used to supply the 5096 resource location for the entity enclosed in the message. In the case 5097 where a resource has multiple entities associated with it, and those 5098 entities actually have separate locations by which they might be 5099 individually accessed, the server should provide a Content-Location for 5100 the particular variant which is returned. In addition, a server SHOULD 5101 provide a Content-Location for the resource corresponding to the 5102 response entity. 5104 Content-Location = "Content-Location" ":" 5105 ( absoluteURI | relativeURI ) 5107 If no Content-Base header field is present, the value of Content- 5108 Location also defines the base URL for the entity (see section 14.11). 5110 The Content-Location value is not a replacement for the original 5111 requested URI; it is only a statement. of the location of the resource 5112 corresponding to this particular entity at the time of the request. 5113 Future requests MAY use the Content-Location URI if the desire is to 5114 identify the source of that particular entity. 5116 A cache cannot assume that an entity with a Content-Location different 5117 from the URI used to retrieve it can be used to respond to later 5118 requests on that Content-Location URI. However, the Content-Location can 5119 be used to differentiate between multiple entities retrieved from a 5120 single requested resource, as described in section 13.6. 5122 If the Content-Location is a relative URI, the URI is interpreted 5123 relative to any Content-Base URI provided in the response. If no 5124 Content-Base is provided, the relative URI is interpreted relative to 5125 the Request-URI. 5127 14.16 Content-MD5 5129 The Content-MD5 entity-header field, as defined in RFC 1864 [23], is an 5130 MD5 digest of the entity-body for the purpose of providing an end-to-end 5131 message integrity check (MIC) of the entity-body. (Note: a MIC is good 5132 for detecting accidental modification of the entity-body in transit, but 5133 is not proof against malicious attacks.) 5135 Content-MD5 = "Content-MD5" ":" md5-digest 5137 md5-digest = 5139 The Content-MD5 header field may be generated by an origin server to 5140 function as an integrity check of the entity-body. Only origin servers 5141 may generate the Content-MD5 header field; proxies and gateways MUST NOT 5142 generate it, as this would defeat its value as an end-to-end integrity 5143 check. Any recipient of the entity-body, including gateways and proxies, 5144 MAY check that the digest value in this header field matches that of the 5145 entity-body as received. 5147 The MD5 digest is computed based on the content of the entity-body, 5148 including any Content-Encoding that has been applied, but not including 5149 any Transfer-Encoding that may have been applied to the message-body. If 5150 the message is received with a Transfer-Encoding, that encoding must be 5151 removed prior to checking the Content-MD5 value against the received 5152 entity. 5154 This has the result that the digest is computed on the octets of the 5155 entity-body exactly as, and in the order that, they would be sent if no 5156 Transfer-Encoding were being applied. 5158 HTTP extends RFC 1864 to permit the digest to be computed for MIME 5159 composite media-types (e.g., multipart/* and message/rfc822), but this 5160 does not change how the digest is computed as defined in the preceding 5161 paragraph. 5163 Note: There are several consequences of this. The entity-body for 5164 composite types may contain many body-parts, each with its own MIME 5165 and HTTP headers (including Content-MD5, Content-Transfer-Encoding, 5166 and Content-Encoding headers). If a body-part has a Content- 5167 Transfer-Encoding or Content-Encoding header, it is assumed that 5168 the content of the body-part has had the encoding applied, and the 5169 body-part is included in the Content-MD5 digest as is -- i.e., 5170 after the application. The Transfer-Encoding header field is not 5171 allowed within body-parts. 5173 Note: while the definition of Content-MD5 is exactly the same for 5174 HTTP as in RFC 1864 for MIME entity-bodies, there are several ways 5175 in which the application of Content-MD5 to HTTP entity-bodies 5176 differs from its application to MIME entity-bodies. One is that 5177 HTTP, unlike MIME, does not use Content-Transfer-Encoding, and does 5178 use Transfer-Encoding and Content-Encoding. Another is that HTTP 5179 more frequently uses binary content types than MIME, so it is worth 5180 noting that, in such cases, the byte order used to compute the 5181 digest is the transmission byte order defined for the type. Lastly, 5182 HTTP allows transmission of text types with any of several line 5183 break conventions and not just the canonical form using CRLF. 5184 Conversion of all line breaks to CRLF should not be done before 5185 computing or checking the digest: the line break convention used in 5186 the text actually transmitted should be left unaltered when 5187 computing the digest. 5189 14.17 Content-Range 5191 The Content-Range entity-header is sent with a partial entity-body to 5192 specify where in the full entity-body the partial body should be 5193 inserted. It also indicates the total size of the full entity-body. When 5194 a server returns a partial response to a client, it must describe both 5195 the extent of the range covered by the response, and the length of the 5196 entire entity-body. 5198 Content-Range = "Content-Range" ":" content-range-spec 5200 content-range-spec = byte-content-range-spec 5202 byte-content-range-spec = bytes-unit SP first-byte-pos "-" 5203 last-byte-pos "/" entity-length 5205 entity-length = 1*DIGIT 5207 Unlike byte-ranges-specifier values, a byte-content-range-spec may only 5208 specify one range, and must contain absolute byte positions for both the 5209 first and last byte of the range. 5211 A byte-content-range-spec whose last-byte-pos value is less than its 5212 first-byte-pos value, or whose entity-length value is less than or equal 5213 to its last-byte-pos value, is invalid. The recipient of an invalid 5214 byte-content-range-spec MUST ignore it and any content transferred along 5215 with it. 5217 Examples of byte-content-range-spec values, assuming that the entity 5218 contains a total of 1234 bytes: 5220 o The first 500 bytes: 5222 bytes 0-499/1234 5223 o The second 500 bytes: 5225 bytes 500-999/1234 5227 o All except for the first 500 bytes: 5229 bytes 500-1233/1234 5231 o The last 500 bytes: 5233 bytes 734-1233/1234 5235 When an HTTP message includes the content of a single range (for 5236 example, a response to a request for a single range, or to a request for 5237 a set of ranges that overlap without any holes), this content is 5238 transmitted with a Content-Range header, and a Content-Length header 5239 showing the number of bytes actually transferred. For example, 5241 HTTP/1.1 206 Partial content 5242 Date: Wed, 15 Nov 1995 06:25:24 GMT 5243 Last-modified: Wed, 15 Nov 1995 04:58:08 GMT 5244 Content-Range: 21010-47021/47022 5245 Content-Length: 26012 5246 Content-Type: image/gif 5248 When an HTTP message includes the content of multiple ranges (for 5249 example, a response to a request for multiple non-overlapping ranges), 5250 these are transmitted as a multipart MIME message. The multipart MIME 5251 content-type used for this purpose is defined in this specification to 5252 be "multipart/byteranges". See appendix 19.2 for its definition. 5254 A client that cannot decode a MIME multipart/byteranges message should 5255 not ask for multiple byte-ranges in a single request. 5257 When a client requests multiple byte-ranges in one request, the server 5258 SHOULD return them in the order that they appeared in the request. 5260 If the server ignores a byte-range-spec because it is invalid, the 5261 server should treat the request as if the invalid Range header field did 5262 not exist. (Normally, this means return a 200 response containing the 5263 full entity). The reason is that the only time a client will make such 5264 an invalid request is when the entity is smaller than the entity 5265 retrieved by a prior request. 5267 14.18 Content-Type 5269 The Content-Type entity-header field indicates the media type of the 5270 entity-body sent to the recipient or, in the case of the HEAD method, 5271 the media type that would have been sent had the request been a GET. 5273 Content-Type = "Content-Type" ":" media-type 5275 Media types are defined in section 3.7. An example of the field is 5277 Content-Type: text/html; charset=ISO-8859-4 5279 Further discussion of methods for identifying the media type of an 5280 entity is provided in section 7.2.1. 5282 14.19 Date 5284 The Date general-header field represents the date and time at which the 5285 message was originated, having the same semantics as orig-date in RFC 5286 822. The field value is an HTTP-date, as described in section 3.3.1. 5288 Date = "Date" ":" HTTP-date 5290 An example is 5292 Date: Tue, 15 Nov 1994 08:12:31 GMT 5294 If a message is received via direct connection with the user agent (in 5295 the case of requests) or the origin server (in the case of responses), 5296 then the date can be assumed to be the current date at the receiving 5297 end. However, since the date--as it is believed by the origin--is 5298 important for evaluating cached responses, origin servers MUST include a 5299 Date header field in all responses. Clients SHOULD only send a Date 5300 header field in messages that include an entity-body, as in the case of 5301 the PUT and POST requests, and even then it is optional. A received 5302 message which does not have a Date header field SHOULD be assigned one 5303 by the recipient if the message will be cached by that recipient or 5304 gatewayed via a protocol which requires a Date. 5306 In theory, the date SHOULD represent the moment just before the entity 5307 is generated. In practice, the date can be generated at any time during 5308 the message origination without affecting its semantic value. 5310 The format of the Date is an absolute date and time as defined by HTTP- 5311 date in section 3.3; it MUST be sent in RFC1123 [8]-date format. 5313 14.20 ETag 5315 The ETag entity-header field defines the entity tag for the associated 5316 entity. The headers used with entity tags are described in sections 5317 14.20, 14.25, 14.26 and 14.43. The entity tag may be used for comparison 5318 with other entities from the same resource (see section 13.3.2). 5320 ETag = "ETag" ":" entity-tag 5321 Examples: 5323 ETag: "xyzzy" 5324 ETag: W/"xyzzy" 5325 ETag: "" 5327 14.21 Expires 5329 The Expires entity-header field gives the date/time after which the 5330 response should be considered stale. A stale cache entry may not 5331 normally be returned by a cache (either a proxy cache or an user agent 5332 cache) unless it is first validated with the origin server (or with an 5333 intermediate cache that has a fresh copy of the entity). See section 5334 13.2 for further discussion of the expiration model. 5336 The presence of an Expires field does not imply that the original 5337 resource will change or cease to exist at, before, or after that time. 5339 The format is an absolute date and time as defined by HTTP-date in 5340 section 3.3; it MUST be in RFC1123-date format: 5342 Expires = "Expires" ":" HTTP-date 5344 An example of its use is 5346 Expires: Thu, 01 Dec 1994 16:00:00 GMT 5348 Note: if a response includes a Cache-Control field with the max-age 5349 directive, that directive overrides the Expires field. 5351 HTTP/1.1 clients and caches MUST treat other invalid date formats, 5352 especially including the value "0", as in the past (i.e., "already 5353 expired"). 5355 To mark a response as "already expired," an origin server should use an 5356 Expires date that is equal to the Date header value. (See the rules for 5357 expiration calculations in section 13.2.4.) 5359 To mark a response as "never expires," an origin server should use an 5360 Expires date approximately one year from the time the response is sent. 5361 HTTP/1.1 servers should not send Expires dates more than one year in the 5362 future. 5364 The presence of an Expires header field with a date value of some time 5365 in the future on an response that otherwise would by default be non- 5366 cacheable indicates that the response is cachable, unless indicated 5367 otherwise by a Cache-Control header field (section 14.9). 5369 14.22 From 5371 The From request-header field, if given, SHOULD contain an Internet e- 5372 mail address for the human user who controls the requesting user agent. 5373 The address SHOULD be machine-usable, as defined by mailbox in RFC 822 5374 (as updated by RFC 1123 ): 5376 From = "From" ":" mailbox 5378 An example is: 5380 From: webmaster@w3.org 5382 This header field MAY be used for logging purposes and as a means for 5383 identifying the source of invalid or unwanted requests. It SHOULD NOT be 5384 used as an insecure form of access protection. The interpretation of 5385 this field is that the request is being performed on behalf of the 5386 person given, who accepts responsibility for the method performed. In 5387 particular, robot agents SHOULD include this header so that the person 5388 responsible for running the robot can be contacted if problems occur on 5389 the receiving end. 5391 The Internet e-mail address in this field MAY be separate from the 5392 Internet host which issued the request. For example, when a request is 5393 passed through a proxy the original issuer's address SHOULD be used. 5395 Note: The client SHOULD not send the From header field without the 5396 user's approval, as it may conflict with the user's privacy 5397 interests or their site's security policy. It is strongly 5398 recommended that the user be able to disable, enable, and modify 5399 the value of this field at any time prior to a request. 5401 14.23 Host 5403 The Host request-header field specifies the Internet host and port 5404 number of the resource being requested, as obtained from the original 5405 URL given by the user or referring resource (generally an HTTP URL, as 5406 described in section 3.2.2). The Host field value MUST represent the 5407 network location of the origin server or gateway given by the original 5408 URL. This allows the origin server or gateway to differentiate between 5409 internally-ambiguous URLs, such as the root "/" URL of a server for 5410 multiple host names on a single IP address. 5412 Host = "Host" ":" host [ ":" port ] ; Section 3.2.2 5414 A "host" without any trailing port information implies the default port 5415 for the service requested (e.g., "80" for an HTTP URL). For example, a 5416 request on the origin server for MUST 5417 include: 5419 GET /pub/WWW/ HTTP/1.1 5420 Host: www.w3.org 5422 A client MUST include a Host header field in all HTTP/1.1 request 5423 messages on the Internet (i.e., on any message corresponding to a 5424 request for a URL which includes an Internet host address for the 5425 service being requested). If the Host field is not already present, an 5426 HTTP/1.1 proxy MUST add a Host field to the request message prior to 5427 forwarding it on the Internet. All Internet-based HTTP/1.1 servers MUST 5428 respond with a 400 status code to any HTTP/1.1 request message which 5429 lacks a Host header field. 5431 See sections 5.2 and 19.5.1 for other requirements relating to Host. 5433 14.24 If-Modified-Since 5435 The If-Modified-Since request-header field is used with the GET method 5436 to make it conditional: if the requested variant has not been modified 5437 since the time specified in this field, an entity will not be returned 5438 from the server; instead, a 304 (not modified) response will be returned 5439 without any message-body. 5441 If-Modified-Since = "If-Modified-Since" ":" HTTP-date 5443 An example of the field is: 5445 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 5447 A GET method with an If-Modified-Since header and no Range header 5448 requests that the identified entity be transferred only if it has been 5449 modified since the date given by the If-Modified-Since header. The 5450 algorithm for determining this includes the following cases: 5452 a)If the request would normally result in anything other than a 200 5453 (OK) status, or if the passed If-Modified-Since date is invalid, the 5454 response is exactly the same as for a normal GET. A date which is 5455 later than the server's current time is invalid. 5457 b)If the variant has been modified since the If-Modified-Since date, 5458 the response is exactly the same as for a normal GET. 5460 c)If the variant has not been modified since a valid If-Modified-Since 5461 date, the server MUST return a 304 (Not Modified) response. 5463 The purpose of this feature is to allow efficient updates of cached 5464 information with a minimum amount of transaction overhead. 5466 Note that the Range request-header field modifies the meaning of 5467 If-Modified-Since; see section 14.36 for full details. 5469 Note that If-Modified-Since times are interpreted by the server, 5470 whose clock may not be synchronized with the client. 5472 Note that if a client uses an arbitrary date in the If-Modified-Since 5473 header instead of a date taken from the Last-Modified header for the 5474 same request, the client should be aware of the fact that this date is 5475 interpreted in the server's understanding of time. The client should 5476 consider unsynchronized clocks and rounding problems due to the 5477 different encodings of time between the client and server. This includes 5478 the possibility of race conditions if the document has changed between 5479 the time it was first requested and the If-Modified-Since date of a 5480 subsequent request, and the possibility of clock-skew-related problems 5481 if the If-Modified-Since date is derived from the client's clock without 5482 correction to the server's clock. Corrections for different time bases 5483 between client and server are at best approximate due to network 5484 latency. 5486 14.25 If-Match 5488 The If-Match request-header field is used with a method to make it 5489 conditional. A client that has one or more entities previously obtained 5490 from the resource can verify that one of those entities is current by 5491 including a list of their associated entity tags in the If-Match header 5492 field. The purpose of this feature is to allow efficient updates of 5493 cached information with a minimum amount of transaction overhead. It is 5494 also used, on updating requests, to prevent inadvertent modification of 5495 the wrong version of a resource. As a special case, the value "*" 5496 matches any current entity of the resource. 5498 If-Match = "If-Match" ":" ( "*" | 1#entity-tag ) 5500 If any of the entity tags match the entity tag of the entity that would 5501 have been returned in the response to a similar GET request (without the 5502 If-Match header) on that resource, or if "*" is given and any current 5503 entity exists for that resource, then the server MAY perform the 5504 requested method as if the If-Match header field did not exist. 5506 A server MUST use the strong comparison function (see section 3.11) to 5507 compare the entity tags in If-Match. 5509 If none of the entity tags match, or if "*" is given and no current 5510 entity exists, the server MUST NOT perform the requested method, and 5511 MUST return a 412 (Precondition Failed) response. This behavior is most 5512 useful when the client wants to prevent an updating method, such as PUT, 5513 from modifying a resource that has changed since the client last 5514 retrieved it. 5516 If the request would, without the If-Match header field, result in 5517 anything other than a 2xx status, then the If-Match header MUST be 5518 ignored. 5520 The meaning of "If-Match: *" is that the method SHOULD be performed if 5521 the representation selected by the origin server (or by a cache, 5522 possibly using the Vary mechanism, see section 14.43) exists, and MUST 5523 NOT be performed if the representation does not exist. 5525 A request intended to update a resource (e.g., a PUT) MAY include an If- 5526 Match header field to signal that the request method MUST NOT be applied 5527 if the entity corresponding to the If-Match value (a single entity tag) 5528 is no longer a representation of that resource. This allows the user to 5529 indicate that they do not wish the request to be successful if the 5530 resource has been changed without their knowledge. Examples: 5532 If-Match: "xyzzy" 5533 If-Match: W/"xyzzy" 5534 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 5535 If-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 5536 If-Match: * 5538 14.26 If-None-Match 5540 The If-None-Match request-header field is used with a method to make it 5541 conditional. A client that has one or more entities previously obtained 5542 from the resource can verify that none of those entities is current by 5543 including a list of their associated entity tags in the If-None-Match 5544 header field. The purpose of this feature is to allow efficient updates 5545 of cached information with a minimum amount of transaction overhead. It 5546 is also used, on updating requests, to prevent inadvertent modification 5547 of a resource which was not known to exist. 5549 As a special case, the value "*" matches any current entity of the 5550 resource. 5552 If-None-Match = "If-None-Match" ":" ( "*" | 1#entity-tag ) 5554 If any of the entity tags match the entity tag of the entity that would 5555 have been returned in the response to a similar GET request (without the 5556 If-None-Match header) on that resource, or if "*" is given and any 5557 current entity exists for that resource, then the server MUST NOT 5558 perform the requested method. Instead, if the request method was GET or 5559 HEAD, the server SHOULD respond with a 304 (Not Modified) response, 5560 including the cache-related entity-header fields (particularly ETag) of 5561 one of the entities that matched. For all other request methods, the 5562 server MUST respond with a status of 412 (Precondition Failed). 5564 See section 13.3.3 for rules on how to determine if two entity tags 5565 match. The weak comparison function can only be used with GET or HEAD 5566 requests. 5568 If none of the entity tags match, or if "*" is given and no current 5569 entity exists, then the server MAY perform the requested method as if 5570 the If-None-Match header field did not exist. 5572 If the request would, without the If-None-Match header field, result in 5573 anything other than a 2xx status, then the If-None-Match header MUST be 5574 ignored. 5576 The meaning of "If-None-Match: *" is that the method MUST NOT be 5577 performed if the representation selected by the origin server (or by a 5578 cache, possibly using the Vary mechanism, see section 14.43) exists, and 5579 SHOULD be performed if the representation does not exist. This feature 5580 may be useful in preventing races between PUT operations. 5582 Examples: 5584 If-None-Match: "xyzzy" 5585 If-None-Match: W/"xyzzy" 5586 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 5587 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 5588 If-None-Match: * 5590 14.27 If-Range 5592 If a client has a partial copy of an entity in its cache, and wishes to 5593 have an up-to-date copy of the entire entity in its cache, it could use 5594 the Range request-header with a conditional GET (using either or both of 5595 If-Unmodified-Since and If-Match.) However, if the condition fails 5596 because the entity has been modified, the client would then have to make 5597 a second request to obtain the entire current entity-body. 5599 The If-Range header allows a client to "short-circuit" the second 5600 request. Informally, its meaning is `if the entity is unchanged, send me 5601 the part(s) that I am missing; otherwise, send me the entire new 5602 entity.' 5604 If-Range = "If-Range" ":" ( entity-tag | HTTP-date ) 5606 If the client has no entity tag for an entity, but does have a Last- 5607 Modified date, it may use that date in a If-Range header. (The server 5608 can distinguish between a valid HTTP-date and any form of entity-tag by 5609 examining no more than two characters.) The If-Range header should only 5610 be used together with a Range header, and must be ignored if the request 5611 does not include a Range header, or if the server does not support the 5612 sub-range operation. 5614 If the entity tag given in the If-Range header matches the current 5615 entity tag for the entity, then the server should provide the specified 5616 sub-range of the entity using a 206 (Partial content) response. If the 5617 entity tag does not match, then the server should return the entire 5618 entity using a 200 (OK) response. 5620 14.28 If-Unmodified-Since 5622 The If-Unmodified-Since request-header field is used with a method to 5623 make it conditional. If the requested resource has not been modified 5624 since the time specified in this field, the server should perform the 5625 requested operation as if the If-Unmodified-Since header were not 5626 present. 5628 If the requested variant has been modified since the specified time, the 5629 server MUST NOT perform the requested operation, and MUST return a 412 5630 (Precondition Failed). 5632 If-Unmodified-Since = "If-Unmodified-Since" ":" HTTP-date 5634 An example of the field is: 5636 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 5638 If the request normally (i.e., without the If-Unmodified-Since header) 5639 would result in anything other than a 2xx status, the If-Unmodified- 5640 Since header should be ignored. 5642 If the specified date is invalid, the header is ignored. 5644 14.29 Last-Modified 5646 The Last-Modified entity-header field indicates the date and time at 5647 which the origin server believes the variant was last modified. 5649 Last-Modified = "Last-Modified" ":" HTTP-date 5651 An example of its use is 5653 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 5655 The exact meaning of this header field depends on the implementation of 5656 the origin server and the nature of the original resource. For files, it 5657 may be just the file system last-modified time. For entities with 5658 dynamically included parts, it may be the most recent of the set of 5659 last-modify times for its component parts. For database gateways, it may 5660 be the last-update time stamp of the record. For virtual objects, it may 5661 be the last time the internal state changed. 5663 An origin server MUST NOT send a Last-Modified date which is later than 5664 the server's time of message origination. In such cases, where the 5665 resource's last modification would indicate some time in the future, the 5666 server MUST replace that date with the message origination date. 5668 An origin server should obtain the Last-Modified value of the entity as 5669 close as possible to the time that it generates the Date value of its 5670 response. This allows a recipient to make an accurate assessment of the 5671 entity's modification time, especially if the entity changes near the 5672 time that the response is generated. 5674 HTTP/1.1 servers SHOULD send Last-Modified whenever feasible. 5676 14.30 Location 5678 The Location response-header field is used to redirect the recipient to 5679 a location other than the Request-URI for completion of the request or 5680 identification of a new resource. For 201 (Created) responses, the 5681 Location is that of the new resource which was created by the request. 5682 For 3xx responses, the location SHOULD indicate the server's preferred 5683 URL for automatic redirection to the resource. The field value consists 5684 of a single absolute URL. 5686 Location = "Location" ":" absoluteURI 5688 An example is 5690 Location: http://www.w3.org/pub/WWW/People.html 5692 Note: The Content-Location header field (section 14.15) differs 5693 from Location in that the Content-Location identifies the original 5694 location of the entity enclosed in the request. It is therefore 5695 possible for a response to contain header fields for both Location 5696 and Content-Location. Also see section 13.10 for cache requirements 5697 of some methods. 5699 14.31 Max-Forwards 5701 The Max-Forwards request-header field may be used with the TRACE method 5702 (section 14.31) to limit the number of proxies or gateways that can 5703 forward the request to the next inbound server. This can be useful when 5704 the client is attempting to trace a request chain which appears to be 5705 failing or looping in mid-chain. 5707 Max-Forwards = "Max-Forwards" ":" 1*DIGIT 5709 The Max-Forwards value is a decimal integer indicating the remaining 5710 number of times this request message may be forwarded. 5712 Each proxy or gateway recipient of a TRACE request containing a Max- 5713 Forwards header field SHOULD check and update its value prior to 5714 forwarding the request. If the received value is zero (0), the recipient 5715 SHOULD NOT forward the request; instead, it SHOULD respond as the final 5716 recipient with a 200 (OK) response containing the received request 5717 message as the response entity-body (as described in section 9.8). If 5718 the received Max-Forwards value is greater than zero, then the forwarded 5719 message SHOULD contain an updated Max-Forwards field with a value 5720 decremented by one (1). 5722 The Max-Forwards header field SHOULD be ignored for all other methods 5723 defined by this specification and for any extension methods for which it 5724 is not explicitly referred to as part of that method definition. 5726 14.32 Pragma 5728 The Pragma general-header field is used to include implementation- 5729 specific directives that may apply to any recipient along the 5730 request/response chain. All pragma directives specify optional behavior 5731 from the viewpoint of the protocol; however, some systems MAY require 5732 that behavior be consistent with the directives. 5734 Pragma = "Pragma" ":" 1#pragma-directive 5736 pragma-directive = "no-cache" | extension-pragma 5737 extension-pragma = token [ "=" ( token | quoted-string ) ] 5739 When the no-cache directive is present in a request message, an 5740 application SHOULD forward the request toward the origin server even if 5741 it has a cached copy of what is being requested. This pragma directive 5742 has the same semantics as the no-cache cache-directive (see section 5743 14.9) and is defined here for backwards compatibility with HTTP/1.0. 5744 Clients SHOULD include both header fields when a no-cache request is 5745 sent to a server not known to be HTTP/1.1 compliant. 5747 Pragma directives MUST be passed through by a proxy or gateway 5748 application, regardless of their significance to that application, since 5749 the directives may be applicable to all recipients along the 5750 request/response chain. It is not possible to specify a pragma for a 5751 specific recipient; however, any pragma directive not relevant to a 5752 recipient SHOULD be ignored by that recipient. 5754 HTTP/1.1 clients SHOULD NOT send the Pragma request-header. HTTP/1.1 5755 caches SHOULD treat "Pragma: no-cache" as if the client had sent "Cache- 5756 Control: no-cache". No new Pragma directives will be defined in HTTP. 5758 14.33 Proxy-Authenticate 5760 The Proxy-Authenticate response-header field MUST be included as part of 5761 a 407 (Proxy Authentication Required) response. The field value consists 5762 of a challenge that indicates the authentication scheme and parameters 5763 applicable to the proxy for this Request-URI. 5765 Proxy-Authenticate = "Proxy-Authenticate" ":" challenge 5767 The HTTP access authentication process is described in section 11. 5768 Unlike WWW-Authenticate, the Proxy-Authenticate header field applies 5769 only to the current connection and SHOULD NOT be passed on to downstream 5770 clients. However, an intermediate proxy may need to obtain its own 5771 credentials by requesting them from the downstream client, which in some 5772 circumstances will appear as if the proxy is forwarding the Proxy- 5773 Authenticate header field. 5775 14.34 Proxy-Authorization 5777 The Proxy-Authorization request-header field allows the client to 5778 identify itself (or its user) to a proxy which requires authentication. 5779 The Proxy-Authorization field value consists of credentials containing 5780 the authentication information of the user agent for the proxy and/or 5781 realm of the resource being requested. 5783 Proxy-Authorization = "Proxy-Authorization" ":" credentials 5785 The HTTP access authentication process is described in section 11. 5786 Unlike Authorization, the Proxy-Authorization header field applies only 5787 to the next outbound proxy that demanded authentication using the Proxy- 5788 Authenticate field. When multiple proxies are used in a chain, the 5789 Proxy-Authorization header field is consumed by the first outbound proxy 5790 that was expecting to receive credentials. A proxy MAY relay the 5791 credentials from the client request to the next proxy if that is the 5792 mechanism by which the proxies cooperatively authenticate a given 5793 request. 5795 14.35 Public 5797 The Public response-header field lists the set of methods supported by 5798 the server. The purpose of this field is strictly to inform the 5799 recipient of the capabilities of the server regarding unusual methods. 5800 The methods listed may or may not be applicable to the Request-URI; the 5801 Allow header field (section 14.7) MAY be used to indicate methods 5802 allowed for a particular URI. 5804 Public = "Public" ":" 1#method 5806 Example of use: 5808 Public: OPTIONS, MGET, MHEAD, GET, HEAD 5809 This header field applies only to the server directly connected to the 5810 client (i.e., the nearest neighbor in a chain of connections). If the 5811 response passes through a proxy, the proxy MUST either remove the Public 5812 header field or replace it with one applicable to its own capabilities. 5814 14.36 Range 5816 14.36.1 Byte Ranges 5818 Since all HTTP entities are represented in HTTP messages as sequences of 5819 bytes, the concept of a byte range is meaningful for any HTTP entity. 5820 (However, not all clients and servers need to support byte-range 5821 operations.) 5823 Byte range specifications in HTTP apply to the sequence of bytes in the 5824 entity-body (not necessarily the same as the message-body). 5826 A byte range operation may specify a single range of bytes, or a set of 5827 ranges within a single entity. 5829 ranges-specifier = byte-ranges-specifier 5831 byte-ranges-specifier = bytes-unit "=" byte-range-set 5833 byte-range-set = 1#( byte-range-spec | suffix-byte-range-spec ) 5835 byte-range-spec = first-byte-pos "-" [last-byte-pos] 5837 first-byte-pos = 1*DIGIT 5839 last-byte-pos = 1*DIGIT 5841 The first-byte-pos value in a byte-range-spec gives the byte-offset of 5842 the first byte in a range. The last-byte-pos value gives the byte-offset 5843 of the last byte in the range; that is, the byte positions specified are 5844 inclusive. Byte offsets start at zero. 5846 If the last-byte-pos value is present, it must be greater than or equal 5847 to the first-byte-pos in that byte-range-spec, or the byte-range-spec is 5848 invalid. The recipient of an invalid byte-range-spec must ignore it. 5850 If the last-byte-pos value is absent, or if the value is greater than or 5851 equal to the current length of the entity-body, last-byte-pos is taken 5852 to be equal to one less than the current length of the entity-body in 5853 bytes. 5855 By its choice of last-byte-pos, a client can limit the number of bytes 5856 retrieved without knowing the size of the entity. 5858 suffix-byte-range-spec = "-" suffix-length 5860 suffix-length = 1*DIGIT 5862 A suffix-byte-range-spec is used to specify the suffix of the entity- 5863 body, of a length given by the suffix-length value. (That is, this form 5864 specifies the last N bytes of an entity-body.) If the entity is shorter 5865 than the specified suffix-length, the entire entity-body is used. 5867 Examples of byte-ranges-specifier values (assuming an entity-body of 5868 length 10000): 5870 o The first 500 bytes (byte offsets 0-499, inclusive): 5872 bytes=0-499 5874 o The second 500 bytes (byte offsets 500-999, inclusive): 5876 bytes=500-999 5878 o The final 500 bytes (byte offsets 9500-9999, inclusive): 5880 bytes=-500 5882 o Or 5884 bytes=9500- 5886 o The first and last bytes only (bytes 0 and 9999): 5888 bytes=0-0,-1 5890 o Several legal but not canonical specifications of the second 500 5891 bytes (byte offsets 500-999, inclusive): 5893 bytes=500-600,601-999 5895 bytes=500-700,601-999 5897 14.36.2 Range Retrieval Requests 5899 HTTP retrieval requests using conditional or unconditional GET methods 5900 may request one or more sub-ranges of the entity, instead of the entire 5901 entity, using the Range request header, which applies to the entity 5902 returned as the result of the request: 5904 Range = "Range" ":" ranges-specifier 5906 A server MAY ignore the Range header. However, HTTP/1.1 origin servers 5907 and intermediate caches SHOULD support byte ranges when possible, since 5908 Range supports efficient recovery from partially failed transfers, and 5909 supports efficient partial retrieval of large entities. 5911 If the server supports the Range header and the specified range or 5912 ranges are appropriate for the entity: 5914 o The presence of a Range header in an unconditional GET modifies 5915 what is returned if the GET is otherwise successful. In other 5916 words, the response carries a status code of 206 (Partial Content) 5917 instead of 200 (OK). 5919 o The presence of a Range header in a conditional GET (a request 5920 using one or both of If-Modified-Since and If-None-Match, or one or 5921 both of If-Unmodified-Since and If-Match) modifies what is returned 5922 if the GET is otherwise successful and the condition is true. It 5923 does not affect the 304 (Not Modified) response returned if the 5924 conditional is false. 5926 In some cases, it may be more appropriate to use the If-Range header 5927 (see section 14.27) in addition to the Range header. 5929 If a proxy that supports ranges receives a Range request, forwards the 5930 request to an inbound server, and receives an entire entity in reply, it 5931 SHOULD only return the requested range to its client. It SHOULD store 5932 the entire received response in its cache, if that is consistent with 5933 its cache allocation policies. 5935 14.37 Referer 5937 The Referer[sic] request-header field allows the client to specify, for 5938 the server's benefit, the address (URI) of the resource from which the 5939 Request-URI was obtained (the "referrer", although the header field is 5940 misspelled.) The Referer request-header allows a server to generate 5941 lists of back-links to resources for interest, logging, optimized 5942 caching, etc. It also allows obsolete or mistyped links to be traced for 5943 maintenance. The Referer field MUST NOT be sent if the Request-URI was 5944 obtained from a source that does not have its own URI, such as input 5945 from the user keyboard. 5947 Referer = "Referer" ":" ( absoluteURI | relativeURI ) 5949 Example: 5951 Referer: http://www.w3.org/hypertext/DataSources/Overview.html 5953 If the field value is a partial URI, it SHOULD be interpreted relative 5954 to the Request-URI. The URI MUST NOT include a fragment. 5956 Note: Because the source of a link may be private information or 5957 may reveal an otherwise private information source, it is strongly 5958 recommended that the user be able to select whether or not the 5959 Referer field is sent. For example, a browser client could have a 5960 toggle switch for browsing openly/anonymously, which would 5961 respectively enable/disable the sending of Referer and From 5962 information. 5964 14.38 Retry-After 5966 The Retry-After response-header field can be used with a 503 (Service 5967 Unavailable) response to indicate how long the service is expected to be 5968 unavailable to the requesting client. The value of this field can be 5969 either an HTTP-date or an integer number of seconds (in decimal) after 5970 the time of the response. 5972 Retry-After = "Retry-After" ":" ( HTTP-date | delta-seconds ) 5974 Two examples of its use are 5976 Retry-After: Fri, 31 Dec 1999 23:59:59 GMT 5977 Retry-After: 120 5979 In the latter example, the delay is 2 minutes. 5981 14.39 Server 5983 The Server response-header field contains information about the software 5984 used by the origin server to handle the request. The field can contain 5985 multiple product tokens (section 3.8) and comments identifying the 5986 server and any significant subproducts. The product tokens are listed in 5987 order of their significance for identifying the application. 5989 Server = "Server" ":" 1*( product | comment ) 5991 Example: 5993 Server: CERN/3.0 libwww/2.17 5995 If the response is being forwarded through a proxy, the proxy 5996 application MUST NOT modify the Server response-header. Instead, it 5997 SHOULD include a Via field (as described in section 14.44). 5999 Note: Revealing the specific software version of the server may 6000 allow the server machine to become more vulnerable to attacks 6001 against software that is known to contain security holes. Server 6002 implementers are encouraged to make this field a configurable 6003 option. 6005 14.40 Transfer-Encoding 6007 The Transfer-Encoding general-header field indicates what (if any) type 6008 of transformation has been applied to the message body in order to 6009 safely transfer it between the sender and the recipient. This differs 6010 from the Content-Encoding in that the transfer coding is a property of 6011 the message, not of the entity. 6013 Transfer-Encoding = "Transfer-Encoding" ":" 1#transfer- 6014 coding 6016 Transfer codings are defined in section 3.6. An example is: 6018 Transfer-Encoding: chunked 6020 Many older HTTP/1.0 applications do not understand the Transfer-Encoding 6021 header. 6023 14.41 Upgrade 6025 The Upgrade general-header allows the client to specify what additional 6026 communication protocols it supports and would like to use if the server 6027 finds it appropriate to switch protocols. The server MUST use the 6028 Upgrade header field within a 101 (Switching Protocols) response to 6029 indicate which protocol(s) are being switched. 6031 Upgrade = "Upgrade" ":" 1#product 6033 For example, 6035 Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11 6037 The Upgrade header field is intended to provide a simple mechanism for 6038 transition from HTTP/1.1 to some other, incompatible protocol. It does 6039 so by allowing the client to advertise its desire to use another 6040 protocol, such as a later version of HTTP with a higher major version 6041 number, even though the current request has been made using HTTP/1.1. 6042 This eases the difficult transition between incompatible protocols by 6043 allowing the client to initiate a request in the more commonly supported 6044 protocol while indicating to the server that it would like to use a 6045 "better" protocol if available (where "better" is determined by the 6046 server, possibly according to the nature of the method and/or resource 6047 being requested). 6049 The Upgrade header field only applies to switching application-layer 6050 protocols upon the existing transport-layer connection. Upgrade cannot 6051 be used to insist on a protocol change; its acceptance and use by the 6052 server is optional. The capabilities and nature of the application-layer 6053 communication after the protocol change is entirely dependent upon the 6054 new protocol chosen, although the first action after changing the 6055 protocol MUST be a response to the initial HTTP request containing the 6056 Upgrade header field. 6058 The Upgrade header field only applies to the immediate connection. 6059 Therefore, the upgrade keyword MUST be supplied within a Connection 6060 header field (section 14.10) whenever Upgrade is present in an HTTP/1.1 6061 message. 6063 The Upgrade header field cannot be used to indicate a switch to a 6064 protocol on a different connection. For that purpose, it is more 6065 appropriate to use a 301, 302, 303, or 305 redirection response. 6067 This specification only defines the protocol name "HTTP" for use by the 6068 family of Hypertext Transfer Protocols, as defined by the HTTP version 6069 rules of section 3.1 and future updates to this specification. Any token 6070 can be used as a protocol name; however, it will only be useful if both 6071 the client and server associate the name with the same protocol. 6073 14.42 User-Agent 6075 The User-Agent request-header field contains information about the user 6076 agent originating the request. This is for statistical purposes, the 6077 tracing of protocol violations, and automated recognition of user agents 6078 for the sake of tailoring responses to avoid particular user agent 6079 limitations. User agents SHOULD include this field with requests. The 6080 field can contain multiple product tokens (section 3.8) and comments 6081 identifying the agent and any subproducts which form a significant part 6082 of the user agent. By convention, the product tokens are listed in order 6083 of their significance for identifying the application. 6085 User-Agent = "User-Agent" ":" 1*( product | comment ) 6087 Example: 6089 User-Agent: CERN-LineMode/2.15 libwww/2.17b3 6091 14.43 Vary 6093 The Vary response-header field is used by a server to signal that the 6094 response entity was selected from the available representations of the 6095 response using server-driven negotiation (section 12). The Vary field 6096 value indicates either that the given set of header fields encompass the 6097 dimensions over which the representation might vary, or that the 6098 dimensions of variance are unspecified ("*") and thus may vary over any 6099 aspect of future requests. 6101 Vary = "Vary" ":" ( "*" | 1#field-name ) 6102 An HTTP/1.1 server MUST include an appropriate Vary header field with 6103 any cachable response that is subject to server-driven negotiation. 6104 Doing so allows a cache to properly interpret future requests on that 6105 resource and informs the user agent about the presence of negotiation on 6106 that resource. A server SHOULD include an appropriate Vary header field 6107 with a non-cachable response that is subject to server-driven 6108 negotiation, since this might provide the user agent with useful 6109 information about the dimensions over which the response might vary. 6111 The set of header fields named by the Vary field value is known as the 6112 "selecting" request-headers. 6114 When the cache receives a subsequent request whose Request-URI specifies 6115 one or more cache entries including a Vary header, the cache MUST NOT 6116 use such a cache entry to construct a response to the new request unless 6117 all of the headers named in the cached Vary header are present in the 6118 new request, and all of the stored selecting request-headers from the 6119 previous request match the corresponding headers in the new request. 6121 The selecting request-headers from two requests are defined to match if 6122 and only if the selecting request-headers in the first request can be 6123 transformed to the selecting request-headers in the second request by 6124 adding or removing linear whitespace (LWS) at places where this is 6125 allowed by the corresponding BNF, and/or combining multiple message- 6126 header fields with the same field name following the rules about message 6127 headers in section 4.2. 6129 A Vary field value of "*" signals that unspecified parameters, possibly 6130 other than the contents of request-header fields (e.g., the network 6131 address of the client), play a role in the selection of the response 6132 representation. Subsequent requests on that resource can only be 6133 properly interpreted by the origin server, and thus a cache MUST forward 6134 a (possibly conditional) request even when it has a fresh response 6135 cached for the resource. See section 13.6 for use of the Vary header by 6136 caches. 6138 A Vary field value consisting of a list of field-names signals that the 6139 representation selected for the response is based on a selection 6140 algorithm which considers ONLY the listed request-header field values in 6141 selecting the most appropriate representation. A cache MAY assume that 6142 the same selection will be made for future requests with the same values 6143 for the listed field names, for the duration of time in which the 6144 response is fresh. 6146 The field-names given are not limited to the set of standard request- 6147 header fields defined by this specification. Field names are case- 6148 insensitive. 6150 14.44 Via 6152 The Via general-header field MUST be used by gateways and proxies to 6153 indicate the intermediate protocols and recipients between the user 6154 agent and the server on requests, and between the origin server and the 6155 client on responses. It is analogous to the "Received" field of RFC 822 6156 and is intended to be used for tracking message forwards, avoiding 6157 request loops, and identifying the protocol capabilities of all senders 6158 along the request/response chain. 6160 Via = "Via" ":" 1#( received-protocol received-by [ comment ] ) 6162 received-protocol = [ protocol-name "/" ] protocol-version 6163 protocol-name = token 6164 protocol-version = token 6165 received-by = ( host [ ":" port ] ) | pseudonym 6166 pseudonym = token 6168 The received-protocol indicates the protocol version of the message 6169 received by the server or client along each segment of the 6170 request/response chain. The received-protocol version is appended to the 6171 Via field value when the message is forwarded so that information about 6172 the protocol capabilities of upstream applications remains visible to 6173 all recipients. 6175 The protocol-name is optional if and only if it would be "HTTP". The 6176 received-by field is normally the host and optional port number of a 6177 recipient server or client that subsequently forwarded the message. 6178 However, if the real host is considered to be sensitive information, it 6179 MAY be replaced by a pseudonym. If the port is not given, it MAY be 6180 assumed to be the default port of the received-protocol. 6182 Multiple Via field values represent each proxy or gateway that has 6183 forwarded the message. Each recipient MUST append its information such 6184 that the end result is ordered according to the sequence of forwarding 6185 applications. 6187 Comments MAY be used in the Via header field to identify the software of 6188 the recipient proxy or gateway, analogous to the User-Agent and Server 6189 header fields. However, all comments in the Via field are optional and 6190 MAY be removed by any recipient prior to forwarding the message. 6192 For example, a request message could be sent from an HTTP/1.0 user agent 6193 to an internal proxy code-named "fred", which uses HTTP/1.1 to forward 6194 the request to a public proxy at nowhere.com, which completes the 6195 request by forwarding it to the origin server at www.ics.uci.edu. The 6196 request received by www.ics.uci.edu would then have the following Via 6197 header field: 6199 Via: 1.0 fred, 1.1 nowhere.com (Apache/1.1) 6200 Proxies and gateways used as a portal through a network firewall SHOULD 6201 NOT, by default, forward the names and ports of hosts within the 6202 firewall region. This information SHOULD only be propagated if 6203 explicitly enabled. If not enabled, the received-by host of any host 6204 behind the firewall SHOULD be replaced by an appropriate pseudonym for 6205 that host. 6207 For organizations that have strong privacy requirements for hiding 6208 internal structures, a proxy MAY combine an ordered subsequence of Via 6209 header field entries with identical received-protocol values into a 6210 single such entry. For example, 6212 Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy 6214 could be collapsed to 6216 Via: 1.0 ricky, 1.1 mertz, 1.0 lucy 6218 Applications SHOULD NOT combine multiple entries unless they are all 6219 under the same organizational control and the hosts have already been 6220 replaced by pseudonyms. Applications MUST NOT combine entries which have 6221 different received-protocol values. 6223 14.45 Warning 6225 The Warning response-header field is used to carry additional 6226 information about the status of a response which may not be reflected by 6227 the response status code. This information is typically, though not 6228 exclusively, used to warn about a possible lack of semantic transparency 6229 from caching operations. 6231 Warning headers are sent with responses using: 6233 Warning = "Warning" ":" 1#warning-value 6235 warning-value = warn-code SP warn-agent SP warn-text 6236 warn-code = 2DIGIT 6237 warn-agent = ( host [ ":" port ] ) | pseudonym 6238 ; the name or pseudonym of the server adding 6239 ; the Warning header, for use in debugging 6240 warn-text = quoted-string 6242 A response may carry more than one Warning header. 6244 The warn-text should be in a natural language and character set that is 6245 most likely to be intelligible to the human user receiving the response. 6246 This decision may be based on any available knowledge, such as the 6247 location of the cache or user, the Accept-Language field in a request, 6248 the Content-Language field in a response, etc. The default language is 6249 English and the default character set is ISO-8599-1. 6251 If a character set other than ISO-8599-1 is used, it MUST be encoded in 6252 the warn-text using the method described in RFC 1522 [14]. 6254 Any server or cache may add Warning headers to a response. New Warning 6255 headers should be added after any existing Warning headers. A cache MUST 6256 NOT delete any Warning header that it received with a response. However, 6257 if a cache successfully validates a cache entry, it SHOULD remove any 6258 Warning headers previously attached to that entry except as specified 6259 for specific Warning codes. It MUST then add any Warning headers 6260 received in the validating response. In other words, Warning headers are 6261 those that would be attached to the most recent relevant response. 6263 When multiple Warning headers are attached to a response, the user agent 6264 SHOULD display as many of them as possible, in the order that they 6265 appear in the response. If it is not possible to display all of the 6266 warnings, the user agent should follow these heuristics: 6268 o Warnings that appear early in the response take priority over those 6269 appearing later in the response. 6270 o Warnings in the user's preferred character set take priority over 6271 warnings in other character sets but with identical warn-codes and 6272 warn-agents. 6273 Systems that generate multiple Warning headers should order them with 6274 this user agent behavior in mind. 6276 This is a list of the currently-defined warn-codes, each with a 6277 recommended warn-text in English, and a description of its meaning. 6279 10 Response is stale 6280 MUST be included whenever the returned response is stale. A cache may 6281 add this warning to any response, but may never remove it until the 6282 response is known to be fresh. 6284 11 Revalidation failed 6285 MUST be included if a cache returns a stale response because an 6286 attempt to revalidate the response failed, due to an inability to 6287 reach the server. A cache may add this warning to any response, but 6288 may never remove it until the response is successfully revalidated. 6290 12 Disconnected operation 6291 SHOULD be included if the cache is intentionally disconnected from 6292 the rest of the network for a period of time. 6294 13 Heuristic expiration 6295 MUST be included if the cache heuristically chose a freshness 6296 lifetime greater than 24 hours and the response's age is greater than 6297 24 hours. 6299 14 Transformation applied 6300 MUST be added by an intermediate cache or proxy if it applies any 6301 transformation changing the content-coding (as specified in the 6302 Content-Encoding header) or media-type (as specified in the Content- 6303 Type header) of the response, unless this Warning code already 6304 appears in the response. MUST NOT be deleted from a response even 6305 after revalidation. 6307 99 Miscellaneous warning 6308 The warning text may include arbitrary information to be presented to 6309 a human user, or logged. A system receiving this warning MUST NOT 6310 take any automated action. 6312 14.46 WWW-Authenticate 6314 The WWW-Authenticate response-header field MUST be included in 401 6315 (Unauthorized) response messages. The field value consists of at least 6316 one challenge that indicates the authentication scheme(s) and parameters 6317 applicable to the Request-URI. 6319 WWW-Authenticate = "WWW-Authenticate" ":" 1#challenge 6321 The HTTP access authentication process is described in section 11. User 6322 agents MUST take special care in parsing the WWW-Authenticate field 6323 value if it contains more than one challenge, or if more than one WWW- 6324 Authenticate header field is provided, since the contents of a challenge 6325 may itself contain a comma-separated list of authentication parameters. 6327 15 Security Considerations 6329 This section is meant to inform application developers, information 6330 providers, and users of the security limitations in HTTP/1.1 as 6331 described by this document. The discussion does not include definitive 6332 solutions to the problems revealed, though it does make some suggestions 6333 for reducing security risks. 6335 15.1 Authentication of Clients 6337 The Basic authentication scheme is not a secure method of user 6338 authentication, nor does it in any way protect the entity, which is 6339 transmitted in clear text across the physical network used as the 6340 carrier. HTTP does not prevent additional authentication schemes and 6341 encryption mechanisms from being employed to increase security or the 6342 addition of enhancements (such as schemes to use one-time passwords) to 6343 Basic authentication. 6345 The most serious flaw in Basic authentication is that it results in the 6346 essentially clear text transmission of the user's password over the 6347 physical network. It is this problem which Digest Authentication 6348 attempts to address. 6350 Because Basic authentication involves the clear text transmission of 6351 passwords it SHOULD never be used (without enhancements) to protect 6352 sensitive or valuable information. 6354 A common use of Basic authentication is for identification purposes -- 6355 requiring the user to provide a user name and password as a means of 6356 identification, for example, for purposes of gathering accurate usage 6357 statistics on a server. When used in this way it is tempting to think 6358 that there is no danger in its use if illicit access to the protected 6359 documents is not a major concern. This is only correct if the server 6360 issues both user name and password to the users and in particular does 6361 not allow the user to choose his or her own password. The danger arises 6362 because naive users frequently reuse a single password to avoid the task 6363 of maintaining multiple passwords. 6365 If a server permits users to select their own passwords, then the threat 6366 is not only illicit access to documents on the server but also illicit 6367 access to the accounts of all users who have chosen to use their account 6368 password. If users are allowed to choose their own password that also 6369 means the server must maintain files containing the (presumably 6370 encrypted) passwords. Many of these may be the account passwords of 6371 users perhaps at distant sites. The owner or administrator of such a 6372 system could conceivably incur liability if this information is not 6373 maintained in a secure fashion. 6375 Basic Authentication is also vulnerable to spoofing by counterfeit 6376 servers. If a user can be led to believe that he is connecting to a host 6377 containing information protected by basic authentication when in fact he 6378 is connecting to a hostile server or gateway then the attacker can 6379 request a password, store it for later use, and feign an error. This 6380 type of attack is not possible with Digest Authentication [32]. Server 6381 implementers SHOULD guard against the possibility of this sort of 6382 counterfeiting by gateways or CGI scripts. In particular it is very 6383 dangerous for a server to simply turn over a connection to a gateway 6384 since that gateway can then use the persistent connection mechanism to 6385 engage in multiple transactions with the client while impersonating the 6386 original server in a way that is not detectable by the client. 6388 15.2 Offering a Choice of Authentication Schemes 6390 An HTTP/1.1 server may return multiple challenges with a 401 6391 (Authenticate) response, and each challenge may use a different scheme. 6392 The order of the challenges returned to the user agent is in the order 6393 that the server would prefer they be chosen. The server should order its 6394 challenges with the "most secure" authentication scheme first. A user 6395 agent should choose as the challenge to be made to the user the first 6396 one that the user agent understands. 6398 When the server offers choices of authentication schemes using the WWW- 6399 Authenticate header, the "security" of the authentication is only as 6400 good as the security of the weakest of the authentication schemes. A 6401 malicious user could capture the set of challenges and try to 6402 authenticate him/herself using the weakest of the authentication 6403 schemes. Thus, the ordering serves more to protect the user's 6404 credentials than the server's information. 6406 A possible man-in-the-middle (MITM) attack would be to add a weak 6407 authentication scheme to the set of choices, hoping that the client will 6408 use one that exposes the user's credentials (e.g. password). For this 6409 reason, the client should always use the strongest scheme that it 6410 understands from the choices accepted. 6412 An even better MITM attack would be to remove all offered choices, and 6413 to insert a challenge that requests Basic authentication. For this 6414 reason, user agents that are concerned about this kind of attack could 6415 remember the strongest authentication scheme ever requested by a server 6416 and produce a warning message that requires user confirmation before 6417 using a weaker one. A particularly insidious way to mount such a MITM 6418 attack would be to offer a "free" proxy caching service to gullible 6419 users. 6421 15.3 Abuse of Server Log Information 6423 A server is in the position to save personal data about a user's 6424 requests which may identify their reading patterns or subjects of 6425 interest. This information is clearly confidential in nature and its 6426 handling may be constrained by law in certain countries. People using 6427 the HTTP protocol to provide data are responsible for ensuring that such 6428 material is not distributed without the permission of any individuals 6429 that are identifiable by the published results. 6431 15.4 Transfer of Sensitive Information 6433 Like any generic data transfer protocol, HTTP cannot regulate the 6434 content of the data that is transferred, nor is there any a priori 6435 method of determining the sensitivity of any particular piece of 6436 information within the context of any given request. Therefore, 6437 applications SHOULD supply as much control over this information as 6438 possible to the provider of that information. Four header fields are 6439 worth special mention in this context: Server, Via, Referer and From. 6441 Revealing the specific software version of the server may allow the 6442 server machine to become more vulnerable to attacks against software 6443 that is known to contain security holes. Implementers SHOULD make the 6444 Server header field a configurable option. 6446 Proxies which serve as a portal through a network firewall SHOULD take 6447 special precautions regarding the transfer of header information that 6448 identifies the hosts behind the firewall. In particular, they SHOULD 6449 remove, or replace with sanitized versions, any Via fields generated 6450 behind the firewall. 6452 The Referer field allows reading patterns to be studied and reverse 6453 links drawn. Although it can be very useful, its power can be abused if 6454 user details are not separated from the information contained in the 6455 Referer. Even when the personal information has been removed, the 6456 Referer field may indicate a private document's URI whose publication 6457 would be inappropriate. 6459 The information sent in the From field might conflict with the user's 6460 privacy interests or their site's security policy, and hence it SHOULD 6461 NOT be transmitted without the user being able to disable, enable, and 6462 modify the contents of the field. The user MUST be able to set the 6463 contents of this field within a user preference or application defaults 6464 configuration. 6466 We suggest, though do not require, that a convenient toggle interface be 6467 provided for the user to enable or disable the sending of From and 6468 Referer information. 6470 15.5 Attacks Based On File and Path Names 6472 Implementations of HTTP origin servers SHOULD be careful to restrict the 6473 documents returned by HTTP requests to be only those that were intended 6474 by the server administrators. If an HTTP server translates HTTP URIs 6475 directly into file system calls, the server MUST take special care not 6476 to serve files that were not intended to be delivered to HTTP clients. 6477 For example, UNIX, Microsoft Windows, and other operating systems use 6478 ".." as a path component to indicate a directory level above the current 6479 one. On such a system, an HTTP server MUST disallow any such construct 6480 in the Request-URI if it would otherwise allow access to a resource 6481 outside those intended to be accessible via the HTTP server. Similarly, 6482 files intended for reference only internally to the server (such as 6483 access control files, configuration files, and script code) MUST be 6484 protected from inappropriate retrieval, since they might contain 6485 sensitive information. Experience has shown that minor bugs in such HTTP 6486 server implementations have turned into security risks. 6488 15.6 Personal Information 6490 HTTP clients are often privy to large amounts of personal information 6491 (e.g. the user's name, location, mail address, passwords, encryption 6492 keys, etc.), and SHOULD be very careful to prevent unintentional leakage 6493 of this information via the HTTP protocol to other sources. We very 6494 strongly recommend that a convenient interface be provided for the user 6495 to control dissemination of such information, and that designers and 6496 implementers be particularly careful in this area. History shows that 6497 errors in this area are often both serious security and/or privacy 6498 problems, and often generate highly adverse publicity for the 6499 implementer's company. 6501 15.7 Privacy Issues Connected to Accept Headers 6503 Accept request-headers can reveal information about the user to all 6504 servers which are accessed. The Accept-Language header in particular can 6505 reveal information the user would consider to be of a private nature, 6506 because the understanding of particular languages is often strongly 6507 correlated to the membership of a particular ethnic group. User agents 6508 which offer the option to configure the contents of an Accept-Language 6509 header to be sent in every request are strongly encouraged to let the 6510 configuration process include a message which makes the user aware of 6511 the loss of privacy involved. 6513 An approach that limits the loss of privacy would be for a user agent to 6514 omit the sending of Accept-Language headers by default, and to ask the 6515 user whether it should start sending Accept-Language headers to a server 6516 if it detects, by looking for any Vary response-header fields generated 6517 by the server, that such sending could improve the quality of service. 6519 Elaborate user-customized accept header fields sent in every request, in 6520 particular if these include quality values, can be used by servers as 6521 relatively reliable and long-lived user identifiers. Such user 6522 identifiers would allow content providers to do click-trail tracking, 6523 and would allow collaborating content providers to match cross-server 6524 click-trails or form submissions of individual users. Note that for many 6525 users not behind a proxy, the network address of the host running the 6526 user agent will also serve as a long-lived user identifier. In 6527 environments where proxies are used to enhance privacy, user agents 6528 should be conservative in offering accept header configuration options 6529 to end users. As an extreme privacy measure, proxies could filter the 6530 accept headers in relayed requests. General purpose user agents which 6531 provide a high degree of header configurability should warn users about 6532 the loss of privacy which can be involved. 6534 15.8 DNS Spoofing 6536 Clients using HTTP rely heavily on the Domain Name Service, and are thus 6537 generally prone to security attacks based on the deliberate mis- 6538 association of IP addresses and DNS names. The deployment of DNSSEC 6539 should help this situation. In advance of this deployment, however, 6540 clients need to be cautious in assuming the continuing validity of an IP 6541 number/DNS name association. 6543 In particular, HTTP clients SHOULD rely on their name resolver for 6544 confirmation of an IP number/DNS name association, rather than caching 6545 the result of previous host name lookups. Many platforms already can 6546 cache host name lookups locally when appropriate, and they SHOULD be 6547 configured to do so. These lookups should be cached, however, only when 6548 the TTL (Time To Live) information reported by the name server makes it 6549 likely that the cached information will remain useful. 6551 If HTTP clients cache the results of host name lookups in order to 6552 achieve a performance improvement, they MUST observe the TTL information 6553 reported by DNS. 6555 If HTTP clients do not observe this rule, they could be spoofed when a 6556 previously-accessed server's IP address changes. As network renumbering 6557 is expected to become increasingly common, the possibility of this form 6558 of attack will grow. Observing this requirement thus reduces this 6559 potential security vulnerability. 6561 This requirement also improves the load-balancing behavior of clients 6562 for replicated servers using the same DNS name and reduces the 6563 likelihood of a user's experiencing failure in accessing sites which use 6564 that strategy. 6566 15.9 Location Headers and Spoofing 6568 If a single server supports multiple organizations that do not trust one 6569 another, then it must check the values of Location and Content-Location 6570 headers in responses that are generated under control of said 6571 organizations to make sure that they do not attempt to invalidate 6572 resources over which they have no authority. 6574 16 Acknowledgments 6576 This specification makes heavy use of the augmented BNF and generic 6577 constructs defined by David H. Crocker for RFC 822. Similarly, it 6578 reuses many of the definitions provided by Nathaniel Borenstein and Ned 6579 Freed for MIME. We hope that their inclusion in this specification will 6580 help reduce past confusion over the relationship between HTTP and 6581 Internet mail message formats. 6583 The HTTP protocol has evolved considerably over the past four years. It 6584 has benefited from a large and active developer community--the many 6585 people who have participated on the www-talk mailing list--and it is 6586 that community which has been most responsible for the success of HTTP 6587 and of the World-Wide Web in general. Marc Andreessen, Robert Cailliau, 6588 Daniel W. Connolly, Bob Denny, John Franks, Jean-Francois Groff, Phillip 6589 M. Hallam-Baker, Hakon W. Lie, Ari Luotonen, Rob McCool, Lou Montulli, 6590 Dave Raggett, Tony Sanders, and Marc VanHeyningen deserve special 6591 recognition for their efforts in defining early aspects of the protocol. 6593 This document has benefited greatly from the comments of all those 6594 participating in the HTTP-WG. In addition to those already mentioned, 6595 the following individuals have contributed to this specification: 6597 Gary Adams Albert Lunde 6598 Harald Tveit Alvestrand John C. Mallery 6599 Keith Ball Jean-Philippe Martin-Flatin 6600 Brian Behlendorf Larry Masinter 6601 Paul Burchard Mitra 6602 Maurizio Codogno David Morris 6603 Mike Cowlishaw Gavin Nicol 6604 Roman Czyborra Bill Perry 6605 Michael A. Dolan Jeffrey Perry 6606 David J. Fiander Scott Powers 6607 Alan Freier Owen Rees 6608 Marc Hedlund Luigi Rizzo 6609 Greg Herlihy David Robinson 6610 Koen Holtman Marc Salomon 6611 Alex Hopmann Rich Salz 6612 Bob Jernigan Allan M. Schiffman 6613 Shel Kaphan Jim Seidman 6614 Rohit Khare Chuck Shotton 6615 John Klensin Eric W. Sink 6616 Martijn Koster Simon E. Spero 6617 Alexei Kosut Richard N. Taylor 6618 David M. Kristol Robert S. Thau 6619 Daniel LaLiberte Bill (BearHeart) Weinman 6620 Ben Laurie Francois Yergeau 6621 Paul J. Leach Mary Ellen Zurko 6622 Daniel DuBois 6624 Much of the content and presentation of the caching design is due to 6625 suggestions and comments from individuals including: Shel Kaphan, Paul 6626 Leach, Koen Holtman, David Morris, and Larry Masinter. 6628 Most of the specification of ranges is based on work originally done by 6629 Ari Luotonen and John Franks, with additional input from Steve Zilles. 6631 Thanks to the "cave men" of Palo Alto. You know who you are. 6633 Jim Gettys (the current editor of this document) wishes particularly to 6634 thank Roy Fielding, the previous editor of this document, along with 6635 John Klensin, Jeff Mogul, Paul Leach, Dave Kristol, Koen Holtman, John 6636 Franks, Alex Hopmann, and Larry Masinter for their help. 6638 17 References 6640 [1] H. Alvestrand. "Tags for the identification of languages." RFC 6641 1766, UNINETT, March 1995. 6643 [2] F. Anklesaria, M. McCahill, P. Lindner, D. Johnson, D. Torrey, 6644 B. Alberti. "The Internet Gopher Protocol: (a distributed document 6645 search and retrieval protocol)", RFC 1436, University of Minnesota, 6646 March 1993. 6648 [3] T. Berners-Lee. "Universal Resource Identifiers in WWW." A 6649 Unifying Syntax for the Expression of Names and Addresses of Objects 6650 on the Network as used in the World-Wide Web." RFC 1630, CERN, June 6651 1994. 6653 [4] T. Berners-Lee, L. Masinter, M. McCahill. 6654 "Uniform Resource Locators (URL)." RFC 1738, CERN, Xerox PARC, 6655 University of Minnesota, December 1994. 6657 [5] T. Berners-Lee, D. Connolly. 6658 "HyperText Markup Language Specification - 2.0." RFC 1866, MIT/LCS, 6659 November 1995. 6661 [6] T. Berners-Lee, R. Fielding, H. Frystyk. 6662 "Hypertext Transfer Protocol -- HTTP/1.0." RFC 1945." MIT/LCS, UC 6663 Irvine, May 1996. 6665 [7] N. Borenstein, N. Freed. 6666 "MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms 6667 for Specifying and Describing the Format of Internet Message Bodies." 6668 RFC 1521, Bellcore, Innosoft, September 1993. 6670 [8] R. Braden. 6671 "Requirements for Internet hosts - application and support." STD 3, 6672 RFC 1123, IETF, October 1989. 6674 [9] D. H. Crocker. 6675 "Standard for the Format of ARPA Internet Text Messages." STD 11, RFC 6676 822, UDEL, August 1982. 6678 [10] F. Davis, B. Kahle, H. Morris, J. Salem, T. Shen, R. Wang, J. 6679 Sui, M. Grinbaum. "WAIS Interface Protocol Prototype Functional 6680 Specification." (v1.5), Thinking Machines Corporation, April 1990. 6682 [11] R. Fielding. "Relative Uniform Resource Locators." RFC 1808, UC 6683 Irvine, June 1995. 6685 [12] M. Horton, R. Adams. "Standard for interchange of USENET 6686 messages." RFC 1036 (Obsoletes RFC 850), AT&T Bell Laboratories, 6687 Center for Seismic Studies, December 1987. 6689 [13] B. Kantor, P. Lapsley. "Network News Transfer Protocol." A 6690 Proposed Standard for the Stream-Based Transmission of News." RFC 6691 977, UC San Diego, UC Berkeley, February 1986. 6693 [14] K. Moore. "MIME (Multipurpose Internet Mail Extensions) Part Two: 6694 Message Header Extensions for Non-ASCII Text." RFC 1522, University 6695 of Tennessee, September 1993. 6697 [15] E. Nebel, L. Masinter. "Form-based File Upload in HTML." RFC 6698 1867, Xerox Corporation, November 1995. 6700 [16] J. Postel. "Simple Mail Transfer Protocol." STD 10, RFC 821, 6701 USC/ISI, August 1982. 6703 [17] J. Postel. "Media Type Registration Procedure." RFC 1590, 6704 USC/ISI, March 1994. 6706 [18] J. Postel, J. K. Reynolds. "File Transfer Protocol (FTP)." STD 6707 9, RFC 959, USC/ISI, October 1985. 6709 [19] J. Reynolds, J. Postel. "Assigned Numbers." STD 2, RFC 1700, 6710 USC/ISI, October 1994. 6712 [20] K. Sollins, L. Masinter. 6713 "Functional Requirements for Uniform Resource Names." RFC 1737, 6714 MIT/LCS, Xerox Corporation, December 1994. 6716 [21] US-ASCII. Coded Character Set - 7-Bit American Standard Code for 6717 Information Interchange. Standard ANSI X3.4-1986, ANSI, 1986. 6719 [22] ISO-8859. International Standard -- Information Processing -- 6720 8-bit Single-Byte Coded Graphic Character Sets -- 6721 Part 1: Latin alphabet No. 1, ISO 8859-1:1987. 6722 Part 2: Latin alphabet No. 2, ISO 8859-2, 1987. 6723 Part 3: Latin alphabet No. 3, ISO 8859-3, 1988. 6724 Part 4: Latin alphabet No. 4, ISO 8859-4, 1988. 6725 Part 5: Latin/Cyrillic alphabet, ISO 8859-5, 1988. 6726 Part 6: Latin/Arabic alphabet, ISO 8859-6, 1987. 6727 Part 7: Latin/Greek alphabet, ISO 8859-7, 1987. 6728 Part 8: Latin/Hebrew alphabet, ISO 8859-8, 1988. 6729 Part 9: Latin alphabet No. 5, ISO 8859-9, 1990. 6731 [23] Meyers, M. Rose "The Content-MD5 Header Field." RFC 1864, 6732 Carnegie Mellon, Dover Beach Consulting, October, 1995. 6734 [24] B. Carpenter, Y. Rekhter, "Renumbering Needs Work." RFC 1900, 6735 IAB, February 1996. 6737 [25] P. Deutsch, "GZIP file format specification version 4.3." RFC 6738 1952, Aladdin Enterprises, May, 1996. 6740 [26] Jeffrey C. Mogul. "The Case for Persistent-Connection HTTP". In 6741 Proc. SIGCOMM '95 Symposium on Communications Architectures and 6742 Protocols, pages 299-313. Cambridge, MA, August, 1995. A longer, more 6743 comprehensive version of this paper is available on line at 6744 , 6745 Digital Equipment Corporation Western Research Laboratory Research 6746 Report 95/4, May, 1995., 6748 [28] Mills, D, "Network Time Protocol, Version 3.", Specification, 6749 Implementation and Analysis RFC 1305, University of Delaware, March, 6750 1992. 6752 [29] P. Deutsch, "DEFLATE Compressed Data Format Specification version 6753 1.3." RFC 1951, Aladdin Enterprises, May 1996. 6755 [30] S. Spero. "Analysis of HTTP Performance Problems" 6756 , Joe Touch, 6757 John Heidemann, and Katia Obraczka, "Analysis of HTTP Performance", 6758 , USC/Information Sciences 6759 Institute, June 1996 6761 [31] P. Deutsch, J-L. Gailly, "ZLIB Compressed Data Format Specification 6762 version 3.3." RFC 1950, Aladdin Enterprises, Info-ZIP, May 1996. 6764 [32] Work In Progress for Digest authentication of the IETF HTTP 6765 working group. 6767 18 Authors' Addresses 6769 Roy T. Fielding 6770 Department of Information and Computer Science 6771 University of California 6772 Irvine, CA 92717-3425, USA 6773 Fax: +1 (714) 824-4056 6774 Email: fielding@ics.uci.edu 6776 Jim Gettys 6777 MIT Laboratory for Computer Science 6778 545 Technology Square 6779 Cambridge, MA 02139, USA 6780 Fax: +1 (617) 258 8682 6781 Email: jg@w3.org 6783 Jeffrey C. Mogul 6784 Western Research Laboratory 6785 Digital Equipment Corporation 6786 250 University Avenue 6787 Palo Alto, California, 94305, USA 6788 Email: mogul@wrl.dec.com 6790 Henrik Frystyk Nielsen 6791 W3 Consortium 6792 MIT Laboratory for Computer Science 6793 545 Technology Square 6794 Cambridge, MA 02139, USA 6795 Fax: +1 (617) 258 8682 6796 Email: frystyk@w3.org 6798 Tim Berners-Lee 6799 Director, W3 Consortium 6800 MIT Laboratory for Computer Science 6801 545 Technology Square 6802 Cambridge, MA 02139, USA 6803 Fax: +1 (617) 258 8682 6804 Email: timbl@w3.org 6805 19 Appendices 6807 19.1 Internet Media Type message/http 6809 In addition to defining the HTTP/1.1 protocol, this document serves as 6810 the specification for the Internet media type "message/http". The 6811 following is to be registered with IANA. 6813 Media Type name: message 6814 Media subtype name: http 6815 Required parameters: none 6816 Optional parameters: version, msgtype 6818 version: The HTTP-Version number of the enclosed message 6819 (e.g., "1.1"). If not present, the version can be 6820 determined from the first line of the body. 6822 msgtype: The message type -- "request" or "response". If not 6823 present, the type can be determined from the first 6824 line of the body. 6826 Encoding considerations: only "7bit", "8bit", or "binary" are 6827 permitted 6829 Security considerations: none 6831 19.2 Internet Media Type multipart/byteranges 6833 When an HTTP message includes the content of multiple ranges (for 6834 example, a response to a request for multiple non-overlapping ranges), 6835 these are transmitted as a multipart MIME message. The multipart media 6836 type for this purpose is called "multipart/byteranges". 6838 The multipart/byteranges media type includes two or more parts, each 6839 with its own Content-Type and Content-Range fields. The parts are 6840 separated using a MIME boundary parameter. 6842 Media Type name: multipart 6843 Media subtype name: byteranges 6844 Required parameters: boundary 6845 Optional parameters: none 6847 Encoding considerations: only "7bit", "8bit", or "binary" are 6848 permitted 6850 Security considerations: none 6852 For example: 6854 HTTP/1.1 206 Partial content 6855 Date: Wed, 15 Nov 1995 06:25:24 GMT 6856 Last-modified: Wed, 15 Nov 1995 04:58:08 GMT 6857 Content-type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 6859 --THIS_STRING_SEPARATES 6860 Content-type: application/pdf 6861 Content-range: bytes 500-999/8000 6863 ...the first range... 6864 --THIS_STRING_SEPARATES 6865 Content-type: application/pdf 6866 Content-range: bytes 7000-7999/8000 6868 ...the second range 6869 --THIS_STRING_SEPARATES-- 6871 19.3 Tolerant Applications 6873 Although this document specifies the requirements for the generation of 6874 HTTP/1.1 messages, not all applications will be correct in their 6875 implementation. We therefore recommend that operational applications be 6876 tolerant of deviations whenever those deviations can be interpreted 6877 unambiguously. 6879 Clients SHOULD be tolerant in parsing the Status-Line and servers 6880 tolerant when parsing the Request-Line. In particular, they SHOULD 6881 accept any amount of SP or HT characters between fields, even though 6882 only a single SP is required. 6884 The line terminator for message-header fields is the sequence CRLF. 6885 However, we recommend that applications, when parsing such headers, 6886 recognize a single LF as a line terminator and ignore the leading CR. 6888 The character set of an entity-body should be labeled as the lowest 6889 common denominator of the character codes used within that body, with 6890 the exception that no label is preferred over the labels US-ASCII or 6891 ISO-8859-1. 6893 Additional rules for requirements on parsing and encoding of dates and 6894 other potential problems with date encodings include: 6896 o HTTP/1.1 clients and caches should assume that an RFC-850 date 6897 which appears to be more than 50 years in the future is in fact in 6898 the past (this helps solve the "year 2000" problem). 6900 o An HTTP/1.1 implementation may internally represent a parsed 6901 Expires date as earlier than the proper value, but MUST NOT 6902 internally represent a parsed Expires date as later than the proper 6903 value. 6905 o All expiration-related calculations must be done in GMT. The local 6906 time zone MUST NOT influence the calculation or comparison of an 6907 age or expiration time. 6909 o If an HTTP header incorrectly carries a date value with a time zone 6910 other than GMT, it must be converted into GMT using the most 6911 conservative possible conversion. 6913 19.4 Differences Between HTTP Entities and RFC 1521 Entities 6915 HTTP/1.1 uses many of the constructs defined for Internet Mail (RFC 822) 6916 and the Multipurpose Internet Mail Extensions (MIME ) to allow 6917 entities to be transmitted in an open variety of representations and 6918 with extensible mechanisms. However, RFC 1521 discusses mail, and HTTP 6919 has a few features that are different from those described in RFC 1521. 6920 These differences were carefully chosen to optimize performance over 6921 binary connections, to allow greater freedom in the use of new media 6922 types, to make date comparisons easier, and to acknowledge the practice 6923 of some early HTTP servers and clients. 6925 At the time of this writing, it is expected that RFC 1521 will be 6926 revised. The revisions may include some of the practices found in 6927 HTTP/1.1 but not in RFC 1521. 6929 This appendix describes specific areas where HTTP differs from RFC 1521. 6930 Proxies and gateways to strict MIME environments SHOULD be aware of 6931 these differences and provide the appropriate conversions where 6932 necessary. Proxies and gateways from MIME environments to HTTP also need 6933 to be aware of the differences because some conversions may be required. 6935 19.4.1 Conversion to Canonical Form 6937 RFC 1521 requires that an Internet mail entity be converted to canonical 6938 form prior to being transferred, as described in Appendix G of RFC 1521. 6939 Section 3.7.1 of this document describes the forms allowed for 6940 subtypes of the "text" media type when transmitted over HTTP. RFC 1521 6941 requires that content with a type of "text" represent line breaks as 6942 CRLF and forbids the use of CR or LF outside of line break sequences. 6943 HTTP allows CRLF, bare CR, and bare LF to indicate a line break within 6944 text content when a message is transmitted over HTTP. 6946 Where it is possible, a proxy or gateway from HTTP to a strict RFC 1521 6947 environment SHOULD translate all line breaks within the text media types 6948 described in section 3.7.1 of this document to the RFC 1521 canonical 6949 form of CRLF. Note, however, that this may be complicated by the 6950 presence of a Content-Encoding and by the fact that HTTP allows the use 6951 of some character sets which do not use octets 13 and 10 to represent CR 6952 and LF, as is the case for some multi-byte character sets. 6954 19.4.2 Conversion of Date Formats 6956 HTTP/1.1 uses a restricted set of date formats (section 3.3.1) to 6957 simplify the process of date comparison. Proxies and gateways from other 6958 protocols SHOULD ensure that any Date header field present in a message 6959 conforms to one of the HTTP/1.1 formats and rewrite the date if 6960 necessary. 6962 19.4.3 Introduction of Content-Encoding 6964 RFC 1521 does not include any concept equivalent to HTTP/1.1's Content- 6965 Encoding header field. Since this acts as a modifier on the media type, 6966 proxies and gateways from HTTP to MIME-compliant protocols MUST either 6967 change the value of the Content-Type header field or decode the entity- 6968 body before forwarding the message. (Some experimental applications of 6969 Content-Type for Internet mail have used a media-type parameter of 6970 ";conversions=" to perform an equivalent function as 6971 Content-Encoding. However, this parameter is not part of RFC 1521.) 6973 19.4.4 No Content-Transfer-Encoding 6975 HTTP does not use the Content-Transfer-Encoding (CTE) field of RFC 1521. 6976 Proxies and gateways from MIME-compliant protocols to HTTP MUST remove 6977 any non-identity CTE ("quoted-printable" or "base64") encoding prior to 6978 delivering the response message to an HTTP client. 6980 Proxies and gateways from HTTP to MIME-compliant protocols are 6981 responsible for ensuring that the message is in the correct format and 6982 encoding for safe transport on that protocol, where "safe transport" is 6983 defined by the limitations of the protocol being used. Such a proxy or 6984 gateway SHOULD label the data with an appropriate Content-Transfer- 6985 Encoding if doing so will improve the likelihood of safe transport over 6986 the destination protocol. 6988 19.4.5 HTTP Header Fields in Multipart Body-Parts 6990 In RFC 1521, most header fields in multipart body-parts are generally 6991 ignored unless the field name begins with "Content-". In HTTP/1.1, 6992 multipart body-parts may contain any HTTP header fields which are 6993 significant to the meaning of that part. 6995 19.4.6 Introduction of Transfer-Encoding 6997 HTTP/1.1 introduces the Transfer-Encoding header field (section 14.40). 6998 Proxies/gateways MUST remove any transfer coding prior to forwarding a 6999 message via a MIME-compliant protocol. 7001 A process for decoding the "chunked" transfer coding (section 3.6) can 7002 be represented in pseudo-code as: 7004 length := 0 7005 read chunk-size, chunk-ext (if any) and CRLF 7006 while (chunk-size > 0) { 7007 read chunk-data and CRLF 7008 append chunk-data to entity-body 7009 length := length + chunk-size 7010 read chunk-size and CRLF 7011 } 7012 read entity-header 7013 while (entity-header not empty) { 7014 append entity-header to existing header fields 7015 read entity-header 7016 } 7017 Content-Length := length 7018 Remove "chunked" from Transfer-Encoding 7020 19.4.7 MIME-Version 7022 HTTP is not a MIME-compliant protocol (see appendix 19.4). However, 7023 HTTP/1.1 messages may include a single MIME-Version general-header field 7024 to indicate what version of the MIME protocol was used to construct the 7025 message. Use of the MIME-Version header field indicates that the message 7026 is in full compliance with the MIME protocol (as defined in RFC 1521). 7027 Proxies/gateways are responsible for ensuring full compliance (where 7028 possible) when exporting HTTP messages to strict MIME environments. 7030 MIME-Version = "MIME-Version" ":" 1*DIGIT "." 1*DIGIT 7032 MIME version "1.0" is the default for use in HTTP/1.1. However, HTTP/1.1 7033 message parsing and semantics are defined by this document and not the 7034 MIME specification. 7036 19.5 Changes from HTTP/1.0 7038 This section summarizes major differences between versions HTTP/1.0 and 7039 HTTP/1.1. 7041 19.5.1 Changes to Simplify Multi-homed Web Servers and Conserve IP 7042 Addresses 7044 The requirements that clients and servers support the Host request- 7045 header, report an error if the Host request-header (section 14.23) is 7046 missing from an HTTP/1.1 request, and accept absolute URIs (section 7047 5.1.2) are among the most important changes defined by this 7048 specification. 7050 Older HTTP/1.0 clients assumed a one-to-one relationship of IP addresses 7051 and servers; there was no other established mechanism for distinguishing 7052 the intended server of a request than the IP address to which that 7053 request was directed. The changes outlined above will allow the 7054 Internet, once older HTTP clients are no longer common, to support 7055 multiple Web sites from a single IP address, greatly simplifying large 7056 operational Web servers, where allocation of many IP addresses to a 7057 single host has created serious problems. The Internet will also be able 7058 to recover the IP addresses that have been allocated for the sole 7059 purpose of allowing special-purpose domain names to be used in root- 7060 level HTTP URLs. Given the rate of growth of the Web, and the number of 7061 servers already deployed, it is extremely important that all 7062 implementations of HTTP (including updates to existing HTTP/1.0 7063 applications) correctly implement these requirements: 7065 o Both clients and servers MUST support the Host request-header. 7067 o Host request-headers are required in HTTP/1.1 requests. 7069 o Servers MUST report a 400 (Bad Request) error if an HTTP/1.1 7070 request does not include a Host request-header. 7072 o Servers MUST accept absolute URIs. 7074 19.6 Additional Features 7076 This appendix documents protocol elements used by some existing HTTP 7077 implementations, but not consistently and correctly across most HTTP/1.1 7078 applications. Implementers should be aware of these features, but cannot 7079 rely upon their presence in, or interoperability with, other HTTP/1.1 7080 applications. Some of these describe proposed experimental features, and 7081 some describe features that experimental deployment found lacking that 7082 are now addressed in the base HTTP/1.1 specification. 7084 19.6.1 Additional Request Methods 7086 19.6.1.1 PATCH 7088 The PATCH method is similar to PUT except that the entity contains a 7089 list of differences between the original version of the resource 7090 identified by the Request-URI and the desired content of the resource 7091 after the PATCH action has been applied. The list of differences is in a 7092 format defined by the media type of the entity (e.g., 7093 "application/diff") and MUST include sufficient information to allow the 7094 server to recreate the changes necessary to convert the original version 7095 of the resource to the desired version. 7097 If the request passes through a cache and the Request-URI identifies a 7098 currently cached entity, that entity MUST be removed from the cache. 7099 Responses to this method are not cachable. 7101 The actual method for determining how the patched resource is placed, 7102 and what happens to its predecessor, is defined entirely by the origin 7103 server. If the original version of the resource being patched included a 7104 Content-Version header field, the request entity MUST include a Derived- 7105 From header field corresponding to the value of the original Content- 7106 Version header field. Applications are encouraged to use these fields 7107 for constructing versioning relationships and resolving version 7108 conflicts. 7110 PATCH requests must obey the message transmission requirements set out 7111 in section 8.2. 7113 Caches that implement PATCH should invalidate cached responses as 7114 defined in section 13.10 for PUT. 7116 19.6.1.2 LINK 7118 The LINK method establishes one or more Link relationships between the 7119 existing resource identified by the Request-URI and other existing 7120 resources. The difference between LINK and other methods allowing links 7121 to be established between resources is that the LINK method does not 7122 allow any message-body to be sent in the request and does not directly 7123 result in the creation of new resources. 7125 If the request passes through a cache and the Request-URI identifies a 7126 currently cached entity, that entity MUST be removed from the cache. 7127 Responses to this method are not cachable. 7129 Caches that implement LINK should invalidate cached responses as defined 7130 in section 13.10 for PUT. 7132 19.6.1.3 UNLINK 7134 The UNLINK method removes one or more Link relationships from the 7135 existing resource identified by the Request-URI. These relationships may 7136 have been established using the LINK method or by any other method 7137 supporting the Link header. The removal of a link to a resource does not 7138 imply that the resource ceases to exist or becomes inaccessible for 7139 future references. 7141 If the request passes through a cache and the Request-URI identifies a 7142 currently cached entity, that entity MUST be removed from the cache. 7143 Responses to this method are not cachable. 7145 Caches that implement UNLINK should invalidate cached responses as 7146 defined in section 13.10 for PUT. 7148 19.6.2 Additional Header Field Definitions 7150 19.6.2.1 Alternates 7152 The Alternates response-header field has been proposed as a means for 7153 the origin server to inform the client about other available 7154 representations of the requested resource, along with their 7155 distinguishing attributes, and thus providing a more reliable means for 7156 a user agent to perform subsequent selection of another representation 7157 which better fits the desires of its user (described as agent-driven 7158 negotiation in section 12). 7160 The Alternates header field is orthogonal to the Vary header field in 7161 that both may coexist in a message without affecting the interpretation 7162 of the response or the available representations. It is expected that 7163 Alternates will provide a significant improvement over the server-driven 7164 negotiation provided by the Vary field for those resources that vary 7165 over common dimensions like type and language. 7167 The Alternates header field will be defined in a future specification. 7169 19.6.2.2 Content-Version 7171 The Content-Version entity-header field defines the version tag 7172 associated with a rendition of an evolving entity. Together with the 7173 Derived-From field described in section 19.6.2.3, it allows a group of 7174 people to work simultaneously on the creation of a work as an iterative 7175 process. The field should be used to allow evolution of a particular 7176 work along a single path rather than derived works or renditions in 7177 different representations. 7179 Content-Version = "Content-Version" ":" quoted-string 7181 Examples of the Content-Version field include: 7183 Content-Version: "2.1.2" 7184 Content-Version: "Fred 19950116-12:26:48" 7185 Content-Version: "2.5a4-omega7" 7187 19.6.2.3 Derived-From 7188 The Derived-From entity-header field can be used to indicate the version 7189 tag of the resource from which the enclosed entity was derived before 7190 modifications were made by the sender. This field is used to help manage 7191 the process of merging successive changes to a resource, particularly 7192 when such changes are being made in parallel and from multiple sources. 7194 Derived-From = "Derived-From" ":" quoted-string 7196 An example use of the field is: 7198 Derived-From: "2.1.1" 7200 The Derived-From field is required for PUT and PATCH requests if the 7201 entity being sent was previously retrieved from the same URI and a 7202 Content-Version header was included with the entity when it was last 7203 retrieved. 7205 19.6.2.4 Link 7207 The Link entity-header field provides a means for describing a 7208 relationship between two resources, generally between the requested 7209 resource and some other resource. An entity MAY include multiple Link 7210 values. Links at the metainformation level typically indicate 7211 relationships like hierarchical structure and navigation paths. The Link 7212 field is semantically equivalent to the element in HTML. 7214 Link = "Link" ":" #("<" URI ">" *( ";" link-param ) 7216 link-param = ( ( "rel" "=" relationship ) 7217 | ( "rev" "=" relationship ) 7218 | ( "title" "=" quoted-string ) 7219 | ( "anchor" "=" <"> URI <"> ) 7220 | ( link-extension ) ) 7222 link-extension = token [ "=" ( token | quoted-string ) ] 7224 relationship = sgml-name 7225 | ( <"> sgml-name *( SP sgml-name) <"> ) 7227 sgml-name = ALPHA *( ALPHA | DIGIT | "." | "-" ) 7229 Relationship values are case-insensitive and MAY be extended within the 7230 constraints of the sgml-name syntax. The title parameter MAY be used to 7231 label the destination of a link such that it can be used as 7232 identification within a human-readable menu. The anchor parameter MAY be 7233 used to indicate a source anchor other than the entire current resource, 7234 such as a fragment of this resource or a third resource. 7236 Examples of usage include: 7238 Link: ; rel="Previous" 7240 Link: ; rev="Made"; title="Tim Berners-Lee" 7242 The first example indicates that chapter2 is previous to this resource 7243 in a logical navigation path. The second indicates that the person 7244 responsible for making the resource available is identified by the given 7245 e-mail address. 7247 19.6.2.5 URI 7249 The URI header field has, in past versions of this specification, been 7250 used as a combination of the existing Location, Content-Location, and 7251 Vary header fields as well as the future Alternates field (above). Its 7252 primary purpose has been to include a list of additional URIs for the 7253 resource, including names and mirror locations. However, it has become 7254 clear that the combination of many different functions within this 7255 single field has been a barrier to consistently and correctly 7256 implementing any of those functions. Furthermore, we believe that the 7257 identification of names and mirror locations would be better performed 7258 via the Link header field. The URI header field is therefore deprecated 7259 in favor of those other fields. 7261 URI-header = "URI" ":" 1#( "<" URI ">" ) 7263 19.7 Compatibility with Previous Versions 7265 It is beyond the scope of a protocol specification to mandate compliance 7266 with previous versions. HTTP/1.1 was deliberately designed, however, to 7267 make supporting previous versions easy. It is worth noting that at the 7268 time of composing this specification, we would expect commercial 7269 HTTP/1.1 servers to: 7271 o recognize the format of the Request-Line for HTTP/0.9, 1.0, and 1.1 7272 requests; 7274 o understand any valid request in the format of HTTP/0.9, 1.0, or 7275 1.1; 7277 o respond appropriately with a message in the same major version used 7278 by the client. 7280 And we would expect HTTP/1.1 clients to: 7282 o recognize the format of the Status-Line for HTTP/1.0 and 1.1 7283 responses; 7285 o understand any valid response in the format of HTTP/0.9, 1.0, or 7286 1.1. 7288 For most implementations of HTTP/1.0, each connection is established by 7289 the client prior to the request and closed by the server after sending 7290 the response. A few implementations implement the Keep-Alive version of 7291 persistent connections described in section 19.7.1.1. 7293 19.7.1 Compatibility with HTTP/1.0 Persistent Connections 7295 Some clients and servers may wish to be compatible with some previous 7296 implementations of persistent connections in HTTP/1.0 clients and 7297 servers. Persistent connections in HTTP/1.0 must be explicitly 7298 negotiated as they are not the default behavior. HTTP/1.0 experimental 7300 implementations of persistent connections are faulty, and the new 7301 facilities in HTTP/1.1 are designed to rectify these problems. The 7302 problem was that some existing 1.0 clients may be sending Keep-Alive to 7303 a proxy server that doesn't understand Connection, which would then 7304 erroneously forward it to the next inbound server, which would establish 7305 the Keep-Alive connection and result in a hung HTTP/1.0 proxy waiting 7306 for the close on the response. The result is that HTTP/1.0 clients must 7307 be prevented from using Keep-Alive when talking to proxies. 7309 However, talking to proxies is the most important use of persistent 7310 connections, so that prohibition is clearly unacceptable. Therefore, we 7311 need some other mechanism for indicating a persistent connection is 7312 desired, which is safe to use even when talking to an old proxy that 7313 ignores Connection. Persistent connections are the default for HTTP/1.1 7314 messages; we introduce a new keyword (Connection: close) for declaring 7315 non-persistence. 7317 The following describes the original HTTP/1.0 form of persistent 7318 connections. 7320 When it connects to an origin server, an HTTP client MAY send the Keep- 7321 Alive connection-token in addition to the Persist connection-token: 7323 Connection: Keep-Alive 7325 An HTTP/1.0 server would then respond with the Keep-Alive connection 7326 token and the client may proceed with an HTTP/1.0 (or Keep-Alive) 7327 persistent connection. 7329 An HTTP/1.1 server may also establish persistent connections with 7330 HTTP/1.0 clients upon receipt of a Keep-Alive connection token. However, 7331 a persistent connection with an HTTP/1.0 client cannot make use of the 7332 chunked transfer-coding, and therefore MUST use a Content-Length for 7333 marking the ending boundary of each message. 7335 A client MUST NOT send the Keep-Alive connection token to a proxy server 7336 as HTTP/1.0 proxy servers do not obey the rules of HTTP/1.1 for parsing 7337 the Connection header field. 7339 19.7.1.1 The Keep-Alive Header 7341 When the Keep-Alive connection-token has been transmitted with a request 7342 or a response, a Keep-Alive header field MAY also be included. The Keep- 7343 Alive header field takes the following form: 7345 Keep-Alive-header = "Keep-Alive" ":" 0# keepalive-param 7347 keepalive-param = param-name "=" value 7349 The Keep-Alive header itself is optional, and is used only if a 7350 parameter is being sent. HTTP/1.1 does not define any parameters. 7352 If the Keep-Alive header is sent, the corresponding connection token 7353 MUST be transmitted. The Keep-Alive header MUST be ignored if received 7354 without the connection token. 7356 19.8 Notes to the RFC Editor and IANA 7358 This section of the document should be DELETED! It calls for the RFC 7359 editor and IANA to take some actions before the draft becomes a Proposed 7360 Standard. After those actions are taken, please delete this section of 7361 the specification. 7363 19.8.1 Charset Registry 7365 The following names should be added to the IANA character set registry 7366 under the category "Preferred MIME name" and this section deleted. 7368 "US-ASCII" 7369 | "ISO-8859-1" | "ISO-8859-2" | "ISO-8859-3" 7370 | "ISO-8859-4" | "ISO-8859-5" | "ISO-8859-6" 7371 | "ISO-8859-7" | "ISO-8859-8" | "ISO-8859-9" 7372 | "ISO-2022-JP" | "ISO-2022-JP-2" | "ISO-2022-KR" 7373 | "SHIFT_JIS" | "EUC-KR" | "GB2312" | "BIG5" | "KOI8-R" 7375 Please also add the following new alias as the "preferred MIME name": 7377 "EUC-JP" for "EXTENDED_UNIX_CODE_PACKED_FORMAT_FOR_JAPANESE" 7378 19.8.2 Content-coding Values 7380 HTTP also defines a new class of registry for its content-coding values. 7381 The initial set of values defined in this document are deflate, gzip and 7382 compress. IANA should create a registry with those entries. The registry 7383 should note that "x-gzip" and "x-compress" are used as content-codings 7384 in HTTP but that their use is deprecated. The registry should note that 7385 "specifications of the content coding algorithms needed to implement a 7386 new value should be publicly available and adequate for independent 7387 implementation, and conform to the purpose of content coding defined RFC 7388 XXX." where RFC XXX is the number assigned to this document. 7390 19.8.3 New Media Types Registered 7392 This document defines two new media types which should be registered. 7393 Specifically appendix 19.1 defines the Internet media type message/http 7394 and appendix 19.2 defines multipart/byteranges. 7396 19.8.4 Possible Merge With Digest Authentication Draft 7398 Note that the working group draft for Digest Authentication may be 7399 processed by the IESG at the same time as this document; we leave it to 7400 the RFC editor to decide whether to issue a single RFC containing both 7401 drafts (see section 11.2 for where it would be put); in any case, the 7402 reference in the reference list will need to be either deleted, or made 7403 to the appropriate RFC (and section 11.2 deleted). 7405 19.8.5 Media type parameters named "q" 7407 Due to historical HTTP usage (i.e. a mistake in HTTP's BNF), IANA should 7408 discourage registering any media type that uses a parameter named "q". 7409 See section 14.1 for more information.