idnits 2.17.1 draft-ietf-httpbis-semantics-12.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There are 2 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 5 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. -- The draft header indicates that this document obsoletes RFC7230, but the abstract doesn't seem to directly say this. It does mention RFC7230 though, so this could be OK. -- The abstract seems to indicate that this document obsoletes RFC7615, but the header doesn't have an 'Obsoletes:' line to match this. -- The abstract seems to indicate that this document obsoletes RFC7538, but the header doesn't have an 'Obsoletes:' line to match this. -- The abstract seems to indicate that this document obsoletes RFC7694, but the header doesn't have an 'Obsoletes:' line to match this. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 8540 has weird spacing: '... yes yes...' == Line 8541 has weird spacing: '... yes yes...' == Line 8542 has weird spacing: '...S yes yes...' == Line 8545 has weird spacing: '... yes yes...' == Line 8681 has weird spacing: '...on-Info stan...' == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 2, 2020) is 1301 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) == Unused Reference: 'RFC2145' is defined on line 8960, but no explicit reference was found in the text == Unused Reference: 'RFC7617' is defined on line 9100, but no explicit reference was found in the text == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-cache-12 -- Possible downref: Normative reference to a draft: ref. 'Caching' == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-messaging-12 -- Possible downref: Normative reference to a draft: ref. 'Messaging' ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** Downref: Normative reference to an Informational RFC: RFC 1950 ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Downref: Normative reference to an Informational RFC: RFC 1952 ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' -- Possible downref: Non-RFC (?) normative reference: ref. 'Welch' -- Duplicate reference: RFC2978, mentioned in 'Err5433', was also mentioned in 'Err1912'. == Outdated reference: A later version (-34) exists of draft-ietf-quic-http-31 -- Obsolete informational reference (is this intentional?): RFC 2068 (Obsoleted by RFC 2616) -- Obsolete informational reference (is this intentional?): RFC 2145 (Obsoleted by RFC 7230) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) -- Duplicate reference: RFC2978, mentioned in 'RFC2978', was also mentioned in 'Err5433'. -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7232 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7233 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7235 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7538 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) -- Obsolete informational reference (is this intentional?): RFC 7615 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7694 (Obsoleted by RFC 9110) Summary: 5 errors (**), 0 flaws (~~), 14 warnings (==), 26 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP Working Group R. Fielding, Ed. 3 Internet-Draft Adobe 4 Obsoletes: 2818, 7230, 7231, 7232, 7233, 7235, M. Nottingham, Ed. 5 7538, 7615, 7694 (if approved) Fastly 6 Intended status: Standards Track J. Reschke, Ed. 7 Expires: April 5, 2021 greenbytes 8 October 2, 2020 10 HTTP Semantics 11 draft-ietf-httpbis-semantics-12 13 Abstract 15 The Hypertext Transfer Protocol (HTTP) is a stateless application- 16 level protocol for distributed, collaborative, hypertext information 17 systems. This document defines the semantics of HTTP: its 18 architecture, terminology, the "http" and "https" Uniform Resource 19 Identifier (URI) schemes, core request methods, request header 20 fields, response status codes, response header fields, and content 21 negotiation. 23 This document obsoletes RFC 2818, RFC 7231, RFC 7232, RFC 7233, RFC 24 7235, RFC 7538, RFC 7615, RFC 7694, and portions of RFC 7230. 26 Editorial Note 28 This note is to be removed before publishing as an RFC. 30 Discussion of this draft takes place on the HTTP working group 31 mailing list (ietf-http-wg@w3.org), which is archived at 32 . 34 Working Group information can be found at ; 35 source code and issues list for this draft can be found at 36 . 38 The changes in this draft are summarized in Appendix C.13. 40 Status of This Memo 42 This Internet-Draft is submitted in full conformance with the 43 provisions of BCP 78 and BCP 79. 45 Internet-Drafts are working documents of the Internet Engineering 46 Task Force (IETF). Note that other groups may also distribute 47 working documents as Internet-Drafts. The list of current Internet- 48 Drafts is at https://datatracker.ietf.org/drafts/current/. 50 Internet-Drafts are draft documents valid for a maximum of six months 51 and may be updated, replaced, or obsoleted by other documents at any 52 time. It is inappropriate to use Internet-Drafts as reference 53 material or to cite them other than as "work in progress." 55 This Internet-Draft will expire on April 5, 2021. 57 Copyright Notice 59 Copyright (c) 2020 IETF Trust and the persons identified as the 60 document authors. All rights reserved. 62 This document is subject to BCP 78 and the IETF Trust's Legal 63 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 64 license-info) in effect on the date of publication of this document. 65 Please review these documents carefully, as they describe your rights 66 and restrictions with respect to this document. Code Components 67 extracted from this document must include Simplified BSD License text 68 as described in Section 4.e of the Trust Legal Provisions and are 69 provided without warranty as described in the Simplified BSD License. 71 This document may contain material from IETF Documents or IETF 72 Contributions published or made publicly available before November 73 10, 2008. The person(s) controlling the copyright in some of this 74 material may not have granted the IETF Trust the right to allow 75 modifications of such material outside the IETF Standards Process. 76 Without obtaining an adequate license from the person(s) controlling 77 the copyright in such materials, this document may not be modified 78 outside the IETF Standards Process, and derivative works of it may 79 not be created outside the IETF Standards Process, except to format 80 it for publication as an RFC or to translate it into languages other 81 than English. 83 Table of Contents 85 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 9 86 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 9 87 1.2. Evolution . . . . . . . . . . . . . . . . . . . . . . . . 9 88 1.3. Semantics . . . . . . . . . . . . . . . . . . . . . . . . 10 89 1.4. Obsoletes . . . . . . . . . . . . . . . . . . . . . . . . 11 90 2. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 12 91 2.1. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 12 92 2.2. Requirements Notation . . . . . . . . . . . . . . . . . . 12 93 2.3. Length Requirements . . . . . . . . . . . . . . . . . . . 13 94 2.4. Error Handling . . . . . . . . . . . . . . . . . . . . . 14 95 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 14 96 3.1. Resources . . . . . . . . . . . . . . . . . . . . . . . . 14 97 3.2. Connections . . . . . . . . . . . . . . . . . . . . . . . 15 98 3.3. Messages . . . . . . . . . . . . . . . . . . . . . . . . 15 99 3.4. User Agent . . . . . . . . . . . . . . . . . . . . . . . 15 100 3.5. Origin Server . . . . . . . . . . . . . . . . . . . . . . 16 101 3.6. Example Request and Response . . . . . . . . . . . . . . 16 102 3.7. Intermediaries . . . . . . . . . . . . . . . . . . . . . 17 103 3.8. Caches . . . . . . . . . . . . . . . . . . . . . . . . . 19 104 4. Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . 20 105 4.1. URI References . . . . . . . . . . . . . . . . . . . . . 20 106 4.2. URI Schemes . . . . . . . . . . . . . . . . . . . . . . . 21 107 4.2.1. http URI Scheme . . . . . . . . . . . . . . . . . . . 22 108 4.2.2. https URI Scheme . . . . . . . . . . . . . . . . . . 22 109 4.2.3. http(s) Normalization and Comparison . . . . . . . . 23 110 4.2.4. http(s) Deprecated userinfo . . . . . . . . . . . . . 24 111 4.2.5. http(s) References with Fragment Identifiers . . . . 24 112 4.3. Authoritative Access . . . . . . . . . . . . . . . . . . 24 113 4.3.1. URI Origin . . . . . . . . . . . . . . . . . . . . . 24 114 4.3.2. http origins . . . . . . . . . . . . . . . . . . . . 25 115 4.3.3. https origins . . . . . . . . . . . . . . . . . . . . 26 116 4.3.4. https certificate verification . . . . . . . . . . . 27 117 5. Message Abstraction . . . . . . . . . . . . . . . . . . . . . 28 118 5.1. Protocol Version . . . . . . . . . . . . . . . . . . . . 28 119 5.2. Framing . . . . . . . . . . . . . . . . . . . . . . . . . 30 120 5.3. Control Data . . . . . . . . . . . . . . . . . . . . . . 30 121 5.3.1. Request . . . . . . . . . . . . . . . . . . . . . . . 30 122 5.3.2. Response . . . . . . . . . . . . . . . . . . . . . . 30 123 5.4. Header Fields . . . . . . . . . . . . . . . . . . . . . . 30 124 5.4.1. Field Ordering and Combination . . . . . . . . . . . 32 125 5.4.2. Field Limits . . . . . . . . . . . . . . . . . . . . 33 126 5.4.3. Field Names . . . . . . . . . . . . . . . . . . . . . 33 127 5.4.4. Field Values . . . . . . . . . . . . . . . . . . . . 33 128 5.5. Payload . . . . . . . . . . . . . . . . . . . . . . . . . 35 129 5.5.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . 35 130 5.5.2. Identification . . . . . . . . . . . . . . . . . . . 36 131 5.5.3. Payload Metadata . . . . . . . . . . . . . . . . . . 37 132 5.5.4. Payload Body . . . . . . . . . . . . . . . . . . . . 37 133 5.6. Trailer Fields . . . . . . . . . . . . . . . . . . . . . 37 134 5.6.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . 38 135 5.6.2. Limitations . . . . . . . . . . . . . . . . . . . . . 38 136 5.6.3. Processing . . . . . . . . . . . . . . . . . . . . . 39 137 5.7. Common Rules for Defining Field Values . . . . . . . . . 39 138 5.7.1. Lists (#rule ABNF Extension) . . . . . . . . . . . . 39 139 5.7.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 41 140 5.7.3. Whitespace . . . . . . . . . . . . . . . . . . . . . 41 141 5.7.4. Quoted Strings . . . . . . . . . . . . . . . . . . . 42 142 5.7.5. Comments . . . . . . . . . . . . . . . . . . . . . . 42 143 5.7.6. Parameters . . . . . . . . . . . . . . . . . . . . . 43 144 5.7.7. Date/Time Formats . . . . . . . . . . . . . . . . . . 43 145 6. Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 146 6.1. Target Resource . . . . . . . . . . . . . . . . . . . . . 45 147 6.1.1. Request Target . . . . . . . . . . . . . . . . . . . 45 148 6.1.2. Host . . . . . . . . . . . . . . . . . . . . . . . . 46 149 6.1.3. Reconstructing the Target URI . . . . . . . . . . . . 47 150 6.2. Routing Inbound . . . . . . . . . . . . . . . . . . . . . 47 151 6.2.1. To a Cache . . . . . . . . . . . . . . . . . . . . . 47 152 6.2.2. To a Proxy . . . . . . . . . . . . . . . . . . . . . 48 153 6.2.3. To the Origin . . . . . . . . . . . . . . . . . . . . 48 154 6.3. Response Correlation . . . . . . . . . . . . . . . . . . 48 155 6.4. Message Forwarding . . . . . . . . . . . . . . . . . . . 48 156 6.4.1. Connection . . . . . . . . . . . . . . . . . . . . . 49 157 6.4.2. Max-Forwards . . . . . . . . . . . . . . . . . . . . 50 158 6.4.3. Via . . . . . . . . . . . . . . . . . . . . . . . . . 51 159 6.5. Transformations . . . . . . . . . . . . . . . . . . . . . 53 160 6.6. Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . 54 161 7. Representations . . . . . . . . . . . . . . . . . . . . . . . 56 162 7.1. Selected Representation . . . . . . . . . . . . . . . . . 57 163 7.2. Data . . . . . . . . . . . . . . . . . . . . . . . . . . 57 164 7.3. Metadata . . . . . . . . . . . . . . . . . . . . . . . . 57 165 7.4. Content-Type . . . . . . . . . . . . . . . . . . . . . . 58 166 7.4.1. Media Type . . . . . . . . . . . . . . . . . . . . . 59 167 7.4.2. Charset . . . . . . . . . . . . . . . . . . . . . . . 59 168 7.4.3. Canonicalization and Text Defaults . . . . . . . . . 60 169 7.4.4. Multipart Types . . . . . . . . . . . . . . . . . . . 61 170 7.5. Content-Encoding . . . . . . . . . . . . . . . . . . . . 61 171 7.5.1. Content Codings . . . . . . . . . . . . . . . . . . . 62 172 7.6. Content-Language . . . . . . . . . . . . . . . . . . . . 63 173 7.6.1. Language Tags . . . . . . . . . . . . . . . . . . . . 64 174 7.7. Content-Length . . . . . . . . . . . . . . . . . . . . . 65 175 7.8. Content-Location . . . . . . . . . . . . . . . . . . . . 66 176 7.9. Validators . . . . . . . . . . . . . . . . . . . . . . . 68 177 7.9.1. Weak versus Strong . . . . . . . . . . . . . . . . . 69 178 7.9.2. Last-Modified . . . . . . . . . . . . . . . . . . . . 71 179 7.9.3. ETag . . . . . . . . . . . . . . . . . . . . . . . . 73 180 7.9.4. When to Use Entity-Tags and Last-Modified Dates . . . 76 181 8. Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 182 8.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 77 183 8.2. Common Method Properties . . . . . . . . . . . . . . . . 78 184 8.2.1. Safe Methods . . . . . . . . . . . . . . . . . . . . 79 185 8.2.2. Idempotent Methods . . . . . . . . . . . . . . . . . 80 186 8.2.3. Methods and Caching . . . . . . . . . . . . . . . . . 81 187 8.3. Method Definitions . . . . . . . . . . . . . . . . . . . 81 188 8.3.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 81 189 8.3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 82 190 8.3.3. POST . . . . . . . . . . . . . . . . . . . . . . . . 83 191 8.3.4. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 84 192 8.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 87 193 8.3.6. CONNECT . . . . . . . . . . . . . . . . . . . . . . . 88 194 8.3.7. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . 89 195 8.3.8. TRACE . . . . . . . . . . . . . . . . . . . . . . . . 90 196 9. Context . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 197 9.1. Request Context . . . . . . . . . . . . . . . . . . . . . 91 198 9.1.1. Expect . . . . . . . . . . . . . . . . . . . . . . . 92 199 9.1.2. From . . . . . . . . . . . . . . . . . . . . . . . . 94 200 9.1.3. Referer . . . . . . . . . . . . . . . . . . . . . . . 95 201 9.1.4. TE . . . . . . . . . . . . . . . . . . . . . . . . . 96 202 9.1.5. Trailer . . . . . . . . . . . . . . . . . . . . . . . 96 203 9.1.6. User-Agent . . . . . . . . . . . . . . . . . . . . . 97 204 9.2. Response Context . . . . . . . . . . . . . . . . . . . . 98 205 9.2.1. Allow . . . . . . . . . . . . . . . . . . . . . . . . 98 206 9.2.2. Date . . . . . . . . . . . . . . . . . . . . . . . . 99 207 9.2.3. Location . . . . . . . . . . . . . . . . . . . . . . 100 208 9.2.4. Retry-After . . . . . . . . . . . . . . . . . . . . . 101 209 9.2.5. Server . . . . . . . . . . . . . . . . . . . . . . . 102 210 10. Authentication . . . . . . . . . . . . . . . . . . . . . . . 102 211 10.1. Authentication Scheme . . . . . . . . . . . . . . . . . 102 212 10.2. Authentication Parameters . . . . . . . . . . . . . . . 103 213 10.3. Challenge and Response . . . . . . . . . . . . . . . . . 103 214 10.4. Credentials . . . . . . . . . . . . . . . . . . . . . . 104 215 10.5. Protection Space (Realm) . . . . . . . . . . . . . . . . 105 216 10.6. Authenticating User to Origin Server . . . . . . . . . . 106 217 10.6.1. WWW-Authenticate . . . . . . . . . . . . . . . . . . 106 218 10.6.2. Authorization . . . . . . . . . . . . . . . . . . . 107 219 10.6.3. Authentication-Info . . . . . . . . . . . . . . . . 107 220 10.7. Authenticating Client to Proxy . . . . . . . . . . . . . 108 221 10.7.1. Proxy-Authenticate . . . . . . . . . . . . . . . . . 108 222 10.7.2. Proxy-Authorization . . . . . . . . . . . . . . . . 108 223 10.7.3. Proxy-Authentication-Info . . . . . . . . . . . . . 109 224 11. Content Negotiation . . . . . . . . . . . . . . . . . . . . . 109 225 11.1. Proactive Negotiation . . . . . . . . . . . . . . . . . 110 226 11.1.1. Shared Negotiation Features . . . . . . . . . . . . 111 227 11.1.2. Accept . . . . . . . . . . . . . . . . . . . . . . . 113 228 11.1.3. Accept-Charset . . . . . . . . . . . . . . . . . . . 115 229 11.1.4. Accept-Encoding . . . . . . . . . . . . . . . . . . 116 230 11.1.5. Accept-Language . . . . . . . . . . . . . . . . . . 117 231 11.2. Reactive Negotiation . . . . . . . . . . . . . . . . . . 119 232 11.2.1. Vary . . . . . . . . . . . . . . . . . . . . . . . . 120 233 11.3. Request Payload Negotiation . . . . . . . . . . . . . . 121 234 12. Conditional Requests . . . . . . . . . . . . . . . . . . . . 121 235 12.1. Preconditions . . . . . . . . . . . . . . . . . . . . . 122 236 12.1.1. If-Match . . . . . . . . . . . . . . . . . . . . . . 122 237 12.1.2. If-None-Match . . . . . . . . . . . . . . . . . . . 124 238 12.1.3. If-Modified-Since . . . . . . . . . . . . . . . . . 125 239 12.1.4. If-Unmodified-Since . . . . . . . . . . . . . . . . 127 240 12.1.5. If-Range . . . . . . . . . . . . . . . . . . . . . . 128 241 12.2. Evaluation . . . . . . . . . . . . . . . . . . . . . . . 129 242 12.3. Precedence . . . . . . . . . . . . . . . . . . . . . . . 130 243 13. Range Requests . . . . . . . . . . . . . . . . . . . . . . . 131 244 13.1. Range Units . . . . . . . . . . . . . . . . . . . . . . 132 245 13.1.1. Range Specifiers . . . . . . . . . . . . . . . . . . 133 246 13.1.2. Byte Ranges . . . . . . . . . . . . . . . . . . . . 134 247 13.2. Range . . . . . . . . . . . . . . . . . . . . . . . . . 135 248 13.3. Accept-Ranges . . . . . . . . . . . . . . . . . . . . . 137 249 13.4. Content-Range . . . . . . . . . . . . . . . . . . . . . 137 250 13.5. Media Type multipart/byteranges . . . . . . . . . . . . 139 251 14. Status Codes . . . . . . . . . . . . . . . . . . . . . . . . 141 252 14.1. Overview of Status Codes . . . . . . . . . . . . . . . . 142 253 14.2. Informational 1xx . . . . . . . . . . . . . . . . . . . 142 254 14.2.1. 100 Continue . . . . . . . . . . . . . . . . . . . . 142 255 14.2.2. 101 Switching Protocols . . . . . . . . . . . . . . 143 256 14.3. Successful 2xx . . . . . . . . . . . . . . . . . . . . . 143 257 14.3.1. 200 OK . . . . . . . . . . . . . . . . . . . . . . . 143 258 14.3.2. 201 Created . . . . . . . . . . . . . . . . . . . . 144 259 14.3.3. 202 Accepted . . . . . . . . . . . . . . . . . . . . 144 260 14.3.4. 203 Non-Authoritative Information . . . . . . . . . 145 261 14.3.5. 204 No Content . . . . . . . . . . . . . . . . . . . 145 262 14.3.6. 205 Reset Content . . . . . . . . . . . . . . . . . 146 263 14.3.7. 206 Partial Content . . . . . . . . . . . . . . . . 146 264 14.4. Redirection 3xx . . . . . . . . . . . . . . . . . . . . 149 265 14.4.1. 300 Multiple Choices . . . . . . . . . . . . . . . . 152 266 14.4.2. 301 Moved Permanently . . . . . . . . . . . . . . . 153 267 14.4.3. 302 Found . . . . . . . . . . . . . . . . . . . . . 153 268 14.4.4. 303 See Other . . . . . . . . . . . . . . . . . . . 154 269 14.4.5. 304 Not Modified . . . . . . . . . . . . . . . . . . 154 270 14.4.6. 305 Use Proxy . . . . . . . . . . . . . . . . . . . 155 271 14.4.7. 306 (Unused) . . . . . . . . . . . . . . . . . . . . 155 272 14.4.8. 307 Temporary Redirect . . . . . . . . . . . . . . . 155 273 14.4.9. 308 Permanent Redirect . . . . . . . . . . . . . . . 156 274 14.5. Client Error 4xx . . . . . . . . . . . . . . . . . . . . 156 275 14.5.1. 400 Bad Request . . . . . . . . . . . . . . . . . . 156 276 14.5.2. 401 Unauthorized . . . . . . . . . . . . . . . . . . 156 277 14.5.3. 402 Payment Required . . . . . . . . . . . . . . . . 157 278 14.5.4. 403 Forbidden . . . . . . . . . . . . . . . . . . . 157 279 14.5.5. 404 Not Found . . . . . . . . . . . . . . . . . . . 157 280 14.5.6. 405 Method Not Allowed . . . . . . . . . . . . . . . 158 281 14.5.7. 406 Not Acceptable . . . . . . . . . . . . . . . . . 158 282 14.5.8. 407 Proxy Authentication Required . . . . . . . . . 158 283 14.5.9. 408 Request Timeout . . . . . . . . . . . . . . . . 158 284 14.5.10. 409 Conflict . . . . . . . . . . . . . . . . . . . . 159 285 14.5.11. 410 Gone . . . . . . . . . . . . . . . . . . . . . . 159 286 14.5.12. 411 Length Required . . . . . . . . . . . . . . . . 159 287 14.5.13. 412 Precondition Failed . . . . . . . . . . . . . . 160 288 14.5.14. 413 Payload Too Large . . . . . . . . . . . . . . . 160 289 14.5.15. 414 URI Too Long . . . . . . . . . . . . . . . . . . 160 290 14.5.16. 415 Unsupported Media Type . . . . . . . . . . . . . 160 291 14.5.17. 416 Range Not Satisfiable . . . . . . . . . . . . . 161 292 14.5.18. 417 Expectation Failed . . . . . . . . . . . . . . . 161 293 14.5.19. 418 (Unused) . . . . . . . . . . . . . . . . . . . . 162 294 14.5.20. 422 Unprocessable Payload . . . . . . . . . . . . . 162 295 14.5.21. 426 Upgrade Required . . . . . . . . . . . . . . . . 162 296 14.6. Server Error 5xx . . . . . . . . . . . . . . . . . . . . 163 297 14.6.1. 500 Internal Server Error . . . . . . . . . . . . . 163 298 14.6.2. 501 Not Implemented . . . . . . . . . . . . . . . . 163 299 14.6.3. 502 Bad Gateway . . . . . . . . . . . . . . . . . . 163 300 14.6.4. 503 Service Unavailable . . . . . . . . . . . . . . 163 301 14.6.5. 504 Gateway Timeout . . . . . . . . . . . . . . . . 164 302 14.6.6. 505 HTTP Version Not Supported . . . . . . . . . . . 164 303 15. Extending HTTP . . . . . . . . . . . . . . . . . . . . . . . 164 304 15.1. Method Extensibility . . . . . . . . . . . . . . . . . . 165 305 15.1.1. Method Registry . . . . . . . . . . . . . . . . . . 165 306 15.1.2. Considerations for New Methods . . . . . . . . . . . 165 307 15.2. Status Code Extensibility . . . . . . . . . . . . . . . 166 308 15.2.1. Status Code Registry . . . . . . . . . . . . . . . . 166 309 15.2.2. Considerations for New Status Codes . . . . . . . . 166 310 15.3. Field Name Extensibility . . . . . . . . . . . . . . . . 167 311 15.3.1. Field Name Registry . . . . . . . . . . . . . . . . 167 312 15.3.2. Considerations for New Field Names . . . . . . . . . 168 313 15.3.3. Considerations for New Field Values . . . . . . . . 169 314 15.4. Authentication Scheme Extensibility . . . . . . . . . . 171 315 15.4.1. Authentication Scheme Registry . . . . . . . . . . . 171 316 15.4.2. Considerations for New Authentication Schemes . . . 171 317 15.5. Range Unit Extensibility . . . . . . . . . . . . . . . . 172 318 15.5.1. Range Unit Registry . . . . . . . . . . . . . . . . 172 319 15.5.2. Considerations for New Range Units . . . . . . . . . 173 320 15.6. Content Coding Extensibility . . . . . . . . . . . . . . 173 321 15.6.1. Content Coding Registry . . . . . . . . . . . . . . 173 322 15.6.2. Considerations for New Content Codings . . . . . . . 173 323 15.7. Upgrade Token Registry . . . . . . . . . . . . . . . . . 174 324 16. Security Considerations . . . . . . . . . . . . . . . . . . . 174 325 16.1. Establishing Authority . . . . . . . . . . . . . . . . . 175 326 16.2. Risks of Intermediaries . . . . . . . . . . . . . . . . 176 327 16.3. Attacks Based on File and Path Names . . . . . . . . . . 176 328 16.4. Attacks Based on Command, Code, or Query Injection . . . 177 329 16.5. Attacks via Protocol Element Length . . . . . . . . . . 177 330 16.6. Attacks using Shared-dictionary Compression . . . . . . 178 331 16.7. Disclosure of Personal Information . . . . . . . . . . . 178 332 16.8. Privacy of Server Log Information . . . . . . . . . . . 179 333 16.9. Disclosure of Sensitive Information in URIs . . . . . . 179 334 16.10. Disclosure of Fragment after Redirects . . . . . . . . . 180 335 16.11. Disclosure of Product Information . . . . . . . . . . . 180 336 16.12. Browser Fingerprinting . . . . . . . . . . . . . . . . . 181 337 16.13. Validator Retention . . . . . . . . . . . . . . . . . . 182 338 16.14. Denial-of-Service Attacks Using Range . . . . . . . . . 182 339 16.15. Authentication Considerations . . . . . . . . . . . . . 183 340 16.15.1. Confidentiality of Credentials . . . . . . . . . . 183 341 16.15.2. Credentials and Idle Clients . . . . . . . . . . . 183 342 16.15.3. Protection Spaces . . . . . . . . . . . . . . . . . 184 343 16.15.4. Additional Response Fields . . . . . . . . . . . . 184 344 17. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 184 345 17.1. URI Scheme Registration . . . . . . . . . . . . . . . . 185 346 17.2. Method Registration . . . . . . . . . . . . . . . . . . 185 347 17.3. Status Code Registration . . . . . . . . . . . . . . . . 185 348 17.4. HTTP Field Name Registration . . . . . . . . . . . . . . 187 349 17.5. Authentication Scheme Registration . . . . . . . . . . . 189 350 17.6. Content Coding Registration . . . . . . . . . . . . . . 189 351 17.7. Range Unit Registration . . . . . . . . . . . . . . . . 189 352 17.8. Media Type Registration . . . . . . . . . . . . . . . . 189 353 17.9. Port Registration . . . . . . . . . . . . . . . . . . . 189 354 17.10. Upgrade Token Registration . . . . . . . . . . . . . . . 190 355 18. References . . . . . . . . . . . . . . . . . . . . . . . . . 190 356 18.1. Normative References . . . . . . . . . . . . . . . . . . 190 357 18.2. Informative References . . . . . . . . . . . . . . . . . 192 358 Appendix A. Collected ABNF . . . . . . . . . . . . . . . . . . . 198 359 Appendix B. Changes from previous RFCs . . . . . . . . . . . . . 203 360 B.1. Changes from RFC 2818 . . . . . . . . . . . . . . . . . . 203 361 B.2. Changes from RFC 7230 . . . . . . . . . . . . . . . . . . 203 362 B.3. Changes from RFC 7231 . . . . . . . . . . . . . . . . . . 204 363 B.4. Changes from RFC 7232 . . . . . . . . . . . . . . . . . . 205 364 B.5. Changes from RFC 7233 . . . . . . . . . . . . . . . . . . 205 365 B.6. Changes from RFC 7235 . . . . . . . . . . . . . . . . . . 205 366 B.7. Changes from RFC 7538 . . . . . . . . . . . . . . . . . . 205 367 B.8. Changes from RFC 7615 . . . . . . . . . . . . . . . . . . 205 368 B.9. Changes from RFC 7694 . . . . . . . . . . . . . . . . . . 206 369 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 206 370 C.1. Between RFC723x and draft 00 . . . . . . . . . . . . . . 206 371 C.2. Since draft-ietf-httpbis-semantics-00 . . . . . . . . . . 206 372 C.3. Since draft-ietf-httpbis-semantics-01 . . . . . . . . . . 207 373 C.4. Since draft-ietf-httpbis-semantics-02 . . . . . . . . . . 208 374 C.5. Since draft-ietf-httpbis-semantics-03 . . . . . . . . . . 209 375 C.6. Since draft-ietf-httpbis-semantics-04 . . . . . . . . . . 210 376 C.7. Since draft-ietf-httpbis-semantics-05 . . . . . . . . . . 210 377 C.8. Since draft-ietf-httpbis-semantics-06 . . . . . . . . . . 212 378 C.9. Since draft-ietf-httpbis-semantics-07 . . . . . . . . . . 213 379 C.10. Since draft-ietf-httpbis-semantics-08 . . . . . . . . . . 214 380 C.11. Since draft-ietf-httpbis-semantics-09 . . . . . . . . . . 216 381 C.12. Since draft-ietf-httpbis-semantics-10 . . . . . . . . . . 216 382 C.13. Since draft-ietf-httpbis-semantics-11 . . . . . . . . . . 217 383 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 218 384 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 218 386 1. Introduction 388 1.1. Purpose 390 The Hypertext Transfer Protocol (HTTP) is a family of stateless, 391 application-level, request/response protocols that share a generic 392 interface, extensible semantics, and self-descriptive messages to 393 enable flexible interaction with network-based hypertext information 394 systems. 396 HTTP hides the details of how a service is implemented by presenting 397 a uniform interface to clients that is independent of the types of 398 resources provided. Likewise, servers do not need to be aware of 399 each client's purpose: a request can be considered in isolation 400 rather than being associated with a specific type of client or a 401 predetermined sequence of application steps. This allows general- 402 purpose implementations to be used effectively in many different 403 contexts, reduces interaction complexity, and enables independent 404 evolution over time. 406 HTTP is also designed for use as an intermediation protocol, wherein 407 proxies and gateways can translate non-HTTP information systems into 408 a more generic interface. 410 One consequence of this flexibility is that the protocol cannot be 411 defined in terms of what occurs behind the interface. Instead, we 412 are limited to defining the syntax of communication, the intent of 413 received communication, and the expected behavior of recipients. If 414 the communication is considered in isolation, then successful actions 415 ought to be reflected in corresponding changes to the observable 416 interface provided by servers. However, since multiple clients might 417 act in parallel and perhaps at cross-purposes, we cannot require that 418 such changes be observable beyond the scope of a single response. 420 1.2. Evolution 422 HTTP has been the primary information transfer protocol for the World 423 Wide Web since its introduction in 1990. It began as a trivial 424 mechanism for low-latency requests, with a single method (GET) to 425 request transfer of a presumed hypertext document identified by a 426 given pathname. This original protocol is now referred to as 427 HTTP/0.9. 429 HTTP's version number consists of two decimal digits separated by a 430 "." (period or decimal point). The first digit ("major version") 431 indicates the messaging syntax, whereas the second digit ("minor 432 version") indicates the highest minor version within that major 433 version to which the sender is conformant (able to understand for 434 future communication). 436 As the Web grew, HTTP was extended to enclose requests and responses 437 within messages, transfer arbitrary data formats using MIME-like 438 media types, and route requests through intermediaries, eventually 439 being defined as HTTP/1.0 [RFC1945]. 441 HTTP/1.1 was designed to refine the protocol's features while 442 retaining compatibility with the existing text-based messaging 443 syntax, improving its interoperability, scalability, and robustness 444 across the Internet. This included length-based payload delimiters 445 for both fixed and dynamic (chunked) content, a consistent framework 446 for content negotiation, opaque validators for conditional requests, 447 cache controls for better cache consistency, range requests for 448 partial updates, and default persistent connections. HTTP/1.1 was 449 introduced in 1995 and published on the standards track in 1997 450 [RFC2068], 1999 [RFC2616], and 2014 ([RFC7230] - [RFC7235]). 452 HTTP/2 ([RFC7540]) introduced a multiplexed session layer on top of 453 the existing TLS and TCP protocols for exchanging concurrent HTTP 454 messages with efficient header field compression and server push. 455 HTTP/3 ([HTTP3]) provides greater independence for concurrent 456 messages by using QUIC as a secure multiplexed transport over UDP 457 instead of TCP. 459 All three major versions of HTTP rely on the semantics defined by 460 this document. They have not obsoleted each other because each one 461 has specific benefits and limitations depending on the context of 462 use. Implementations are expected to choose the most appropriate 463 transport and messaging syntax for their particular context. 465 This revision of HTTP separates the definition of semantics (this 466 document) and caching ([Caching]) from the current HTTP/1.1 messaging 467 syntax ([Messaging]) to allow each major protocol version to progress 468 independently while referring to the same core semantics. 470 1.3. Semantics 472 HTTP provides a uniform interface for interacting with a resource 473 (Section 3.1), regardless of its type, nature, or implementation, by 474 sending messages that manipulate or transfer representations 475 (Section 7). 477 Each message is either a request or a response. A client constructs 478 request messages that communicate its intentions and routes those 479 messages toward an identified origin server. A server listens for 480 requests, parses each message received, interprets the message 481 semantics in relation to the identified target resource, and responds 482 to that request with one or more response messages. The client 483 examines received responses to see if its intentions were carried 484 out, determining what to do next based on the received status and 485 payloads. 487 HTTP semantics include the intentions defined by each request method 488 (Section 8), extensions to those semantics that might be described in 489 request header fields, status codes that describe the response 490 (Section 14), and other control data and resource metadata that might 491 be given in response fields. 493 Semantics also include representation metadata that describe how a 494 payload is intended to be interpreted by a recipient, request header 495 fields that might influence content selection, and the various 496 selection algorithms that are collectively referred to as "content 497 negotiation" (Section 11). 499 1.4. Obsoletes 501 This document obsoletes the following specifications: 503 -------------------------------------------- ----------- --------- 504 Title Reference Changes 505 -------------------------------------------- ----------- --------- 506 HTTP Over TLS [RFC2818] B.1 507 HTTP/1.1 Message Syntax and Routing [*] [RFC7230] B.2 508 HTTP/1.1 Semantics and Content [RFC7231] B.3 509 HTTP/1.1 Conditional Requests [RFC7232] B.4 510 HTTP/1.1 Range Requests [RFC7233] B.5 511 HTTP/1.1 Authentication [RFC7235] B.6 512 HTTP Status Code 308 (Permanent Redirect) [RFC7538] B.7 513 HTTP Authentication-Info and Proxy- [RFC7615] B.8 514 Authentication-Info Response Header Fields 515 HTTP Client-Initiated Content-Encoding [RFC7694] B.9 516 -------------------------------------------- ----------- --------- 518 Table 1 520 [*] This document only obsoletes the portions of RFC 7230 that are 521 independent of the HTTP/1.1 messaging syntax and connection 522 management; the remaining bits of RFC 7230 are obsoleted by "HTTP/1.1 523 Messaging" [Messaging]. 525 2. Conformance 527 2.1. Syntax Notation 529 This specification uses the Augmented Backus-Naur Form (ABNF) 530 notation of [RFC5234], extended with the notation for case- 531 sensitivity in strings defined in [RFC7405]. 533 It also uses a list extension, defined in Section 5.7.1, that allows 534 for compact definition of comma-separated lists using a '#' operator 535 (similar to how the '*' operator indicates repetition). Appendix A 536 shows the collected grammar with all list operators expanded to 537 standard ABNF notation. 539 As a convention, ABNF rule names prefixed with "obs-" denote 540 "obsolete" grammar rules that appear for historical reasons. 542 The following core rules are included by reference, as defined in 543 Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), 544 CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double 545 quote), HEXDIG (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF 546 (line feed), OCTET (any 8-bit sequence of data), SP (space), and 547 VCHAR (any visible US-ASCII character). 549 Section 5.7 defines some generic syntactic components for field 550 values. 552 The rule below is defined in [Messaging]; 554 transfer-coding = 556 This specification uses the terms "character", "character encoding 557 scheme", "charset", and "protocol element" as they are defined in 558 [RFC6365]. 560 2.2. Requirements Notation 562 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 563 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 564 "OPTIONAL" in this document are to be interpreted as described in BCP 565 14 [RFC2119] [RFC8174] when, and only when, they appear in all 566 capitals, as shown here. 568 This specification targets conformance criteria according to the role 569 of a participant in HTTP communication. Hence, requirements are 570 placed on senders, recipients, clients, servers, user agents, 571 intermediaries, origin servers, proxies, gateways, or caches, 572 depending on what behavior is being constrained by the requirement. 574 Additional (social) requirements are placed on implementations, 575 resource owners, and protocol element registrations when they apply 576 beyond the scope of a single communication. 578 The verb "generate" is used instead of "send" where a requirement 579 applies only to implementations that create the protocol element, 580 rather than an implementation that forwards a received element 581 downstream. 583 An implementation is considered conformant if it complies with all of 584 the requirements associated with the roles it partakes in HTTP. 586 Conformance includes both the syntax and semantics of protocol 587 elements. A sender MUST NOT generate protocol elements that convey a 588 meaning that is known by that sender to be false. A sender MUST NOT 589 generate protocol elements that do not match the grammar defined by 590 the corresponding ABNF rules. Within a given message, a sender MUST 591 NOT generate protocol elements or syntax alternatives that are only 592 allowed to be generated by participants in other roles (i.e., a role 593 that the sender does not have for that message). 595 2.3. Length Requirements 597 When a received protocol element is parsed, the recipient MUST be 598 able to parse any value of reasonable length that is applicable to 599 the recipient's role and that matches the grammar defined by the 600 corresponding ABNF rules. Note, however, that some received protocol 601 elements might not be parsed. For example, an intermediary 602 forwarding a message might parse a field into generic field name and 603 field value components, but then forward the field without further 604 parsing inside the field value. 606 HTTP does not have specific length limitations for many of its 607 protocol elements because the lengths that might be appropriate will 608 vary widely, depending on the deployment context and purpose of the 609 implementation. Hence, interoperability between senders and 610 recipients depends on shared expectations regarding what is a 611 reasonable length for each protocol element. Furthermore, what is 612 commonly understood to be a reasonable length for some protocol 613 elements has changed over the course of the past two decades of HTTP 614 use and is expected to continue changing in the future. 616 At a minimum, a recipient MUST be able to parse and process protocol 617 element lengths that are at least as long as the values that it 618 generates for those same protocol elements in other messages. For 619 example, an origin server that publishes very long URI references to 620 its own resources needs to be able to parse and process those same 621 references when received as a target URI. 623 2.4. Error Handling 625 A recipient MUST interpret a received protocol element according to 626 the semantics defined for it by this specification, including 627 extensions to this specification, unless the recipient has determined 628 (through experience or configuration) that the sender incorrectly 629 implements what is implied by those semantics. For example, an 630 origin server might disregard the contents of a received 631 Accept-Encoding header field if inspection of the User-Agent header 632 field indicates a specific implementation version that is known to 633 fail on receipt of certain content codings. 635 Unless noted otherwise, a recipient MAY attempt to recover a usable 636 protocol element from an invalid construct. HTTP does not define 637 specific error handling mechanisms except when they have a direct 638 impact on security, since different applications of the protocol 639 require different error handling strategies. For example, a Web 640 browser might wish to transparently recover from a response where the 641 Location header field doesn't parse according to the ABNF, whereas a 642 systems control client might consider any form of error recovery to 643 be dangerous. 645 Some requests can be automatically retried by a client in the event 646 of an underlying connection failure, as described in Section 8.2.2. 648 3. Terminology 650 HTTP was created for the World Wide Web (WWW) architecture and has 651 evolved over time to support the scalability needs of a worldwide 652 hypertext system. Much of that architecture is reflected in the 653 terminology and syntax productions used to define HTTP. 655 3.1. Resources 657 The target of an HTTP request is called a "resource". HTTP does not 658 limit the nature of a resource; it merely defines an interface that 659 might be used to interact with resources. Most resources are 660 identified by a Uniform Resource Identifier (URI), as described in 661 Section 4. 663 One design goal of HTTP is to separate resource identification from 664 request semantics, which is made possible by vesting the request 665 semantics in the request method (Section 8) and a few request- 666 modifying header fields. If there is a conflict between the method 667 semantics and any semantic implied by the URI itself, as described in 668 Section 8.2.1, the method semantics take precedence. 670 HTTP relies upon the Uniform Resource Identifier (URI) standard 671 [RFC3986] to indicate the target resource (Section 6.1) and 672 relationships between resources. 674 3.2. Connections 676 HTTP is a client/server protocol that operates over a reliable 677 transport- or session-layer "connection". 679 An HTTP "client" is a program that establishes a connection to a 680 server for the purpose of sending one or more HTTP requests. An HTTP 681 "server" is a program that accepts connections in order to service 682 HTTP requests by sending HTTP responses. 684 The terms "client" and "server" refer only to the roles that these 685 programs perform for a particular connection. The same program might 686 act as a client on some connections and a server on others. 688 3.3. Messages 690 HTTP is a stateless request/response protocol for exchanging 691 "messages" across a connection. The terms "sender" and "recipient" 692 refer to any implementation that sends or receives a given message, 693 respectively. 695 A client sends requests to a server in the form of a request message 696 with a method (Section 8) and request target (Section 6.1.1). The 697 request might also contain header fields (Section 5.4) for request 698 modifiers, client information, and representation metadata, a payload 699 body (Section 5.5.4) to be processed in accordance with the method, 700 and trailer fields (Section 5.6) for metadata collected while sending 701 the payload. 703 A server responds to a client's request by sending one or more 704 response messages, each including a status code (Section 14). The 705 response might also contain header fields for server information, 706 resource metadata, and representation metadata, a payload body to be 707 interpreted in accordance with the status code, and trailer fields 708 for metadata collected while sending the payload. 710 3.4. User Agent 712 The term "user agent" refers to any of the various client programs 713 that initiate a request. 715 The most familiar form of user agent is the general-purpose Web 716 browser, but that's only a small percentage of implementations. 717 Other common user agents include spiders (web-traversing robots), 718 command-line tools, billboard screens, household appliances, scales, 719 light bulbs, firmware update scripts, mobile apps, and communication 720 devices in a multitude of shapes and sizes. 722 Being a user agent does not imply that there is a human user directly 723 interacting with the software agent at the time of a request. In 724 many cases, a user agent is installed or configured to run in the 725 background and save its results for later inspection (or save only a 726 subset of those results that might be interesting or erroneous). 727 Spiders, for example, are typically given a start URI and configured 728 to follow certain behavior while crawling the Web as a hypertext 729 graph. 731 Many user agents cannot, or choose not to, make interactive 732 suggestions to their user or provide adequate warning for security or 733 privacy concerns. In the few cases where this specification requires 734 reporting of errors to the user, it is acceptable for such reporting 735 to only be observable in an error console or log file. Likewise, 736 requirements that an automated action be confirmed by the user before 737 proceeding might be met via advance configuration choices, run-time 738 options, or simple avoidance of the unsafe action; confirmation does 739 not imply any specific user interface or interruption of normal 740 processing if the user has already made that choice. 742 3.5. Origin Server 744 The term "origin server" refers to a program that can originate 745 authoritative responses for a given target resource. 747 The most familiar form of origin server are large public websites. 748 However, like user agents being equated with browsers, it is easy to 749 be misled into thinking that all origin servers are alike. Common 750 origin servers also include home automation units, configurable 751 networking components, office machines, autonomous robots, news 752 feeds, traffic cameras, real-time ad selectors, and video-on-demand 753 platforms. 755 3.6. Example Request and Response 757 Most HTTP communication consists of a retrieval request (GET) for a 758 representation of some resource identified by a URI. In the simplest 759 case, this might be accomplished via a single bidirectional 760 connection (===) between the user agent (UA) and the origin server 761 (O). 763 request > 764 UA ======================================= O 765 < response 767 Figure 1 769 The following example illustrates a typical message exchange for a 770 GET request (Section 8.3.1) on the URI "http://www.example.com/ 771 hello.txt": 773 Client request: 775 GET /hello.txt HTTP/1.1 776 User-Agent: curl/7.16.3 libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3 777 Host: www.example.com 778 Accept-Language: en, mi 780 Server response: 782 HTTP/1.1 200 OK 783 Date: Mon, 27 Jul 2009 12:28:53 GMT 784 Server: Apache 785 Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT 786 ETag: "34aa387-d-1568eb00" 787 Accept-Ranges: bytes 788 Content-Length: 51 789 Vary: Accept-Encoding 790 Content-Type: text/plain 792 Hello World! My payload includes a trailing CRLF. 794 3.7. Intermediaries 796 HTTP enables the use of intermediaries to satisfy requests through a 797 chain of connections. There are three common forms of HTTP 798 intermediary: proxy, gateway, and tunnel. In some cases, a single 799 intermediary might act as an origin server, proxy, gateway, or 800 tunnel, switching behavior based on the nature of each request. 802 > > > > 803 UA =========== A =========== B =========== C =========== O 804 < < < < 806 Figure 2 808 The figure above shows three intermediaries (A, B, and C) between the 809 user agent and origin server. A request or response message that 810 travels the whole chain will pass through four separate connections. 811 Some HTTP communication options might apply only to the connection 812 with the nearest, non-tunnel neighbor, only to the endpoints of the 813 chain, or to all connections along the chain. Although the diagram 814 is linear, each participant might be engaged in multiple, 815 simultaneous communications. For example, B might be receiving 816 requests from many clients other than A, and/or forwarding requests 817 to servers other than C, at the same time that it is handling A's 818 request. Likewise, later requests might be sent through a different 819 path of connections, often based on dynamic configuration for load 820 balancing. 822 The terms "upstream" and "downstream" are used to describe 823 directional requirements in relation to the message flow: all 824 messages flow from upstream to downstream. The terms "inbound" and 825 "outbound" are used to describe directional requirements in relation 826 to the request route: "inbound" means toward the origin server and 827 "outbound" means toward the user agent. 829 A "proxy" is a message-forwarding agent that is chosen by the client, 830 usually via local configuration rules, to receive requests for some 831 type(s) of absolute URI and attempt to satisfy those requests via 832 translation through the HTTP interface. Some translations are 833 minimal, such as for proxy requests for "http" URIs, whereas other 834 requests might require translation to and from entirely different 835 application-level protocols. Proxies are often used to group an 836 organization's HTTP requests through a common intermediary for the 837 sake of security, annotation services, or shared caching. Some 838 proxies are designed to apply transformations to selected messages or 839 payloads while they are being forwarded, as described in Section 6.5. 841 A "gateway" (a.k.a. "reverse proxy") is an intermediary that acts as 842 an origin server for the outbound connection but translates received 843 requests and forwards them inbound to another server or servers. 844 Gateways are often used to encapsulate legacy or untrusted 845 information services, to improve server performance through 846 "accelerator" caching, and to enable partitioning or load balancing 847 of HTTP services across multiple machines. 849 All HTTP requirements applicable to an origin server also apply to 850 the outbound communication of a gateway. A gateway communicates with 851 inbound servers using any protocol that it desires, including private 852 extensions to HTTP that are outside the scope of this specification. 853 However, an HTTP-to-HTTP gateway that wishes to interoperate with 854 third-party HTTP servers ought to conform to user agent requirements 855 on the gateway's inbound connection. 857 A "tunnel" acts as a blind relay between two connections without 858 changing the messages. Once active, a tunnel is not considered a 859 party to the HTTP communication, though the tunnel might have been 860 initiated by an HTTP request. A tunnel ceases to exist when both 861 ends of the relayed connection are closed. Tunnels are used to 862 extend a virtual connection through an intermediary, such as when 863 Transport Layer Security (TLS, [RFC8446]) is used to establish 864 confidential communication through a shared firewall proxy. 866 The above categories for intermediary only consider those acting as 867 participants in the HTTP communication. There are also 868 intermediaries that can act on lower layers of the network protocol 869 stack, filtering or redirecting HTTP traffic without the knowledge or 870 permission of message senders. Network intermediaries are 871 indistinguishable (at a protocol level) from an on-path attacker, 872 often introducing security flaws or interoperability problems due to 873 mistakenly violating HTTP semantics. 875 For example, an "interception proxy" [RFC3040] (also commonly known 876 as a "transparent proxy" [RFC1919] or "captive portal") differs from 877 an HTTP proxy because it is not chosen by the client. Instead, an 878 interception proxy filters or redirects outgoing TCP port 80 packets 879 (and occasionally other common port traffic). Interception proxies 880 are commonly found on public network access points, as a means of 881 enforcing account subscription prior to allowing use of non-local 882 Internet services, and within corporate firewalls to enforce network 883 usage policies. 885 HTTP is defined as a stateless protocol, meaning that each request 886 message can be understood in isolation. Many implementations depend 887 on HTTP's stateless design in order to reuse proxied connections or 888 dynamically load balance requests across multiple servers. Hence, a 889 server MUST NOT assume that two requests on the same connection are 890 from the same user agent unless the connection is secured and 891 specific to that agent. Some non-standard HTTP extensions (e.g., 892 [RFC4559]) have been known to violate this requirement, resulting in 893 security and interoperability problems. 895 3.8. Caches 897 A "cache" is a local store of previous response messages and the 898 subsystem that controls its message storage, retrieval, and deletion. 899 A cache stores cacheable responses in order to reduce the response 900 time and network bandwidth consumption on future, equivalent 901 requests. Any client or server MAY employ a cache, though a cache 902 cannot be used by a server while it is acting as a tunnel. 904 The effect of a cache is that the request/response chain is shortened 905 if one of the participants along the chain has a cached response 906 applicable to that request. The following illustrates the resulting 907 chain if B has a cached copy of an earlier response from O (via C) 908 for a request that has not been cached by UA or A. 910 > > 911 UA =========== A =========== B - - - - - - C - - - - - - O 912 < < 914 Figure 3 916 A response is "cacheable" if a cache is allowed to store a copy of 917 the response message for use in answering subsequent requests. Even 918 when a response is cacheable, there might be additional constraints 919 placed by the client or by the origin server on when that cached 920 response can be used for a particular request. HTTP requirements for 921 cache behavior and cacheable responses are defined in Section 2 of 922 [Caching]. 924 There is a wide variety of architectures and configurations of caches 925 deployed across the World Wide Web and inside large organizations. 926 These include national hierarchies of proxy caches to save 927 transoceanic bandwidth, collaborative systems that broadcast or 928 multicast cache entries, archives of pre-fetched cache entries for 929 use in off-line or high-latency environments, and so on. 931 4. Identifiers 933 Uniform Resource Identifiers (URIs) [RFC3986] are used throughout 934 HTTP as the means for identifying resources (Section 3.1). 936 4.1. URI References 938 URI references are used to target requests, indicate redirects, and 939 define relationships. 941 The definitions of "URI-reference", "absolute-URI", "relative-part", 942 "authority", "port", "host", "path-abempty", "segment", and "query" 943 are adopted from the URI generic syntax. An "absolute-path" rule is 944 defined for protocol elements that can contain a non-empty path 945 component. (This rule differs slightly from the path-abempty rule of 946 RFC 3986, which allows for an empty path to be used in references, 947 and path-absolute rule, which does not allow paths that begin with 948 "//".) A "partial-URI" rule is defined for protocol elements that 949 can contain a relative URI but not a fragment component. 951 URI-reference = 952 absolute-URI = 953 relative-part = 954 authority = 955 uri-host = 956 port = 957 path-abempty = 958 segment = 959 query = 961 absolute-path = 1*( "/" segment ) 962 partial-URI = relative-part [ "?" query ] 964 Each protocol element in HTTP that allows a URI reference will 965 indicate in its ABNF production whether the element allows any form 966 of reference (URI-reference), only a URI in absolute form (absolute- 967 URI), only the path and optional query components, or some 968 combination of the above. Unless otherwise indicated, URI references 969 are parsed relative to the target URI (Section 6.1). 971 It is RECOMMENDED that all senders and recipients support, at a 972 minimum, URIs with lengths of 8000 octets in protocol elements. Note 973 that this implies some structures and on-wire representations (for 974 example, the request line in HTTP/1.1) will necessarily be larger in 975 some cases. 977 4.2. URI Schemes 979 IANA maintains the registry of URI Schemes [BCP35] at 980 . Although requests 981 might target any URI scheme, the following schemes are inherent to 982 HTTP servers: 984 ------------ ------------------------------------ ------- 985 URI Scheme Description Ref. 986 ------------ ------------------------------------ ------- 987 http Hypertext Transfer Protocol 4.2.1 988 https Hypertext Transfer Protocol Secure 4.2.2 989 ------------ ------------------------------------ ------- 991 Table 2 993 Note that the presence of an "http" or "https" URI does not imply 994 that there is always an HTTP server at the identified origin 995 listening for connections. Anyone can mint a URI, whether or not a 996 server exists and whether or not that server currently maps that 997 identifier to a resource. The delegated nature of registered names 998 and IP addresses creates a federated namespace whether or not an HTTP 999 server is present. 1001 4.2.1. http URI Scheme 1003 The "http" URI scheme is hereby defined for minting identifiers 1004 within the hierarchical namespace governed by a potential HTTP origin 1005 server listening for TCP ([RFC0793]) connections on a given port. 1007 http-URI = "http" "://" authority path-abempty [ "?" query ] 1009 The origin server for an "http" URI is identified by the authority 1010 component, which includes a host identifier and optional port number 1011 ([RFC3986], Section 3.2.2). If the port subcomponent is empty or not 1012 given, TCP port 80 (the reserved port for WWW services) is the 1013 default. The origin determines who has the right to respond 1014 authoritatively to requests that target the identified resource, as 1015 defined in Section 4.3.2. 1017 A sender MUST NOT generate an "http" URI with an empty host 1018 identifier. A recipient that processes such a URI reference MUST 1019 reject it as invalid. 1021 The hierarchical path component and optional query component identify 1022 the target resource within that origin server's name space. 1024 4.2.2. https URI Scheme 1026 The "https" URI scheme is hereby defined for minting identifiers 1027 within the hierarchical namespace governed by a potential origin 1028 server listening for TCP connections on a given port and capable of 1029 establishing a TLS ([RFC8446]) connection that has been secured for 1030 HTTP communication. In this context, "secured" specifically means 1031 that the server has been authenticated as acting on behalf of the 1032 identified authority and all HTTP communication with that server has 1033 been protected for confidentiality and integrity through the use of 1034 strong encryption. 1036 https-URI = "https" "://" authority path-abempty [ "?" query ] 1038 The origin server for an "https" URI is identified by the authority 1039 component, which includes a host identifier and optional port number 1040 ([RFC3986], Section 3.2.2). If the port subcomponent is empty or not 1041 given, TCP port 443 (the reserved port for HTTP over TLS) is the 1042 default. The origin determines who has the right to respond 1043 authoritatively to requests that target the identified resource, as 1044 defined in Section 4.3.3. 1046 A sender MUST NOT generate an "https" URI with an empty host 1047 identifier. A recipient that processes such a URI reference MUST 1048 reject it as invalid. 1050 The hierarchical path component and optional query component identify 1051 the target resource within that origin server's name space. 1053 A client MUST ensure that its HTTP requests for an "https" resource 1054 are secured, prior to being communicated, and that it only accepts 1055 secured responses to those requests. 1057 Resources made available via the "https" scheme have no shared 1058 identity with the "http" scheme. They are distinct origins with 1059 separate namespaces. However, an extension to HTTP that is defined 1060 to apply to all origins with the same host, such as the Cookie 1061 protocol [RFC6265], can allow information set by one service to 1062 impact communication with other services within a matching group of 1063 host domains. 1065 4.2.3. http(s) Normalization and Comparison 1067 Since the "http" and "https" schemes conform to the URI generic 1068 syntax, such URIs are normalized and compared according to the 1069 algorithm defined in Section 6 of [RFC3986], using the defaults 1070 described above for each scheme. 1072 If the port is equal to the default port for a scheme, the normal 1073 form is to omit the port subcomponent. When not being used as the 1074 target of an OPTIONS request, an empty path component is equivalent 1075 to an absolute path of "/", so the normal form is to provide a path 1076 of "/" instead. The scheme and host are case-insensitive and 1077 normally provided in lowercase; all other components are compared in 1078 a case-sensitive manner. Characters other than those in the 1079 "reserved" set are equivalent to their percent-encoded octets: the 1080 normal form is to not encode them (see Sections 2.1 and 2.2 of 1081 [RFC3986]). 1083 For example, the following three URIs are equivalent: 1085 http://example.com:80/~smith/home.html 1086 http://EXAMPLE.com/%7Esmith/home.html 1087 http://EXAMPLE.com:/%7esmith/home.html 1089 4.2.4. http(s) Deprecated userinfo 1091 The URI generic syntax for authority also includes a userinfo 1092 subcomponent ([RFC3986], Section 3.2.1) for including user 1093 authentication information in the URI. In that subcomponent, the use 1094 of the format "user:password" is deprecated. 1096 Some implementations make use of the userinfo component for internal 1097 configuration of authentication information, such as within command 1098 invocation options, configuration files, or bookmark lists, even 1099 though such usage might expose a user identifier or password. 1101 A sender MUST NOT generate the userinfo subcomponent (and its "@" 1102 delimiter) when an "http" or "https" URI reference is generated 1103 within a message as a target URI or field value. 1105 Before making use of an "http" or "https" URI reference received from 1106 an untrusted source, a recipient SHOULD parse for userinfo and treat 1107 its presence as an error; it is likely being used to obscure the 1108 authority for the sake of phishing attacks. 1110 4.2.5. http(s) References with Fragment Identifiers 1112 Fragment identifiers allow for indirect identification of a secondary 1113 resource, independent of the URI scheme, as defined in Section 3.5 of 1114 [RFC3986]. Some protocol elements that refer to a URI allow 1115 inclusion of a fragment, while others do not. They are distinguished 1116 by use of the ABNF rule for elements where fragment is allowed; 1117 otherwise, a specific rule that excludes fragments is used (see 1118 Section 6.1). 1120 | *Note:* the fragment identifier component is not part of the 1121 | actual scheme definition for a URI scheme (see Section 4.3 of 1122 | [RFC3986]), thus does not appear in the ABNF definitions for 1123 | the "http" and "https" URI schemes above. 1125 4.3. Authoritative Access 1127 See Section 16.1 for security considerations related to establishing 1128 authority. 1130 4.3.1. URI Origin 1132 The "origin" for a given URI is the triple of scheme, host, and port 1133 after normalizing the scheme and host to lowercase and normalizing 1134 the port to remove any leading zeros. If port is elided from the 1135 URI, the default port for that scheme is used. For example, the URI 1136 https://Example.Com/happy.js 1138 would have the origin 1140 { "https", "example.com", "443" } 1142 which can also be described as the normalized URI prefix with port 1143 always present: 1145 https://example.com:443 1147 Each origin defines its own namespace and controls how identifiers 1148 within that namespace are mapped to resources. In turn, how the 1149 origin responds to valid requests, consistently over time, determines 1150 the semantics that users will associate with a URI, and the 1151 usefulness of those semantics is what ultimately transforms these 1152 mechanisms into a "resource" for users to reference and access in the 1153 future. 1155 Two origins are distinct if they differ in scheme, host, or port. 1156 Even when it can be verified that the same entity controls two 1157 distinct origins, the two namespaces under those origins are distinct 1158 unless explicitly aliased by a server authoritative for that origin. 1160 Origin is also used within HTML and related Web protocols, beyond the 1161 scope of this document, as described in [RFC6454]. 1163 4.3.2. http origins 1165 Although HTTP is independent of the transport protocol, the "http" 1166 scheme (Section 4.2.1) is specific to associating authority with 1167 whomever controls the origin server listening for TCP connections on 1168 the indicated port of whatever host is identified within the 1169 authority component. This is a very weak sense of authority because 1170 it depends on both client-specific name resolution mechanisms and 1171 communication that might not be secured from an on-path attacker. 1172 Nevertheless, it is a sufficient minimum for binding "http" 1173 identifiers to an origin server for consistent resolution within a 1174 trusted environment. 1176 If the host identifier is provided as an IP address, the origin 1177 server is the listener (if any) on the indicated TCP port at that IP 1178 address. If host is a registered name, the registered name is an 1179 indirect identifier for use with a name resolution service, such as 1180 DNS, to find an address for an appropriate origin server. 1182 When an "http" URI is used within a context that calls for access to 1183 the indicated resource, a client MAY attempt access by resolving the 1184 host identifier to an IP address, establishing a TCP connection to 1185 that address on the indicated port, and sending an HTTP request 1186 message to the server containing the URI's identifying data. 1188 If the server responds to such a request with a non-interim HTTP 1189 response message, as described in Section 14, then that response is 1190 considered an authoritative answer to the client's request. 1192 Note, however, that the above is not the only means for obtaining an 1193 authoritative response, nor does it imply that an authoritative 1194 response is always necessary (see [Caching]). For example, the Alt- 1195 Svc header field [RFC7838] allows an origin server to identify other 1196 services that are also authoritative for that origin. Access to 1197 "http" identified resources might also be provided by protocols 1198 outside the scope of this document. 1200 4.3.3. https origins 1202 The "https" scheme (Section 4.2.2) associates authority based on the 1203 ability of a server to use the private key corresponding to a 1204 certificate that the client considers to be trustworthy for the 1205 identified origin server. The client usually relies upon a chain of 1206 trust, conveyed from some prearranged or configured trust anchor, to 1207 deem a certificate trustworthy (Section 4.3.4). 1209 In HTTP/1.1 and earlier, a client will only attribute authority to a 1210 server when they are communicating over a successfully established 1211 and secured connection specifically to that URI origin's host. The 1212 connection establishment and certificate verification are used as 1213 proof of authority. 1215 In HTTP/2 and HTTP/3, a client will attribute authority to a server 1216 when they are communicating over a successfully established and 1217 secured connection if the URI origin's host matches any of the hosts 1218 present in the server's certificate and the client believes that it 1219 could open a connection to that host for that URI. In practice, a 1220 client will make a DNS query to check that the origin's host contains 1221 the same server IP address as the established connection. This 1222 restriction can be removed by the origin server sending an equivalent 1223 ORIGIN frame [RFC8336]. 1225 The request target's host and port value are passed within each HTTP 1226 request, identifying the origin and distinguishing it from other 1227 namespaces that might be controlled by the same server. It is the 1228 origin's responsibility to ensure that any services provided with 1229 control over its certificate's private key are equally responsible 1230 for managing the corresponding "https" namespaces, or at least 1231 prepared to reject requests that appear to have been misdirected. A 1232 server might be unwilling to serve as the origin for some hosts even 1233 when they have the authority to do so. 1235 For example, if a network attacker causes connections for port N to 1236 be received at port Q, checking the target URI is necessary to ensure 1237 that the attacker can't cause "https://example.com:N/foo" to be 1238 replaced by "https://example.com:Q/foo" without consent. 1240 Note that the "https" scheme does not rely on TCP and the connected 1241 port number for associating authority, since both are outside the 1242 secured communication and thus cannot be trusted as definitive. 1243 Hence, the HTTP communication might take place over any channel that 1244 has been secured, as defined in Section 4.2.2, including protocols 1245 that don't use TCP. 1247 When an "https" URI is used within a context that calls for access to 1248 the indicated resource, a client MAY attempt access by resolving the 1249 host identifier to an IP address, establishing a TCP connection to 1250 that address on the indicated port, securing the connection end-to- 1251 end by successfully initiating TLS over TCP with confidentiality and 1252 integrity protection, and sending an HTTP request message over that 1253 connection containing the URI's identifying data. 1255 If the server responds to such a request with a non-interim HTTP 1256 response message, as described in Section 14, then that response is 1257 considered an authoritative answer to the client's request. 1259 Note, however, that the above is not the only means for obtaining an 1260 authoritative response, nor does it imply that an authoritative 1261 response is always necessary (see [Caching]). 1263 4.3.4. https certificate verification 1265 To establish a secured connection to dereference a URI, a client MUST 1266 verify that the service's identity is an acceptable match for the 1267 URI's origin server. Certificate verification is used to prevent 1268 server impersonation by an on-path attacker or by an attacker that 1269 controls name resolution. This process requires that a client be 1270 configured with a set of trust anchors. 1272 In general, a client MUST verify the service identity using the 1273 verification process defined in Section 6 of [RFC6125] (for a 1274 reference identifier of type URI-ID) unless the client has been 1275 specifically configured to accept some other form of verification. 1276 For example, a client might be connecting to a server whose address 1277 and hostname are dynamic, with an expectation that the service will 1278 present a specific certificate (or a certificate matching some 1279 externally defined reference identity) rather than one matching the 1280 dynamic URI's origin server identifier. 1282 In special cases, it might be appropriate for a client to simply 1283 ignore the server's identity, but it must be understood that this 1284 leaves a connection open to active attack. 1286 If the certificate is not valid for the URI's origin server, a user 1287 agent MUST either notify the user (user agents MAY give the user an 1288 option to continue with the connection in any case) or terminate the 1289 connection with a bad certificate error. Automated clients MUST log 1290 the error to an appropriate audit log (if available) and SHOULD 1291 terminate the connection (with a bad certificate error). Automated 1292 clients MAY provide a configuration setting that disables this check, 1293 but MUST provide a setting which enables it. 1295 5. Message Abstraction 1297 Each major version of HTTP defines its own syntax for the 1298 communication of messages. However, they share a common data 1299 abstraction. 1301 A message consists of control data to describe and route the message, 1302 optional header fields that modify or extend the message semantics, 1303 describe the sender, the payload, or provide additional context, a 1304 potentially unbounded stream of payload data, and optional trailer 1305 fields for metadata collected while sending the payload. 1307 Messages are intended to be self-descriptive. This means that 1308 everything a recipient needs to know about the message can be 1309 determined by looking at the message itself, after decoding or 1310 reconstituting parts that have been compressed or elided in transit, 1311 without requiring an understanding of the sender's current 1312 application state (established via prior messages). 1314 5.1. Protocol Version 1316 While HTTP's core semantics don't change between protocol versions, 1317 the expression of them "on the wire" can change, and so the HTTP 1318 version number changes when incompatible changes are made to the wire 1319 format. Additionally, HTTP allows incremental, backwards-compatible 1320 changes to be made to the protocol without changing its version 1321 through the use of defined extension points (Section 15). 1323 The protocol version as a whole indicates the sender's conformance 1324 with the set of requirements laid out in that version's corresponding 1325 specification of HTTP. For example, the version "HTTP/1.1" is 1326 defined by the combined specifications of this document, "HTTP 1327 Caching" [Caching], and "HTTP/1.1 Messaging" [Messaging]. 1329 HTTP's major version number is incremented when an incompatible 1330 message syntax is introduced. The minor number is incremented when 1331 changes made to the protocol have the effect of adding to the message 1332 semantics or implying additional capabilities of the sender. 1334 The minor version advertises the sender's communication capabilities 1335 even when the sender is only using a backwards-compatible subset of 1336 the protocol, thereby letting the recipient know that more advanced 1337 features can be used in response (by servers) or in future requests 1338 (by clients). 1340 A client SHOULD send a request version equal to the highest version 1341 to which the client is conformant and whose major version is no 1342 higher than the highest version supported by the server, if this is 1343 known. A client MUST NOT send a version to which it is not 1344 conformant. 1346 A client MAY send a lower request version if it is known that the 1347 server incorrectly implements the HTTP specification, but only after 1348 the client has attempted at least one normal request and determined 1349 from the response status code or header fields (e.g., Server) that 1350 the server improperly handles higher request versions. 1352 A server SHOULD send a response version equal to the highest version 1353 to which the server is conformant that has a major version less than 1354 or equal to the one received in the request. A server MUST NOT send 1355 a version to which it is not conformant. A server can send a 505 1356 (HTTP Version Not Supported) response if it wishes, for any reason, 1357 to refuse service of the client's major protocol version. 1359 When an HTTP message is received with a major version number that the 1360 recipient implements, but a higher minor version number than what the 1361 recipient implements, the recipient SHOULD process the message as if 1362 it were in the highest minor version within that major version to 1363 which the recipient is conformant. A recipient can assume that a 1364 message with a higher minor version, when sent to a recipient that 1365 has not yet indicated support for that higher version, is 1366 sufficiently backwards-compatible to be safely processed by any 1367 implementation of the same major version. 1369 When a major version of HTTP does not define any minor versions, the 1370 minor version "0" is implied and is used when referring to that 1371 protocol within a protocol element that requires sending a minor 1372 version. 1374 5.2. Framing 1376 // Message framing defines how each message begins and ends, such 1377 // that the message can be distinguished from other message (or 1378 // noise) on the same connection. Framing is specific to each major 1379 // version of HTTP. 1381 One of the functions of message framing is to assure that messages 1382 are complete. A message is considered complete when all of the 1383 octets indicated by its framing are available. Note that, when no 1384 explicit framing is used, a response message that is ended by the 1385 transport connection's close is considered complete even though it 1386 might be indistinguishable from an incomplete response, unless a 1387 transport-level error indicates that it is not complete. 1389 5.3. Control Data 1391 5.3.1. Request 1393 HTTP communication is initiated by a user agent for some purpose. 1394 The purpose is a combination of request semantics and a target 1395 resource upon which to apply those semantics. 1397 5.3.2. Response 1399 5.4. Header Fields 1401 HTTP messages use key/value pairs to convey data about the message, 1402 its payload, the target resource, or the connection. They are called 1403 "HTTP fields" or just "fields". 1405 Fields that are sent/received before the message body are referred to 1406 as "header fields" (or just "headers", colloquially) and are located 1407 within the "header section" of a message. We refer to some named 1408 fields specifically as a "header field" when they are only allowed to 1409 be sent in the header section. 1411 Fields that are sent/received after the header section has ended 1412 (usually after the message body begins to stream) are referred to as 1413 "trailer fields" (or just "trailers", colloquially) and located 1414 within a "trailer section". One or more trailer sections are only 1415 possible when supported by the version of HTTP in use and enabled by 1416 an extensible mechanism for framing message sections. 1418 Both sections are composed of any number of "field lines", each with 1419 a "field name" (see Section 5.4.3) identifying the field, and a 1420 "field line value" that conveys data for the field. 1422 Each field name present in a section has a corresponding "field 1423 value" for that section, composed from all field line values with 1424 that given field name in that section, concatenated together and 1425 separated with commas. See Section 5.4.1 for further discussion of 1426 the semantics of field ordering and combination in messages, and 1427 Section 5.4.4 for more discussion of field values. 1429 For example, this section: 1431 Example-Field: Foo, Bar 1432 Example-Field: Baz 1434 contains two field lines, both with the field name "Example-Field". 1435 The first field line has a field line value of "Foo, Bar", while the 1436 second field line value is "Baz". The field value for "Example- 1437 Field" is a list with three members: "Foo", "Bar", and "Baz". 1439 The interpretation of a field does not change between minor versions 1440 of the same major HTTP version, though the default behavior of a 1441 recipient in the absence of such a field can change. Unless 1442 specified otherwise, fields are defined for all versions of HTTP. In 1443 particular, the Host and Connection fields ought to be implemented by 1444 all HTTP/1.x implementations whether or not they advertise 1445 conformance with HTTP/1.1. 1447 New fields can be introduced without changing the protocol version if 1448 their defined semantics allow them to be safely ignored by recipients 1449 that do not recognize them; see Section 15.3. 1451 A proxy MUST forward unrecognized header fields unless the field name 1452 is listed in the Connection header field (Section 6.4.1) or the proxy 1453 is specifically configured to block, or otherwise transform, such 1454 fields. Other recipients SHOULD ignore unrecognized header and 1455 trailer fields. These requirements allow HTTP's functionality to be 1456 enhanced without requiring prior update of deployed intermediaries. 1458 5.4.1. Field Ordering and Combination 1460 The order in which field lines with differing names are received in a 1461 message is not significant. However, it is good practice to send 1462 header fields that contain control data first, such as Host on 1463 requests and Date on responses, so that implementations can decide 1464 when not to handle a message as early as possible. A server MUST NOT 1465 apply a request to the target resource until the entire request 1466 header section is received, since later header field lines might 1467 include conditionals, authentication credentials, or deliberately 1468 misleading duplicate header fields that would impact request 1469 processing. 1471 A recipient MAY combine multiple field lines with the same field name 1472 into one field line, without changing the semantics of the message, 1473 by appending each subsequent field line value to the initial field 1474 line value in order, separated by a comma and OWS (optional 1475 whitespace). For consistency, use comma SP. 1477 The order in which field lines with the same name are received is 1478 therefore significant to the interpretation of the field value; a 1479 proxy MUST NOT change the order of these field line values when 1480 forwarding a message. 1482 This means that, aside from the well-known exception noted below, a 1483 sender MUST NOT generate multiple field lines with the same name in a 1484 message (whether in the headers or trailers), or append a field line 1485 when a field line of the same name already exists in the message, 1486 unless that field's definition allows multiple field line values to 1487 be recombined as a comma-separated list [i.e., at least one 1488 alternative of the field's definition allows a comma-separated list, 1489 such as an ABNF rule of #(values) defined in Section 5.7.1]. 1491 | *Note:* In practice, the "Set-Cookie" header field ([RFC6265]) 1492 | often appears in a response message across multiple field lines 1493 | and does not use the list syntax, violating the above 1494 | requirements on multiple field lines with the same field name. 1495 | Since it cannot be combined into a single field value, 1496 | recipients ought to handle "Set-Cookie" as a special case while 1497 | processing fields. (See Appendix A.2.3 of [Kri2001] for 1498 | details.) 1500 5.4.2. Field Limits 1502 HTTP does not place a predefined limit on the length of each field 1503 line, field value, or on the length of a header or trailer section as 1504 a whole, as described in Section 2. Various ad hoc limitations on 1505 individual lengths are found in practice, often depending on the 1506 specific field's semantics. 1508 A server that receives a request header field line, field value, or 1509 set of fields larger than it wishes to process MUST respond with an 1510 appropriate 4xx (Client Error) status code. Ignoring such header 1511 fields would increase the server's vulnerability to request smuggling 1512 attacks (Section 11.2 of [Messaging]). 1514 A client MAY discard or truncate received field lines that are larger 1515 than the client wishes to process if the field semantics are such 1516 that the dropped value(s) can be safely ignored without changing the 1517 message framing or response semantics. 1519 5.4.3. Field Names 1521 The field-name token labels the corresponding field value as having 1522 the semantics defined by that field. For example, the Date header 1523 field is defined in Section 9.2.2 as containing the origination 1524 timestamp for the message in which it appears. 1526 field-name = token 1528 Field names are case-insensitive and ought to be registered within 1529 the "Hypertext Transfer Protocol (HTTP) Field Name Registry"; see 1530 Section 15.3.1. 1532 5.4.4. Field Values 1534 HTTP field values typically have their syntax defined using ABNF 1535 ([RFC5234]), using the extension defined in Section 5.7.1 as 1536 necessary, and are usually constrained to the range of US-ASCII 1537 characters. Fields needing a greater range of characters can use an 1538 encoding such as the one defined in [RFC8187]. 1540 field-value = *field-content 1541 field-content = field-vchar 1542 [ 1*( SP / HTAB / field-vchar ) field-vchar ] 1543 field-vchar = VCHAR / obs-text 1545 Historically, HTTP allowed field content with text in the ISO-8859-1 1546 charset [ISO-8859-1], supporting other charsets only through use of 1547 [RFC2047] encoding. In practice, most HTTP field values use only a 1548 subset of the US-ASCII charset [USASCII]. Newly defined fields 1549 SHOULD limit their values to US-ASCII octets. A recipient SHOULD 1550 treat other octets in field content (obs-text) as opaque data. 1552 Field values containing control (CTL) characters such as CR or LF are 1553 invalid; recipients MUST either reject a field value containing 1554 control characters, or convert them to SP before processing or 1555 forwarding the message. 1557 Leading and trailing whitespace in raw field values is removed upon 1558 field parsing (e.g., Section 5.1 of [Messaging]). Field definitions 1559 where leading or trailing whitespace in values is significant will 1560 have to use a container syntax such as quoted-string (Section 5.7.4). 1562 Commas (",") often are used to separate members in field values. 1563 Fields that allow multiple members are referred to as list-based 1564 fields. Fields that only anticipate a single member are referred to 1565 as singleton fields. 1567 Because commas are used as a generic delimiter between members, they 1568 need to be treated with care if they are allowed as data within a 1569 member. This is true for both list-based and singleton fields, since 1570 a singleton field might be sent with multiple members erroneously; 1571 being able to detect this condition improves interoperability. 1572 Fields that expect to contain a comma within a member, such as an 1573 HTTP-date or URI-reference element, ought to be defined with 1574 delimiters around that element to distinguish any comma within that 1575 data from potential list separators. 1577 For example, a textual date and a URI (either of which might contain 1578 a comma) could be safely carried in list-based field values like 1579 these: 1581 Example-URI-Field: "http://example.com/a.html,foo", 1582 "http://without-a-comma.example.com/" 1583 Example-Date-Field: "Sat, 04 May 1996", "Wed, 14 Sep 2005" 1585 Note that double-quote delimiters almost always are used with the 1586 quoted-string production; using a different syntax inside double- 1587 quotes will likely cause unnecessary confusion. 1589 Many fields (such as Content-Type, defined in Section 7.4) use a 1590 common syntax for parameters that allows both unquoted (token) and 1591 quoted (quoted-string) syntax for a parameter value (Section 5.7.6). 1592 Use of common syntax allows recipients to reuse existing parser 1593 components. When allowing both forms, the meaning of a parameter 1594 value ought to be the same whether it was received as a token or a 1595 quoted string. 1597 Historically, HTTP field values could be extended over multiple lines 1598 by preceding each extra line with at least one space or horizontal 1599 tab (obs-fold). This document assumes that any such obsolete line 1600 folding has been replaced with one or more SP octets prior to 1601 interpreting the field value, as described in Section 5.2 of 1602 [Messaging]. 1604 | *Note:* This specification does not use ABNF rules to define 1605 | each "Field Name: Field Value" pair, as was done in earlier 1606 | editions (published before [RFC7230]). Instead, ABNF rules are 1607 | named according to each registered field name, wherein the rule 1608 | defines the valid grammar for that field's corresponding field 1609 | values (i.e., after the field value has been extracted by a 1610 | generic field parser). 1612 5.5. Payload 1614 Some HTTP messages transfer a complete or partial representation as 1615 the message "payload". In some cases, a payload might contain only 1616 the associated representation's header fields (e.g., responses to 1617 HEAD) or only some part(s) of the representation data (e.g., the 206 1618 (Partial Content) status code). 1620 5.5.1. Purpose 1622 The purpose of a payload in a request is defined by the method 1623 semantics. For example, a representation in the payload of a PUT 1624 request (Section 8.3.4) represents the desired state of the target 1625 resource if the request is successfully applied, whereas a 1626 representation in the payload of a POST request (Section 8.3.3) 1627 represents information to be processed by the target resource. 1629 In a response, the payload's purpose is defined by both the request 1630 method and the response status code. For example, the payload of a 1631 200 (OK) response to GET (Section 8.3.1) represents the current state 1632 of the target resource, as observed at the time of the message 1633 origination date (Section 9.2.2), whereas the payload of the same 1634 status code in a response to POST might represent either the 1635 processing result or the new state of the target resource after 1636 applying the processing. Response messages with an error status code 1637 usually contain a payload that represents the error condition, such 1638 that it describes the error state and what next steps are suggested 1639 for resolving it. 1641 5.5.2. Identification 1643 When a complete or partial representation is transferred in a message 1644 payload, it is often desirable for the sender to supply, or the 1645 recipient to determine, an identifier for a resource corresponding to 1646 that representation. 1648 For a request message: 1650 o If the request has a Content-Location header field, then the 1651 sender asserts that the payload is a representation of the 1652 resource identified by the Content-Location field value. However, 1653 such an assertion cannot be trusted unless it can be verified by 1654 other means (not defined by this specification). The information 1655 might still be useful for revision history links. 1657 o Otherwise, the payload is unidentified. 1659 For a response message, the following rules are applied in order 1660 until a match is found: 1662 1. If the request method is GET or HEAD and the response status code 1663 is 200 (OK), 204 (No Content), 206 (Partial Content), or 304 (Not 1664 Modified), the payload is a representation of the resource 1665 identified by the target URI (Section 6.1). 1667 2. If the request method is GET or HEAD and the response status code 1668 is 203 (Non-Authoritative Information), the payload is a 1669 potentially modified or enhanced representation of the target 1670 resource as provided by an intermediary. 1672 3. If the response has a Content-Location header field and its field 1673 value is a reference to the same URI as the target URI, the 1674 payload is a representation of the target resource. 1676 4. If the response has a Content-Location header field and its field 1677 value is a reference to a URI different from the target URI, then 1678 the sender asserts that the payload is a representation of the 1679 resource identified by the Content-Location field value. 1680 However, such an assertion cannot be trusted unless it can be 1681 verified by other means (not defined by this specification). 1683 5. Otherwise, the payload is unidentified. 1685 5.5.3. Payload Metadata 1687 Header fields that specifically describe the payload, rather than the 1688 associated representation, are referred to as "payload header 1689 fields". Payload header fields are defined in other parts of this 1690 specification, due to their impact on message parsing. 1692 5.5.4. Payload Body 1694 The payload body contains the data of a request or response. This is 1695 distinct from the message body (e.g., Section 6 of [Messaging]), 1696 which is how the payload body is transferred "on the wire", and might 1697 be encoded, depending on the HTTP version in use. 1699 It is also distinct from a request or response's representation data 1700 (Section 7.2), which can be inferred from protocol operation, rather 1701 than necessarily appearing "on the wire." 1703 The presence of a payload body in a request depends on whether the 1704 request method used defines semantics for it. 1706 The presence of a payload body in a response depends on both the 1707 request method to which it is responding and the response status code 1708 (Section 14). 1710 Responses to the HEAD request method (Section 8.3.2) never include a 1711 payload body because the associated response header fields indicate 1712 only what their values would have been if the request method had been 1713 GET (Section 8.3.1). 1715 2xx (Successful) responses to a CONNECT request method 1716 (Section 8.3.6) switch the connection to tunnel mode instead of 1717 having a payload body. 1719 All 1xx (Informational), 204 (No Content), and 304 (Not Modified) 1720 responses do not include a payload body. 1722 All other responses do include a payload body, although that body 1723 might be of zero length. 1725 5.6. Trailer Fields 1726 5.6.1. Purpose 1728 In some HTTP versions, additional metadata can be sent after the 1729 initial header section has been completed (during or after 1730 transmission of the payload body), such as a message integrity check, 1731 digital signature, or post-processing status. For example, the 1732 chunked coding in HTTP/1.1 allows a trailer section after the payload 1733 body (Section 7.1.2 of [Messaging]) which can contain trailer fields: 1734 field names and values that share the same syntax and namespace as 1735 header fields but that are received after the header section. 1737 Trailer fields ought to be processed and stored separately from the 1738 fields in the header section to avoid contradicting message semantics 1739 known at the time the header section was complete. The presence or 1740 absence of certain header fields might impact choices made for the 1741 routing or processing of the message as a whole before the trailers 1742 are received; those choices cannot be unmade by the later discovery 1743 of trailer fields. 1745 5.6.2. Limitations 1747 Many fields cannot be processed outside the header section because 1748 their evaluation is necessary prior to receiving the message body, 1749 such as those that describe message framing, routing, authentication, 1750 request modifiers, response controls, or payload format. A sender 1751 MUST NOT generate a trailer field unless the sender knows the 1752 corresponding header field name's definition permits the field to be 1753 sent in trailers. 1755 Trailer fields can be difficult to process by intermediaries that 1756 forward messages from one protocol version to another. If the entire 1757 message can be buffered in transit, some intermediaries could merge 1758 trailer fields into the header section (as appropriate) before it is 1759 forwarded. However, in most cases, the trailers are simply 1760 discarded. A recipient MUST NOT merge a trailer field into a header 1761 section unless the recipient understands the corresponding header 1762 field definition and that definition explicitly permits and defines 1763 how trailer field values can be safely merged. 1765 The presence of the keyword "trailers" in the TE header field 1766 (Section 9.1.4) indicates that the client is willing to accept 1767 trailer fields, on behalf of itself and any downstream clients. For 1768 requests from an intermediary, this implies that all downstream 1769 clients are willing to accept trailer fields in the forwarded 1770 response. Note that the presence of "trailers" does not mean that 1771 the client(s) will process any particular trailer field in the 1772 response; only that the trailer section(s) will not be dropped by any 1773 of the clients. 1775 Because of the potential for trailer fields to be discarded in 1776 transit, a server SHOULD NOT generate trailer fields that it believes 1777 are necessary for the user agent to receive. 1779 5.6.3. Processing 1781 Like header fields, trailer fields with the same name are processed 1782 in the order received; multiple trailer field lines with the same 1783 name have the equivalent semantics as appending the multiple values 1784 as a list of members, even when the field lines are received in 1785 separate trailer sections. Trailer fields that might be generated 1786 more than once during a message MUST be defined as a list value even 1787 if each member value is only processed once per field line received. 1789 Trailer fields are expected (but not required) to be processed one 1790 trailer section at a time. That is, for each trailer section 1791 received, a recipient that is looking for trailer fields will parse 1792 the received section into fields, invoke any associated processing 1793 for those fields at that point in the message processing, and then 1794 append those fields to the set of trailer fields received for the 1795 overall message. 1797 This behavior allows for iterative processing of trailer fields that 1798 contain incremental signatures or mid-stream status information, and 1799 fields that might refer to each other's values within the same 1800 section. However, there is no guarantee that trailer sections won't 1801 shift in relation to the message body stream, or won't be recombined 1802 (or dropped) in transit, so trailer fields that refer to data outside 1803 the present trailer section need to use self-descriptive references 1804 (i.e., refer to the data by name, ordinal position, or an octet 1805 range) rather than assume it is the data most recently received. 1807 Likewise, at the end of a message, a recipient MAY treat the entire 1808 set of received trailer fields as one data structure to be considered 1809 as the message concludes. Additional processing expectations, if 1810 any, can be defined within the field specification for a field 1811 intended for use in trailers. 1813 5.7. Common Rules for Defining Field Values 1815 5.7.1. Lists (#rule ABNF Extension) 1817 A #rule extension to the ABNF rules of [RFC5234] is used to improve 1818 readability in the definitions of some list-based field values. 1820 A construct "#" is defined, similar to "*", for defining comma- 1821 delimited lists of elements. The full form is "#element" 1822 indicating at least and at most elements, each separated by a 1823 single comma (",") and optional whitespace (OWS). 1825 5.7.1.1. Sender Requirements 1827 In any production that uses the list construct, a sender MUST NOT 1828 generate empty list elements. In other words, a sender MUST generate 1829 lists that satisfy the following syntax: 1831 1#element => element *( OWS "," OWS element ) 1833 and: 1835 #element => [ 1#element ] 1837 and for n >= 1 and m > 1: 1839 #element => element *( OWS "," OWS element ) 1841 Appendix A shows the collected ABNF for senders after the list 1842 constructs have been expanded. 1844 5.7.1.2. Recipient Requirements 1846 Empty elements do not contribute to the count of elements present. A 1847 recipient MUST parse and ignore a reasonable number of empty list 1848 elements: enough to handle common mistakes by senders that merge 1849 values, but not so much that they could be used as a denial-of- 1850 service mechanism. In other words, a recipient MUST accept lists 1851 that satisfy the following syntax: 1853 #element => [ element ] *( OWS "," OWS [ element ] ) 1855 Note that because of the potential presence of empty list elements, 1856 the RFC 5234 ABNF cannot enforce the cardinality of list elements, 1857 and consequently all cases are mapped as if there was no cardinality 1858 specified. 1860 For example, given these ABNF productions: 1862 example-list = 1#example-list-elmt 1863 example-list-elmt = token ; see Section 5.7.2 1865 Then the following are valid values for example-list (not including 1866 the double quotes, which are present for delimitation only): 1868 "foo,bar" 1869 "foo ,bar," 1870 "foo , ,bar,charlie" 1872 In contrast, the following values would be invalid, since at least 1873 one non-empty element is required by the example-list production: 1875 "" 1876 "," 1877 ", ," 1879 5.7.2. Tokens 1881 Many HTTP field values are defined using common syntax components, 1882 separated by whitespace or specific delimiting characters. 1883 Delimiters are chosen from the set of US-ASCII visual characters not 1884 allowed in a token (DQUOTE and "(),/:;<=>?@[\]{}"). 1886 Tokens are short textual identifiers that do not include whitespace 1887 or delimiters. 1889 token = 1*tchar 1891 tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" 1892 / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" 1893 / DIGIT / ALPHA 1894 ; any VCHAR, except delimiters 1896 5.7.3. Whitespace 1898 This specification uses three rules to denote the use of linear 1899 whitespace: OWS (optional whitespace), RWS (required whitespace), and 1900 BWS ("bad" whitespace). 1902 The OWS rule is used where zero or more linear whitespace octets 1903 might appear. For protocol elements where optional whitespace is 1904 preferred to improve readability, a sender SHOULD generate the 1905 optional whitespace as a single SP; otherwise, a sender SHOULD NOT 1906 generate optional whitespace except as needed to white out invalid or 1907 unwanted protocol elements during in-place message filtering. 1909 The RWS rule is used when at least one linear whitespace octet is 1910 required to separate field tokens. A sender SHOULD generate RWS as a 1911 single SP. 1913 OWS and RWS have the same semantics as a single SP. Any content 1914 known to be defined as OWS or RWS MAY be replaced with a single SP 1915 before interpreting it or forwarding the message downstream. 1917 The BWS rule is used where the grammar allows optional whitespace 1918 only for historical reasons. A sender MUST NOT generate BWS in 1919 messages. A recipient MUST parse for such bad whitespace and remove 1920 it before interpreting the protocol element. 1922 BWS has no semantics. Any content known to be defined as BWS MAY be 1923 removed before interpreting it or forwarding the message downstream. 1925 OWS = *( SP / HTAB ) 1926 ; optional whitespace 1927 RWS = 1*( SP / HTAB ) 1928 ; required whitespace 1929 BWS = OWS 1930 ; "bad" whitespace 1932 5.7.4. Quoted Strings 1934 A string of text is parsed as a single value if it is quoted using 1935 double-quote marks. 1937 quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE 1938 qdtext = HTAB / SP / %x21 / %x23-5B / %x5D-7E / obs-text 1939 obs-text = %x80-FF 1941 The backslash octet ("\") can be used as a single-octet quoting 1942 mechanism within quoted-string and comment constructs. Recipients 1943 that process the value of a quoted-string MUST handle a quoted-pair 1944 as if it were replaced by the octet following the backslash. 1946 quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text ) 1948 A sender SHOULD NOT generate a quoted-pair in a quoted-string except 1949 where necessary to quote DQUOTE and backslash octets occurring within 1950 that string. A sender SHOULD NOT generate a quoted-pair in a comment 1951 except where necessary to quote parentheses ["(" and ")"] and 1952 backslash octets occurring within that comment. 1954 5.7.5. Comments 1956 Comments can be included in some HTTP fields by surrounding the 1957 comment text with parentheses. Comments are only allowed in fields 1958 containing "comment" as part of their field value definition. 1960 comment = "(" *( ctext / quoted-pair / comment ) ")" 1961 ctext = HTAB / SP / %x21-27 / %x2A-5B / %x5D-7E / obs-text 1963 5.7.6. Parameters 1965 Parameters are zero or more instances of a name=value pair; they are 1966 often used in field values as a common syntax for appending auxiliary 1967 information to an item. Each parameter is usually delimited by an 1968 immediately preceding semicolon. 1970 parameters = *( OWS ";" OWS [ parameter ] ) 1971 parameter = parameter-name "=" parameter-value 1972 parameter-name = token 1973 parameter-value = ( token / quoted-string ) 1975 Parameter names are case-insensitive. Parameter values might or 1976 might not be case-sensitive, depending on the semantics of the 1977 parameter name. Examples of parameters and some equivalent forms can 1978 be seen in media types (Section 7.4.1) and the Accept header field 1979 (Section 11.1.2). 1981 A parameter value that matches the token production can be 1982 transmitted either as a token or within a quoted-string. The quoted 1983 and unquoted values are equivalent. 1985 | *Note:* Parameters do not allow whitespace (not even "bad" 1986 | whitespace) around the "=" character. 1988 5.7.7. Date/Time Formats 1990 Prior to 1995, there were three different formats commonly used by 1991 servers to communicate timestamps. For compatibility with old 1992 implementations, all three are defined here. The preferred format is 1993 a fixed-length and single-zone subset of the date and time 1994 specification used by the Internet Message Format [RFC5322]. 1996 HTTP-date = IMF-fixdate / obs-date 1998 An example of the preferred format is 2000 Sun, 06 Nov 1994 08:49:37 GMT ; IMF-fixdate 2002 Examples of the two obsolete formats are 2004 Sunday, 06-Nov-94 08:49:37 GMT ; obsolete RFC 850 format 2005 Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format 2007 A recipient that parses a timestamp value in an HTTP field MUST 2008 accept all three HTTP-date formats. When a sender generates a field 2009 that contains one or more timestamps defined as HTTP-date, the sender 2010 MUST generate those timestamps in the IMF-fixdate format. 2012 An HTTP-date value represents time as an instance of Coordinated 2013 Universal Time (UTC). The first two formats indicate UTC by the 2014 three-letter abbreviation for Greenwich Mean Time, "GMT", a 2015 predecessor of the UTC name; values in the asctime format are assumed 2016 to be in UTC. A sender that generates HTTP-date values from a local 2017 clock ought to use NTP ([RFC5905]) or some similar protocol to 2018 synchronize its clock to UTC. 2020 Preferred format: 2022 IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT 2023 ; fixed length/zone/capitalization subset of the format 2024 ; see Section 3.3 of [RFC5322] 2026 day-name = %s"Mon" / %s"Tue" / %s"Wed" 2027 / %s"Thu" / %s"Fri" / %s"Sat" / %s"Sun" 2029 date1 = day SP month SP year 2030 ; e.g., 02 Jun 1982 2032 day = 2DIGIT 2033 month = %s"Jan" / %s"Feb" / %s"Mar" / %s"Apr" 2034 / %s"May" / %s"Jun" / %s"Jul" / %s"Aug" 2035 / %s"Sep" / %s"Oct" / %s"Nov" / %s"Dec" 2036 year = 4DIGIT 2038 GMT = %s"GMT" 2040 time-of-day = hour ":" minute ":" second 2041 ; 00:00:00 - 23:59:60 (leap second) 2043 hour = 2DIGIT 2044 minute = 2DIGIT 2045 second = 2DIGIT 2047 Obsolete formats: 2049 obs-date = rfc850-date / asctime-date 2051 rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT 2052 date2 = day "-" month "-" 2DIGIT 2053 ; e.g., 02-Jun-82 2055 day-name-l = %s"Monday" / %s"Tuesday" / %s"Wednesday" 2056 / %s"Thursday" / %s"Friday" / %s"Saturday" 2057 / %s"Sunday" 2059 asctime-date = day-name SP date3 SP time-of-day SP year 2060 date3 = month SP ( 2DIGIT / ( SP 1DIGIT )) 2061 ; e.g., Jun 2 2063 HTTP-date is case sensitive. A sender MUST NOT generate additional 2064 whitespace in an HTTP-date beyond that specifically included as SP in 2065 the grammar. The semantics of day-name, day, month, year, and 2066 time-of-day are the same as those defined for the Internet Message 2067 Format constructs with the corresponding name ([RFC5322], 2068 Section 3.3). 2070 Recipients of a timestamp value in rfc850-date format, which uses a 2071 two-digit year, MUST interpret a timestamp that appears to be more 2072 than 50 years in the future as representing the most recent year in 2073 the past that had the same last two digits. 2075 Recipients of timestamp values are encouraged to be robust in parsing 2076 timestamps unless otherwise restricted by the field definition. For 2077 example, messages are occasionally forwarded over HTTP from a non- 2078 HTTP source that might generate any of the date and time 2079 specifications defined by the Internet Message Format. 2081 | *Note:* HTTP requirements for the date/time stamp format apply 2082 | only to their usage within the protocol stream. 2083 | Implementations are not required to use these formats for user 2084 | presentation, request logging, etc. 2086 6. Routing 2088 HTTP is used in a wide variety of applications, ranging from general- 2089 purpose computers to home appliances. In some cases, communication 2090 options are hard-coded in a client's configuration. However, most 2091 HTTP clients rely on the same resource identification mechanism and 2092 configuration techniques as general-purpose Web browsers. 2094 HTTP request message routing is determined by each client based on 2095 the target resource, the client's proxy configuration, and 2096 establishment or reuse of an inbound connection. The corresponding 2097 response routing follows the same connection chain back to the 2098 client. 2100 6.1. Target Resource 2102 6.1.1. Request Target 2104 The "request target" is the protocol element that identifies the 2105 "target resource". 2107 Typically, the request target is a URI reference (Section 4) which a 2108 user agent would resolve to its absolute form in order to obtain the 2109 "target URI". The target URI excludes the reference's fragment 2110 component, if any, since fragment identifiers are reserved for 2111 client-side processing ([RFC3986], Section 3.5). 2113 However, there are two special, method-specific forms allowed for the 2114 request target in specific circumstances: 2116 o For CONNECT (Section 8.3.6), the request target is the host name 2117 and port number of the tunnel destination, separated by a colon. 2119 o For OPTIONS (Section 8.3.7), the request target can be a single 2120 asterisk ("*"). 2122 See the respective method definitions for details. These forms MUST 2123 NOT be used with other methods. 2125 6.1.2. Host 2127 The "Host" header field in a request provides the host and port 2128 information from the target URI, enabling the origin server to 2129 distinguish among resources while servicing requests for multiple 2130 host names on a single IP address. 2132 Host = uri-host [ ":" port ] ; Section 4 2134 Since the Host field value is critical information for handling a 2135 request, a user agent SHOULD generate Host as the first field in the 2136 header section. 2138 For example, a GET request to the origin server for 2139 would begin with: 2141 GET /pub/WWW/ HTTP/1.1 2142 Host: www.example.org 2144 Since the Host header field acts as an application-level routing 2145 mechanism, it is a frequent target for malware seeking to poison a 2146 shared cache or redirect a request to an unintended server. An 2147 interception proxy is particularly vulnerable if it relies on the 2148 Host field value for redirecting requests to internal servers, or for 2149 use as a cache key in a shared cache, without first verifying that 2150 the intercepted connection is targeting a valid IP address for that 2151 host. 2153 6.1.3. Reconstructing the Target URI 2155 Once an inbound connection is obtained, the client sends an HTTP 2156 request message. 2158 Depending on the nature of the request, the client's target URI might 2159 be split into components and transmitted (or implied) within various 2160 parts of a request message. These parts are recombined by each 2161 recipient, in accordance with their local configuration and incoming 2162 connection context, to determine the target URI. Appendix of 2163 [Messaging] defines how a server determines the target URI for an 2164 HTTP/1.1 request. 2166 Once the target URI has been reconstructed, an origin server needs to 2167 decide whether or not to provide service for that URI via the 2168 connection in which the request was received. For example, the 2169 request might have been misdirected, deliberately or accidentally, 2170 such that the information within a received Host header field differs 2171 from the host or port upon which the connection has been made. If 2172 the connection is from a trusted gateway, that inconsistency might be 2173 expected; otherwise, it might indicate an attempt to bypass security 2174 filters, trick the server into delivering non-public content, or 2175 poison a cache. See Section 16 for security considerations regarding 2176 message routing. 2178 | *Note:* previous specifications defined the recomposed target 2179 | URI as a distinct concept, the effective request URI. 2181 6.2. Routing Inbound 2183 Once the target URI and its origin are determined, a client decides 2184 whether a network request is necessary to accomplish the desired 2185 semantics and, if so, where that request is to be directed. 2187 6.2.1. To a Cache 2189 If the client has a cache [Caching] and the request can be satisfied 2190 by it, then the request is usually directed there first. 2192 6.2.2. To a Proxy 2194 If the request is not satisfied by a cache, then a typical client 2195 will check its configuration to determine whether a proxy is to be 2196 used to satisfy the request. Proxy configuration is implementation- 2197 dependent, but is often based on URI prefix matching, selective 2198 authority matching, or both, and the proxy itself is usually 2199 identified by an "http" or "https" URI. If a proxy is applicable, 2200 the client connects inbound by establishing (or reusing) a connection 2201 to that proxy. 2203 6.2.3. To the Origin 2205 If no proxy is applicable, a typical client will invoke a handler 2206 routine, usually specific to the target URI's scheme, to connect 2207 directly to an origin for the target resource. How that is 2208 accomplished is dependent on the target URI scheme and defined by its 2209 associated specification. 2211 6.3. Response Correlation 2213 A connection might be used for multiple request/response exchanges. 2214 The mechanism used to correlate between request and response messages 2215 is version dependent; some versions of HTTP use implicit ordering of 2216 messages, while others use an explicit identifier. 2218 Responses (both final and interim) can be sent at any time after a 2219 request is received, even if it is not yet complete. However, 2220 clients (including intermediaries) might abandon a request if the 2221 response is not forthcoming within a reasonable period of time. 2223 6.4. Message Forwarding 2225 As described in Section 3.7, intermediaries can serve a variety of 2226 roles in the processing of HTTP requests and responses. Some 2227 intermediaries are used to improve performance or availability. 2228 Others are used for access control or to filter content. Since an 2229 HTTP stream has characteristics similar to a pipe-and-filter 2230 architecture, there are no inherent limits to the extent an 2231 intermediary can enhance (or interfere) with either direction of the 2232 stream. 2234 An intermediary not acting as a tunnel MUST implement the Connection 2235 header field, as specified in Section 6.4.1, and exclude fields from 2236 being forwarded that are only intended for the incoming connection. 2238 An intermediary MUST NOT forward a message to itself unless it is 2239 protected from an infinite request loop. In general, an intermediary 2240 ought to recognize its own server names, including any aliases, local 2241 variations, or literal IP addresses, and respond to such requests 2242 directly. 2244 An HTTP message can be parsed as a stream for incremental processing 2245 or forwarding downstream. However, recipients cannot rely on 2246 incremental delivery of partial messages, since some implementations 2247 will buffer or delay message forwarding for the sake of network 2248 efficiency, security checks, or payload transformations. 2250 6.4.1. Connection 2252 The "Connection" header field allows the sender to list desired 2253 control options for the current connection. 2255 When a field aside from Connection is used to supply control 2256 information for or about the current connection, the sender MUST list 2257 the corresponding field name within the Connection header field. 2258 Note that some versions of HTTP prohibit the use of fields for such 2259 information, and therefore do not allow the Connection field. 2261 Intermediaries MUST parse a received Connection header field before a 2262 message is forwarded and, for each connection-option in this field, 2263 remove any header or trailer field(s) from the message with the same 2264 name as the connection-option, and then remove the Connection header 2265 field itself (or replace it with the intermediary's own connection 2266 options for the forwarded message). 2268 Hence, the Connection header field provides a declarative way of 2269 distinguishing fields that are only intended for the immediate 2270 recipient ("hop-by-hop") from those fields that are intended for all 2271 recipients on the chain ("end-to-end"), enabling the message to be 2272 self-descriptive and allowing future connection-specific extensions 2273 to be deployed without fear that they will be blindly forwarded by 2274 older intermediaries. 2276 Furthermore, intermediaries SHOULD remove or replace field(s) whose 2277 semantics are known to require removal before forwarding, whether or 2278 not they appear as a Connection option, after applying those fields' 2279 semantics. This includes but is not limited to: 2281 o Proxy-Connection (Appendix C.1.2 of [Messaging]) 2283 o Keep-Alive (Section 19.7.1 of [RFC2068]) 2285 o TE (Section 9.1.4) 2286 o Trailer (Section 9.1.5) 2288 o Transfer-Encoding (Section 6.1 of [Messaging]) 2290 o Upgrade (Section 6.6) 2292 The Connection header field's value has the following grammar: 2294 Connection = #connection-option 2295 connection-option = token 2297 Connection options are case-insensitive. 2299 A sender MUST NOT send a connection option corresponding to a field 2300 that is intended for all recipients of the payload. For example, 2301 Cache-Control is never appropriate as a connection option 2302 (Section 5.2 of [Caching]). 2304 The connection options do not always correspond to a field present in 2305 the message, since a connection-specific field might not be needed if 2306 there are no parameters associated with a connection option. In 2307 contrast, a connection-specific field that is received without a 2308 corresponding connection option usually indicates that the field has 2309 been improperly forwarded by an intermediary and ought to be ignored 2310 by the recipient. 2312 When defining new connection options, specification authors ought to 2313 document it as reserved field name and register that definition in 2314 the Hypertext Transfer Protocol (HTTP) Field Name Registry 2315 (Section 15.3.1), to avoid collisions. 2317 6.4.2. Max-Forwards 2319 The "Max-Forwards" header field provides a mechanism with the TRACE 2320 (Section 8.3.8) and OPTIONS (Section 8.3.7) request methods to limit 2321 the number of times that the request is forwarded by proxies. This 2322 can be useful when the client is attempting to trace a request that 2323 appears to be failing or looping mid-chain. 2325 Max-Forwards = 1*DIGIT 2327 The Max-Forwards value is a decimal integer indicating the remaining 2328 number of times this request message can be forwarded. 2330 Each intermediary that receives a TRACE or OPTIONS request containing 2331 a Max-Forwards header field MUST check and update its value prior to 2332 forwarding the request. If the received value is zero (0), the 2333 intermediary MUST NOT forward the request; instead, the intermediary 2334 MUST respond as the final recipient. If the received Max-Forwards 2335 value is greater than zero, the intermediary MUST generate an updated 2336 Max-Forwards field in the forwarded message with a field value that 2337 is the lesser of a) the received value decremented by one (1) or b) 2338 the recipient's maximum supported value for Max-Forwards. 2340 A recipient MAY ignore a Max-Forwards header field received with any 2341 other request methods. 2343 6.4.3. Via 2345 The "Via" header field indicates the presence of intermediate 2346 protocols and recipients between the user agent and the server (on 2347 requests) or between the origin server and the client (on responses), 2348 similar to the "Received" header field in email (Section 3.6.7 of 2349 [RFC5322]). Via can be used for tracking message forwards, avoiding 2350 request loops, and identifying the protocol capabilities of senders 2351 along the request/response chain. 2353 Via = #( received-protocol RWS received-by [ RWS comment ] ) 2355 received-protocol = [ protocol-name "/" ] protocol-version 2356 ; see Section 6.6 2357 received-by = pseudonym [ ":" port ] 2358 pseudonym = token 2360 Each member of the Via field value represents a proxy or gateway that 2361 has forwarded the message. Each intermediary appends its own 2362 information about how the message was received, such that the end 2363 result is ordered according to the sequence of forwarding recipients. 2365 A proxy MUST send an appropriate Via header field, as described 2366 below, in each message that it forwards. An HTTP-to-HTTP gateway 2367 MUST send an appropriate Via header field in each inbound request 2368 message and MAY send a Via header field in forwarded response 2369 messages. 2371 For each intermediary, the received-protocol indicates the protocol 2372 and protocol version used by the upstream sender of the message. 2373 Hence, the Via field value records the advertised protocol 2374 capabilities of the request/response chain such that they remain 2375 visible to downstream recipients; this can be useful for determining 2376 what backwards-incompatible features might be safe to use in 2377 response, or within a later request, as described in Section 5.1. 2378 For brevity, the protocol-name is omitted when the received protocol 2379 is HTTP. 2381 The received-by portion is normally the host and optional port number 2382 of a recipient server or client that subsequently forwarded the 2383 message. However, if the real host is considered to be sensitive 2384 information, a sender MAY replace it with a pseudonym. If a port is 2385 not provided, a recipient MAY interpret that as meaning it was 2386 received on the default TCP port, if any, for the received-protocol. 2388 A sender MAY generate comments to identify the software of each 2389 recipient, analogous to the User-Agent and Server header fields. 2390 However, comments in Via are optional, and a recipient MAY remove 2391 them prior to forwarding the message. 2393 For example, a request message could be sent from an HTTP/1.0 user 2394 agent to an internal proxy code-named "fred", which uses HTTP/1.1 to 2395 forward the request to a public proxy at p.example.net, which 2396 completes the request by forwarding it to the origin server at 2397 www.example.com. The request received by www.example.com would then 2398 have the following Via header field: 2400 Via: 1.0 fred, 1.1 p.example.net 2402 An intermediary used as a portal through a network firewall SHOULD 2403 NOT forward the names and ports of hosts within the firewall region 2404 unless it is explicitly enabled to do so. If not enabled, such an 2405 intermediary SHOULD replace each received-by host of any host behind 2406 the firewall by an appropriate pseudonym for that host. 2408 An intermediary MAY combine an ordered subsequence of Via header 2409 field list members into a single member if the entries have identical 2410 received-protocol values. For example, 2412 Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy 2414 could be collapsed to 2416 Via: 1.0 ricky, 1.1 mertz, 1.0 lucy 2418 A sender SHOULD NOT combine multiple list members unless they are all 2419 under the same organizational control and the hosts have already been 2420 replaced by pseudonyms. A sender MUST NOT combine members that have 2421 different received-protocol values. 2423 6.5. Transformations 2425 Some intermediaries include features for transforming messages and 2426 their payloads. A proxy might, for example, convert between image 2427 formats in order to save cache space or to reduce the amount of 2428 traffic on a slow link. However, operational problems might occur 2429 when these transformations are applied to payloads intended for 2430 critical applications, such as medical imaging or scientific data 2431 analysis, particularly when integrity checks or digital signatures 2432 are used to ensure that the payload received is identical to the 2433 original. 2435 An HTTP-to-HTTP proxy is called a "transforming proxy" if it is 2436 designed or configured to modify messages in a semantically 2437 meaningful way (i.e., modifications, beyond those required by normal 2438 HTTP processing, that change the message in a way that would be 2439 significant to the original sender or potentially significant to 2440 downstream recipients). For example, a transforming proxy might be 2441 acting as a shared annotation server (modifying responses to include 2442 references to a local annotation database), a malware filter, a 2443 format transcoder, or a privacy filter. Such transformations are 2444 presumed to be desired by whichever client (or client organization) 2445 chose the proxy. 2447 If a proxy receives a target URI with a host name that is not a fully 2448 qualified domain name, it MAY add its own domain to the host name it 2449 received when forwarding the request. A proxy MUST NOT change the 2450 host name if the target URI contains a fully qualified domain name. 2452 A proxy MUST NOT modify the "absolute-path" and "query" parts of the 2453 received target URI when forwarding it to the next inbound server, 2454 except as noted above to replace an empty path with "/" or "*". 2456 A proxy MUST NOT transform the payload (Section 5.5) of a message 2457 that contains a no-transform cache-control response directive 2458 (Section 5.2 of [Caching]). Note that this does not include changes 2459 to the message body that do not affect the payload, such as transfer 2460 codings (Section 7 of [Messaging]). 2462 A proxy MAY transform the payload of a message that does not contain 2463 a no-transform cache-control directive. A proxy that transforms the 2464 payload of a 200 (OK) response can inform downstream recipients that 2465 a transformation has been applied by changing the response status 2466 code to 203 (Non-Authoritative Information) (Section 14.3.4). 2468 A proxy SHOULD NOT modify header fields that provide information 2469 about the endpoints of the communication chain, the resource state, 2470 or the selected representation (other than the payload) unless the 2471 field's definition specifically allows such modification or the 2472 modification is deemed necessary for privacy or security. 2474 6.6. Upgrade 2476 The "Upgrade" header field is intended to provide a simple mechanism 2477 for transitioning from HTTP/1.1 to some other protocol on the same 2478 connection. 2480 A client MAY send a list of protocol names in the Upgrade header 2481 field of a request to invite the server to switch to one or more of 2482 the named protocols, in order of descending preference, before 2483 sending the final response. A server MAY ignore a received Upgrade 2484 header field if it wishes to continue using the current protocol on 2485 that connection. Upgrade cannot be used to insist on a protocol 2486 change. 2488 Upgrade = #protocol 2490 protocol = protocol-name ["/" protocol-version] 2491 protocol-name = token 2492 protocol-version = token 2494 Although protocol names are registered with a preferred case, 2495 recipients SHOULD use case-insensitive comparison when matching each 2496 protocol-name to supported protocols. 2498 A server that sends a 101 (Switching Protocols) response MUST send an 2499 Upgrade header field to indicate the new protocol(s) to which the 2500 connection is being switched; if multiple protocol layers are being 2501 switched, the sender MUST list the protocols in layer-ascending 2502 order. A server MUST NOT switch to a protocol that was not indicated 2503 by the client in the corresponding request's Upgrade header field. A 2504 server MAY choose to ignore the order of preference indicated by the 2505 client and select the new protocol(s) based on other factors, such as 2506 the nature of the request or the current load on the server. 2508 A server that sends a 426 (Upgrade Required) response MUST send an 2509 Upgrade header field to indicate the acceptable protocols, in order 2510 of descending preference. 2512 A server MAY send an Upgrade header field in any other response to 2513 advertise that it implements support for upgrading to the listed 2514 protocols, in order of descending preference, when appropriate for a 2515 future request. 2517 The following is a hypothetical example sent by a client: 2519 GET /hello HTTP/1.1 2520 Host: www.example.com 2521 Connection: upgrade 2522 Upgrade: websocket, IRC/6.9, RTA/x11 2524 The capabilities and nature of the application-level communication 2525 after the protocol change is entirely dependent upon the new 2526 protocol(s) chosen. However, immediately after sending the 101 2527 (Switching Protocols) response, the server is expected to continue 2528 responding to the original request as if it had received its 2529 equivalent within the new protocol (i.e., the server still has an 2530 outstanding request to satisfy after the protocol has been changed, 2531 and is expected to do so without requiring the request to be 2532 repeated). 2534 For example, if the Upgrade header field is received in a GET request 2535 and the server decides to switch protocols, it first responds with a 2536 101 (Switching Protocols) message in HTTP/1.1 and then immediately 2537 follows that with the new protocol's equivalent of a response to a 2538 GET on the target resource. This allows a connection to be upgraded 2539 to protocols with the same semantics as HTTP without the latency cost 2540 of an additional round trip. A server MUST NOT switch protocols 2541 unless the received message semantics can be honored by the new 2542 protocol; an OPTIONS request can be honored by any protocol. 2544 The following is an example response to the above hypothetical 2545 request: 2547 HTTP/1.1 101 Switching Protocols 2548 Connection: upgrade 2549 Upgrade: websocket 2551 [... data stream switches to websocket with an appropriate response 2552 (as defined by new protocol) to the "GET /hello" request ...] 2554 When Upgrade is sent, the sender MUST also send a Connection header 2555 field (Section 6.4.1) that contains an "upgrade" connection option, 2556 in order to prevent Upgrade from being accidentally forwarded by 2557 intermediaries that might not implement the listed protocols. A 2558 server MUST ignore an Upgrade header field that is received in an 2559 HTTP/1.0 request. 2561 A client cannot begin using an upgraded protocol on the connection 2562 until it has completely sent the request message (i.e., the client 2563 can't change the protocol it is sending in the middle of a message). 2565 If a server receives both an Upgrade and an Expect header field with 2566 the "100-continue" expectation (Section 9.1.1), the server MUST send 2567 a 100 (Continue) response before sending a 101 (Switching Protocols) 2568 response. 2570 The Upgrade header field only applies to switching protocols on top 2571 of the existing connection; it cannot be used to switch the 2572 underlying connection (transport) protocol, nor to switch the 2573 existing communication to a different connection. For those 2574 purposes, it is more appropriate to use a 3xx (Redirection) response 2575 (Section 14.4). 2577 This specification only defines the protocol name "HTTP" for use by 2578 the family of Hypertext Transfer Protocols, as defined by the HTTP 2579 version rules of Section 5.1 and future updates to this 2580 specification. Additional protocol names ought to be registered 2581 using the registration procedure defined in Section 15.7. 2583 7. Representations 2585 A "representation" is information that is intended to reflect a past, 2586 current, or desired state of a given resource, in a format that can 2587 be readily communicated via the protocol. A representation consists 2588 of a set of representation metadata and a potentially unbounded 2589 stream of representation data. 2591 HTTP allows "information hiding" behind its uniform interface by 2592 phrasing communication with respect to a transferable representation 2593 of the resource state, rather than transferring the resource itself. 2594 This allows the resource identified by a URI to be anything, 2595 including temporal functions like "the current weather in Laguna 2596 Beach", while potentially providing information that represents that 2597 resource at the time a message is generated [REST]. 2599 The uniform interface is similar to a window through which one can 2600 observe and act upon a thing only through the communication of 2601 messages to an independent actor on the other side. A shared 2602 abstraction is needed to represent ("take the place of") the current 2603 or desired state of that thing in our communications. When a 2604 representation is hypertext, it can provide both a representation of 2605 the resource state and processing instructions that help guide the 2606 recipient's future interactions. 2608 7.1. Selected Representation 2610 An origin server might be provided with, or be capable of generating, 2611 multiple representations that are each intended to reflect the 2612 current state of a target resource. In such cases, some algorithm is 2613 used by the origin server to select one of those representations as 2614 most applicable to a given request, usually based on content 2615 negotiation. This "selected representation" is used to provide the 2616 data and metadata for evaluating conditional requests (Section 12.1) 2617 and constructing the payload for 200 (OK), 206 (Partial Content), and 2618 304 (Not Modified) responses to GET (Section 8.3.1). 2620 7.2. Data 2622 The representation data associated with an HTTP message is either 2623 provided as the payload body of the message or referred to by the 2624 message semantics and the target URI. The representation data is in 2625 a format and encoding defined by the representation metadata header 2626 fields. 2628 The data type of the representation data is determined via the header 2629 fields Content-Type and Content-Encoding. These define a two-layer, 2630 ordered encoding model: 2632 representation-data := Content-Encoding( Content-Type( bits ) ) 2634 7.3. Metadata 2636 Representation header fields provide metadata about the 2637 representation. When a message includes a payload body, the 2638 representation header fields describe how to interpret the 2639 representation data enclosed in the payload body. In a response to a 2640 HEAD request, the representation header fields describe the 2641 representation data that would have been enclosed in the payload body 2642 if the same request had been a GET. 2644 The following header fields convey representation metadata: 2646 ------------------ ------ 2647 Field Name Ref. 2648 ------------------ ------ 2649 Content-Type 7.4 2650 Content-Encoding 7.5 2651 Content-Language 7.6 2652 Content-Length 7.7 2653 Content-Location 7.8 2654 ------------------ ------ 2656 Table 3 2658 7.4. Content-Type 2660 The "Content-Type" header field indicates the media type of the 2661 associated representation: either the representation enclosed in the 2662 message payload or the selected representation, as determined by the 2663 message semantics. The indicated media type defines both the data 2664 format and how that data is intended to be processed by a recipient, 2665 within the scope of the received message semantics, after any content 2666 codings indicated by Content-Encoding are decoded. 2668 Content-Type = media-type 2670 Media types are defined in Section 7.4.1. An example of the field is 2672 Content-Type: text/html; charset=ISO-8859-4 2674 A sender that generates a message containing a payload body SHOULD 2675 generate a Content-Type header field in that message unless the 2676 intended media type of the enclosed representation is unknown to the 2677 sender. If a Content-Type header field is not present, the recipient 2678 MAY either assume a media type of "application/octet-stream" 2679 ([RFC2046], Section 4.5.1) or examine the data to determine its type. 2681 In practice, resource owners do not always properly configure their 2682 origin server to provide the correct Content-Type for a given 2683 representation. Some user agents examine a payload's content and, in 2684 certain cases, override the received type (for example, see 2685 [Sniffing]). This "MIME sniffing" risks drawing incorrect 2686 conclusions about the data, which might expose the user to additional 2687 security risks (e.g., "privilege escalation"). Furthermore, it is 2688 impossible to determine the sender's intended processing model by 2689 examining the data format: many data formats match multiple media 2690 types that differ only in processing semantics. Implementers are 2691 encouraged to provide a means to disable such sniffing. 2693 Furthermore, although Content-Type is defined as a singleton field, 2694 it is sometimes incorrectly generated multiple times, resulting in a 2695 combined field value that appears to be a list. Recipients often 2696 attempt to handle this error by using the last syntactically valid 2697 member of the list, but note that some implementations might have 2698 different error handling behaviors, leading to interoperability and/ 2699 or security issues. 2701 7.4.1. Media Type 2703 HTTP uses media types [RFC2046] in the Content-Type (Section 7.4) and 2704 Accept (Section 11.1.2) header fields in order to provide open and 2705 extensible data typing and type negotiation. Media types define both 2706 a data format and various processing models: how to process that data 2707 in accordance with each context in which it is received. 2709 media-type = type "/" subtype parameters 2710 type = token 2711 subtype = token 2713 The type and subtype tokens are case-insensitive. 2715 The type/subtype MAY be followed by semicolon-delimited parameters 2716 (Section 5.7.6) in the form of name=value pairs. The presence or 2717 absence of a parameter might be significant to the processing of a 2718 media type, depending on its definition within the media type 2719 registry. Parameter values might or might not be case-sensitive, 2720 depending on the semantics of the parameter name. 2722 For example, the following media types are equivalent in describing 2723 HTML text data encoded in the UTF-8 character encoding scheme, but 2724 the first is preferred for consistency (the "charset" parameter value 2725 is defined as being case-insensitive in [RFC2046], Section 4.1.2): 2727 text/html;charset=utf-8 2728 Text/HTML;Charset="utf-8" 2729 text/html; charset="utf-8" 2730 text/html;charset=UTF-8 2732 Media types ought to be registered with IANA according to the 2733 procedures defined in [BCP13]. 2735 7.4.2. Charset 2737 HTTP uses charset names to indicate or negotiate the character 2738 encoding scheme of a textual representation [RFC6365]. A charset is 2739 identified by a case-insensitive token. 2741 charset = token 2743 Charset names ought to be registered in the IANA "Character Sets" 2744 registry () 2745 according to the procedures defined in Section 2 of [RFC2978]. 2747 | *Note:* In theory, charset names are defined by the "mime- 2748 | charset" ABNF rule defined in Section 2.3 of [RFC2978] (as 2749 | corrected in [Err1912]). That rule allows two characters that 2750 | are not included in "token" ("{" and "}"), but no charset name 2751 | registered at the time of this writing includes braces (see 2752 | [Err5433]). 2754 7.4.3. Canonicalization and Text Defaults 2756 Media types are registered with a canonical form in order to be 2757 interoperable among systems with varying native encoding formats. 2758 Representations selected or transferred via HTTP ought to be in 2759 canonical form, for many of the same reasons described by the 2760 Multipurpose Internet Mail Extensions (MIME) [RFC2045]. However, the 2761 performance characteristics of email deployments (i.e., store and 2762 forward messages to peers) are significantly different from those 2763 common to HTTP and the Web (server-based information services). 2764 Furthermore, MIME's constraints for the sake of compatibility with 2765 older mail transfer protocols do not apply to HTTP (see Appendix B of 2766 [Messaging]). 2768 MIME's canonical form requires that media subtypes of the "text" type 2769 use CRLF as the text line break. HTTP allows the transfer of text 2770 media with plain CR or LF alone representing a line break, when such 2771 line breaks are consistent for an entire representation. An HTTP 2772 sender MAY generate, and a recipient MUST be able to parse, line 2773 breaks in text media that consist of CRLF, bare CR, or bare LF. In 2774 addition, text media in HTTP is not limited to charsets that use 2775 octets 13 and 10 for CR and LF, respectively. This flexibility 2776 regarding line breaks applies only to text within a representation 2777 that has been assigned a "text" media type; it does not apply to 2778 "multipart" types or HTTP elements outside the payload body (e.g., 2779 header fields). 2781 If a representation is encoded with a content-coding, the underlying 2782 data ought to be in a form defined above prior to being encoded. 2784 7.4.4. Multipart Types 2786 MIME provides for a number of "multipart" types - encapsulations of 2787 one or more representations within a single message body. All 2788 multipart types share a common syntax, as defined in Section 5.1.1 of 2789 [RFC2046], and include a boundary parameter as part of the media type 2790 value. The message body is itself a protocol element; a sender MUST 2791 generate only CRLF to represent line breaks between body parts. 2793 HTTP message framing does not use the multipart boundary as an 2794 indicator of message body length, though it might be used by 2795 implementations that generate or process the payload. For example, 2796 the "multipart/form-data" type is often used for carrying form data 2797 in a request, as described in [RFC7578], and the "multipart/ 2798 byteranges" type is defined by this specification for use in some 206 2799 (Partial Content) responses (see Section 14.3.7). 2801 7.5. Content-Encoding 2803 The "Content-Encoding" header field indicates what content codings 2804 have been applied to the representation, beyond those inherent in the 2805 media type, and thus what decoding mechanisms have to be applied in 2806 order to obtain data in the media type referenced by the Content-Type 2807 header field. Content-Encoding is primarily used to allow a 2808 representation's data to be compressed without losing the identity of 2809 its underlying media type. 2811 Content-Encoding = #content-coding 2813 An example of its use is 2815 Content-Encoding: gzip 2817 If one or more encodings have been applied to a representation, the 2818 sender that applied the encodings MUST generate a Content-Encoding 2819 header field that lists the content codings in the order in which 2820 they were applied. Note that the coding named "identity" is reserved 2821 for its special role in Accept-Encoding, and thus SHOULD NOT be 2822 included. 2824 Additional information about the encoding parameters can be provided 2825 by other header fields not defined by this specification. 2827 Unlike Transfer-Encoding (Section 6.1 of [Messaging]), the codings 2828 listed in Content-Encoding are a characteristic of the 2829 representation; the representation is defined in terms of the coded 2830 form, and all other metadata about the representation is about the 2831 coded form unless otherwise noted in the metadata definition. 2832 Typically, the representation is only decoded just prior to rendering 2833 or analogous usage. 2835 If the media type includes an inherent encoding, such as a data 2836 format that is always compressed, then that encoding would not be 2837 restated in Content-Encoding even if it happens to be the same 2838 algorithm as one of the content codings. Such a content coding would 2839 only be listed if, for some bizarre reason, it is applied a second 2840 time to form the representation. Likewise, an origin server might 2841 choose to publish the same data as multiple representations that 2842 differ only in whether the coding is defined as part of Content-Type 2843 or Content-Encoding, since some user agents will behave differently 2844 in their handling of each response (e.g., open a "Save as ..." dialog 2845 instead of automatic decompression and rendering of content). 2847 An origin server MAY respond with a status code of 415 (Unsupported 2848 Media Type) if a representation in the request message has a content 2849 coding that is not acceptable. 2851 7.5.1. Content Codings 2853 Content coding values indicate an encoding transformation that has 2854 been or can be applied to a representation. Content codings are 2855 primarily used to allow a representation to be compressed or 2856 otherwise usefully transformed without losing the identity of its 2857 underlying media type and without loss of information. Frequently, 2858 the representation is stored in coded form, transmitted directly, and 2859 only decoded by the final recipient. 2861 content-coding = token 2863 All content codings are case-insensitive and ought to be registered 2864 within the "HTTP Content Coding Registry", as described in 2865 Section 15.6 2867 Content-coding values are used in the Accept-Encoding 2868 (Section 11.1.4) and Content-Encoding (Section 7.5) header fields. 2870 The following content-coding values are defined by this 2871 specification: 2873 ------------ ------------------------------------------- --------- 2874 Name Description Ref. 2875 ------------ ------------------------------------------- --------- 2876 compress UNIX "compress" data format [Welch] 7.5.1.1 2877 deflate "deflate" compressed data ([RFC1951]) 7.5.1.2 2878 inside the "zlib" data format ([RFC1950]) 2879 gzip GZIP file format [RFC1952] 7.5.1.3 2880 identity Reserved 11.1.4 2881 x-compress Deprecated (alias for compress) 7.5.1.1 2882 x-gzip Deprecated (alias for gzip) 7.5.1.3 2883 ------------ ------------------------------------------- --------- 2885 Table 4 2887 7.5.1.1. Compress Coding 2889 The "compress" coding is an adaptive Lempel-Ziv-Welch (LZW) coding 2890 [Welch] that is commonly produced by the UNIX file compression 2891 program "compress". A recipient SHOULD consider "x-compress" to be 2892 equivalent to "compress". 2894 7.5.1.2. Deflate Coding 2896 The "deflate" coding is a "zlib" data format [RFC1950] containing a 2897 "deflate" compressed data stream [RFC1951] that uses a combination of 2898 the Lempel-Ziv (LZ77) compression algorithm and Huffman coding. 2900 | *Note:* Some non-conformant implementations send the "deflate" 2901 | compressed data without the zlib wrapper. 2903 7.5.1.3. Gzip Coding 2905 The "gzip" coding is an LZ77 coding with a 32-bit Cyclic Redundancy 2906 Check (CRC) that is commonly produced by the gzip file compression 2907 program [RFC1952]. A recipient SHOULD consider "x-gzip" to be 2908 equivalent to "gzip". 2910 7.6. Content-Language 2912 The "Content-Language" header field describes the natural language(s) 2913 of the intended audience for the representation. Note that this 2914 might not be equivalent to all the languages used within the 2915 representation. 2917 Content-Language = #language-tag 2919 Language tags are defined in Section 7.6.1. The primary purpose of 2920 Content-Language is to allow a user to identify and differentiate 2921 representations according to the users' own preferred language. 2922 Thus, if the content is intended only for a Danish-literate audience, 2923 the appropriate field is 2925 Content-Language: da 2927 If no Content-Language is specified, the default is that the content 2928 is intended for all language audiences. This might mean that the 2929 sender does not consider it to be specific to any natural language, 2930 or that the sender does not know for which language it is intended. 2932 Multiple languages MAY be listed for content that is intended for 2933 multiple audiences. For example, a rendition of the "Treaty of 2934 Waitangi", presented simultaneously in the original Maori and English 2935 versions, would call for 2937 Content-Language: mi, en 2939 However, just because multiple languages are present within a 2940 representation does not mean that it is intended for multiple 2941 linguistic audiences. An example would be a beginner's language 2942 primer, such as "A First Lesson in Latin", which is clearly intended 2943 to be used by an English-literate audience. In this case, the 2944 Content-Language would properly only include "en". 2946 Content-Language MAY be applied to any media type - it is not limited 2947 to textual documents. 2949 7.6.1. Language Tags 2951 A language tag, as defined in [RFC5646], identifies a natural 2952 language spoken, written, or otherwise conveyed by human beings for 2953 communication of information to other human beings. Computer 2954 languages are explicitly excluded. 2956 HTTP uses language tags within the Accept-Language and 2957 Content-Language header fields. Accept-Language uses the broader 2958 language-range production defined in Section 11.1.5, whereas 2959 Content-Language uses the language-tag production defined below. 2961 language-tag = 2963 A language tag is a sequence of one or more case-insensitive subtags, 2964 each separated by a hyphen character ("-", %x2D). In most cases, a 2965 language tag consists of a primary language subtag that identifies a 2966 broad family of related languages (e.g., "en" = English), which is 2967 optionally followed by a series of subtags that refine or narrow that 2968 language's range (e.g., "en-CA" = the variety of English as 2969 communicated in Canada). Whitespace is not allowed within a language 2970 tag. Example tags include: 2972 fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN 2974 See [RFC5646] for further information. 2976 7.7. Content-Length 2978 The "Content-Length" header field indicates the associated 2979 representation's data length as a decimal non-negative integer number 2980 of octets. When transferring a representation in a message, Content- 2981 Length refers specifically to the amount of data enclosed so that it 2982 can be used to delimit framing of the message body (e.g., Section 6.2 2983 of [Messaging]). In other cases, Content-Length indicates the 2984 selected representation's current length, which can be used by 2985 recipients to estimate transfer time or compare to previously stored 2986 representations. 2988 Content-Length = 1*DIGIT 2990 An example is 2992 Content-Length: 3495 2994 A sender MUST NOT send a Content-Length header field in any message 2995 that contains a Transfer-Encoding header field. 2997 A user agent SHOULD send a Content-Length in a request message when 2998 no Transfer-Encoding is sent and the request method defines a meaning 2999 for an enclosed payload body. For example, a Content-Length header 3000 field is normally sent in a POST request even when the value is 0 3001 (indicating an empty payload body). A user agent SHOULD NOT send a 3002 Content-Length header field when the request message does not contain 3003 a payload body and the method semantics do not anticipate such a 3004 body. 3006 A server MAY send a Content-Length header field in a response to a 3007 HEAD request (Section 8.3.2); a server MUST NOT send Content-Length 3008 in such a response unless its field value equals the decimal number 3009 of octets that would have been sent in the payload body of a response 3010 if the same request had used the GET method. 3012 A server MAY send a Content-Length header field in a 304 (Not 3013 Modified) response to a conditional GET request (Section 14.4.5); a 3014 server MUST NOT send Content-Length in such a response unless its 3015 field value equals the decimal number of octets that would have been 3016 sent in the payload body of a 200 (OK) response to the same request. 3018 A server MUST NOT send a Content-Length header field in any response 3019 with a status code of 1xx (Informational) or 204 (No Content). A 3020 server MUST NOT send a Content-Length header field in any 2xx 3021 (Successful) response to a CONNECT request (Section 8.3.6). 3023 Aside from the cases defined above, in the absence of Transfer- 3024 Encoding, an origin server SHOULD send a Content-Length header field 3025 when the payload body size is known prior to sending the complete 3026 header section. This will allow downstream recipients to measure 3027 transfer progress, know when a received message is complete, and 3028 potentially reuse the connection for additional requests. 3030 Any Content-Length field value greater than or equal to zero is 3031 valid. Since there is no predefined limit to the length of a 3032 payload, a recipient MUST anticipate potentially large decimal 3033 numerals and prevent parsing errors due to integer conversion 3034 overflows (Section 16.5). 3036 If a message is received that has a Content-Length header field value 3037 consisting of the same decimal value as a comma-separated list 3038 (Section 5.7.1) - for example, "Content-Length: 42, 42" - indicating 3039 that duplicate Content-Length header fields have been generated or 3040 combined by an upstream message processor, then the recipient MUST 3041 either reject the message as invalid or replace the duplicated field 3042 values with a single valid Content-Length field containing that 3043 decimal value prior to determining the message body length or 3044 forwarding the message. 3046 7.8. Content-Location 3048 The "Content-Location" header field references a URI that can be used 3049 as an identifier for a specific resource corresponding to the 3050 representation in this message's payload. In other words, if one 3051 were to perform a GET request on this URI at the time of this 3052 message's generation, then a 200 (OK) response would contain the same 3053 representation that is enclosed as payload in this message. 3055 Content-Location = absolute-URI / partial-URI 3057 The field value is either an absolute-URI or a partial-URI. In the 3058 latter case (Section 4), the referenced URI is relative to the target 3059 URI ([RFC3986], Section 5). 3061 The Content-Location value is not a replacement for the target URI 3062 (Section 6.1). It is representation metadata. It has the same 3063 syntax and semantics as the header field of the same name defined for 3064 MIME body parts in Section 4 of [RFC2557]. However, its appearance 3065 in an HTTP message has some special implications for HTTP recipients. 3067 If Content-Location is included in a 2xx (Successful) response 3068 message and its value refers (after conversion to absolute form) to a 3069 URI that is the same as the target URI, then the recipient MAY 3070 consider the payload to be a current representation of that resource 3071 at the time indicated by the message origination date. For a GET 3072 (Section 8.3.1) or HEAD (Section 8.3.2) request, this is the same as 3073 the default semantics when no Content-Location is provided by the 3074 server. For a state-changing request like PUT (Section 8.3.4) or 3075 POST (Section 8.3.3), it implies that the server's response contains 3076 the new representation of that resource, thereby distinguishing it 3077 from representations that might only report about the action (e.g., 3078 "It worked!"). This allows authoring applications to update their 3079 local copies without the need for a subsequent GET request. 3081 If Content-Location is included in a 2xx (Successful) response 3082 message and its field value refers to a URI that differs from the 3083 target URI, then the origin server claims that the URI is an 3084 identifier for a different resource corresponding to the enclosed 3085 representation. Such a claim can only be trusted if both identifiers 3086 share the same resource owner, which cannot be programmatically 3087 determined via HTTP. 3089 o For a response to a GET or HEAD request, this is an indication 3090 that the target URI refers to a resource that is subject to 3091 content negotiation and the Content-Location field value is a more 3092 specific identifier for the selected representation. 3094 o For a 201 (Created) response to a state-changing method, a 3095 Content-Location field value that is identical to the Location 3096 field value indicates that this payload is a current 3097 representation of the newly created resource. 3099 o Otherwise, such a Content-Location indicates that this payload is 3100 a representation reporting on the requested action's status and 3101 that the same report is available (for future access with GET) at 3102 the given URI. For example, a purchase transaction made via a 3103 POST request might include a receipt document as the payload of 3104 the 200 (OK) response; the Content-Location field value provides 3105 an identifier for retrieving a copy of that same receipt in the 3106 future. 3108 A user agent that sends Content-Location in a request message is 3109 stating that its value refers to where the user agent originally 3110 obtained the content of the enclosed representation (prior to any 3111 modifications made by that user agent). In other words, the user 3112 agent is providing a back link to the source of the original 3113 representation. 3115 An origin server that receives a Content-Location field in a request 3116 message MUST treat the information as transitory request context 3117 rather than as metadata to be saved verbatim as part of the 3118 representation. An origin server MAY use that context to guide in 3119 processing the request or to save it for other uses, such as within 3120 source links or versioning metadata. However, an origin server MUST 3121 NOT use such context information to alter the request semantics. 3123 For example, if a client makes a PUT request on a negotiated resource 3124 and the origin server accepts that PUT (without redirection), then 3125 the new state of that resource is expected to be consistent with the 3126 one representation supplied in that PUT; the Content-Location cannot 3127 be used as a form of reverse content selection identifier to update 3128 only one of the negotiated representations. If the user agent had 3129 wanted the latter semantics, it would have applied the PUT directly 3130 to the Content-Location URI. 3132 7.9. Validators 3134 Validator header fields convey metadata about the selected 3135 representation (Section 7). In responses to safe requests, validator 3136 fields describe the selected representation chosen by the origin 3137 server while handling the response. Note that, depending on the 3138 status code semantics, the selected representation for a given 3139 response is not necessarily the same as the representation enclosed 3140 as response payload. 3142 In a successful response to a state-changing request, validator 3143 fields describe the new representation that has replaced the prior 3144 selected representation as a result of processing the request. 3146 For example, an ETag field in a 201 (Created) response communicates 3147 the entity-tag of the newly created resource's representation, so 3148 that it can be used in later conditional requests to prevent the 3149 "lost update" problem Section 12.1. 3151 --------------- ------- 3152 Field Name Ref. 3153 --------------- ------- 3154 ETag 7.9.3 3155 Last-Modified 7.9.2 3156 --------------- ------- 3158 Table 5 3160 This specification defines two forms of metadata that are commonly 3161 used to observe resource state and test for preconditions: 3162 modification dates (Section 7.9.2) and opaque entity tags 3163 (Section 7.9.3). Additional metadata that reflects resource state 3164 has been defined by various extensions of HTTP, such as Web 3165 Distributed Authoring and Versioning (WebDAV, [RFC4918]), that are 3166 beyond the scope of this specification. A resource metadata value is 3167 referred to as a "validator" when it is used within a precondition. 3169 7.9.1. Weak versus Strong 3171 Validators come in two flavors: strong or weak. Weak validators are 3172 easy to generate but are far less useful for comparisons. Strong 3173 validators are ideal for comparisons but can be very difficult (and 3174 occasionally impossible) to generate efficiently. Rather than impose 3175 that all forms of resource adhere to the same strength of validator, 3176 HTTP exposes the type of validator in use and imposes restrictions on 3177 when weak validators can be used as preconditions. 3179 A "strong validator" is representation metadata that changes value 3180 whenever a change occurs to the representation data that would be 3181 observable in the payload body of a 200 (OK) response to GET. 3183 A strong validator might change for reasons other than a change to 3184 the representation data, such as when a semantically significant part 3185 of the representation metadata is changed (e.g., Content-Type), but 3186 it is in the best interests of the origin server to only change the 3187 value when it is necessary to invalidate the stored responses held by 3188 remote caches and authoring tools. 3190 Cache entries might persist for arbitrarily long periods, regardless 3191 of expiration times. Thus, a cache might attempt to validate an 3192 entry using a validator that it obtained in the distant past. A 3193 strong validator is unique across all versions of all representations 3194 associated with a particular resource over time. However, there is 3195 no implication of uniqueness across representations of different 3196 resources (i.e., the same strong validator might be in use for 3197 representations of multiple resources at the same time and does not 3198 imply that those representations are equivalent). 3200 There are a variety of strong validators used in practice. The best 3201 are based on strict revision control, wherein each change to a 3202 representation always results in a unique node name and revision 3203 identifier being assigned before the representation is made 3204 accessible to GET. A collision-resistant hash function applied to 3205 the representation data is also sufficient if the data is available 3206 prior to the response header fields being sent and the digest does 3207 not need to be recalculated every time a validation request is 3208 received. However, if a resource has distinct representations that 3209 differ only in their metadata, such as might occur with content 3210 negotiation over media types that happen to share the same data 3211 format, then the origin server needs to incorporate additional 3212 information in the validator to distinguish those representations. 3214 In contrast, a "weak validator" is representation metadata that might 3215 not change for every change to the representation data. This 3216 weakness might be due to limitations in how the value is calculated, 3217 such as clock resolution, an inability to ensure uniqueness for all 3218 possible representations of the resource, or a desire of the resource 3219 owner to group representations by some self-determined set of 3220 equivalency rather than unique sequences of data. An origin server 3221 SHOULD change a weak entity-tag whenever it considers prior 3222 representations to be unacceptable as a substitute for the current 3223 representation. In other words, a weak entity-tag ought to change 3224 whenever the origin server wants caches to invalidate old responses. 3226 For example, the representation of a weather report that changes in 3227 content every second, based on dynamic measurements, might be grouped 3228 into sets of equivalent representations (from the origin server's 3229 perspective) with the same weak validator in order to allow cached 3230 representations to be valid for a reasonable period of time (perhaps 3231 adjusted dynamically based on server load or weather quality). 3232 Likewise, a representation's modification time, if defined with only 3233 one-second resolution, might be a weak validator if it is possible 3234 for the representation to be modified twice during a single second 3235 and retrieved between those modifications. 3237 Likewise, a validator is weak if it is shared by two or more 3238 representations of a given resource at the same time, unless those 3239 representations have identical representation data. For example, if 3240 the origin server sends the same validator for a representation with 3241 a gzip content coding applied as it does for a representation with no 3242 content coding, then that validator is weak. However, two 3243 simultaneous representations might share the same strong validator if 3244 they differ only in the representation metadata, such as when two 3245 different media types are available for the same representation data. 3247 Strong validators are usable for all conditional requests, including 3248 cache validation, partial content ranges, and "lost update" 3249 avoidance. Weak validators are only usable when the client does not 3250 require exact equality with previously obtained representation data, 3251 such as when validating a cache entry or limiting a web traversal to 3252 recent changes. 3254 7.9.2. Last-Modified 3256 The "Last-Modified" header field in a response provides a timestamp 3257 indicating the date and time at which the origin server believes the 3258 selected representation was last modified, as determined at the 3259 conclusion of handling the request. 3261 Last-Modified = HTTP-date 3263 An example of its use is 3265 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 3267 7.9.2.1. Generation 3269 An origin server SHOULD send Last-Modified for any selected 3270 representation for which a last modification date can be reasonably 3271 and consistently determined, since its use in conditional requests 3272 and evaluating cache freshness ([Caching]) results in a substantial 3273 reduction of HTTP traffic on the Internet and can be a significant 3274 factor in improving service scalability and reliability. 3276 A representation is typically the sum of many parts behind the 3277 resource interface. The last-modified time would usually be the most 3278 recent time that any of those parts were changed. How that value is 3279 determined for any given resource is an implementation detail beyond 3280 the scope of this specification. What matters to HTTP is how 3281 recipients of the Last-Modified header field can use its value to 3282 make conditional requests and test the validity of locally cached 3283 responses. 3285 An origin server SHOULD obtain the Last-Modified value of the 3286 representation as close as possible to the time that it generates the 3287 Date field value for its response. This allows a recipient to make 3288 an accurate assessment of the representation's modification time, 3289 especially if the representation changes near the time that the 3290 response is generated. 3292 An origin server with a clock MUST NOT send a Last-Modified date that 3293 is later than the server's time of message origination (Date). If 3294 the last modification time is derived from implementation-specific 3295 metadata that evaluates to some time in the future, according to the 3296 origin server's clock, then the origin server MUST replace that value 3297 with the message origination date. This prevents a future 3298 modification date from having an adverse impact on cache validation. 3300 An origin server without a clock MUST NOT assign Last-Modified values 3301 to a response unless these values were associated with the resource 3302 by some other system or user with a reliable clock. 3304 7.9.2.2. Comparison 3306 A Last-Modified time, when used as a validator in a request, is 3307 implicitly weak unless it is possible to deduce that it is strong, 3308 using the following rules: 3310 o The validator is being compared by an origin server to the actual 3311 current validator for the representation and, 3313 o That origin server reliably knows that the associated 3314 representation did not change twice during the second covered by 3315 the presented validator. 3317 or 3319 o The validator is about to be used by a client in an 3320 If-Modified-Since, If-Unmodified-Since, or If-Range header field, 3321 because the client has a cache entry for the associated 3322 representation, and 3324 o That cache entry includes a Date value, which gives the time when 3325 the origin server sent the original response, and 3327 o The presented Last-Modified time is at least 60 seconds before the 3328 Date value. 3330 or 3332 o The validator is being compared by an intermediate cache to the 3333 validator stored in its cache entry for the representation, and 3335 o That cache entry includes a Date value, which gives the time when 3336 the origin server sent the original response, and 3338 o The presented Last-Modified time is at least 60 seconds before the 3339 Date value. 3341 This method relies on the fact that if two different responses were 3342 sent by the origin server during the same second, but both had the 3343 same Last-Modified time, then at least one of those responses would 3344 have a Date value equal to its Last-Modified time. The arbitrary 3345 60-second limit guards against the possibility that the Date and 3346 Last-Modified values are generated from different clocks or at 3347 somewhat different times during the preparation of the response. An 3348 implementation MAY use a value larger than 60 seconds, if it is 3349 believed that 60 seconds is too short. 3351 7.9.3. ETag 3353 The "ETag" field in a response provides the current entity-tag for 3354 the selected representation, as determined at the conclusion of 3355 handling the request. An entity-tag is an opaque validator for 3356 differentiating between multiple representations of the same 3357 resource, regardless of whether those multiple representations are 3358 due to resource state changes over time, content negotiation 3359 resulting in multiple representations being valid at the same time, 3360 or both. An entity-tag consists of an opaque quoted string, possibly 3361 prefixed by a weakness indicator. 3363 ETag = entity-tag 3365 entity-tag = [ weak ] opaque-tag 3366 weak = %s"W/" 3367 opaque-tag = DQUOTE *etagc DQUOTE 3368 etagc = %x21 / %x23-7E / obs-text 3369 ; VCHAR except double quotes, plus obs-text 3371 | *Note:* Previously, opaque-tag was defined to be a quoted- 3372 | string ([RFC2616], Section 3.11); thus, some recipients might 3373 | perform backslash unescaping. Servers therefore ought to avoid 3374 | backslash characters in entity tags. 3376 An entity-tag can be more reliable for validation than a modification 3377 date in situations where it is inconvenient to store modification 3378 dates, where the one-second resolution of HTTP date values is not 3379 sufficient, or where modification dates are not consistently 3380 maintained. 3382 Examples: 3384 ETag: "xyzzy" 3385 ETag: W/"xyzzy" 3386 ETag: "" 3388 An entity-tag can be either a weak or strong validator, with strong 3389 being the default. If an origin server provides an entity-tag for a 3390 representation and the generation of that entity-tag does not satisfy 3391 all of the characteristics of a strong validator (Section 7.9.1), 3392 then the origin server MUST mark the entity-tag as weak by prefixing 3393 its opaque value with "W/" (case-sensitive). 3395 A sender MAY send the Etag field in a trailer section (see 3396 Section 5.6). However, since trailers are often ignored, it is 3397 preferable to send Etag as a header field unless the entity-tag is 3398 generated while sending the message body. 3400 7.9.3.1. Generation 3402 The principle behind entity-tags is that only the service author 3403 knows the implementation of a resource well enough to select the most 3404 accurate and efficient validation mechanism for that resource, and 3405 that any such mechanism can be mapped to a simple sequence of octets 3406 for easy comparison. Since the value is opaque, there is no need for 3407 the client to be aware of how each entity-tag is constructed. 3409 For example, a resource that has implementation-specific versioning 3410 applied to all changes might use an internal revision number, perhaps 3411 combined with a variance identifier for content negotiation, to 3412 accurately differentiate between representations. Other 3413 implementations might use a collision-resistant hash of 3414 representation content, a combination of various file attributes, or 3415 a modification timestamp that has sub-second resolution. 3417 An origin server SHOULD send an ETag for any selected representation 3418 for which detection of changes can be reasonably and consistently 3419 determined, since the entity-tag's use in conditional requests and 3420 evaluating cache freshness ([Caching]) can result in a substantial 3421 reduction of HTTP network traffic and can be a significant factor in 3422 improving service scalability and reliability. 3424 7.9.3.2. Comparison 3426 There are two entity-tag comparison functions, depending on whether 3427 or not the comparison context allows the use of weak validators: 3429 o Strong comparison: two entity-tags are equivalent if both are not 3430 weak and their opaque-tags match character-by-character. 3432 o Weak comparison: two entity-tags are equivalent if their opaque- 3433 tags match character-by-character, regardless of either or both 3434 being tagged as "weak". 3436 The example below shows the results for a set of entity-tag pairs and 3437 both the weak and strong comparison function results: 3439 -------- -------- ------------------- ----------------- 3440 ETag 1 ETag 2 Strong Comparison Weak Comparison 3441 -------- -------- ------------------- ----------------- 3442 W/"1" W/"1" no match match 3443 W/"1" W/"2" no match no match 3444 W/"1" "1" no match match 3445 "1" "1" match match 3446 -------- -------- ------------------- ----------------- 3448 Table 6 3450 7.9.3.3. Example: Entity-Tags Varying on Content-Negotiated Resources 3452 Consider a resource that is subject to content negotiation 3453 (Section 11), and where the representations sent in response to a GET 3454 request vary based on the Accept-Encoding request header field 3455 (Section 11.1.4): 3457 >> Request: 3459 GET /index HTTP/1.1 3460 Host: www.example.com 3461 Accept-Encoding: gzip 3463 In this case, the response might or might not use the gzip content 3464 coding. If it does not, the response might look like: 3466 >> Response: 3468 HTTP/1.1 200 OK 3469 Date: Fri, 26 Mar 2010 00:05:00 GMT 3470 ETag: "123-a" 3471 Content-Length: 70 3472 Vary: Accept-Encoding 3473 Content-Type: text/plain 3475 Hello World! 3476 Hello World! 3477 Hello World! 3478 Hello World! 3479 Hello World! 3481 An alternative representation that does use gzip content coding would 3482 be: 3484 >> Response: 3486 HTTP/1.1 200 OK 3487 Date: Fri, 26 Mar 2010 00:05:00 GMT 3488 ETag: "123-b" 3489 Content-Length: 43 3490 Vary: Accept-Encoding 3491 Content-Type: text/plain 3492 Content-Encoding: gzip 3494 ...binary data... 3496 | *Note:* Content codings are a property of the representation 3497 | data, so a strong entity-tag for a content-encoded 3498 | representation has to be distinct from the entity tag of an 3499 | unencoded representation to prevent potential conflicts during 3500 | cache updates and range requests. In contrast, transfer 3501 | codings (Section 7 of [Messaging]) apply only during message 3502 | transfer and do not result in distinct entity-tags. 3504 7.9.4. When to Use Entity-Tags and Last-Modified Dates 3506 In 200 (OK) responses to GET or HEAD, an origin server: 3508 o SHOULD send an entity-tag validator unless it is not feasible to 3509 generate one. 3511 o MAY send a weak entity-tag instead of a strong entity-tag, if 3512 performance considerations support the use of weak entity-tags, or 3513 if it is unfeasible to send a strong entity-tag. 3515 o SHOULD send a Last-Modified value if it is feasible to send one. 3517 In other words, the preferred behavior for an origin server is to 3518 send both a strong entity-tag and a Last-Modified value in successful 3519 responses to a retrieval request. 3521 A client: 3523 o MUST send that entity-tag in any cache validation request (using 3524 If-Match or If-None-Match) if an entity-tag has been provided by 3525 the origin server. 3527 o SHOULD send the Last-Modified value in non-subrange cache 3528 validation requests (using If-Modified-Since) if only a Last- 3529 Modified value has been provided by the origin server. 3531 o MAY send the Last-Modified value in subrange cache validation 3532 requests (using If-Unmodified-Since) if only a Last-Modified value 3533 has been provided by an HTTP/1.0 origin server. The user agent 3534 SHOULD provide a way to disable this, in case of difficulty. 3536 o SHOULD send both validators in cache validation requests if both 3537 an entity-tag and a Last-Modified value have been provided by the 3538 origin server. This allows both HTTP/1.0 and HTTP/1.1 caches to 3539 respond appropriately. 3541 8. Methods 3543 8.1. Overview 3545 The request method token is the primary source of request semantics; 3546 it indicates the purpose for which the client has made this request 3547 and what is expected by the client as a successful result. 3549 The request method's semantics might be further specialized by the 3550 semantics of some header fields when present in a request if those 3551 additional semantics do not conflict with the method. For example, a 3552 client can send conditional request header fields (Section 12.1) to 3553 make the requested action conditional on the current state of the 3554 target resource. 3556 method = token 3558 HTTP was originally designed to be usable as an interface to 3559 distributed object systems. The request method was envisioned as 3560 applying semantics to a target resource in much the same way as 3561 invoking a defined method on an identified object would apply 3562 semantics. 3564 The method token is case-sensitive because it might be used as a 3565 gateway to object-based systems with case-sensitive method names. By 3566 convention, standardized methods are defined in all-uppercase US- 3567 ASCII letters. 3569 Unlike distributed objects, the standardized request methods in HTTP 3570 are not resource-specific, since uniform interfaces provide for 3571 better visibility and reuse in network-based systems [REST]. Once 3572 defined, a standardized method ought to have the same semantics when 3573 applied to any resource, though each resource determines for itself 3574 whether those semantics are implemented or allowed. 3576 This specification defines a number of standardized methods that are 3577 commonly used in HTTP, as outlined by the following table. 3579 --------- -------------------------------------------- ------- 3580 Method Description Ref. 3581 --------- -------------------------------------------- ------- 3582 GET Transfer a current representation of the 8.3.1 3583 target resource. 3584 HEAD Same as GET, but do not transfer the 8.3.2 3585 response body. 3586 POST Perform resource-specific processing on 8.3.3 3587 the request payload. 3588 PUT Replace all current representations of the 8.3.4 3589 target resource with the request payload. 3590 DELETE Remove all current representations of the 8.3.5 3591 target resource. 3592 CONNECT Establish a tunnel to the server 8.3.6 3593 identified by the target resource. 3594 OPTIONS Describe the communication options for the 8.3.7 3595 target resource. 3596 TRACE Perform a message loop-back test along the 8.3.8 3597 path to the target resource. 3598 --------- -------------------------------------------- ------- 3600 Table 7 3602 All general-purpose servers MUST support the methods GET and HEAD. 3603 All other methods are OPTIONAL. 3605 The set of methods allowed by a target resource can be listed in an 3606 Allow header field (Section 9.2.1). However, the set of allowed 3607 methods can change dynamically. When a request method is received 3608 that is unrecognized or not implemented by an origin server, the 3609 origin server SHOULD respond with the 501 (Not Implemented) status 3610 code. When a request method is received that is known by an origin 3611 server but not allowed for the target resource, the origin server 3612 SHOULD respond with the 405 (Method Not Allowed) status code. 3614 Additional methods, outside the scope of this specification, have 3615 been specified for use in HTTP. All such methods ought to be 3616 registered within the "Hypertext Transfer Protocol (HTTP) Method 3617 Registry", as described in Section 15.1. 3619 8.2. Common Method Properties 3620 8.2.1. Safe Methods 3622 Request methods are considered "safe" if their defined semantics are 3623 essentially read-only; i.e., the client does not request, and does 3624 not expect, any state change on the origin server as a result of 3625 applying a safe method to a target resource. Likewise, reasonable 3626 use of a safe method is not expected to cause any harm, loss of 3627 property, or unusual burden on the origin server. 3629 This definition of safe methods does not prevent an implementation 3630 from including behavior that is potentially harmful, that is not 3631 entirely read-only, or that causes side effects while invoking a safe 3632 method. What is important, however, is that the client did not 3633 request that additional behavior and cannot be held accountable for 3634 it. For example, most servers append request information to access 3635 log files at the completion of every response, regardless of the 3636 method, and that is considered safe even though the log storage might 3637 become full and crash the server. Likewise, a safe request initiated 3638 by selecting an advertisement on the Web will often have the side 3639 effect of charging an advertising account. 3641 Of the request methods defined by this specification, the GET, HEAD, 3642 OPTIONS, and TRACE methods are defined to be safe. 3644 The purpose of distinguishing between safe and unsafe methods is to 3645 allow automated retrieval processes (spiders) and cache performance 3646 optimization (pre-fetching) to work without fear of causing harm. In 3647 addition, it allows a user agent to apply appropriate constraints on 3648 the automated use of unsafe methods when processing potentially 3649 untrusted content. 3651 A user agent SHOULD distinguish between safe and unsafe methods when 3652 presenting potential actions to a user, such that the user can be 3653 made aware of an unsafe action before it is requested. 3655 When a resource is constructed such that parameters within the target 3656 URI have the effect of selecting an action, it is the resource 3657 owner's responsibility to ensure that the action is consistent with 3658 the request method semantics. For example, it is common for Web- 3659 based content editing software to use actions within query 3660 parameters, such as "page?do=delete". If the purpose of such a 3661 resource is to perform an unsafe action, then the resource owner MUST 3662 disable or disallow that action when it is accessed using a safe 3663 request method. Failure to do so will result in unfortunate side 3664 effects when automated processes perform a GET on every URI reference 3665 for the sake of link maintenance, pre-fetching, building a search 3666 index, etc. 3668 8.2.2. Idempotent Methods 3670 A request method is considered "idempotent" if the intended effect on 3671 the server of multiple identical requests with that method is the 3672 same as the effect for a single such request. Of the request methods 3673 defined by this specification, PUT, DELETE, and safe request methods 3674 are idempotent. 3676 Like the definition of safe, the idempotent property only applies to 3677 what has been requested by the user; a server is free to log each 3678 request separately, retain a revision control history, or implement 3679 other non-idempotent side effects for each idempotent request. 3681 Idempotent methods are distinguished because the request can be 3682 repeated automatically if a communication failure occurs before the 3683 client is able to read the server's response. For example, if a 3684 client sends a PUT request and the underlying connection is closed 3685 before any response is received, then the client can establish a new 3686 connection and retry the idempotent request. It knows that repeating 3687 the request will have the same intended effect, even if the original 3688 request succeeded, though the response might differ. 3690 A client SHOULD NOT automatically retry a request with a non- 3691 idempotent method unless it has some means to know that the request 3692 semantics are actually idempotent, regardless of the method, or some 3693 means to detect that the original request was never applied. 3695 For example, a user agent that knows (through design or 3696 configuration) that a POST request to a given resource is safe can 3697 repeat that request automatically. Likewise, a user agent designed 3698 specifically to operate on a version control repository might be able 3699 to recover from partial failure conditions by checking the target 3700 resource revision(s) after a failed connection, reverting or fixing 3701 any changes that were partially applied, and then automatically 3702 retrying the requests that failed. 3704 Some clients use weaker signals to initiate automatic retries. For 3705 example, when a POST request is sent, but the underlying transport 3706 connection is closed before any part of the response is received. 3707 Although this is commonly implemented, it is not recommended. 3709 A proxy MUST NOT automatically retry non-idempotent requests. A 3710 client SHOULD NOT automatically retry a failed automatic retry. 3712 8.2.3. Methods and Caching 3714 For a cache to store and use a response, the associated method needs 3715 to explicitly allow caching, and detail under what conditions a 3716 response can be used to satisfy subsequent requests; a method 3717 definition which does not do so cannot be cached. For additional 3718 requirements see [Caching]. 3720 This specification defines caching semantics for GET, HEAD, and POST, 3721 although the overwhelming majority of cache implementations only 3722 support GET and HEAD. 3724 8.3. Method Definitions 3726 8.3.1. GET 3728 The GET method requests transfer of a current selected representation 3729 for the target resource. 3731 GET is the primary mechanism of information retrieval and the focus 3732 of almost all performance optimizations. Hence, when people speak of 3733 retrieving some identifiable information via HTTP, they are generally 3734 referring to making a GET request. A successful response reflects 3735 the quality of "sameness" identified by the target URI. In turn, 3736 constructing applications such that they produce a URI for each 3737 important resource results in more resources being available for 3738 other applications, producing a network effect that promotes further 3739 expansion of the Web. 3741 It is tempting to think of resource identifiers as remote file system 3742 pathnames and of representations as being a copy of the contents of 3743 such files. In fact, that is how many resources are implemented (see 3744 Section 16.3 for related security considerations). However, there 3745 are no such limitations in practice. 3747 The HTTP interface for a resource is just as likely to be implemented 3748 as a tree of content objects, a programmatic view on various database 3749 records, or a gateway to other information systems. Even when the 3750 URI mapping mechanism is tied to a file system, an origin server 3751 might be configured to execute the files with the request as input 3752 and send the output as the representation rather than transfer the 3753 files directly. Regardless, only the origin server needs to know how 3754 each of its resource identifiers corresponds to an implementation and 3755 how each implementation manages to select and send a current 3756 representation of the target resource in a response to GET. 3758 A client can alter the semantics of GET to be a "range request", 3759 requesting transfer of only some part(s) of the selected 3760 representation, by sending a Range header field in the request 3761 (Section 13.2). 3763 A client SHOULD NOT generate a body in a GET request. A payload 3764 received in a GET request has no defined semantics, cannot alter the 3765 meaning or target of the request, and might lead some implementations 3766 to reject the request and close the connection because of its 3767 potential as a request smuggling attack (Section 11.2 of 3768 [Messaging]). 3770 The response to a GET request is cacheable; a cache MAY use it to 3771 satisfy subsequent GET and HEAD requests unless otherwise indicated 3772 by the Cache-Control header field (Section 5.2 of [Caching]). A 3773 cache that receives a payload in a GET request is likely to ignore 3774 that payload and cache regardless of the payload contents. 3776 When information retrieval is performed with a mechanism that 3777 constructs a target URI from user-provided information, such as the 3778 query fields of a form using GET, potentially sensitive data might be 3779 provided that would not be appropriate for disclosure within a URI 3780 (see Section 16.9). In some cases, the data can be filtered or 3781 transformed such that it would not reveal such information. In 3782 others, particularly when there is no benefit from caching a 3783 response, using the POST method (Section 8.3.3) instead of GET will 3784 usually transmit such information in the request body rather than 3785 construct a new URI. 3787 8.3.2. HEAD 3789 The HEAD method is identical to GET except that the server MUST NOT 3790 send a message body in the response (i.e., the response terminates at 3791 the end of the header section). The server SHOULD send the same 3792 header fields in response to a HEAD request as it would have sent if 3793 the request had been a GET, except that the payload header fields 3794 (Section 5.5) MAY be omitted. This method can be used for obtaining 3795 metadata about the selected representation without transferring the 3796 representation data and is often used for testing hypertext links for 3797 validity, accessibility, and recent modification. 3799 A payload within a HEAD request message has no defined semantics; 3800 sending a payload body on a HEAD request might cause some existing 3801 implementations to reject the request. 3803 The response to a HEAD request is cacheable; a cache MAY use it to 3804 satisfy subsequent HEAD requests unless otherwise indicated by the 3805 Cache-Control header field (Section 5.2 of [Caching]). A HEAD 3806 response might also have an effect on previously cached responses to 3807 GET; see Section 4.3.5 of [Caching]. 3809 8.3.3. POST 3811 The POST method requests that the target resource process the 3812 representation enclosed in the request according to the resource's 3813 own specific semantics. For example, POST is used for the following 3814 functions (among others): 3816 o Providing a block of data, such as the fields entered into an HTML 3817 form, to a data-handling process; 3819 o Posting a message to a bulletin board, newsgroup, mailing list, 3820 blog, or similar group of articles; 3822 o Creating a new resource that has yet to be identified by the 3823 origin server; and 3825 o Appending data to a resource's existing representation(s). 3827 An origin server indicates response semantics by choosing an 3828 appropriate status code depending on the result of processing the 3829 POST request; almost all of the status codes defined by this 3830 specification could be received in a response to POST (the exceptions 3831 being 206 (Partial Content), 304 (Not Modified), and 416 (Range Not 3832 Satisfiable)). 3834 If one or more resources has been created on the origin server as a 3835 result of successfully processing a POST request, the origin server 3836 SHOULD send a 201 (Created) response containing a Location header 3837 field that provides an identifier for the primary resource created 3838 (Section 9.2.3) and a representation that describes the status of the 3839 request while referring to the new resource(s). 3841 Responses to POST requests are only cacheable when they include 3842 explicit freshness information (see Section 4.2.1 of [Caching]) and a 3843 Content-Location header field that has the same value as the POST's 3844 target URI (Section 7.8). A cached POST response can be reused to 3845 satisfy a later GET or HEAD request, but not a POST request, since 3846 POST is required to be written through to the origin server, because 3847 it is unsafe; see Section 4 of [Caching]. 3849 If the result of processing a POST would be equivalent to a 3850 representation of an existing resource, an origin server MAY redirect 3851 the user agent to that resource by sending a 303 (See Other) response 3852 with the existing resource's identifier in the Location field. This 3853 has the benefits of providing the user agent a resource identifier 3854 and transferring the representation via a method more amenable to 3855 shared caching, though at the cost of an extra request if the user 3856 agent does not already have the representation cached. 3858 8.3.4. PUT 3860 The PUT method requests that the state of the target resource be 3861 created or replaced with the state defined by the representation 3862 enclosed in the request message payload. A successful PUT of a given 3863 representation would suggest that a subsequent GET on that same 3864 target resource will result in an equivalent representation being 3865 sent in a 200 (OK) response. However, there is no guarantee that 3866 such a state change will be observable, since the target resource 3867 might be acted upon by other user agents in parallel, or might be 3868 subject to dynamic processing by the origin server, before any 3869 subsequent GET is received. A successful response only implies that 3870 the user agent's intent was achieved at the time of its processing by 3871 the origin server. 3873 If the target resource does not have a current representation and the 3874 PUT successfully creates one, then the origin server MUST inform the 3875 user agent by sending a 201 (Created) response. If the target 3876 resource does have a current representation and that representation 3877 is successfully modified in accordance with the state of the enclosed 3878 representation, then the origin server MUST send either a 200 (OK) or 3879 a 204 (No Content) response to indicate successful completion of the 3880 request. 3882 An origin server SHOULD ignore unrecognized header and trailer fields 3883 received in a PUT request (i.e., do not save them as part of the 3884 resource state). 3886 An origin server SHOULD verify that the PUT representation is 3887 consistent with any constraints the server has for the target 3888 resource that cannot or will not be changed by the PUT. This is 3889 particularly important when the origin server uses internal 3890 configuration information related to the URI in order to set the 3891 values for representation metadata on GET responses. When a PUT 3892 representation is inconsistent with the target resource, the origin 3893 server SHOULD either make them consistent, by transforming the 3894 representation or changing the resource configuration, or respond 3895 with an appropriate error message containing sufficient information 3896 to explain why the representation is unsuitable. The 409 (Conflict) 3897 or 415 (Unsupported Media Type) status codes are suggested, with the 3898 latter being specific to constraints on Content-Type values. 3900 For example, if the target resource is configured to always have a 3901 Content-Type of "text/html" and the representation being PUT has a 3902 Content-Type of "image/jpeg", the origin server ought to do one of: 3904 a. reconfigure the target resource to reflect the new media type; 3906 b. transform the PUT representation to a format consistent with that 3907 of the resource before saving it as the new resource state; or, 3909 c. reject the request with a 415 (Unsupported Media Type) response 3910 indicating that the target resource is limited to "text/html", 3911 perhaps including a link to a different resource that would be a 3912 suitable target for the new representation. 3914 HTTP does not define exactly how a PUT method affects the state of an 3915 origin server beyond what can be expressed by the intent of the user 3916 agent request and the semantics of the origin server response. It 3917 does not define what a resource might be, in any sense of that word, 3918 beyond the interface provided via HTTP. It does not define how 3919 resource state is "stored", nor how such storage might change as a 3920 result of a change in resource state, nor how the origin server 3921 translates resource state into representations. Generally speaking, 3922 all implementation details behind the resource interface are 3923 intentionally hidden by the server. 3925 An origin server MUST NOT send a validator header field 3926 (Section 7.9), such as an ETag or Last-Modified field, in a 3927 successful response to PUT unless the request's representation data 3928 was saved without any transformation applied to the body (i.e., the 3929 resource's new representation data is identical to the representation 3930 data received in the PUT request) and the validator field value 3931 reflects the new representation. This requirement allows a user 3932 agent to know when the representation body it has in memory remains 3933 current as a result of the PUT, thus not in need of being retrieved 3934 again from the origin server, and that the new validator(s) received 3935 in the response can be used for future conditional requests in order 3936 to prevent accidental overwrites (Section 12.1). 3938 The fundamental difference between the POST and PUT methods is 3939 highlighted by the different intent for the enclosed representation. 3940 The target resource in a POST request is intended to handle the 3941 enclosed representation according to the resource's own semantics, 3942 whereas the enclosed representation in a PUT request is defined as 3943 replacing the state of the target resource. Hence, the intent of PUT 3944 is idempotent and visible to intermediaries, even though the exact 3945 effect is only known by the origin server. 3947 Proper interpretation of a PUT request presumes that the user agent 3948 knows which target resource is desired. A service that selects a 3949 proper URI on behalf of the client, after receiving a state-changing 3950 request, SHOULD be implemented using the POST method rather than PUT. 3951 If the origin server will not make the requested PUT state change to 3952 the target resource and instead wishes to have it applied to a 3953 different resource, such as when the resource has been moved to a 3954 different URI, then the origin server MUST send an appropriate 3xx 3955 (Redirection) response; the user agent MAY then make its own decision 3956 regarding whether or not to redirect the request. 3958 A PUT request applied to the target resource can have side effects on 3959 other resources. For example, an article might have a URI for 3960 identifying "the current version" (a resource) that is separate from 3961 the URIs identifying each particular version (different resources 3962 that at one point shared the same state as the current version 3963 resource). A successful PUT request on "the current version" URI 3964 might therefore create a new version resource in addition to changing 3965 the state of the target resource, and might also cause links to be 3966 added between the related resources. 3968 An origin server that allows PUT on a given target resource MUST send 3969 a 400 (Bad Request) response to a PUT request that contains a 3970 Content-Range header field (Section 13.4), since the payload is 3971 likely to be partial content that has been mistakenly PUT as a full 3972 representation. Partial content updates are possible by targeting a 3973 separately identified resource with state that overlaps a portion of 3974 the larger resource, or by using a different method that has been 3975 specifically defined for partial updates (for example, the PATCH 3976 method defined in [RFC5789]). 3978 Responses to the PUT method are not cacheable. If a successful PUT 3979 request passes through a cache that has one or more stored responses 3980 for the target URI, those stored responses will be invalidated (see 3981 Section 4.4 of [Caching]). 3983 8.3.5. DELETE 3985 The DELETE method requests that the origin server remove the 3986 association between the target resource and its current 3987 functionality. In effect, this method is similar to the rm command 3988 in UNIX: it expresses a deletion operation on the URI mapping of the 3989 origin server rather than an expectation that the previously 3990 associated information be deleted. 3992 If the target resource has one or more current representations, they 3993 might or might not be destroyed by the origin server, and the 3994 associated storage might or might not be reclaimed, depending 3995 entirely on the nature of the resource and its implementation by the 3996 origin server (which are beyond the scope of this specification). 3997 Likewise, other implementation aspects of a resource might need to be 3998 deactivated or archived as a result of a DELETE, such as database or 3999 gateway connections. In general, it is assumed that the origin 4000 server will only allow DELETE on resources for which it has a 4001 prescribed mechanism for accomplishing the deletion. 4003 Relatively few resources allow the DELETE method - its primary use is 4004 for remote authoring environments, where the user has some direction 4005 regarding its effect. For example, a resource that was previously 4006 created using a PUT request, or identified via the Location header 4007 field after a 201 (Created) response to a POST request, might allow a 4008 corresponding DELETE request to undo those actions. Similarly, 4009 custom user agent implementations that implement an authoring 4010 function, such as revision control clients using HTTP for remote 4011 operations, might use DELETE based on an assumption that the server's 4012 URI space has been crafted to correspond to a version repository. 4014 If a DELETE method is successfully applied, the origin server SHOULD 4015 send 4017 o a 202 (Accepted) status code if the action will likely succeed but 4018 has not yet been enacted, 4020 o a 204 (No Content) status code if the action has been enacted and 4021 no further information is to be supplied, or 4023 o a 200 (OK) status code if the action has been enacted and the 4024 response message includes a representation describing the status. 4026 A client SHOULD NOT generate a body in a DELETE request. A payload 4027 received in a DELETE request has no defined semantics, cannot alter 4028 the meaning or target of the request, and might lead some 4029 implementations to reject the request. 4031 Responses to the DELETE method are not cacheable. If a successful 4032 DELETE request passes through a cache that has one or more stored 4033 responses for the target URI, those stored responses will be 4034 invalidated (see Section 4.4 of [Caching]). 4036 8.3.6. CONNECT 4038 The CONNECT method requests that the recipient establish a tunnel to 4039 the destination origin server identified by the request target and, 4040 if successful, thereafter restrict its behavior to blind forwarding 4041 of data, in both directions, until the tunnel is closed. Tunnels are 4042 commonly used to create an end-to-end virtual connection, through one 4043 or more proxies, which can then be secured using TLS (Transport Layer 4044 Security, [RFC8446]). 4046 Because CONNECT changes the request/response nature of an HTTP 4047 connection, specific HTTP versions might have different ways of 4048 mapping its semantics into the protocol's wire format. 4050 CONNECT is intended only for use in requests to a proxy. An origin 4051 server that receives a CONNECT request for itself MAY respond with a 4052 2xx (Successful) status code to indicate that a connection is 4053 established. However, most origin servers do not implement CONNECT. 4055 A client sending a CONNECT request MUST send the authority component 4056 (described in Section 3.2 of [RFC3986]) as the request target; i.e., 4057 the request target consists of only the host name and port number of 4058 the tunnel destination, separated by a colon. For example, 4060 CONNECT server.example.com:80 HTTP/1.1 4061 Host: server.example.com:80 4063 The recipient proxy can establish a tunnel either by directly 4064 connecting to the request target or, if configured to use another 4065 proxy, by forwarding the CONNECT request to the next inbound proxy. 4066 Any 2xx (Successful) response indicates that the sender (and all 4067 inbound proxies) will switch to tunnel mode immediately after the 4068 blank line that concludes the successful response's header section; 4069 data received after that blank line is from the server identified by 4070 the request target. Any response other than a successful response 4071 indicates that the tunnel has not yet been formed and that the 4072 connection remains governed by HTTP. 4074 A tunnel is closed when a tunnel intermediary detects that either 4075 side has closed its connection: the intermediary MUST attempt to send 4076 any outstanding data that came from the closed side to the other 4077 side, close both connections, and then discard any remaining data 4078 left undelivered. 4080 Proxy authentication might be used to establish the authority to 4081 create a tunnel. For example, 4083 CONNECT server.example.com:80 HTTP/1.1 4084 Host: server.example.com:80 4085 Proxy-Authorization: basic aGVsbG86d29ybGQ= 4087 There are significant risks in establishing a tunnel to arbitrary 4088 servers, particularly when the destination is a well-known or 4089 reserved TCP port that is not intended for Web traffic. For example, 4090 a CONNECT to "example.com:25" would suggest that the proxy connect to 4091 the reserved port for SMTP traffic; if allowed, that could trick the 4092 proxy into relaying spam email. Proxies that support CONNECT SHOULD 4093 restrict its use to a limited set of known ports or a configurable 4094 whitelist of safe request targets. 4096 A server MUST NOT send any Transfer-Encoding or Content-Length header 4097 fields in a 2xx (Successful) response to CONNECT. A client MUST 4098 ignore any Content-Length or Transfer-Encoding header fields received 4099 in a successful response to CONNECT. 4101 A payload within a CONNECT request message has no defined semantics; 4102 sending a payload body on a CONNECT request might cause some existing 4103 implementations to reject the request. 4105 Responses to the CONNECT method are not cacheable. 4107 8.3.7. OPTIONS 4109 The OPTIONS method requests information about the communication 4110 options available for the target resource, at either the origin 4111 server or an intervening intermediary. This method allows a client 4112 to determine the options and/or requirements associated with a 4113 resource, or the capabilities of a server, without implying a 4114 resource action. 4116 An OPTIONS request with an asterisk ("*") as the request target 4117 (Section 6.1) applies to the server in general rather than to a 4118 specific resource. Since a server's communication options typically 4119 depend on the resource, the "*" request is only useful as a "ping" or 4120 "no-op" type of method; it does nothing beyond allowing the client to 4121 test the capabilities of the server. For example, this can be used 4122 to test a proxy for HTTP/1.1 conformance (or lack thereof). 4124 If the request target is not an asterisk, the OPTIONS request applies 4125 to the options that are available when communicating with the target 4126 resource. 4128 A server generating a successful response to OPTIONS SHOULD send any 4129 header that might indicate optional features implemented by the 4130 server and applicable to the target resource (e.g., Allow), including 4131 potential extensions not defined by this specification. The response 4132 payload, if any, might also describe the communication options in a 4133 machine or human-readable representation. A standard format for such 4134 a representation is not defined by this specification, but might be 4135 defined by future extensions to HTTP. 4137 A client MAY send a Max-Forwards header field in an OPTIONS request 4138 to target a specific recipient in the request chain (see 4139 Section 6.4.2). A proxy MUST NOT generate a Max-Forwards header 4140 field while forwarding a request unless that request was received 4141 with a Max-Forwards field. 4143 A client that generates an OPTIONS request containing a payload body 4144 MUST send a valid Content-Type header field describing the 4145 representation media type. Note that this specification does not 4146 define any use for such a payload. 4148 Responses to the OPTIONS method are not cacheable. 4150 8.3.8. TRACE 4152 The TRACE method requests a remote, application-level loop-back of 4153 the request message. The final recipient of the request SHOULD 4154 reflect the message received, excluding some fields described below, 4155 back to the client as the message body of a 200 (OK) response with a 4156 Content-Type of "message/http" (Section 10.1 of [Messaging]). The 4157 final recipient is either the origin server or the first server to 4158 receive a Max-Forwards value of zero (0) in the request 4159 (Section 6.4.2). 4161 A client MUST NOT generate fields in a TRACE request containing 4162 sensitive data that might be disclosed by the response. For example, 4163 it would be foolish for a user agent to send stored user credentials 4164 Section 10 or cookies [RFC6265] in a TRACE request. The final 4165 recipient of the request SHOULD exclude any request fields that are 4166 likely to contain sensitive data when that recipient generates the 4167 response body. 4169 TRACE allows the client to see what is being received at the other 4170 end of the request chain and use that data for testing or diagnostic 4171 information. The value of the Via header field (Section 6.4.3) is of 4172 particular interest, since it acts as a trace of the request chain. 4173 Use of the Max-Forwards header field allows the client to limit the 4174 length of the request chain, which is useful for testing a chain of 4175 proxies forwarding messages in an infinite loop. 4177 A client MUST NOT send a message body in a TRACE request. 4179 Responses to the TRACE method are not cacheable. 4181 9. Context 4183 9.1. Request Context 4185 A client sends request header fields to provide more information 4186 about the request context, make the request conditional based on the 4187 target resource state, suggest preferred formats for the response, 4188 supply authentication credentials, or modify the expected request 4189 processing. These fields act as request modifiers, similar to the 4190 parameters on a programming language method invocation. 4192 The following request header fields provide additional information 4193 about the request context, including information about the user, user 4194 agent, and resource behind the request. 4196 ------------ ------- 4197 Field Name Ref. 4198 ------------ ------- 4199 Expect 9.1.1 4200 From 9.1.2 4201 Referer 9.1.3 4202 TE 9.1.4 4203 Trailer 9.1.5 4204 User-Agent 9.1.6 4205 ------------ ------- 4207 Table 8 4209 9.1.1. Expect 4211 The "Expect" header field in a request indicates a certain set of 4212 behaviors (expectations) that need to be supported by the server in 4213 order to properly handle this request. 4215 Expect = #expectation 4216 expectation = token [ "=" ( token / quoted-string ) parameters ] 4218 The Expect field value is case-insensitive. 4220 The only expectation defined by this specification is "100-continue" 4221 (with no defined parameters). 4223 A server that receives an Expect field value containing a member 4224 other than 100-continue MAY respond with a 417 (Expectation Failed) 4225 status code to indicate that the unexpected expectation cannot be 4226 met. 4228 A 100-continue expectation informs recipients that the client is 4229 about to send a (presumably large) message body in this request and 4230 wishes to receive a 100 (Continue) interim response if the method, 4231 target URI, and header fields are not sufficient to cause an 4232 immediate success, redirect, or error response. This allows the 4233 client to wait for an indication that it is worthwhile to send the 4234 message body before actually doing so, which can improve efficiency 4235 when the message body is huge or when the client anticipates that an 4236 error is likely (e.g., when sending a state-changing method, for the 4237 first time, without previously verified authentication credentials). 4239 For example, a request that begins with 4241 PUT /somewhere/fun HTTP/1.1 4242 Host: origin.example.com 4243 Content-Type: video/h264 4244 Content-Length: 1234567890987 4245 Expect: 100-continue 4247 allows the origin server to immediately respond with an error 4248 message, such as 401 (Unauthorized) or 405 (Method Not Allowed), 4249 before the client starts filling the pipes with an unnecessary data 4250 transfer. 4252 Requirements for clients: 4254 o A client MUST NOT generate a 100-continue expectation in a request 4255 that does not include a message body. 4257 o A client that will wait for a 100 (Continue) response before 4258 sending the request message body MUST send an Expect header field 4259 containing a 100-continue expectation. 4261 o A client that sends a 100-continue expectation is not required to 4262 wait for any specific length of time; such a client MAY proceed to 4263 send the message body even if it has not yet received a response. 4264 Furthermore, since 100 (Continue) responses cannot be sent through 4265 an HTTP/1.0 intermediary, such a client SHOULD NOT wait for an 4266 indefinite period before sending the message body. 4268 o A client that receives a 417 (Expectation Failed) status code in 4269 response to a request containing a 100-continue expectation SHOULD 4270 repeat that request without a 100-continue expectation, since the 4271 417 response merely indicates that the response chain does not 4272 support expectations (e.g., it passes through an HTTP/1.0 server). 4274 Requirements for servers: 4276 o A server that receives a 100-continue expectation in an HTTP/1.0 4277 request MUST ignore that expectation. 4279 o A server MAY omit sending a 100 (Continue) response if it has 4280 already received some or all of the message body for the 4281 corresponding request, or if the framing indicates that there is 4282 no message body. 4284 o A server that sends a 100 (Continue) response MUST ultimately send 4285 a final status code, once the message body is received and 4286 processed, unless the connection is closed prematurely. 4288 o A server that responds with a final status code before reading the 4289 entire request payload body SHOULD indicate whether it intends to 4290 close the connection (e.g., see Section 9.6 of [Messaging]) or 4291 continue reading the payload body. 4293 An origin server MUST, upon receiving an HTTP/1.1 (or later) request 4294 that has a method, target URI, and complete header section that 4295 contains a 100-continue expectation and indicates a request message 4296 body will follow, either send an immediate response with a final 4297 status code, if that status can be determined by examining just the 4298 method, target URI, and header fields, or send an immediate 100 4299 (Continue) response to encourage the client to send the request's 4300 message body. The origin server MUST NOT wait for the message body 4301 before sending the 100 (Continue) response. 4303 A proxy MUST, upon receiving an HTTP/1.1 (or later) request that has 4304 a method, target URI, and complete header section that contains a 4305 100-continue expectation and indicates a request message body will 4306 follow, either send an immediate response with a final status code, 4307 if that status can be determined by examining just the method, target 4308 URI, and header fields, or begin forwarding the request toward the 4309 origin server by sending a corresponding request-line and header 4310 section to the next inbound server. If the proxy believes (from 4311 configuration or past interaction) that the next inbound server only 4312 supports HTTP/1.0, the proxy MAY generate an immediate 100 (Continue) 4313 response to encourage the client to begin sending the message body. 4315 | *Note:* The Expect header field was added after the original 4316 | publication of HTTP/1.1 [RFC2068] as both the means to request 4317 | an interim 100 (Continue) response and the general mechanism 4318 | for indicating must-understand extensions. However, the 4319 | extension mechanism has not been used by clients and the must- 4320 | understand requirements have not been implemented by many 4321 | servers, rendering the extension mechanism useless. This 4322 | specification has removed the extension mechanism in order to 4323 | simplify the definition and processing of 100-continue. 4325 9.1.2. From 4327 The "From" header field contains an Internet email address for a 4328 human user who controls the requesting user agent. The address ought 4329 to be machine-usable, as defined by "mailbox" in Section 3.4 of 4330 [RFC5322]: 4332 From = mailbox 4334 mailbox = 4336 An example is: 4338 From: webmaster@example.org 4340 The From header field is rarely sent by non-robotic user agents. A 4341 user agent SHOULD NOT send a From header field without explicit 4342 configuration by the user, since that might conflict with the user's 4343 privacy interests or their site's security policy. 4345 A robotic user agent SHOULD send a valid From header field so that 4346 the person responsible for running the robot can be contacted if 4347 problems occur on servers, such as if the robot is sending excessive, 4348 unwanted, or invalid requests. 4350 A server SHOULD NOT use the From header field for access control or 4351 authentication, since most recipients will assume that the field 4352 value is public information. 4354 9.1.3. Referer 4356 The "Referer" [sic] header field allows the user agent to specify a 4357 URI reference for the resource from which the target URI was obtained 4358 (i.e., the "referrer", though the field name is misspelled). A user 4359 agent MUST NOT include the fragment and userinfo components of the 4360 URI reference [RFC3986], if any, when generating the Referer field 4361 value. 4363 Referer = absolute-URI / partial-URI 4365 The field value is either an absolute-URI or a partial-URI. In the 4366 latter case (Section 4), the referenced URI is relative to the target 4367 URI ([RFC3986], Section 5). 4369 The Referer header field allows servers to generate back-links to 4370 other resources for simple analytics, logging, optimized caching, 4371 etc. It also allows obsolete or mistyped links to be found for 4372 maintenance. Some servers use the Referer header field as a means of 4373 denying links from other sites (so-called "deep linking") or 4374 restricting cross-site request forgery (CSRF), but not all requests 4375 contain it. 4377 Example: 4379 Referer: http://www.example.org/hypertext/Overview.html 4381 If the target URI was obtained from a source that does not have its 4382 own URI (e.g., input from the user keyboard, or an entry within the 4383 user's bookmarks/favorites), the user agent MUST either exclude the 4384 Referer field or send it with a value of "about:blank". 4386 The Referer field has the potential to reveal information about the 4387 request context or browsing history of the user, which is a privacy 4388 concern if the referring resource's identifier reveals personal 4389 information (such as an account name) or a resource that is supposed 4390 to be confidential (such as behind a firewall or internal to a 4391 secured service). Most general-purpose user agents do not send the 4392 Referer header field when the referring resource is a local "file" or 4393 "data" URI. A user agent MUST NOT send a Referer header field in an 4394 unsecured HTTP request if the referring page was received with a 4395 secure protocol. See Section 16.9 for additional security 4396 considerations. 4398 Some intermediaries have been known to indiscriminately remove 4399 Referer header fields from outgoing requests. This has the 4400 unfortunate side effect of interfering with protection against CSRF 4401 attacks, which can be far more harmful to their users. 4402 Intermediaries and user agent extensions that wish to limit 4403 information disclosure in Referer ought to restrict their changes to 4404 specific edits, such as replacing internal domain names with 4405 pseudonyms or truncating the query and/or path components. An 4406 intermediary SHOULD NOT modify or delete the Referer header field 4407 when the field value shares the same scheme and host as the target 4408 URI. 4410 9.1.4. TE 4412 The "TE" header field in a request can be used to indicate that the 4413 sender will not discard trailer fields when it contains a "trailers" 4414 member, as described in Section 5.6. 4416 Additionally, specific HTTP versions can use it to indicate the 4417 transfer codings the client is willing to accept in the response. 4419 The TE field-value consists of a list of tokens, each allowing for 4420 optional parameters (as described in Section 5.7.6). 4422 TE = #t-codings 4423 t-codings = "trailers" / ( transfer-coding [ t-ranking ] ) 4424 t-ranking = OWS ";" OWS "q=" rank 4425 rank = ( "0" [ "." 0*3DIGIT ] ) 4426 / ( "1" [ "." 0*3("0") ] ) 4428 9.1.5. Trailer 4430 The "Trailer" header field provides a list of field names that the 4431 sender anticipates sending as trailer fields within that message. 4432 This allows a recipient to prepare for receipt of the indicated 4433 metadata before it starts processing the body. 4435 Trailer = #field-name 4437 For example, a sender might indicate that a message integrity check 4438 will be computed as the payload is being streamed and provide the 4439 final signature as a trailer field. This allows a recipient to 4440 perform the same check on the fly as the payload data is received. 4442 A sender that intends to generate one or more trailer fields in a 4443 message SHOULD generate a Trailer header field in the header section 4444 of that message to indicate which fields might be present in the 4445 trailers. 4447 9.1.6. User-Agent 4449 The "User-Agent" header field contains information about the user 4450 agent originating the request, which is often used by servers to help 4451 identify the scope of reported interoperability problems, to work 4452 around or tailor responses to avoid particular user agent 4453 limitations, and for analytics regarding browser or operating system 4454 use. A user agent SHOULD send a User-Agent field in each request 4455 unless specifically configured not to do so. 4457 User-Agent = product *( RWS ( product / comment ) ) 4459 The User-Agent field value consists of one or more product 4460 identifiers, each followed by zero or more comments (Section 5.7.5), 4461 which together identify the user agent software and its significant 4462 subproducts. By convention, the product identifiers are listed in 4463 decreasing order of their significance for identifying the user agent 4464 software. Each product identifier consists of a name and optional 4465 version. 4467 product = token ["/" product-version] 4468 product-version = token 4470 A sender SHOULD limit generated product identifiers to what is 4471 necessary to identify the product; a sender MUST NOT generate 4472 advertising or other nonessential information within the product 4473 identifier. A sender SHOULD NOT generate information in 4474 product-version that is not a version identifier (i.e., successive 4475 versions of the same product name ought to differ only in the 4476 product-version portion of the product identifier). 4478 Example: 4480 User-Agent: CERN-LineMode/2.15 libwww/2.17b3 4482 A user agent SHOULD NOT generate a User-Agent field containing 4483 needlessly fine-grained detail and SHOULD limit the addition of 4484 subproducts by third parties. Overly long and detailed User-Agent 4485 field values increase request latency and the risk of a user being 4486 identified against their wishes ("fingerprinting"). 4488 Likewise, implementations are encouraged not to use the product 4489 tokens of other implementations in order to declare compatibility 4490 with them, as this circumvents the purpose of the field. If a user 4491 agent masquerades as a different user agent, recipients can assume 4492 that the user intentionally desires to see responses tailored for 4493 that identified user agent, even if they might not work as well for 4494 the actual user agent being used. 4496 9.2. Response Context 4498 Response header fields can supply control data that supplements the 4499 status code, directs caching, or instructs the client where to go 4500 next. 4502 The response header fields allow the server to pass additional 4503 information about the response beyond the status code. These header 4504 fields give information about the server, about further access to the 4505 target resource, or about related resources. 4507 Although each response header field has a defined meaning, in 4508 general, the precise semantics might be further refined by the 4509 semantics of the request method and/or response status code. 4511 The remaining response header fields provide more information about 4512 the target resource for potential use in later requests. 4514 ------------- ------- 4515 Field Name Ref. 4516 ------------- ------- 4517 Allow 9.2.1 4518 Date 9.2.2 4519 Location 9.2.3 4520 Retry-After 9.2.4 4521 Server 9.2.5 4522 ------------- ------- 4524 Table 9 4526 9.2.1. Allow 4528 The "Allow" header field lists the set of methods advertised as 4529 supported by the target resource. The purpose of this field is 4530 strictly to inform the recipient of valid request methods associated 4531 with the resource. 4533 Allow = #method 4535 Example of use: 4537 Allow: GET, HEAD, PUT 4539 The actual set of allowed methods is defined by the origin server at 4540 the time of each request. An origin server MUST generate an Allow 4541 field in a 405 (Method Not Allowed) response and MAY do so in any 4542 other response. An empty Allow field value indicates that the 4543 resource allows no methods, which might occur in a 405 response if 4544 the resource has been temporarily disabled by configuration. 4546 A proxy MUST NOT modify the Allow header field - it does not need to 4547 understand all of the indicated methods in order to handle them 4548 according to the generic message handling rules. 4550 9.2.2. Date 4552 The "Date" header field represents the date and time at which the 4553 message was originated, having the same semantics as the Origination 4554 Date Field (orig-date) defined in Section 3.6.1 of [RFC5322]. The 4555 field value is an HTTP-date, as defined in Section 5.7.7. 4557 Date = HTTP-date 4559 An example is 4561 Date: Tue, 15 Nov 1994 08:12:31 GMT 4563 When a Date header field is generated, the sender SHOULD generate its 4564 field value as the best available approximation of the date and time 4565 of message generation. In theory, the date ought to represent the 4566 moment just before the payload is generated. In practice, the date 4567 can be generated at any time during message origination. 4569 An origin server MUST NOT send a Date header field if it does not 4570 have a clock capable of providing a reasonable approximation of the 4571 current instance in Coordinated Universal Time. An origin server MAY 4572 send a Date header field if the response is in the 1xx 4573 (Informational) or 5xx (Server Error) class of status codes. An 4574 origin server MUST send a Date header field in all other cases. 4576 A recipient with a clock that receives a response message without a 4577 Date header field MUST record the time it was received and append a 4578 corresponding Date header field to the message's header section if it 4579 is cached or forwarded downstream. 4581 A user agent MAY send a Date header field in a request, though 4582 generally will not do so unless it is believed to convey useful 4583 information to the server. For example, custom applications of HTTP 4584 might convey a Date if the server is expected to adjust its 4585 interpretation of the user's request based on differences between the 4586 user agent and server clocks. 4588 9.2.3. Location 4590 The "Location" header field is used in some responses to refer to a 4591 specific resource in relation to the response. The type of 4592 relationship is defined by the combination of request method and 4593 status code semantics. 4595 Location = URI-reference 4597 The field value consists of a single URI-reference. When it has the 4598 form of a relative reference ([RFC3986], Section 4.2), the final 4599 value is computed by resolving it against the target URI ([RFC3986], 4600 Section 5). 4602 For 201 (Created) responses, the Location value refers to the primary 4603 resource created by the request. For 3xx (Redirection) responses, 4604 the Location value refers to the preferred target resource for 4605 automatically redirecting the request. 4607 If the Location value provided in a 3xx (Redirection) response does 4608 not have a fragment component, a user agent MUST process the 4609 redirection as if the value inherits the fragment component of the 4610 URI reference used to generate the target URI (i.e., the redirection 4611 inherits the original reference's fragment, if any). 4613 For example, a GET request generated for the URI reference 4614 "http://www.example.org/~tim" might result in a 303 (See Other) 4615 response containing the header field: 4617 Location: /People.html#tim 4619 which suggests that the user agent redirect to 4620 "http://www.example.org/People.html#tim" 4622 Likewise, a GET request generated for the URI reference 4623 "http://www.example.org/index.html#larry" might result in a 301 4624 (Moved Permanently) response containing the header field: 4626 Location: http://www.example.net/index.html 4628 which suggests that the user agent redirect to 4629 "http://www.example.net/index.html#larry", preserving the original 4630 fragment identifier. 4632 There are circumstances in which a fragment identifier in a Location 4633 value would not be appropriate. For example, the Location header 4634 field in a 201 (Created) response is supposed to provide a URI that 4635 is specific to the created resource. 4637 | *Note:* Some recipients attempt to recover from Location fields 4638 | that are not valid URI references. This specification does not 4639 | mandate or define such processing, but does allow it for the 4640 | sake of robustness. A Location field value cannot allow a list 4641 | of members because the comma list separator is a valid data 4642 | character within a URI-reference. If an invalid message is 4643 | sent with multiple Location field instances, a recipient along 4644 | the path might combine the field instances into one value. 4645 | Recovery of a valid Location field value from that situation is 4646 | difficult and not interoperable across implementations. 4648 | *Note:* The Content-Location header field (Section 7.8) differs 4649 | from Location in that the Content-Location refers to the most 4650 | specific resource corresponding to the enclosed representation. 4651 | It is therefore possible for a response to contain both the 4652 | Location and Content-Location header fields. 4654 9.2.4. Retry-After 4656 Servers send the "Retry-After" header field to indicate how long the 4657 user agent ought to wait before making a follow-up request. When 4658 sent with a 503 (Service Unavailable) response, Retry-After indicates 4659 how long the service is expected to be unavailable to the client. 4660 When sent with any 3xx (Redirection) response, Retry-After indicates 4661 the minimum time that the user agent is asked to wait before issuing 4662 the redirected request. 4664 The value of this field can be either an HTTP-date or a number of 4665 seconds to delay after the response is received. 4667 Retry-After = HTTP-date / delay-seconds 4669 A delay-seconds value is a non-negative decimal integer, representing 4670 time in seconds. 4672 delay-seconds = 1*DIGIT 4674 Two examples of its use are 4676 Retry-After: Fri, 31 Dec 1999 23:59:59 GMT 4677 Retry-After: 120 4679 In the latter example, the delay is 2 minutes. 4681 9.2.5. Server 4683 The "Server" header field contains information about the software 4684 used by the origin server to handle the request, which is often used 4685 by clients to help identify the scope of reported interoperability 4686 problems, to work around or tailor requests to avoid particular 4687 server limitations, and for analytics regarding server or operating 4688 system use. An origin server MAY generate a Server field in its 4689 responses. 4691 Server = product *( RWS ( product / comment ) ) 4693 The Server field value consists of one or more product identifiers, 4694 each followed by zero or more comments (Section 5.7.5), which 4695 together identify the origin server software and its significant 4696 subproducts. By convention, the product identifiers are listed in 4697 decreasing order of their significance for identifying the origin 4698 server software. Each product identifier consists of a name and 4699 optional version, as defined in Section 9.1.6. 4701 Example: 4703 Server: CERN/3.0 libwww/2.17 4705 An origin server SHOULD NOT generate a Server field containing 4706 needlessly fine-grained detail and SHOULD limit the addition of 4707 subproducts by third parties. Overly long and detailed Server field 4708 values increase response latency and potentially reveal internal 4709 implementation details that might make it (slightly) easier for 4710 attackers to find and exploit known security holes. 4712 10. Authentication 4714 10.1. Authentication Scheme 4716 HTTP provides a general framework for access control and 4717 authentication, via an extensible set of challenge-response 4718 authentication schemes, which can be used by a server to challenge a 4719 client request and by a client to provide authentication information. 4720 It uses a case-insensitive token to identify the authentication 4721 scheme 4723 auth-scheme = token 4725 Aside from the general framework, this document does not specify any 4726 authentication schemes. New and existing authentication schemes are 4727 specified independently and ought to be registered within the 4728 "Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry". 4729 For example, the "basic" and "digest" authentication schemes are 4730 defined by RFC 7617 and RFC 7616, respectively. 4732 10.2. Authentication Parameters 4734 The authentication scheme is followed by additional information 4735 necessary for achieving authentication via that scheme as either a 4736 comma-separated list of parameters or a single sequence of characters 4737 capable of holding base64-encoded information. 4739 token68 = 1*( ALPHA / DIGIT / 4740 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 4742 The token68 syntax allows the 66 unreserved URI characters 4743 ([RFC3986]), plus a few others, so that it can hold a base64, 4744 base64url (URL and filename safe alphabet), base32, or base16 (hex) 4745 encoding, with or without padding, but excluding whitespace 4746 ([RFC4648]). 4748 Authentication parameters are name=value pairs, where the name token 4749 is matched case-insensitively and each parameter name MUST only occur 4750 once per challenge. 4752 auth-param = token BWS "=" BWS ( token / quoted-string ) 4754 Parameter values can be expressed either as "token" or as "quoted- 4755 string" (Section 5.7). Authentication scheme definitions need to 4756 accept both notations, both for senders and recipients, to allow 4757 recipients to use generic parsing components regardless of the 4758 authentication scheme. 4760 For backwards compatibility, authentication scheme definitions can 4761 restrict the format for senders to one of the two variants. This can 4762 be important when it is known that deployed implementations will fail 4763 when encountering one of the two formats. 4765 10.3. Challenge and Response 4767 A 401 (Unauthorized) response message is used by an origin server to 4768 challenge the authorization of a user agent, including a 4769 WWW-Authenticate header field containing at least one challenge 4770 applicable to the requested resource. 4772 A 407 (Proxy Authentication Required) response message is used by a 4773 proxy to challenge the authorization of a client, including a 4774 Proxy-Authenticate header field containing at least one challenge 4775 applicable to the proxy for the requested resource. 4777 challenge = auth-scheme [ 1*SP ( token68 / #auth-param ) ] 4779 | *Note:* Many clients fail to parse a challenge that contains an 4780 | unknown scheme. A workaround for this problem is to list well- 4781 | supported schemes (such as "basic") first. 4783 A user agent that wishes to authenticate itself with an origin server 4784 - usually, but not necessarily, after receiving a 401 (Unauthorized) 4785 - can do so by including an Authorization header field with the 4786 request. 4788 A client that wishes to authenticate itself with a proxy - usually, 4789 but not necessarily, after receiving a 407 (Proxy Authentication 4790 Required) - can do so by including a Proxy-Authorization header field 4791 with the request. 4793 10.4. Credentials 4795 Both the Authorization field value and the Proxy-Authorization field 4796 value contain the client's credentials for the realm of the resource 4797 being requested, based upon a challenge received in a response 4798 (possibly at some point in the past). When creating their values, 4799 the user agent ought to do so by selecting the challenge with what it 4800 considers to be the most secure auth-scheme that it understands, 4801 obtaining credentials from the user as appropriate. Transmission of 4802 credentials within header field values implies significant security 4803 considerations regarding the confidentiality of the underlying 4804 connection, as described in Section 16.15.1. 4806 credentials = auth-scheme [ 1*SP ( token68 / #auth-param ) ] 4808 Upon receipt of a request for a protected resource that omits 4809 credentials, contains invalid credentials (e.g., a bad password) or 4810 partial credentials (e.g., when the authentication scheme requires 4811 more than one round trip), an origin server SHOULD send a 401 4812 (Unauthorized) response that contains a WWW-Authenticate header field 4813 with at least one (possibly new) challenge applicable to the 4814 requested resource. 4816 Likewise, upon receipt of a request that omits proxy credentials or 4817 contains invalid or partial proxy credentials, a proxy that requires 4818 authentication SHOULD generate a 407 (Proxy Authentication Required) 4819 response that contains a Proxy-Authenticate header field with at 4820 least one (possibly new) challenge applicable to the proxy. 4822 A server that receives valid credentials that are not adequate to 4823 gain access ought to respond with the 403 (Forbidden) status code 4824 (Section 14.5.4). 4826 HTTP does not restrict applications to this simple challenge-response 4827 framework for access authentication. Additional mechanisms can be 4828 used, such as authentication at the transport level or via message 4829 encapsulation, and with additional header fields specifying 4830 authentication information. However, such additional mechanisms are 4831 not defined by this specification. 4833 Note that various custom mechanisms for user authentication use the 4834 Set-Cookie and Cookie header fields, defined in [RFC6265], for 4835 passing tokens related to authentication. 4837 10.5. Protection Space (Realm) 4839 The "realm" authentication parameter is reserved for use by 4840 authentication schemes that wish to indicate a scope of protection. 4842 A protection space is defined by the canonical root URI (the scheme 4843 and authority components of the target URI; see Section 6.1) of the 4844 server being accessed, in combination with the realm value if 4845 present. These realms allow the protected resources on a server to 4846 be partitioned into a set of protection spaces, each with its own 4847 authentication scheme and/or authorization database. The realm value 4848 is a string, generally assigned by the origin server, that can have 4849 additional semantics specific to the authentication scheme. Note 4850 that a response can have multiple challenges with the same auth- 4851 scheme but with different realms. 4853 The protection space determines the domain over which credentials can 4854 be automatically applied. If a prior request has been authorized, 4855 the user agent MAY reuse the same credentials for all other requests 4856 within that protection space for a period of time determined by the 4857 authentication scheme, parameters, and/or user preferences (such as a 4858 configurable inactivity timeout). Unless specifically allowed by the 4859 authentication scheme, a single protection space cannot extend 4860 outside the scope of its server. 4862 For historical reasons, a sender MUST only generate the quoted-string 4863 syntax. Recipients might have to support both token and quoted- 4864 string syntax for maximum interoperability with existing clients that 4865 have been accepting both notations for a long time. 4867 10.6. Authenticating User to Origin Server 4869 10.6.1. WWW-Authenticate 4871 The "WWW-Authenticate" header field indicates the authentication 4872 scheme(s) and parameters applicable to the target resource. 4874 WWW-Authenticate = #challenge 4876 A server generating a 401 (Unauthorized) response MUST send a WWW- 4877 Authenticate header field containing at least one challenge. A 4878 server MAY generate a WWW-Authenticate header field in other response 4879 messages to indicate that supplying credentials (or different 4880 credentials) might affect the response. 4882 A proxy forwarding a response MUST NOT modify any WWW-Authenticate 4883 fields in that response. 4885 User agents are advised to take special care in parsing the field 4886 value, as it might contain more than one challenge, and each 4887 challenge can contain a comma-separated list of authentication 4888 parameters. Furthermore, the header field itself can occur multiple 4889 times. 4891 For instance: 4893 WWW-Authenticate: Newauth realm="apps", type=1, 4894 title="Login to \"apps\"", Basic realm="simple" 4896 This header field contains two challenges; one for the "Newauth" 4897 scheme with a realm value of "apps", and two additional parameters 4898 "type" and "title", and another one for the "Basic" scheme with a 4899 realm value of "simple". 4901 Some user agents do not recognise this form, however. As a result, 4902 sending a WWW-Authenticate field value with more than one member on 4903 the same field line might not be interoperable. 4905 | *Note:* The challenge grammar production uses the list syntax 4906 | as well. Therefore, a sequence of comma, whitespace, and comma 4907 | can be considered either as applying to the preceding 4908 | challenge, or to be an empty entry in the list of challenges. 4909 | In practice, this ambiguity does not affect the semantics of 4910 | the header field value and thus is harmless. 4912 10.6.2. Authorization 4914 The "Authorization" header field allows a user agent to authenticate 4915 itself with an origin server - usually, but not necessarily, after 4916 receiving a 401 (Unauthorized) response. Its value consists of 4917 credentials containing the authentication information of the user 4918 agent for the realm of the resource being requested. 4920 Authorization = credentials 4922 If a request is authenticated and a realm specified, the same 4923 credentials are presumed to be valid for all other requests within 4924 this realm (assuming that the authentication scheme itself does not 4925 require otherwise, such as credentials that vary according to a 4926 challenge value or using synchronized clocks). 4928 A proxy forwarding a request MUST NOT modify any Authorization fields 4929 in that request. See Section 3.3 of [Caching] for details of and 4930 requirements pertaining to handling of the Authorization field by 4931 HTTP caches. 4933 10.6.3. Authentication-Info 4935 HTTP authentication schemes can use the Authentication-Info response 4936 header field to communicate information after the client's 4937 authentication credentials have been accepted. This information can 4938 include a finalization message from the server (e.g., it can contain 4939 the server authentication). 4941 The field value is a list of parameters (name/value pairs), using the 4942 "auth-param" syntax defined in Section 10.3. This specification only 4943 describes the generic format; authentication schemes using 4944 Authentication-Info will define the individual parameters. The 4945 "Digest" Authentication Scheme, for instance, defines multiple 4946 parameters in Section 3.5 of [RFC7616]. 4948 Authentication-Info = #auth-param 4950 The Authentication-Info header field can be used in any HTTP 4951 response, independently of request method and status code. Its 4952 semantics are defined by the authentication scheme indicated by the 4953 Authorization header field (Section 10.6.2) of the corresponding 4954 request. 4956 A proxy forwarding a response is not allowed to modify the field 4957 value in any way. 4959 Authentication-Info can be sent as a trailer field (Section 5.6) when 4960 the authentication scheme explicitly allows this. 4962 10.7. Authenticating Client to Proxy 4964 10.7.1. Proxy-Authenticate 4966 The "Proxy-Authenticate" header field consists of at least one 4967 challenge that indicates the authentication scheme(s) and parameters 4968 applicable to the proxy for this request. A proxy MUST send at least 4969 one Proxy-Authenticate header field in each 407 (Proxy Authentication 4970 Required) response that it generates. 4972 Proxy-Authenticate = #challenge 4974 Unlike WWW-Authenticate, the Proxy-Authenticate header field applies 4975 only to the next outbound client on the response chain. This is 4976 because only the client that chose a given proxy is likely to have 4977 the credentials necessary for authentication. However, when multiple 4978 proxies are used within the same administrative domain, such as 4979 office and regional caching proxies within a large corporate network, 4980 it is common for credentials to be generated by the user agent and 4981 passed through the hierarchy until consumed. Hence, in such a 4982 configuration, it will appear as if Proxy-Authenticate is being 4983 forwarded because each proxy will send the same challenge set. 4985 Note that the parsing considerations for WWW-Authenticate apply to 4986 this header field as well; see Section 10.6.1 for details. 4988 10.7.2. Proxy-Authorization 4990 The "Proxy-Authorization" header field allows the client to identify 4991 itself (or its user) to a proxy that requires authentication. Its 4992 value consists of credentials containing the authentication 4993 information of the client for the proxy and/or realm of the resource 4994 being requested. 4996 Proxy-Authorization = credentials 4998 Unlike Authorization, the Proxy-Authorization header field applies 4999 only to the next inbound proxy that demanded authentication using the 5000 Proxy-Authenticate field. When multiple proxies are used in a chain, 5001 the Proxy-Authorization header field is consumed by the first inbound 5002 proxy that was expecting to receive credentials. A proxy MAY relay 5003 the credentials from the client request to the next proxy if that is 5004 the mechanism by which the proxies cooperatively authenticate a given 5005 request. 5007 10.7.3. Proxy-Authentication-Info 5009 The Proxy-Authentication-Info response header field is equivalent to 5010 Authentication-Info, except that it applies to proxy authentication 5011 (Section 10.3) and its semantics are defined by the authentication 5012 scheme indicated by the Proxy-Authorization header field 5013 (Section 10.7.2) of the corresponding request: 5015 Proxy-Authentication-Info = #auth-param 5017 However, unlike Authentication-Info, the Proxy-Authentication-Info 5018 header field applies only to the next outbound client on the response 5019 chain. This is because only the client that chose a given proxy is 5020 likely to have the credentials necessary for authentication. 5021 However, when multiple proxies are used within the same 5022 administrative domain, such as office and regional caching proxies 5023 within a large corporate network, it is common for credentials to be 5024 generated by the user agent and passed through the hierarchy until 5025 consumed. Hence, in such a configuration, it will appear as if 5026 Proxy-Authentication-Info is being forwarded because each proxy will 5027 send the same field value. 5029 11. Content Negotiation 5031 When responses convey payload information, whether indicating a 5032 success or an error, the origin server often has different ways of 5033 representing that information; for example, in different formats, 5034 languages, or encodings. Likewise, different users or user agents 5035 might have differing capabilities, characteristics, or preferences 5036 that could influence which representation, among those available, 5037 would be best to deliver. For this reason, HTTP provides mechanisms 5038 for content negotiation. 5040 This specification defines three patterns of content negotiation that 5041 can be made visible within the protocol: "proactive" negotiation, 5042 where the server selects the representation based upon the user 5043 agent's stated preferences, "reactive" negotiation, where the server 5044 provides a list of representations for the user agent to choose from, 5045 and "request payload" negotiation, where the user agent selects the 5046 representation for a future request based upon the server's stated 5047 preferences in past responses. Other patterns of content negotiation 5048 include "conditional content", where the representation consists of 5049 multiple parts that are selectively rendered based on user agent 5050 parameters, "active content", where the representation contains a 5051 script that makes additional (more specific) requests based on the 5052 user agent characteristics, and "Transparent Content Negotiation" 5053 ([RFC2295]), where content selection is performed by an intermediary. 5054 These patterns are not mutually exclusive, and each has trade-offs in 5055 applicability and practicality. 5057 Note that, in all cases, HTTP is not aware of the resource semantics. 5058 The consistency with which an origin server responds to requests, 5059 over time and over the varying dimensions of content negotiation, and 5060 thus the "sameness" of a resource's observed representations over 5061 time, is determined entirely by whatever entity or algorithm selects 5062 or generates those responses. 5064 11.1. Proactive Negotiation 5066 When content negotiation preferences are sent by the user agent in a 5067 request to encourage an algorithm located at the server to select the 5068 preferred representation, it is called proactive negotiation (a.k.a., 5069 server-driven negotiation). Selection is based on the available 5070 representations for a response (the dimensions over which it might 5071 vary, such as language, content-coding, etc.) compared to various 5072 information supplied in the request, including both the explicit 5073 negotiation fields below and implicit characteristics, such as the 5074 client's network address or parts of the User-Agent field. 5076 Proactive negotiation is advantageous when the algorithm for 5077 selecting from among the available representations is difficult to 5078 describe to a user agent, or when the server desires to send its 5079 "best guess" to the user agent along with the first response (hoping 5080 to avoid the round trip delay of a subsequent request if the "best 5081 guess" is good enough for the user). In order to improve the 5082 server's guess, a user agent MAY send request header fields that 5083 describe its preferences. 5085 Proactive negotiation has serious disadvantages: 5087 o It is impossible for the server to accurately determine what might 5088 be "best" for any given user, since that would require complete 5089 knowledge of both the capabilities of the user agent and the 5090 intended use for the response (e.g., does the user want to view it 5091 on screen or print it on paper?); 5093 o Having the user agent describe its capabilities in every request 5094 can be both very inefficient (given that only a small percentage 5095 of responses have multiple representations) and a potential risk 5096 to the user's privacy; 5098 o It complicates the implementation of an origin server and the 5099 algorithms for generating responses to a request; and, 5101 o It limits the reusability of responses for shared caching. 5103 A user agent cannot rely on proactive negotiation preferences being 5104 consistently honored, since the origin server might not implement 5105 proactive negotiation for the requested resource or might decide that 5106 sending a response that doesn't conform to the user agent's 5107 preferences is better than sending a 406 (Not Acceptable) response. 5109 A Vary header field (Section 11.2.1) is often sent in a response 5110 subject to proactive negotiation to indicate what parts of the 5111 request information were used in the selection algorithm. 5113 The following request header fields can be sent by a user agent to 5114 engage in proactive negotiation of the response content, as defined 5115 in Section 11.1. The preferences sent in these fields apply to any 5116 content in the response, including representations of the target 5117 resource, representations of error or processing status, and 5118 potentially even the miscellaneous text strings that might appear 5119 within the protocol. 5121 ----------------- -------- 5122 Field Name Ref. 5123 ----------------- -------- 5124 Accept 11.1.2 5125 Accept-Charset 11.1.3 5126 Accept-Encoding 11.1.4 5127 Accept-Language 11.1.5 5128 ----------------- -------- 5130 Table 10 5132 11.1.1. Shared Negotiation Features 5133 11.1.1.1. Absence 5135 For each of these header fields, a request that does not contain the 5136 field implies that the user agent has no preference on that axis of 5137 negotiation. If the header field is present in a request and none of 5138 the available representations for the response can be considered 5139 acceptable according to it, the origin server can either honor the 5140 header field by sending a 406 (Not Acceptable) response or disregard 5141 the header field by treating the response as if it is not subject to 5142 content negotiation for that request header field. This does not 5143 imply, however, that the client will be able to use the 5144 representation. 5146 *Note:* Sending these header fields makes it easier for a server to 5147 identify an individual by virtue of the user agent's request 5148 characteristics (Section 16.12). 5150 11.1.1.2. Quality Values 5152 The content negotiation fields defined by this specification use a 5153 common parameter, named "q" (case-insensitive), to assign a relative 5154 "weight" to the preference for that associated kind of content. This 5155 weight is referred to as a "quality value" (or "qvalue") because the 5156 same parameter name is often used within server configurations to 5157 assign a weight to the relative quality of the various 5158 representations that can be selected for a resource. 5160 The weight is normalized to a real number in the range 0 through 1, 5161 where 0.001 is the least preferred and 1 is the most preferred; a 5162 value of 0 means "not acceptable". If no "q" parameter is present, 5163 the default weight is 1. 5165 weight = OWS ";" OWS "q=" qvalue 5166 qvalue = ( "0" [ "." 0*3DIGIT ] ) 5167 / ( "1" [ "." 0*3("0") ] ) 5169 A sender of qvalue MUST NOT generate more than three digits after the 5170 decimal point. User configuration of these values ought to be 5171 limited in the same fashion. 5173 11.1.1.3. Wildcard Values 5175 Most of these header fields, where indicated, define a wildcard value 5176 ("*") to select unspecified values. If no wildcard is present, all 5177 values not explicitly mentioned in the field are considered "not 5178 acceptable" to the client. 5180 *Note:* In practice, using wildcards in content negotiation has 5181 limited practical value, because it is seldom useful to say, for 5182 example, "I prefer image/* more or less than (some other specific 5183 value)". Clients can explicitly request a 406 (Not Acceptable) 5184 response if a more preferred format is not available by sending 5185 Accept: */*;q=0, but they still need to be able to handle a different 5186 response, since the server is allowed to ignore their preference. 5188 11.1.2. Accept 5190 The "Accept" header field can be used by user agents to specify their 5191 preferences regarding response media types. For example, Accept 5192 header fields can be used to indicate that the request is 5193 specifically limited to a small set of desired types, as in the case 5194 of a request for an in-line image. 5196 When sent by a server in a response, Accept provides information 5197 about what content types are preferred in the payload of a subsequent 5198 request to the same resource. 5200 Accept = #( media-range [ accept-params ] ) 5202 media-range = ( "*/*" 5203 / ( type "/" "*" ) 5204 / ( type "/" subtype ) 5205 ) parameters 5206 accept-params = weight *( accept-ext ) 5207 accept-ext = OWS ";" OWS token [ "=" ( token / quoted-string ) ] 5209 The asterisk "*" character is used to group media types into ranges, 5210 with "*/*" indicating all media types and "type/*" indicating all 5211 subtypes of that type. The media-range can include media type 5212 parameters that are applicable to that range. 5214 Each media-range might be followed by zero or more applicable media 5215 type parameters (e.g., charset), an optional "q" parameter for 5216 indicating a relative weight (Section 11.1.1.2), and then zero or 5217 more extension parameters. The "q" parameter is necessary if any 5218 extensions (accept-ext) are present, since it acts as a separator 5219 between the two parameter sets. 5221 | *Note:* Use of the "q" parameter name to separate media type 5222 | parameters from Accept extension parameters is due to 5223 | historical practice. Although this prevents any media type 5224 | parameter named "q" from being used with a media range, such an 5225 | event is believed to be unlikely given the lack of any "q" 5226 | parameters in the IANA media type registry and the rare usage 5227 | of any media type parameters in Accept. Future media types are 5228 | discouraged from registering any parameter named "q". 5230 The example 5232 Accept: audio/*; q=0.2, audio/basic 5234 is interpreted as "I prefer audio/basic, but send me any audio type 5235 if it is the best available after an 80% markdown in quality". 5237 A more elaborate example is 5239 Accept: text/plain; q=0.5, text/html, 5240 text/x-dvi; q=0.8, text/x-c 5242 Verbally, this would be interpreted as "text/html and text/x-c are 5243 the equally preferred media types, but if they do not exist, then 5244 send the text/x-dvi representation, and if that does not exist, send 5245 the text/plain representation". 5247 Media ranges can be overridden by more specific media ranges or 5248 specific media types. If more than one media range applies to a 5249 given type, the most specific reference has precedence. For example, 5251 Accept: text/*, text/plain, text/plain;format=flowed, */* 5253 have the following precedence: 5255 1. text/plain;format=flowed 5257 2. text/plain 5259 3. text/* 5261 4. */* 5263 The media type quality factor associated with a given type is 5264 determined by finding the media range with the highest precedence 5265 that matches the type. For example, 5267 Accept: text/*;q=0.3, text/plain;q=0.7, text/plain;format=flowed, 5268 text/plain;format=fixed;q=0.4, */*;q=0.5 5270 would cause the following values to be associated: 5272 -------------------------- --------------- 5273 Media Type Quality Value 5274 -------------------------- --------------- 5275 text/plain;format=flowed 1 5276 text/plain 0.7 5277 text/html 0.3 5278 image/jpeg 0.5 5279 text/plain;format=fixed 0.4 5280 text/html;level=3 0.7 5281 -------------------------- --------------- 5283 Table 11 5285 *Note:* A user agent might be provided with a default set of quality 5286 values for certain media ranges. However, unless the user agent is a 5287 closed system that cannot interact with other rendering agents, this 5288 default set ought to be configurable by the user. 5290 11.1.3. Accept-Charset 5292 The "Accept-Charset" header field can be sent by a user agent to 5293 indicate its preferences for charsets in textual response content. 5294 For example, this field allows user agents capable of understanding 5295 more comprehensive or special-purpose charsets to signal that 5296 capability to an origin server that is capable of representing 5297 information in those charsets. 5299 Accept-Charset = #( ( charset / "*" ) [ weight ] ) 5301 Charset names are defined in Section 7.4.2. A user agent MAY 5302 associate a quality value with each charset to indicate the user's 5303 relative preference for that charset, as defined in Section 11.1.1.2. 5304 An example is 5306 Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 5308 The special value "*", if present in the Accept-Charset field, 5309 matches every charset that is not mentioned elsewhere in the Accept- 5310 Charset field. 5312 *Note:* Accept-Charset is deprecated because UTF-8 has become nearly 5313 ubiquitous and sending a detailed list of user-preferred charsets 5314 wastes bandwidth, increases latency, and makes passive fingerprinting 5315 far too easy (Section 16.12). Most general-purpose user agents do 5316 not send Accept-Charset, unless specifically configured to do so. 5318 11.1.4. Accept-Encoding 5320 The "Accept-Encoding" header field can be used to indicate 5321 preferences regarding the use of content codings (Section 7.5.1). 5323 When sent by a user agent in a request, Accept-Encoding indicates the 5324 content codings acceptable in a response. 5326 When sent by a server in a response, Accept-Encoding provides 5327 information about what content codings are preferred in the payload 5328 of a subsequent request to the same resource. 5330 An "identity" token is used as a synonym for "no encoding" in order 5331 to communicate when no encoding is preferred. 5333 Accept-Encoding = #( codings [ weight ] ) 5334 codings = content-coding / "identity" / "*" 5336 Each codings value MAY be given an associated quality value 5337 representing the preference for that encoding, as defined in 5338 Section 11.1.1.2. The asterisk "*" symbol in an Accept-Encoding 5339 field matches any available content-coding not explicitly listed in 5340 the header field. 5342 For example, 5344 Accept-Encoding: compress, gzip 5345 Accept-Encoding: 5346 Accept-Encoding: * 5347 Accept-Encoding: compress;q=0.5, gzip;q=1.0 5348 Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0 5350 A server tests whether a content-coding for a given representation is 5351 acceptable using these rules: 5353 1. If no Accept-Encoding field is in the request, any content-coding 5354 is considered acceptable by the user agent. 5356 2. If the representation has no content-coding, then it is 5357 acceptable by default unless specifically excluded by the Accept- 5358 Encoding field stating either "identity;q=0" or "*;q=0" without a 5359 more specific entry for "identity". 5361 3. If the representation's content-coding is one of the content- 5362 codings listed in the Accept-Encoding field value, then it is 5363 acceptable unless it is accompanied by a qvalue of 0. (As 5364 defined in Section 11.1.1.2, a qvalue of 0 means "not 5365 acceptable".) 5367 4. If multiple content-codings are acceptable, then the acceptable 5368 content-coding with the highest non-zero qvalue is preferred. 5370 An Accept-Encoding header field with a field value that is empty 5371 implies that the user agent does not want any content-coding in 5372 response. If an Accept-Encoding header field is present in a request 5373 and none of the available representations for the response have a 5374 content-coding that is listed as acceptable, the origin server SHOULD 5375 send a response without any content-coding. 5377 When the Accept-Encoding header field is present in a response, it 5378 indicates what content codings the resource was willing to accept in 5379 the associated request. The field value is evaluated the same way as 5380 in a request. 5382 Note that this information is specific to the associated request; the 5383 set of supported encodings might be different for other resources on 5384 the same server and could change over time or depend on other aspects 5385 of the request (such as the request method). 5387 Servers that fail a request due to an unsupported content coding 5388 ought to respond with a 415 (Unsupported Media Type) status and 5389 include an Accept-Encoding header field in that response, allowing 5390 clients to distinguish between issues related to content codings and 5391 media types. In order to avoid confusion with issues related to 5392 media types, servers that fail a request with a 415 status for 5393 reasons unrelated to content codings MUST NOT include the Accept- 5394 Encoding header field. 5396 The most common use of Accept-Encoding is in responses with a 415 5397 (Unsupported Media Type) status code, in response to optimistic use 5398 of a content coding by clients. However, the header field can also 5399 be used to indicate to clients that content codings are supported, to 5400 optimize future interactions. For example, a resource might include 5401 it in a 2xx (Successful) response when the request payload was big 5402 enough to justify use of a compression coding but the client failed 5403 do so. 5405 | *Note:* Most HTTP/1.0 applications do not recognize or obey 5406 | qvalues associated with content-codings. This means that 5407 | qvalues might not work and are not permitted with x-gzip or 5408 | x-compress. 5410 11.1.5. Accept-Language 5412 The "Accept-Language" header field can be used by user agents to 5413 indicate the set of natural languages that are preferred in the 5414 response. Language tags are defined in Section 7.6.1. 5416 Accept-Language = #( language-range [ weight ] ) 5417 language-range = 5418 5420 Each language-range can be given an associated quality value 5421 representing an estimate of the user's preference for the languages 5422 specified by that range, as defined in Section 11.1.1.2. For 5423 example, 5425 Accept-Language: da, en-gb;q=0.8, en;q=0.7 5427 would mean: "I prefer Danish, but will accept British English and 5428 other types of English". 5430 Note that some recipients treat the order in which language tags are 5431 listed as an indication of descending priority, particularly for tags 5432 that are assigned equal quality values (no value is the same as q=1). 5433 However, this behavior cannot be relied upon. For consistency and to 5434 maximize interoperability, many user agents assign each language tag 5435 a unique quality value while also listing them in order of decreasing 5436 quality. Additional discussion of language priority lists can be 5437 found in Section 2.3 of [RFC4647]. 5439 For matching, Section 3 of [RFC4647] defines several matching 5440 schemes. Implementations can offer the most appropriate matching 5441 scheme for their requirements. The "Basic Filtering" scheme 5442 ([RFC4647], Section 3.3.1) is identical to the matching scheme that 5443 was previously defined for HTTP in Section 14.4 of [RFC2616]. 5445 It might be contrary to the privacy expectations of the user to send 5446 an Accept-Language header field with the complete linguistic 5447 preferences of the user in every request (Section 16.12). 5449 Since intelligibility is highly dependent on the individual user, 5450 user agents need to allow user control over the linguistic preference 5451 (either through configuration of the user agent itself or by 5452 defaulting to a user controllable system setting). A user agent that 5453 does not provide such control to the user MUST NOT send an Accept- 5454 Language header field. 5456 | *Note:* User agents ought to provide guidance to users when 5457 | setting a preference, since users are rarely familiar with the 5458 | details of language matching as described above. For example, 5459 | users might assume that on selecting "en-gb", they will be 5460 | served any kind of English document if British English is not 5461 | available. A user agent might suggest, in such a case, to add 5462 | "en" to the list for better matching behavior. 5464 11.2. Reactive Negotiation 5466 With reactive negotiation (a.k.a., agent-driven negotiation), 5467 selection of the best response representation (regardless of the 5468 status code) is performed by the user agent after receiving an 5469 initial response from the origin server that contains a list of 5470 resources for alternative representations. If the user agent is not 5471 satisfied by the initial response representation, it can perform a 5472 GET request on one or more of the alternative resources, selected 5473 based on metadata included in the list, to obtain a different form of 5474 representation for that response. Selection of alternatives might be 5475 performed automatically by the user agent or manually by the user 5476 selecting from a generated (possibly hypertext) menu. 5478 Note that the above refers to representations of the response, in 5479 general, not representations of the resource. The alternative 5480 representations are only considered representations of the target 5481 resource if the response in which those alternatives are provided has 5482 the semantics of being a representation of the target resource (e.g., 5483 a 200 (OK) response to a GET request) or has the semantics of 5484 providing links to alternative representations for the target 5485 resource (e.g., a 300 (Multiple Choices) response to a GET request). 5487 A server might choose not to send an initial representation, other 5488 than the list of alternatives, and thereby indicate that reactive 5489 negotiation by the user agent is preferred. For example, the 5490 alternatives listed in responses with the 300 (Multiple Choices) and 5491 406 (Not Acceptable) status codes include information about the 5492 available representations so that the user or user agent can react by 5493 making a selection. 5495 Reactive negotiation is advantageous when the response would vary 5496 over commonly used dimensions (such as type, language, or encoding), 5497 when the origin server is unable to determine a user agent's 5498 capabilities from examining the request, and generally when public 5499 caches are used to distribute server load and reduce network usage. 5501 Reactive negotiation suffers from the disadvantages of transmitting a 5502 list of alternatives to the user agent, which degrades user-perceived 5503 latency if transmitted in the header section, and needing a second 5504 request to obtain an alternate representation. Furthermore, this 5505 specification does not define a mechanism for supporting automatic 5506 selection, though it does not prevent such a mechanism from being 5507 developed as an extension. 5509 11.2.1. Vary 5511 The "Vary" header field in a response describes what parts of a 5512 request message, aside from the method and target URI, might 5513 influence the origin server's process for selecting and representing 5514 this response. 5516 Vary = #( "*" / field-name ) 5518 A Vary field value is a list of request field names, known as the 5519 selecting header fields, that might have a role in selecting the 5520 representation for this response. Potential selecting header fields 5521 are not limited to those defined by this specification. 5523 If the list contains "*", it signals that other aspects of the 5524 request might play a role in selecting the response representation, 5525 possibly including elements outside the message syntax (e.g., the 5526 client's network address). A recipient will not be able to determine 5527 whether this response is appropriate for a later request without 5528 forwarding the request to the origin server. A proxy MUST NOT 5529 generate "*" in a Vary field value. 5531 For example, a response that contains 5533 Vary: accept-encoding, accept-language 5535 indicates that the origin server might have used the request's 5536 Accept-Encoding and Accept-Language fields (or lack thereof) as 5537 determining factors while choosing the content for this response. 5539 An origin server might send Vary with a list of fields for two 5540 purposes: 5542 1. To inform cache recipients that they MUST NOT use this response 5543 to satisfy a later request unless the later request has the same 5544 values for the listed fields as the original request (Section 4.1 5545 of [Caching]). In other words, Vary expands the cache key 5546 required to match a new request to the stored cache entry. 5548 2. To inform user agent recipients that this response is subject to 5549 content negotiation (Section 11) and that a different 5550 representation might be sent in a subsequent request if 5551 additional parameters are provided in the listed header fields 5552 (proactive negotiation). 5554 An origin server SHOULD send a Vary header field when its algorithm 5555 for selecting a representation varies based on aspects of the request 5556 message other than the method and target URI, unless the variance 5557 cannot be crossed or the origin server has been deliberately 5558 configured to prevent cache transparency. For example, there is no 5559 need to send the Authorization field name in Vary because reuse 5560 across users is constrained by the field definition (Section 10.6.2). 5561 Likewise, an origin server might use Cache-Control response 5562 directives (Section 5.2 of [Caching]) to supplant Vary if it 5563 considers the variance less significant than the performance cost of 5564 Vary's impact on caching. 5566 11.3. Request Payload Negotiation 5568 When content negotiation preferences are sent in a server's response, 5569 the listed preferences are called request payload negotiation because 5570 they intend to influence selection of an appropriate payload for 5571 subsequent requests to that resource. For example, the 5572 Accept-Encoding field (Section 11.1.4) can be sent in a response to 5573 indicate preferred content codings for subsequent requests to that 5574 resource [RFC7694]. 5576 | Similarly, Section 3.1 of [RFC5789] defines the "Accept-Patch" 5577 | response header field which allows discovery of which content 5578 | types are accepted in PATCH requests. 5580 12. Conditional Requests 5582 A conditional request is an HTTP request with one or more request 5583 header fields that indicate a precondition to be tested before 5584 applying the request method to the target resource. Section 12.2 5585 defines when preconditions are applied. Section 12.3 defines the 5586 order of evaluation when more than one precondition is present. 5588 Conditional GET requests are the most efficient mechanism for HTTP 5589 cache updates [Caching]. Conditionals can also be applied to state- 5590 changing methods, such as PUT and DELETE, to prevent the "lost 5591 update" problem: one client accidentally overwriting the work of 5592 another client that has been acting in parallel. 5594 Conditional request preconditions are based on the state of the 5595 target resource as a whole (its current value set) or the state as 5596 observed in a previously obtained representation (one value in that 5597 set). A resource might have multiple current representations, each 5598 with its own observable state. The conditional request mechanisms 5599 assume that the mapping of requests to a selected representation 5600 (Section 7) will be consistent over time if the server intends to 5601 take advantage of conditionals. Regardless, if the mapping is 5602 inconsistent and the server is unable to select the appropriate 5603 representation, then no harm will result when the precondition 5604 evaluates to false. 5606 12.1. Preconditions 5608 The following request header fields allow a client to place a 5609 precondition on the state of the target resource, so that the action 5610 corresponding to the method semantics will not be applied if the 5611 precondition evaluates to false. Each precondition defined by this 5612 specification consists of a comparison between a set of validators 5613 obtained from prior representations of the target resource to the 5614 current state of validators for the selected representation 5615 (Section 7.9). Hence, these preconditions evaluate whether the state 5616 of the target resource has changed since a given state known by the 5617 client. The effect of such an evaluation depends on the method 5618 semantics and choice of conditional, as defined in Section 12.2. 5620 --------------------- -------- 5621 Field Name Ref. 5622 --------------------- -------- 5623 If-Match 12.1.1 5624 If-None-Match 12.1.2 5625 If-Modified-Since 12.1.3 5626 If-Unmodified-Since 12.1.4 5627 If-Range 12.1.5 5628 --------------------- -------- 5630 Table 12 5632 12.1.1. If-Match 5634 The "If-Match" header field makes the request method conditional on 5635 the recipient origin server either having at least one current 5636 representation of the target resource, when the field value is "*", 5637 or having a current representation of the target resource that has an 5638 entity-tag matching a member of the list of entity-tags provided in 5639 the field value. 5641 An origin server MUST use the strong comparison function when 5642 comparing entity-tags for If-Match (Section 7.9.3.2), since the 5643 client intends this precondition to prevent the method from being 5644 applied if there have been any changes to the representation data. 5646 If-Match = "*" / #entity-tag 5648 Examples: 5650 If-Match: "xyzzy" 5651 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 5652 If-Match: * 5654 If-Match is most often used with state-changing methods (e.g., POST, 5655 PUT, DELETE) to prevent accidental overwrites when multiple user 5656 agents might be acting in parallel on the same resource (i.e., to 5657 prevent the "lost update" problem). It can also be used with any 5658 method to abort a request if the selected representation does not 5659 match one that the client has already stored (or partially stored) 5660 from a prior request. 5662 An origin server that receives an If-Match header field MUST evaluate 5663 the condition as per Section 12.2 prior to performing the method. 5665 To evaluate a received If-Match header field: 5667 1. If the field value is "*", the condition is true if the origin 5668 server has a current representation for the target resource. 5670 2. If the field value is a list of entity-tags, the condition is 5671 true if any of the listed tags match the entity-tag of the 5672 selected representation. 5674 3. Otherwise, the condition is false. 5676 An origin server MUST NOT perform the requested method if a received 5677 If-Match condition evaluates to false. Instead, the origin server 5678 MAY indicate that the conditional request failed by responding with a 5679 412 (Precondition Failed) status code. Alternatively, if the request 5680 is a state-changing operation that appears to have already been 5681 applied to the selected representation, the origin server MAY respond 5682 with a 2xx (Successful) status code (i.e., the change requested by 5683 the user agent has already succeeded, but the user agent might not be 5684 aware of it, perhaps because the prior response was lost or an 5685 equivalent change was made by some other user agent). 5687 Allowing an origin server to send a success response when a change 5688 request appears to have already been applied is more efficient for 5689 many authoring use cases, but comes with some risk if multiple user 5690 agents are making change requests that are very similar but not 5691 cooperative. For example, multiple user agents writing to a common 5692 resource as a semaphore (e.g., a non-atomic increment) are likely to 5693 collide and potentially lose important state transitions. For those 5694 kinds of resources, an origin server is better off being stringent in 5695 sending 412 for every failed precondition on an unsafe method. In 5696 other cases, excluding the ETag field from a success response might 5697 encourage the user agent to perform a GET as its next request to 5698 eliminate confusion about the resource's current state. 5700 The If-Match header field can be ignored by caches and intermediaries 5701 because it is not applicable to a stored response. 5703 Note that an If-Match header field with a list value containing "*" 5704 and other values (including other instances of "*") is unlikely to be 5705 interoperable. 5707 12.1.2. If-None-Match 5709 The "If-None-Match" header field makes the request method conditional 5710 on a recipient cache or origin server either not having any current 5711 representation of the target resource, when the field value is "*", 5712 or having a selected representation with an entity-tag that does not 5713 match any of those listed in the field value. 5715 A recipient MUST use the weak comparison function when comparing 5716 entity-tags for If-None-Match (Section 7.9.3.2), since weak entity- 5717 tags can be used for cache validation even if there have been changes 5718 to the representation data. 5720 If-None-Match = "*" / #entity-tag 5722 Examples: 5724 If-None-Match: "xyzzy" 5725 If-None-Match: W/"xyzzy" 5726 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 5727 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 5728 If-None-Match: * 5730 If-None-Match is primarily used in conditional GET requests to enable 5731 efficient updates of cached information with a minimum amount of 5732 transaction overhead. When a client desires to update one or more 5733 stored responses that have entity-tags, the client SHOULD generate an 5734 If-None-Match header field containing a list of those entity-tags 5735 when making a GET request; this allows recipient servers to send a 5736 304 (Not Modified) response to indicate when one of those stored 5737 responses matches the selected representation. 5739 If-None-Match can also be used with a value of "*" to prevent an 5740 unsafe request method (e.g., PUT) from inadvertently modifying an 5741 existing representation of the target resource when the client 5742 believes that the resource does not have a current representation 5743 (Section 8.2.1). This is a variation on the "lost update" problem 5744 that might arise if more than one client attempts to create an 5745 initial representation for the target resource. 5747 An origin server that receives an If-None-Match header field MUST 5748 evaluate the condition as per Section 12.2 prior to performing the 5749 method. 5751 To evaluate a received If-None-Match header field: 5753 1. If the field value is "*", the condition is false if the origin 5754 server has a current representation for the target resource. 5756 2. If the field value is a list of entity-tags, the condition is 5757 false if one of the listed tags matches the entity-tag of the 5758 selected representation. 5760 3. Otherwise, the condition is true. 5762 An origin server MUST NOT perform the requested method if the 5763 condition evaluates to false; instead, the origin server MUST respond 5764 with either a) the 304 (Not Modified) status code if the request 5765 method is GET or HEAD or b) the 412 (Precondition Failed) status code 5766 for all other request methods. 5768 Requirements on cache handling of a received If-None-Match header 5769 field are defined in Section 4.3.2 of [Caching]. 5771 Note that an If-None-Match header field with a list value containing 5772 "*" and other values (including other instances of "*") is unlikely 5773 to be interoperable. 5775 12.1.3. If-Modified-Since 5777 The "If-Modified-Since" header field makes a GET or HEAD request 5778 method conditional on the selected representation's modification date 5779 being more recent than the date provided in the field value. 5780 Transfer of the selected representation's data is avoided if that 5781 data has not changed. 5783 If-Modified-Since = HTTP-date 5785 An example of the field is: 5787 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 5789 A recipient MUST ignore If-Modified-Since if the request contains an 5790 If-None-Match header field; the condition in If-None-Match is 5791 considered to be a more accurate replacement for the condition in If- 5792 Modified-Since, and the two are only combined for the sake of 5793 interoperating with older intermediaries that might not implement 5794 If-None-Match. 5796 A recipient MUST ignore the If-Modified-Since header field if the 5797 received field value is not a valid HTTP-date, the field value has 5798 more than one member, or if the request method is neither GET nor 5799 HEAD. 5801 A recipient MUST interpret an If-Modified-Since field value's 5802 timestamp in terms of the origin server's clock. 5804 If-Modified-Since is typically used for two distinct purposes: 1) to 5805 allow efficient updates of a cached representation that does not have 5806 an entity-tag and 2) to limit the scope of a web traversal to 5807 resources that have recently changed. 5809 When used for cache updates, a cache will typically use the value of 5810 the cached message's Last-Modified field to generate the field value 5811 of If-Modified-Since. This behavior is most interoperable for cases 5812 where clocks are poorly synchronized or when the server has chosen to 5813 only honor exact timestamp matches (due to a problem with Last- 5814 Modified dates that appear to go "back in time" when the origin 5815 server's clock is corrected or a representation is restored from an 5816 archived backup). However, caches occasionally generate the field 5817 value based on other data, such as the Date header field of the 5818 cached message or the local clock time that the message was received, 5819 particularly when the cached message does not contain a Last-Modified 5820 field. 5822 When used for limiting the scope of retrieval to a recent time 5823 window, a user agent will generate an If-Modified-Since field value 5824 based on either its own local clock or a Date header field received 5825 from the server in a prior response. Origin servers that choose an 5826 exact timestamp match based on the selected representation's 5827 Last-Modified field will not be able to help the user agent limit its 5828 data transfers to only those changed during the specified window. 5830 An origin server that receives an If-Modified-Since header field 5831 SHOULD evaluate the condition as per Section 12.2 prior to performing 5832 the method. The origin server SHOULD NOT perform the requested 5833 method if the selected representation's last modification date is 5834 earlier than or equal to the date provided in the field value; 5835 instead, the origin server SHOULD generate a 304 (Not Modified) 5836 response, including only those metadata that are useful for 5837 identifying or updating a previously cached response. 5839 Requirements on cache handling of a received If-Modified-Since header 5840 field are defined in Section 4.3.2 of [Caching]. 5842 12.1.4. If-Unmodified-Since 5844 The "If-Unmodified-Since" header field makes the request method 5845 conditional on the selected representation's last modification date 5846 being earlier than or equal to the date provided in the field value. 5847 This field accomplishes the same purpose as If-Match for cases where 5848 the user agent does not have an entity-tag for the representation. 5850 If-Unmodified-Since = HTTP-date 5852 An example of the field is: 5854 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 5856 A recipient MUST ignore If-Unmodified-Since if the request contains 5857 an If-Match header field; the condition in If-Match is considered to 5858 be a more accurate replacement for the condition in If-Unmodified- 5859 Since, and the two are only combined for the sake of interoperating 5860 with older intermediaries that might not implement If-Match. 5862 A recipient MUST ignore the If-Unmodified-Since header field if the 5863 received field value is not a valid HTTP-date (including when the 5864 field value appears to be a list of dates). 5866 A recipient MUST interpret an If-Unmodified-Since field value's 5867 timestamp in terms of the origin server's clock. 5869 If-Unmodified-Since is most often used with state-changing methods 5870 (e.g., POST, PUT, DELETE) to prevent accidental overwrites when 5871 multiple user agents might be acting in parallel on a resource that 5872 does not supply entity-tags with its representations (i.e., to 5873 prevent the "lost update" problem). It can also be used with any 5874 method to abort a request if the selected representation does not 5875 match one that the client already stored (or partially stored) from a 5876 prior request. 5878 An origin server that receives an If-Unmodified-Since header field 5879 MUST evaluate the condition as per Section 12.2 prior to performing 5880 the method. 5882 If the selected representation has a last modification date, the 5883 origin server MUST NOT perform the requested method if that date is 5884 more recent than the date provided in the field value. Instead, the 5885 origin server MAY indicate that the conditional request failed by 5886 responding with a 412 (Precondition Failed) status code. 5887 Alternatively, if the request is a state-changing operation that 5888 appears to have already been applied to the selected representation, 5889 the origin server MAY respond with a 2xx (Successful) status code 5890 (i.e., the change requested by the user agent has already succeeded, 5891 but the user agent might not be aware of it, perhaps because the 5892 prior response was lost or an equivalent change was made by some 5893 other user agent). 5895 Allowing an origin server to send a success response when a change 5896 request appears to have already been applied is more efficient for 5897 many authoring use cases, but comes with some risk if multiple user 5898 agents are making change requests that are very similar but not 5899 cooperative. In those cases, an origin server is better off being 5900 stringent in sending 412 for every failed precondition on an unsafe 5901 method. 5903 The If-Unmodified-Since header field can be ignored by caches and 5904 intermediaries because it is not applicable to a stored response. 5906 12.1.5. If-Range 5908 The "If-Range" header field provides a special conditional request 5909 mechanism that is similar to the If-Match and If-Unmodified-Since 5910 header fields but that instructs the recipient to ignore the Range 5911 header field if the validator doesn't match, resulting in transfer of 5912 the new selected representation instead of a 412 (Precondition 5913 Failed) response. 5915 If a client has a partial copy of a representation and wishes to have 5916 an up-to-date copy of the entire representation, it could use the 5917 Range header field with a conditional GET (using either or both of 5918 If-Unmodified-Since and If-Match.) However, if the precondition 5919 fails because the representation has been modified, the client would 5920 then have to make a second request to obtain the entire current 5921 representation. 5923 The "If-Range" header field allows a client to "short-circuit" the 5924 second request. Informally, its meaning is as follows: if the 5925 representation is unchanged, send me the part(s) that I am requesting 5926 in Range; otherwise, send me the entire representation. 5928 If-Range = entity-tag / HTTP-date 5930 A client MUST NOT generate an If-Range header field in a request that 5931 does not contain a Range header field. A server MUST ignore an If- 5932 Range header field received in a request that does not contain a 5933 Range header field. An origin server MUST ignore an If-Range header 5934 field received in a request for a target resource that does not 5935 support Range requests. 5937 A client MUST NOT generate an If-Range header field containing an 5938 entity-tag that is marked as weak. A client MUST NOT generate an If- 5939 Range header field containing an HTTP-date unless the client has no 5940 entity-tag for the corresponding representation and the date is a 5941 strong validator in the sense defined by Section 7.9.2.2. 5943 A server that evaluates an If-Range precondition MUST use the strong 5944 comparison function when comparing entity-tags (Section 7.9.3.2) and 5945 MUST evaluate the condition as false if an HTTP-date validator is 5946 provided that is not a strong validator in the sense defined by 5947 Section 7.9.2.2. A valid entity-tag can be distinguished from a 5948 valid HTTP-date by examining the first two characters for a DQUOTE. 5950 If the validator given in the If-Range header field matches the 5951 current validator for the selected representation of the target 5952 resource, then the server SHOULD process the Range header field as 5953 requested. If the validator does not match, the server MUST ignore 5954 the Range header field. Note that this comparison by exact match, 5955 including when the validator is an HTTP-date, differs from the 5956 "earlier than or equal to" comparison used when evaluating an 5957 If-Unmodified-Since conditional. 5959 12.2. Evaluation 5961 Except when excluded below, a recipient cache or origin server MUST 5962 evaluate received request preconditions after it has successfully 5963 performed its normal request checks and just before it would process 5964 the request body (if any) or perform the action associated with the 5965 request method. A server MUST ignore all received preconditions if 5966 its response to the same request without those conditions, prior to 5967 processing the request body, would have been a status code other than 5968 a 2xx (Successful) or 412 (Precondition Failed). In other words, 5969 redirects and failures that can be detected before significant 5970 processing occurs take precedence over the evaluation of 5971 preconditions. 5973 A server that is not the origin server for the target resource and 5974 cannot act as a cache for requests on the target resource MUST NOT 5975 evaluate the conditional request header fields defined by this 5976 specification, and it MUST forward them if the request is forwarded, 5977 since the generating client intends that they be evaluated by a 5978 server that can provide a current representation. Likewise, a server 5979 MUST ignore the conditional request header fields defined by this 5980 specification when received with a request method that does not 5981 involve the selection or modification of a selected representation, 5982 such as CONNECT, OPTIONS, or TRACE. 5984 Note that protocol extensions can modify the conditions under which 5985 revalidation is triggered. For example, the "immutable" cache 5986 directive (defined by [RFC8246]) instructs caches to forgo 5987 revalidation of fresh responses even when requested by the client. 5989 Conditional request header fields that are defined by extensions to 5990 HTTP might place conditions on all recipients, on the state of the 5991 target resource in general, or on a group of resources. For 5992 instance, the "If" header field in WebDAV can make a request 5993 conditional on various aspects of multiple resources, such as locks, 5994 if the recipient understands and implements that field ([RFC4918], 5995 Section 10.4). 5997 Although conditional request header fields are defined as being 5998 usable with the HEAD method (to keep HEAD's semantics consistent with 5999 those of GET), there is no point in sending a conditional HEAD 6000 because a successful response is around the same size as a 304 (Not 6001 Modified) response and more useful than a 412 (Precondition Failed) 6002 response. 6004 12.3. Precedence 6006 When more than one conditional request header field is present in a 6007 request, the order in which the fields are evaluated becomes 6008 important. In practice, the fields defined in this document are 6009 consistently implemented in a single, logical order, since "lost 6010 update" preconditions have more strict requirements than cache 6011 validation, a validated cache is more efficient than a partial 6012 response, and entity tags are presumed to be more accurate than date 6013 validators. 6015 A recipient cache or origin server MUST evaluate the request 6016 preconditions defined by this specification in the following order: 6018 1. When recipient is the origin server and If-Match is present, 6019 evaluate the If-Match precondition: 6021 o if true, continue to step 3 6023 o if false, respond 412 (Precondition Failed) unless it can be 6024 determined that the state-changing request has already 6025 succeeded (see Section 12.1.1) 6027 2. When recipient is the origin server, If-Match is not present, and 6028 If-Unmodified-Since is present, evaluate the If-Unmodified-Since 6029 precondition: 6031 o if true, continue to step 3 6032 o if false, respond 412 (Precondition Failed) unless it can be 6033 determined that the state-changing request has already 6034 succeeded (see Section 12.1.4) 6036 3. When If-None-Match is present, evaluate the If-None-Match 6037 precondition: 6039 o if true, continue to step 5 6041 o if false for GET/HEAD, respond 304 (Not Modified) 6043 o if false for other methods, respond 412 (Precondition Failed) 6045 4. When the method is GET or HEAD, If-None-Match is not present, and 6046 If-Modified-Since is present, evaluate the If-Modified-Since 6047 precondition: 6049 o if true, continue to step 5 6051 o if false, respond 304 (Not Modified) 6053 5. When the method is GET and both Range and If-Range are present, 6054 evaluate the If-Range precondition: 6056 o if the validator matches and the Range specification is 6057 applicable to the selected representation, respond 206 6058 (Partial Content) 6060 6. Otherwise, 6062 o all conditions are met, so perform the requested action and 6063 respond according to its success or failure. 6065 Any extension to HTTP that defines additional conditional request 6066 header fields ought to define its own expectations regarding the 6067 order for evaluating such fields in relation to those defined in this 6068 document and other conditionals that might be found in practice. 6070 13. Range Requests 6072 Clients often encounter interrupted data transfers as a result of 6073 canceled requests or dropped connections. When a client has stored a 6074 partial representation, it is desirable to request the remainder of 6075 that representation in a subsequent request rather than transfer the 6076 entire representation. Likewise, devices with limited local storage 6077 might benefit from being able to request only a subset of a larger 6078 representation, such as a single page of a very large document, or 6079 the dimensions of an embedded image. 6081 Range requests are an OPTIONAL feature of HTTP, designed so that 6082 recipients not implementing this feature (or not supporting it for 6083 the target resource) can respond as if it is a normal GET request 6084 without impacting interoperability. Partial responses are indicated 6085 by a distinct status code to not be mistaken for full responses by 6086 caches that might not implement the feature. 6088 13.1. Range Units 6090 Representation data can be partitioned into subranges when there are 6091 addressable structural units inherent to that data's content coding 6092 or media type. For example, octet (a.k.a., byte) boundaries are a 6093 structural unit common to all representation data, allowing 6094 partitions of the data to be identified as a range of bytes at some 6095 offset from the start or end of that data. 6097 This general notion of a "range unit" is used in the Accept-Ranges 6098 (Section 13.3) response header field to advertise support for range 6099 requests, the Range (Section 13.2) request header field to delineate 6100 the parts of a representation that are requested, and the 6101 Content-Range (Section 13.4) payload header field to describe which 6102 part of a representation is being transferred. 6104 range-unit = token 6106 All range unit names are case-insensitive and ought to be registered 6107 within the "HTTP Range Unit Registry", as defined in Section 15.5.1 6109 Range units are intended to be extensible, as described in 6110 Section 15.5. The following range unit names are defined by this 6111 document: 6113 ----------------- ---------------------------------- -------- 6114 Range Unit Name Description Ref. 6115 ----------------- ---------------------------------- -------- 6116 bytes a range of octets 13.1.2 6117 none reserved as keyword to indicate 13.3 6118 range requests are not supported 6119 ----------------- ---------------------------------- -------- 6121 Table 13 6123 13.1.1. Range Specifiers 6125 Ranges are expressed in terms of a range unit paired with a set of 6126 range specifiers. The range unit name determines what kinds of 6127 range-spec are applicable to its own specifiers. Hence, the 6128 following gramar is generic: each range unit is expected to specify 6129 requirements on when int-range, suffix-range, and other-range are 6130 allowed. 6132 A range request can specify a single range or a set of ranges within 6133 a single representation. 6135 ranges-specifier = range-unit "=" range-set 6136 range-set = 1#range-spec 6137 range-spec = int-range 6138 / suffix-range 6139 / other-range 6141 An int-range is a range expressed as two non-negative integers or as 6142 one non-negative integer through to the end of the representation 6143 data. The range unit specifies what the integers mean (e.g., they 6144 might indicate unit offsets from the beginning, inclusive numbered 6145 parts, etc.). 6147 int-range = first-pos "-" [ last-pos ] 6148 first-pos = 1*DIGIT 6149 last-pos = 1*DIGIT 6151 An int-range is invalid if the last-pos value is present and less 6152 than the first-pos. 6154 A suffix-range is a range expressed as a suffix of the representation 6155 data with the provided non-negative integer maximum length (in range 6156 units). In other words, the last N units of the representation data. 6158 suffix-range = "-" suffix-length 6159 suffix-length = 1*DIGIT 6161 To provide for extensibility, the other-range rule is a mostly 6162 unconstrained grammar that allows application-specific or future 6163 range units to define additional range specifiers. 6165 other-range = 1*( %x21-2B / %x2D-7E ) 6166 ; 1*(VCHAR excluding comma) 6168 13.1.2. Byte Ranges 6170 The "bytes" range unit is used to express subranges of a 6171 representation data's octet sequence. Each byte range is expressed 6172 as an integer range at some offset, relative to either the beginning 6173 (int-range) or end (suffix-range) of the representation data. Byte 6174 ranges do not use the other-range specifier. 6176 The first-pos value in a bytes int-range gives the offset of the 6177 first byte in a range. The last-pos value gives the offset of the 6178 last byte in the range; that is, the byte positions specified are 6179 inclusive. Byte offsets start at zero. 6181 If the representation data has a content coding applied, each byte 6182 range is calculated with respect to the encoded sequence of bytes, 6183 not the sequence of underlying bytes that would be obtained after 6184 decoding. 6186 Examples of bytes range specifiers: 6188 o The first 500 bytes (byte offsets 0-499, inclusive): 6190 bytes=0-499 6192 o The second 500 bytes (byte offsets 500-999, inclusive): 6194 bytes=500-999 6196 A client can limit the number of bytes requested without knowing the 6197 size of the selected representation. If the last-pos value is 6198 absent, or if the value is greater than or equal to the current 6199 length of the representation data, the byte range is interpreted as 6200 the remainder of the representation (i.e., the server replaces the 6201 value of last-pos with a value that is one less than the current 6202 length of the selected representation). 6204 A client can request the last N bytes (N > 0) of the selected 6205 representation using a suffix-range. If the selected representation 6206 is shorter than the specified suffix-length, the entire 6207 representation is used. 6209 Additional examples, assuming a representation of length 10000: 6211 o The final 500 bytes (byte offsets 9500-9999, inclusive): 6213 bytes=-500 6215 Or: 6217 bytes=9500- 6219 o The first and last bytes only (bytes 0 and 9999): 6221 bytes=0-0,-1 6223 o The first, middle, and last 1000 bytes: 6225 bytes= 0-999, 4500-5499, -1000 6227 o Other valid (but not canonical) specifications of the second 500 6228 bytes (byte offsets 500-999, inclusive): 6230 bytes=500-600,601-999 6231 bytes=500-700,601-999 6233 If a valid bytes range-set includes at least one range-spec with a 6234 first-pos that is less than the current length of the representation, 6235 or at least one suffix-range with a non-zero suffix-length, then the 6236 bytes range-set is satisfiable. Otherwise, the bytes range-set is 6237 unsatisfiable. 6239 If the selected representation has zero length, the only satisfiable 6240 form of range-spec is a suffix-range with a non-zero suffix-length. 6242 In the byte-range syntax, first-pos, last-pos, and suffix-length are 6243 expressed as decimal number of octets. Since there is no predefined 6244 limit to the length of a payload, recipients MUST anticipate 6245 potentially large decimal numerals and prevent parsing errors due to 6246 integer conversion overflows. 6248 13.2. Range 6250 The "Range" header field on a GET request modifies the method 6251 semantics to request transfer of only one or more subranges of the 6252 selected representation data (Section 7.2), rather than the entire 6253 selected representation. 6255 Range = ranges-specifier 6257 A server MAY ignore the Range header field. However, origin servers 6258 and intermediate caches ought to support byte ranges when possible, 6259 since they support efficient recovery from partially failed transfers 6260 and partial retrieval of large representations. A server MUST ignore 6261 a Range header field received with a request method other than GET. 6263 An origin server MUST ignore a Range header field that contains a 6264 range unit it does not understand. A proxy MAY discard a Range 6265 header field that contains a range unit it does not understand. 6267 A server that supports range requests MAY ignore or reject a Range 6268 header field that consists of more than two overlapping ranges, or a 6269 set of many small ranges that are not listed in ascending order, 6270 since both are indications of either a broken client or a deliberate 6271 denial-of-service attack (Section 16.14). A client SHOULD NOT 6272 request multiple ranges that are inherently less efficient to process 6273 and transfer than a single range that encompasses the same data. 6275 A server that supports range requests MAY ignore a Range header field 6276 when the selected representation has no body (i.e., the selected 6277 representation data is of zero length). 6279 A client that is requesting multiple ranges SHOULD list those ranges 6280 in ascending order (the order in which they would typically be 6281 received in a complete representation) unless there is a specific 6282 need to request a later part earlier. For example, a user agent 6283 processing a large representation with an internal catalog of parts 6284 might need to request later parts first, particularly if the 6285 representation consists of pages stored in reverse order and the user 6286 agent wishes to transfer one page at a time. 6288 The Range header field is evaluated after evaluating the precondition 6289 header fields defined in Section 12.1, and only if the result in 6290 absence of the Range header field would be a 200 (OK) response. In 6291 other words, Range is ignored when a conditional GET would result in 6292 a 304 (Not Modified) response. 6294 The If-Range header field (Section 12.1.5) can be used as a 6295 precondition to applying the Range header field. 6297 If all of the preconditions are true, the server supports the Range 6298 header field for the target resource, and the specified range(s) are 6299 valid and satisfiable (as defined in Section 13.1.2), the server 6300 SHOULD send a 206 (Partial Content) response with a payload 6301 containing one or more partial representations that correspond to the 6302 satisfiable ranges requested. 6304 If all of the preconditions are true, the server supports the Range 6305 header field for the target resource, and the specified range(s) are 6306 invalid or unsatisfiable, the server SHOULD send a 416 (Range Not 6307 Satisfiable) response. 6309 13.3. Accept-Ranges 6311 The "Accept-Ranges" header field allows a server to indicate that it 6312 supports range requests for the target resource. 6314 Accept-Ranges = acceptable-ranges 6315 acceptable-ranges = 1#range-unit / "none" 6317 An origin server that supports byte-range requests for a given target 6318 resource MAY send 6320 Accept-Ranges: bytes 6322 to indicate what range units are supported. A client MAY generate 6323 range requests without having received this header field for the 6324 resource involved. Range units are defined in Section 13.1. 6326 A server that does not support any kind of range request for the 6327 target resource MAY send 6329 Accept-Ranges: none 6331 to advise the client not to attempt a range request. 6333 13.4. Content-Range 6335 The "Content-Range" header field is sent in a single part 206 6336 (Partial Content) response to indicate the partial range of the 6337 selected representation enclosed as the message payload, sent in each 6338 part of a multipart 206 response to indicate the range enclosed 6339 within each body part, and sent in 416 (Range Not Satisfiable) 6340 responses to provide information about the selected representation. 6342 Content-Range = range-unit SP 6343 ( range-resp / unsatisfied-range ) 6345 range-resp = incl-range "/" ( complete-length / "*" ) 6346 incl-range = first-pos "-" last-pos 6347 unsatisfied-range = "*/" complete-length 6349 complete-length = 1*DIGIT 6351 If a 206 (Partial Content) response contains a Content-Range header 6352 field with a range unit (Section 13.1) that the recipient does not 6353 understand, the recipient MUST NOT attempt to recombine it with a 6354 stored representation. A proxy that receives such a message SHOULD 6355 forward it downstream. 6357 For byte ranges, a sender SHOULD indicate the complete length of the 6358 representation from which the range has been extracted, unless the 6359 complete length is unknown or difficult to determine. An asterisk 6360 character ("*") in place of the complete-length indicates that the 6361 representation length was unknown when the header field was 6362 generated. 6364 The following example illustrates when the complete length of the 6365 selected representation is known by the sender to be 1234 bytes: 6367 Content-Range: bytes 42-1233/1234 6369 and this second example illustrates when the complete length is 6370 unknown: 6372 Content-Range: bytes 42-1233/* 6374 A Content-Range field value is invalid if it contains a range-resp 6375 that has a last-pos value less than its first-pos value, or a 6376 complete-length value less than or equal to its last-pos value. The 6377 recipient of an invalid Content-Range MUST NOT attempt to recombine 6378 the received content with a stored representation. 6380 A server generating a 416 (Range Not Satisfiable) response to a byte- 6381 range request SHOULD send a Content-Range header field with an 6382 unsatisfied-range value, as in the following example: 6384 Content-Range: bytes */1234 6386 The complete-length in a 416 response indicates the current length of 6387 the selected representation. 6389 The Content-Range header field has no meaning for status codes that 6390 do not explicitly describe its semantic. For this specification, 6391 only the 206 (Partial Content) and 416 (Range Not Satisfiable) status 6392 codes describe a meaning for Content-Range. 6394 The following are examples of Content-Range values in which the 6395 selected representation contains a total of 1234 bytes: 6397 o The first 500 bytes: 6399 Content-Range: bytes 0-499/1234 6401 o The second 500 bytes: 6403 Content-Range: bytes 500-999/1234 6405 o All except for the first 500 bytes: 6407 Content-Range: bytes 500-1233/1234 6409 o The last 500 bytes: 6411 Content-Range: bytes 734-1233/1234 6413 13.5. Media Type multipart/byteranges 6415 When a 206 (Partial Content) response message includes the content of 6416 multiple ranges, they are transmitted as body parts in a multipart 6417 message body ([RFC2046], Section 5.1) with the media type of 6418 "multipart/byteranges". 6420 The multipart/byteranges media type includes one or more body parts, 6421 each with its own Content-Type and Content-Range fields. The 6422 required boundary parameter specifies the boundary string used to 6423 separate each body part. 6425 Implementation Notes: 6427 1. Additional CRLFs might precede the first boundary string in the 6428 body. 6430 2. Although [RFC2046] permits the boundary string to be quoted, some 6431 existing implementations handle a quoted boundary string 6432 incorrectly. 6434 3. A number of clients and servers were coded to an early draft of 6435 the byteranges specification that used a media type of multipart/ 6436 x-byteranges , which is almost (but not quite) compatible with 6437 this type. 6439 Despite the name, the "multipart/byteranges" media type is not 6440 limited to byte ranges. The following example uses an "exampleunit" 6441 range unit: 6443 HTTP/1.1 206 Partial Content 6444 Date: Tue, 14 Nov 1995 06:25:24 GMT 6445 Last-Modified: Tue, 14 July 04:58:08 GMT 6446 Content-Length: 2331785 6447 Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 6449 --THIS_STRING_SEPARATES 6450 Content-Type: video/example 6451 Content-Range: exampleunit 1.2-4.3/25 6453 ...the first range... 6454 --THIS_STRING_SEPARATES 6455 Content-Type: video/example 6456 Content-Range: exampleunit 11.2-14.3/25 6458 ...the second range 6459 --THIS_STRING_SEPARATES-- 6461 The following information serves as the registration form for the 6462 multipart/byteranges media type. 6464 Type name: multipart 6466 Subtype name: byteranges 6468 Required parameters: boundary 6470 Optional parameters: N/A 6472 Encoding considerations: only "7bit", "8bit", or "binary" are 6473 permitted 6475 Security considerations: see Section 16 6477 Interoperability considerations: N/A 6479 Published specification: This specification (see Section 13.5). 6481 Applications that use this media type: HTTP components supporting 6482 multiple ranges in a single request. 6484 Fragment identifier considerations: N/A 6486 Additional information: Deprecated alias names for this type: N/A 6488 Magic number(s): N/A 6490 File extension(s): N/A 6491 Macintosh file type code(s): N/A 6493 Person and email address to contact for further information: See Aut 6494 hors' Addresses section. 6496 Intended usage: COMMON 6498 Restrictions on usage: N/A 6500 Author: See Authors' Addresses section. 6502 Change controller: IESG 6504 14. Status Codes 6506 The (response) status code is a three-digit integer code giving the 6507 result of the attempt to understand and satisfy the request. 6509 HTTP status codes are extensible. HTTP clients are not required to 6510 understand the meaning of all registered status codes, though such 6511 understanding is obviously desirable. However, a client MUST 6512 understand the class of any status code, as indicated by the first 6513 digit, and treat an unrecognized status code as being equivalent to 6514 the x00 status code of that class. 6516 For example, if an unrecognized status code of 471 is received by a 6517 client, the client can assume that there was something wrong with its 6518 request and treat the response as if it had received a 400 (Bad 6519 Request) status code. The response message will usually contain a 6520 representation that explains the status. 6522 The first digit of the status code defines the class of response. 6523 The last two digits do not have any categorization role. There are 6524 five values for the first digit: 6526 o 1xx (Informational): The request was received, continuing process 6528 o 2xx (Successful): The request was successfully received, 6529 understood, and accepted 6531 o 3xx (Redirection): Further action needs to be taken in order to 6532 complete the request 6534 o 4xx (Client Error): The request contains bad syntax or cannot be 6535 fulfilled 6537 o 5xx (Server Error): The server failed to fulfill an apparently 6538 valid request 6540 A single request can have multiple associated responses: zero or more 6541 interim (non-final) responses with status codes in the 6542 "informational" (1xx) range, followed by exactly one final response 6543 with a status code in one of the other ranges. 6545 14.1. Overview of Status Codes 6547 The status codes listed below are defined in this specification. The 6548 reason phrases listed here are only recommendations - they can be 6549 replaced by local equivalents without affecting the protocol. 6551 Responses with status codes that are defined as heuristically 6552 cacheable (e.g., 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 6553 414, and 501 in this specification) can be reused by a cache with 6554 heuristic expiration unless otherwise indicated by the method 6555 definition or explicit cache controls [Caching]; all other status 6556 codes are not heuristically cacheable. 6558 Additional status codes, outside the scope of this specification, 6559 have been specified for use in HTTP. All such status codes ought to 6560 be registered within the "Hypertext Transfer Protocol (HTTP) Status 6561 Code Registry", as described in Section 15.2. 6563 14.2. Informational 1xx 6565 The 1xx (Informational) class of status code indicates an interim 6566 response for communicating connection status or request progress 6567 prior to completing the requested action and sending a final 6568 response. 1xx responses are terminated by the end of the header 6569 section. Since HTTP/1.0 did not define any 1xx status codes, a 6570 server MUST NOT send a 1xx response to an HTTP/1.0 client. 6572 A client MUST be able to parse one or more 1xx responses received 6573 prior to a final response, even if the client does not expect one. A 6574 user agent MAY ignore unexpected 1xx responses. 6576 A proxy MUST forward 1xx responses unless the proxy itself requested 6577 the generation of the 1xx response. For example, if a proxy adds an 6578 "Expect: 100-continue" field when it forwards a request, then it need 6579 not forward the corresponding 100 (Continue) response(s). 6581 14.2.1. 100 Continue 6583 The 100 (Continue) status code indicates that the initial part of a 6584 request has been received and has not yet been rejected by the 6585 server. The server intends to send a final response after the 6586 request has been fully received and acted upon. 6588 When the request contains an Expect header field that includes a 6589 100-continue expectation, the 100 response indicates that the server 6590 wishes to receive the request payload body, as described in 6591 Section 9.1.1. The client ought to continue sending the request and 6592 discard the 100 response. 6594 If the request did not contain an Expect header field containing the 6595 100-continue expectation, the client can simply discard this interim 6596 response. 6598 14.2.2. 101 Switching Protocols 6600 The 101 (Switching Protocols) status code indicates that the server 6601 understands and is willing to comply with the client's request, via 6602 the Upgrade header field (Section 6.6), for a change in the 6603 application protocol being used on this connection. The server MUST 6604 generate an Upgrade header field in the response that indicates which 6605 protocol(s) will be switched to immediately after the empty line that 6606 terminates the 101 response. 6608 It is assumed that the server will only agree to switch protocols 6609 when it is advantageous to do so. For example, switching to a newer 6610 version of HTTP might be advantageous over older versions, and 6611 switching to a real-time, synchronous protocol might be advantageous 6612 when delivering resources that use such features. 6614 14.3. Successful 2xx 6616 The 2xx (Successful) class of status code indicates that the client's 6617 request was successfully received, understood, and accepted. 6619 14.3.1. 200 OK 6621 The 200 (OK) status code indicates that the request has succeeded. 6622 The payload sent in a 200 response depends on the request method. 6623 For the methods defined by this specification, the intended meaning 6624 of the payload can be summarized as: 6626 GET a representation of the target resource; 6628 HEAD the same representation as GET, but without the representation 6629 data; 6631 POST a representation of the status of, or results obtained from, 6632 the action; 6634 PUT, DELETE a representation of the status of the action; 6635 OPTIONS a representation of the communications options; 6637 TRACE a representation of the request message as received by the end 6638 server. 6640 Aside from responses to CONNECT, a 200 response always has a payload, 6641 though an origin server MAY generate a payload body of zero length. 6642 If no payload is desired, an origin server ought to send 204 (No 6643 Content) instead. For CONNECT, no payload is allowed because the 6644 successful result is a tunnel, which begins immediately after the 200 6645 response header section. 6647 A 200 response is heuristically cacheable; i.e., unless otherwise 6648 indicated by the method definition or explicit cache controls (see 6649 Section 4.2.2 of [Caching]). 6651 14.3.2. 201 Created 6653 The 201 (Created) status code indicates that the request has been 6654 fulfilled and has resulted in one or more new resources being 6655 created. The primary resource created by the request is identified 6656 by either a Location header field in the response or, if no Location 6657 field is received, by the target URI. 6659 The 201 response payload typically describes and links to the 6660 resource(s) created. See Section 7.9 for a discussion of the meaning 6661 and purpose of validator header fields, such as ETag and 6662 Last-Modified, in a 201 response. 6664 14.3.3. 202 Accepted 6666 The 202 (Accepted) status code indicates that the request has been 6667 accepted for processing, but the processing has not been completed. 6668 The request might or might not eventually be acted upon, as it might 6669 be disallowed when processing actually takes place. There is no 6670 facility in HTTP for re-sending a status code from an asynchronous 6671 operation. 6673 The 202 response is intentionally noncommittal. Its purpose is to 6674 allow a server to accept a request for some other process (perhaps a 6675 batch-oriented process that is only run once per day) without 6676 requiring that the user agent's connection to the server persist 6677 until the process is completed. The representation sent with this 6678 response ought to describe the request's current status and point to 6679 (or embed) a status monitor that can provide the user with an 6680 estimate of when the request will be fulfilled. 6682 14.3.4. 203 Non-Authoritative Information 6684 The 203 (Non-Authoritative Information) status code indicates that 6685 the request was successful but the enclosed payload has been modified 6686 from that of the origin server's 200 (OK) response by a transforming 6687 proxy (Section 6.5). This status code allows the proxy to notify 6688 recipients when a transformation has been applied, since that 6689 knowledge might impact later decisions regarding the content. For 6690 example, future cache validation requests for the content might only 6691 be applicable along the same request path (through the same proxies). 6693 The 203 response is similar to the Warning code of 214 Transformation 6694 Applied (Section 5.5 of [Caching]), which has the advantage of being 6695 applicable to responses with any status code. 6697 A 203 response is heuristically cacheable; i.e., unless otherwise 6698 indicated by the method definition or explicit cache controls (see 6699 Section 4.2.2 of [Caching]). 6701 14.3.5. 204 No Content 6703 The 204 (No Content) status code indicates that the server has 6704 successfully fulfilled the request and that there is no additional 6705 content to send in the response payload body. Metadata in the 6706 response header fields refer to the target resource and its selected 6707 representation after the requested action was applied. 6709 For example, if a 204 status code is received in response to a PUT 6710 request and the response contains an ETag field, then the PUT was 6711 successful and the ETag field value contains the entity-tag for the 6712 new representation of that target resource. 6714 The 204 response allows a server to indicate that the action has been 6715 successfully applied to the target resource, while implying that the 6716 user agent does not need to traverse away from its current "document 6717 view" (if any). The server assumes that the user agent will provide 6718 some indication of the success to its user, in accord with its own 6719 interface, and apply any new or updated metadata in the response to 6720 its active representation. 6722 For example, a 204 status code is commonly used with document editing 6723 interfaces corresponding to a "save" action, such that the document 6724 being saved remains available to the user for editing. It is also 6725 frequently used with interfaces that expect automated data transfers 6726 to be prevalent, such as within distributed version control systems. 6728 A 204 response is terminated by the first empty line after the header 6729 fields because it cannot contain a message body. 6731 A 204 response is heuristically cacheable; i.e., unless otherwise 6732 indicated by the method definition or explicit cache controls (see 6733 Section 4.2.2 of [Caching]). 6735 14.3.6. 205 Reset Content 6737 The 205 (Reset Content) status code indicates that the server has 6738 fulfilled the request and desires that the user agent reset the 6739 "document view", which caused the request to be sent, to its original 6740 state as received from the origin server. 6742 This response is intended to support a common data entry use case 6743 where the user receives content that supports data entry (a form, 6744 notepad, canvas, etc.), enters or manipulates data in that space, 6745 causes the entered data to be submitted in a request, and then the 6746 data entry mechanism is reset for the next entry so that the user can 6747 easily initiate another input action. 6749 Since the 205 status code implies that no additional content will be 6750 provided, a server MUST NOT generate a payload in a 205 response. 6752 14.3.7. 206 Partial Content 6754 The 206 (Partial Content) status code indicates that the server is 6755 successfully fulfilling a range request for the target resource by 6756 transferring one or more parts of the selected representation. 6758 When a 206 response is generated, the server MUST generate the 6759 following header fields, in addition to those required in the 6760 subsections below, if the field would have been sent in a 200 (OK) 6761 response to the same request: Date, Cache-Control, ETag, Expires, 6762 Content-Location, and Vary. 6764 A Content-Length field present in a 206 response indicates the number 6765 of octets in the body of this message, which is usually not the 6766 complete length of the selected representation. Each Content-Range 6767 field includes information about the selected representation's 6768 complete length. 6770 If a 206 is generated in response to a request with an If-Range 6771 header field, the sender SHOULD NOT generate other representation 6772 header fields beyond those required, because the client is understood 6773 to already have a prior response containing those header fields. 6774 Otherwise, the sender MUST generate all of the representation header 6775 fields that would have been sent in a 200 (OK) response to the same 6776 request. 6778 A 206 response is heuristically cacheable; i.e., unless otherwise 6779 indicated by explicit cache controls (see Section 4.2.2 of 6780 [Caching]). 6782 14.3.7.1. Single Part 6784 If a single part is being transferred, the server generating the 206 6785 response MUST generate a Content-Range header field, describing what 6786 range of the selected representation is enclosed, and a payload 6787 consisting of the range. For example: 6789 HTTP/1.1 206 Partial Content 6790 Date: Wed, 15 Nov 1995 06:25:24 GMT 6791 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 6792 Content-Range: bytes 21010-47021/47022 6793 Content-Length: 26012 6794 Content-Type: image/gif 6796 ... 26012 bytes of partial image data ... 6798 14.3.7.2. Multiple Parts 6800 If multiple parts are being transferred, the server generating the 6801 206 response MUST generate a "multipart/byteranges" payload, as 6802 defined in Section 13.5, and a Content-Type header field containing 6803 the multipart/byteranges media type and its required boundary 6804 parameter. To avoid confusion with single-part responses, a server 6805 MUST NOT generate a Content-Range header field in the HTTP header 6806 section of a multiple part response (this field will be sent in each 6807 part instead). 6809 Within the header area of each body part in the multipart payload, 6810 the server MUST generate a Content-Range header field corresponding 6811 to the range being enclosed in that body part. If the selected 6812 representation would have had a Content-Type header field in a 200 6813 (OK) response, the server SHOULD generate that same Content-Type 6814 field in the header area of each body part. For example: 6816 HTTP/1.1 206 Partial Content 6817 Date: Wed, 15 Nov 1995 06:25:24 GMT 6818 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 6819 Content-Length: 1741 6820 Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 6822 --THIS_STRING_SEPARATES 6823 Content-Type: application/pdf 6824 Content-Range: bytes 500-999/8000 6826 ...the first range... 6827 --THIS_STRING_SEPARATES 6828 Content-Type: application/pdf 6829 Content-Range: bytes 7000-7999/8000 6831 ...the second range 6832 --THIS_STRING_SEPARATES-- 6834 When multiple ranges are requested, a server MAY coalesce any of the 6835 ranges that overlap, or that are separated by a gap that is smaller 6836 than the overhead of sending multiple parts, regardless of the order 6837 in which the corresponding range-spec appeared in the received Range 6838 header field. Since the typical overhead between parts of a 6839 multipart/byteranges payload is around 80 bytes, depending on the 6840 selected representation's media type and the chosen boundary 6841 parameter length, it can be less efficient to transfer many small 6842 disjoint parts than it is to transfer the entire selected 6843 representation. 6845 A server MUST NOT generate a multipart response to a request for a 6846 single range, since a client that does not request multiple parts 6847 might not support multipart responses. However, a server MAY 6848 generate a multipart/byteranges payload with only a single body part 6849 if multiple ranges were requested and only one range was found to be 6850 satisfiable or only one range remained after coalescing. A client 6851 that cannot process a multipart/byteranges response MUST NOT generate 6852 a request that asks for multiple ranges. 6854 When a multipart response payload is generated, the server SHOULD 6855 send the parts in the same order that the corresponding range-spec 6856 appeared in the received Range header field, excluding those ranges 6857 that were deemed unsatisfiable or that were coalesced into other 6858 ranges. A client that receives a multipart response MUST inspect the 6859 Content-Range header field present in each body part in order to 6860 determine which range is contained in that body part; a client cannot 6861 rely on receiving the same ranges that it requested, nor the same 6862 order that it requested. 6864 14.3.7.3. Combining Parts 6866 A response might transfer only a subrange of a representation if the 6867 connection closed prematurely or if the request used one or more 6868 Range specifications. After several such transfers, a client might 6869 have received several ranges of the same representation. These 6870 ranges can only be safely combined if they all have in common the 6871 same strong validator (Section 7.9.1). 6873 A client that has received multiple partial responses to GET requests 6874 on a target resource MAY combine those responses into a larger 6875 continuous range if they share the same strong validator. 6877 If the most recent response is an incomplete 200 (OK) response, then 6878 the header fields of that response are used for any combined response 6879 and replace those of the matching stored responses. 6881 If the most recent response is a 206 (Partial Content) response and 6882 at least one of the matching stored responses is a 200 (OK), then the 6883 combined response header fields consist of the most recent 200 6884 response's header fields. If all of the matching stored responses 6885 are 206 responses, then the stored response with the most recent 6886 header fields is used as the source of header fields for the combined 6887 response, except that the client MUST use other header fields 6888 provided in the new response, aside from Content-Range, to replace 6889 all instances of the corresponding header fields in the stored 6890 response. 6892 The combined response message body consists of the union of partial 6893 content ranges in the new response and each of the selected 6894 responses. If the union consists of the entire range of the 6895 representation, then the client MUST process the combined response as 6896 if it were a complete 200 (OK) response, including a Content-Length 6897 header field that reflects the complete length. Otherwise, the 6898 client MUST process the set of continuous ranges as one of the 6899 following: an incomplete 200 (OK) response if the combined response 6900 is a prefix of the representation, a single 206 (Partial Content) 6901 response containing a multipart/byteranges body, or multiple 206 6902 (Partial Content) responses, each with one continuous range that is 6903 indicated by a Content-Range header field. 6905 14.4. Redirection 3xx 6907 The 3xx (Redirection) class of status code indicates that further 6908 action needs to be taken by the user agent in order to fulfill the 6909 request. There are several types of redirects: 6911 1. Redirects that indicate this resource might be available at a 6912 different URI, as provided by the Location field, as in the 6913 status codes 301 (Moved Permanently), 302 (Found), 307 (Temporary 6914 Redirect), and 308 (Permanent Redirect). 6916 2. Redirection that offers a choice among matching resources capable 6917 of representing this resource, as in the 300 (Multiple Choices) 6918 status code. 6920 3. Redirection to a different resource, identified by the Location 6921 field, that can represent an indirect response to the request, as 6922 in the 303 (See Other) status code. 6924 4. Redirection to a previously stored result, as in the 304 (Not 6925 Modified) status code. 6927 If a Location header field (Section 9.2.3) is provided, the user 6928 agent MAY automatically redirect its request to the URI referenced by 6929 the Location field value, even if the specific status code is not 6930 understood. Automatic redirection needs to be done with care for 6931 methods not known to be safe, as defined in Section 8.2.1, since the 6932 user might not wish to redirect an unsafe request. 6934 When automatically following a redirected request, the user agent 6935 SHOULD resend the original request message with the following 6936 modifications: 6938 1. Replace the target URI with the URI referenced by the redirection 6939 response's Location header field value after resolving it 6940 relative to the original request's target URI. 6942 2. Remove header fields that were automatically generated by the 6943 implementation, replacing them with updated values as appropriate 6944 to the new request. This includes: 6946 1. Connection-specific header fields (see Section 6.4.1), 6948 2. Header fields specific to the client's proxy configuration, 6949 including (but not limited to) Proxy-Authorization, 6951 3. Origin-specific header fields (if any), including (but not 6952 limited to) Host, 6954 4. Validating header fields that were added by the 6955 implementation's cache (e.g., If-None-Match, 6956 If-Modified-Since), 6958 5. Resource-specific header fields, including (but not limited 6959 to) Referer, Origin, Authorization, and Cookie. 6961 3. Consider removing header fields that were not automatically 6962 generated by the implementation (i.e., those present in the 6963 request because they were added by the calling context) where 6964 there are security implications; this includes but is not limited 6965 to Authorization and Cookie. 6967 4. Change the request method according to the redirecting status 6968 code's semantics, if applicable. 6970 5. If the request method has been changed to GET or HEAD, remove 6971 content-specific header fields, including (but not limited to) 6972 Content-Encoding, Content-Language, Content-Location, 6973 Content-Type, Content-Length, Digest, ETag, Last-Modified. 6975 | *Note:* In HTTP/1.0, the status codes 301 (Moved Permanently) 6976 | and 302 (Found) were defined for the first type of redirect 6977 | ([RFC1945], Section 9.3). Early user agents split on whether 6978 | the method applied to the redirect target would be the same as 6979 | the original request or would be rewritten as GET. Although 6980 | HTTP originally defined the former semantics for 301 and 302 6981 | (to match its original implementation at CERN), and defined 303 6982 | (See Other) to match the latter semantics, prevailing practice 6983 | gradually converged on the latter semantics for 301 and 302 as 6984 | well. The first revision of HTTP/1.1 added 307 (Temporary 6985 | Redirect) to indicate the former semantics of 302 without being 6986 | impacted by divergent practice. For the same reason, 308 6987 | (Permanent Redirect) was later on added in [RFC7538] to match 6988 | 301. Over 10 years later, most user agents still do method 6989 | rewriting for 301 and 302; therefore, [RFC7231] made that 6990 | behavior conformant when the original request is POST. 6992 A client SHOULD detect and intervene in cyclical redirections (i.e., 6993 "infinite" redirection loops). 6995 | *Note:* An earlier version of this specification recommended a 6996 | maximum of five redirections ([RFC2068], Section 10.3). 6997 | Content developers need to be aware that some clients might 6998 | implement such a fixed limitation. 7000 14.4.1. 300 Multiple Choices 7002 The 300 (Multiple Choices) status code indicates that the target 7003 resource has more than one representation, each with its own more 7004 specific identifier, and information about the alternatives is being 7005 provided so that the user (or user agent) can select a preferred 7006 representation by redirecting its request to one or more of those 7007 identifiers. In other words, the server desires that the user agent 7008 engage in reactive negotiation to select the most appropriate 7009 representation(s) for its needs (Section 11). 7011 If the server has a preferred choice, the server SHOULD generate a 7012 Location header field containing a preferred choice's URI reference. 7013 The user agent MAY use the Location field value for automatic 7014 redirection. 7016 For request methods other than HEAD, the server SHOULD generate a 7017 payload in the 300 response containing a list of representation 7018 metadata and URI reference(s) from which the user or user agent can 7019 choose the one most preferred. The user agent MAY make a selection 7020 from that list automatically if it understands the provided media 7021 type. A specific format for automatic selection is not defined by 7022 this specification because HTTP tries to remain orthogonal to the 7023 definition of its payloads. In practice, the representation is 7024 provided in some easily parsed format believed to be acceptable to 7025 the user agent, as determined by shared design or content 7026 negotiation, or in some commonly accepted hypertext format. 7028 A 300 response is heuristically cacheable; i.e., unless otherwise 7029 indicated by the method definition or explicit cache controls (see 7030 Section 4.2.2 of [Caching]). 7032 | *Note:* The original proposal for the 300 status code defined 7033 | the URI header field as providing a list of alternative 7034 | representations, such that it would be usable for 200, 300, and 7035 | 406 responses and be transferred in responses to the HEAD 7036 | method. However, lack of deployment and disagreement over 7037 | syntax led to both URI and Alternates (a subsequent proposal) 7038 | being dropped from this specification. It is possible to 7039 | communicate the list as a Link header field value [RFC8288] 7040 | whose members have a relationship of "alternate", though 7041 | deployment is a chicken-and-egg problem. 7043 14.4.2. 301 Moved Permanently 7045 The 301 (Moved Permanently) status code indicates that the target 7046 resource has been assigned a new permanent URI and any future 7047 references to this resource ought to use one of the enclosed URIs. 7048 Clients with link-editing capabilities ought to automatically re-link 7049 references to the target URI to one or more of the new references 7050 sent by the server, where possible. 7052 The server SHOULD generate a Location header field in the response 7053 containing a preferred URI reference for the new permanent URI. The 7054 user agent MAY use the Location field value for automatic 7055 redirection. The server's response payload usually contains a short 7056 hypertext note with a hyperlink to the new URI(s). 7058 | *Note:* For historical reasons, a user agent MAY change the 7059 | request method from POST to GET for the subsequent request. If 7060 | this behavior is undesired, the 308 (Permanent Redirect) status 7061 | code can be used instead. 7063 A 301 response is heuristically cacheable; i.e., unless otherwise 7064 indicated by the method definition or explicit cache controls (see 7065 Section 4.2.2 of [Caching]). 7067 14.4.3. 302 Found 7069 The 302 (Found) status code indicates that the target resource 7070 resides temporarily under a different URI. Since the redirection 7071 might be altered on occasion, the client ought to continue to use the 7072 target URI for future requests. 7074 The server SHOULD generate a Location header field in the response 7075 containing a URI reference for the different URI. The user agent MAY 7076 use the Location field value for automatic redirection. The server's 7077 response payload usually contains a short hypertext note with a 7078 hyperlink to the different URI(s). 7080 | *Note:* For historical reasons, a user agent MAY change the 7081 | request method from POST to GET for the subsequent request. If 7082 | this behavior is undesired, the 307 (Temporary Redirect) status 7083 | code can be used instead. 7085 14.4.4. 303 See Other 7087 The 303 (See Other) status code indicates that the server is 7088 redirecting the user agent to a different resource, as indicated by a 7089 URI in the Location header field, which is intended to provide an 7090 indirect response to the original request. A user agent can perform 7091 a retrieval request targeting that URI (a GET or HEAD request if 7092 using HTTP), which might also be redirected, and present the eventual 7093 result as an answer to the original request. Note that the new URI 7094 in the Location header field is not considered equivalent to the 7095 target URI. 7097 This status code is applicable to any HTTP method. It is primarily 7098 used to allow the output of a POST action to redirect the user agent 7099 to a selected resource, since doing so provides the information 7100 corresponding to the POST response in a form that can be separately 7101 identified, bookmarked, and cached, independent of the original 7102 request. 7104 A 303 response to a GET request indicates that the origin server does 7105 not have a representation of the target resource that can be 7106 transferred by the server over HTTP. However, the Location field 7107 value refers to a resource that is descriptive of the target 7108 resource, such that making a retrieval request on that other resource 7109 might result in a representation that is useful to recipients without 7110 implying that it represents the original target resource. Note that 7111 answers to the questions of what can be represented, what 7112 representations are adequate, and what might be a useful description 7113 are outside the scope of HTTP. 7115 Except for responses to a HEAD request, the representation of a 303 7116 response ought to contain a short hypertext note with a hyperlink to 7117 the same URI reference provided in the Location header field. 7119 14.4.5. 304 Not Modified 7121 The 304 (Not Modified) status code indicates that a conditional GET 7122 or HEAD request has been received and would have resulted in a 200 7123 (OK) response if it were not for the fact that the condition 7124 evaluated to false. In other words, there is no need for the server 7125 to transfer a representation of the target resource because the 7126 request indicates that the client, which made the request 7127 conditional, already has a valid representation; the server is 7128 therefore redirecting the client to make use of that stored 7129 representation as if it were the payload of a 200 (OK) response. 7131 The server generating a 304 response MUST generate any of the 7132 following header fields that would have been sent in a 200 (OK) 7133 response to the same request: Cache-Control, Content-Location, Date, 7134 ETag, Expires, and Vary. 7136 Since the goal of a 304 response is to minimize information transfer 7137 when the recipient already has one or more cached representations, a 7138 sender SHOULD NOT generate representation metadata other than the 7139 above listed fields unless said metadata exists for the purpose of 7140 guiding cache updates (e.g., Last-Modified might be useful if the 7141 response does not have an ETag field). 7143 Requirements on a cache that receives a 304 response are defined in 7144 Section 4.3.4 of [Caching]. If the conditional request originated 7145 with an outbound client, such as a user agent with its own cache 7146 sending a conditional GET to a shared proxy, then the proxy SHOULD 7147 forward the 304 response to that client. 7149 A 304 response cannot contain a message-body; it is always terminated 7150 by the first empty line after the header fields. 7152 14.4.6. 305 Use Proxy 7154 The 305 (Use Proxy) status code was defined in a previous version of 7155 this specification and is now deprecated (Appendix B of [RFC7231]). 7157 14.4.7. 306 (Unused) 7159 The 306 status code was defined in a previous version of this 7160 specification, is no longer used, and the code is reserved. 7162 14.4.8. 307 Temporary Redirect 7164 The 307 (Temporary Redirect) status code indicates that the target 7165 resource resides temporarily under a different URI and the user agent 7166 MUST NOT change the request method if it performs an automatic 7167 redirection to that URI. Since the redirection can change over time, 7168 the client ought to continue using the original target URI for future 7169 requests. 7171 The server SHOULD generate a Location header field in the response 7172 containing a URI reference for the different URI. The user agent MAY 7173 use the Location field value for automatic redirection. The server's 7174 response payload usually contains a short hypertext note with a 7175 hyperlink to the different URI(s). 7177 14.4.9. 308 Permanent Redirect 7179 The 308 (Permanent Redirect) status code indicates that the target 7180 resource has been assigned a new permanent URI and any future 7181 references to this resource ought to use one of the enclosed URIs. 7182 Clients with link editing capabilities ought to automatically re-link 7183 references to the target URI to one or more of the new references 7184 sent by the server, where possible. 7186 The server SHOULD generate a Location header field in the response 7187 containing a preferred URI reference for the new permanent URI. The 7188 user agent MAY use the Location field value for automatic 7189 redirection. The server's response payload usually contains a short 7190 hypertext note with a hyperlink to the new URI(s). 7192 A 308 response is heuristically cacheable; i.e., unless otherwise 7193 indicated by the method definition or explicit cache controls (see 7194 Section 4.2.2 of [Caching]). 7196 | *Note:* This status code is much younger (June 2014) than its 7197 | sibling codes, and thus might not be recognized everywhere. 7198 | See Section 4 of [RFC7538] for deployment considerations. 7200 14.5. Client Error 4xx 7202 The 4xx (Client Error) class of status code indicates that the client 7203 seems to have erred. Except when responding to a HEAD request, the 7204 server SHOULD send a representation containing an explanation of the 7205 error situation, and whether it is a temporary or permanent 7206 condition. These status codes are applicable to any request method. 7207 User agents SHOULD display any included representation to the user. 7209 14.5.1. 400 Bad Request 7211 The 400 (Bad Request) status code indicates that the server cannot or 7212 will not process the request due to something that is perceived to be 7213 a client error (e.g., malformed request syntax, invalid request 7214 message framing, or deceptive request routing). 7216 14.5.2. 401 Unauthorized 7218 The 401 (Unauthorized) status code indicates that the request has not 7219 been applied because it lacks valid authentication credentials for 7220 the target resource. The server generating a 401 response MUST send 7221 a WWW-Authenticate header field (Section 10.6.1) containing at least 7222 one challenge applicable to the target resource. 7224 If the request included authentication credentials, then the 401 7225 response indicates that authorization has been refused for those 7226 credentials. The user agent MAY repeat the request with a new or 7227 replaced Authorization header field (Section 10.6.2). If the 401 7228 response contains the same challenge as the prior response, and the 7229 user agent has already attempted authentication at least once, then 7230 the user agent SHOULD present the enclosed representation to the 7231 user, since it usually contains relevant diagnostic information. 7233 14.5.3. 402 Payment Required 7235 The 402 (Payment Required) status code is reserved for future use. 7237 14.5.4. 403 Forbidden 7239 The 403 (Forbidden) status code indicates that the server understood 7240 the request but refuses to fulfill it. A server that wishes to make 7241 public why the request has been forbidden can describe that reason in 7242 the response payload (if any). 7244 If authentication credentials were provided in the request, the 7245 server considers them insufficient to grant access. The client 7246 SHOULD NOT automatically repeat the request with the same 7247 credentials. The client MAY repeat the request with new or different 7248 credentials. However, a request might be forbidden for reasons 7249 unrelated to the credentials. 7251 An origin server that wishes to "hide" the current existence of a 7252 forbidden target resource MAY instead respond with a status code of 7253 404 (Not Found). 7255 14.5.5. 404 Not Found 7257 The 404 (Not Found) status code indicates that the origin server did 7258 not find a current representation for the target resource or is not 7259 willing to disclose that one exists. A 404 status code does not 7260 indicate whether this lack of representation is temporary or 7261 permanent; the 410 (Gone) status code is preferred over 404 if the 7262 origin server knows, presumably through some configurable means, that 7263 the condition is likely to be permanent. 7265 A 404 response is heuristically cacheable; i.e., unless otherwise 7266 indicated by the method definition or explicit cache controls (see 7267 Section 4.2.2 of [Caching]). 7269 14.5.6. 405 Method Not Allowed 7271 The 405 (Method Not Allowed) status code indicates that the method 7272 received in the request-line is known by the origin server but not 7273 supported by the target resource. The origin server MUST generate an 7274 Allow header field in a 405 response containing a list of the target 7275 resource's currently supported methods. 7277 A 405 response is heuristically cacheable; i.e., unless otherwise 7278 indicated by the method definition or explicit cache controls (see 7279 Section 4.2.2 of [Caching]). 7281 14.5.7. 406 Not Acceptable 7283 The 406 (Not Acceptable) status code indicates that the target 7284 resource does not have a current representation that would be 7285 acceptable to the user agent, according to the proactive negotiation 7286 header fields received in the request (Section 11.1), and the server 7287 is unwilling to supply a default representation. 7289 The server SHOULD generate a payload containing a list of available 7290 representation characteristics and corresponding resource identifiers 7291 from which the user or user agent can choose the one most 7292 appropriate. A user agent MAY automatically select the most 7293 appropriate choice from that list. However, this specification does 7294 not define any standard for such automatic selection, as described in 7295 Section 14.4.1. 7297 14.5.8. 407 Proxy Authentication Required 7299 The 407 (Proxy Authentication Required) status code is similar to 401 7300 (Unauthorized), but it indicates that the client needs to 7301 authenticate itself in order to use a proxy for this request. The 7302 proxy MUST send a Proxy-Authenticate header field (Section 10.7.1) 7303 containing a challenge applicable to that proxy for the request. The 7304 client MAY repeat the request with a new or replaced 7305 Proxy-Authorization header field (Section 10.7.2). 7307 14.5.9. 408 Request Timeout 7309 The 408 (Request Timeout) status code indicates that the server did 7310 not receive a complete request message within the time that it was 7311 prepared to wait. If the client has an outstanding request in 7312 transit, the client MAY repeat that request on a new connection. 7314 14.5.10. 409 Conflict 7316 The 409 (Conflict) status code indicates that the request could not 7317 be completed due to a conflict with the current state of the target 7318 resource. This code is used in situations where the user might be 7319 able to resolve the conflict and resubmit the request. The server 7320 SHOULD generate a payload that includes enough information for a user 7321 to recognize the source of the conflict. 7323 Conflicts are most likely to occur in response to a PUT request. For 7324 example, if versioning were being used and the representation being 7325 PUT included changes to a resource that conflict with those made by 7326 an earlier (third-party) request, the origin server might use a 409 7327 response to indicate that it can't complete the request. In this 7328 case, the response representation would likely contain information 7329 useful for merging the differences based on the revision history. 7331 14.5.11. 410 Gone 7333 The 410 (Gone) status code indicates that access to the target 7334 resource is no longer available at the origin server and that this 7335 condition is likely to be permanent. If the origin server does not 7336 know, or has no facility to determine, whether or not the condition 7337 is permanent, the status code 404 (Not Found) ought to be used 7338 instead. 7340 The 410 response is primarily intended to assist the task of web 7341 maintenance by notifying the recipient that the resource is 7342 intentionally unavailable and that the server owners desire that 7343 remote links to that resource be removed. Such an event is common 7344 for limited-time, promotional services and for resources belonging to 7345 individuals no longer associated with the origin server's site. It 7346 is not necessary to mark all permanently unavailable resources as 7347 "gone" or to keep the mark for any length of time - that is left to 7348 the discretion of the server owner. 7350 A 410 response is heuristically cacheable; i.e., unless otherwise 7351 indicated by the method definition or explicit cache controls (see 7352 Section 4.2.2 of [Caching]). 7354 14.5.12. 411 Length Required 7356 The 411 (Length Required) status code indicates that the server 7357 refuses to accept the request without a defined Content-Length 7358 (Section 7.7). The client MAY repeat the request if it adds a valid 7359 Content-Length header field containing the length of the message body 7360 in the request message. 7362 14.5.13. 412 Precondition Failed 7364 The 412 (Precondition Failed) status code indicates that one or more 7365 conditions given in the request header fields evaluated to false when 7366 tested on the server. This response status code allows the client to 7367 place preconditions on the current resource state (its current 7368 representations and metadata) and, thus, prevent the request method 7369 from being applied if the target resource is in an unexpected state. 7371 14.5.14. 413 Payload Too Large 7373 The 413 (Payload Too Large) status code indicates that the server is 7374 refusing to process a request because the request payload is larger 7375 than the server is willing or able to process. The server MAY 7376 terminate the request, if the protocol version in use allows it; 7377 otherwise, the server MAY close the connection. 7379 If the condition is temporary, the server SHOULD generate a 7380 Retry-After header field to indicate that it is temporary and after 7381 what time the client MAY try again. 7383 14.5.15. 414 URI Too Long 7385 The 414 (URI Too Long) status code indicates that the server is 7386 refusing to service the request because the target URI is longer than 7387 the server is willing to interpret. This rare condition is only 7388 likely to occur when a client has improperly converted a POST request 7389 to a GET request with long query information, when the client has 7390 descended into a "black hole" of redirection (e.g., a redirected URI 7391 prefix that points to a suffix of itself) or when the server is under 7392 attack by a client attempting to exploit potential security holes. 7394 A 414 response is heuristically cacheable; i.e., unless otherwise 7395 indicated by the method definition or explicit cache controls (see 7396 Section 4.2.2 of [Caching]). 7398 14.5.16. 415 Unsupported Media Type 7400 The 415 (Unsupported Media Type) status code indicates that the 7401 origin server is refusing to service the request because the payload 7402 is in a format not supported by this method on the target resource. 7404 The format problem might be due to the request's indicated 7405 Content-Type or Content-Encoding, or as a result of inspecting the 7406 data directly. 7408 If the problem was caused by an unsupported content coding, the 7409 Accept-Encoding response header field (Section 11.1.4) ought to be 7410 used to indicate what (if any) content codings would have been 7411 accepted in the request. 7413 On the other hand, if the cause was an unsupported media type, the 7414 Accept response header field (Section 11.1.2) can be used to indicate 7415 what media types would have been accepted in the request. 7417 14.5.17. 416 Range Not Satisfiable 7419 The 416 (Range Not Satisfiable) status code indicates that the set of 7420 ranges in the request's Range header field (Section 13.2) has been 7421 rejected either because none of the requested ranges are satisfiable 7422 or because the client has requested an excessive number of small or 7423 overlapping ranges (a potential denial of service attack). 7425 Each range unit defines what is required for its own range sets to be 7426 satisfiable. For example, Section 13.1.2 defines what makes a bytes 7427 range set satisfiable. 7429 When this status code is generated in response to a byte-range 7430 request, the sender SHOULD generate a Content-Range header field 7431 specifying the current length of the selected representation 7432 (Section 13.4). 7434 For example: 7436 HTTP/1.1 416 Range Not Satisfiable 7437 Date: Fri, 20 Jan 2012 15:41:54 GMT 7438 Content-Range: bytes */47022 7440 | *Note:* Because servers are free to ignore Range, many 7441 | implementations will respond with the entire selected 7442 | representation in a 200 (OK) response. That is partly because 7443 | most clients are prepared to receive a 200 (OK) to complete the 7444 | task (albeit less efficiently) and partly because clients might 7445 | not stop making an invalid partial request until they have 7446 | received a complete representation. Thus, clients cannot 7447 | depend on receiving a 416 (Range Not Satisfiable) response even 7448 | when it is most appropriate. 7450 14.5.18. 417 Expectation Failed 7452 The 417 (Expectation Failed) status code indicates that the 7453 expectation given in the request's Expect header field 7454 (Section 9.1.1) could not be met by at least one of the inbound 7455 servers. 7457 14.5.19. 418 (Unused) 7459 [RFC2324] was an April 1 RFC that lampooned the various ways HTTP was 7460 abused; one such abuse was the definition of an application-specific 7461 418 status code. In the intervening years, this status code has been 7462 widely implemented as an "Easter Egg", and therefore is effectively 7463 consumed by this use. 7465 Therefore, the 418 status code is reserved in the IANA HTTP Status 7466 Code Registry. This indicates that the status code cannot be 7467 assigned to other applications currently. If future circumstances 7468 require its use (e.g., exhaustion of 4NN status codes), it can be re- 7469 assigned to another use. 7471 14.5.20. 422 Unprocessable Payload 7473 The 422 (Unprocessable Payload) status code indicates that the server 7474 understands the content type of the request payload (hence a 415 7475 (Unsupported Media Type) status code is inappropriate), and the 7476 syntax of the request payload is correct, but was unable to process 7477 the contained instructions. For example, this status code can be 7478 sent if an XML request payload contains well-formed (i.e., 7479 syntactically correct), but semantically erroneous XML instructions. 7481 14.5.21. 426 Upgrade Required 7483 The 426 (Upgrade Required) status code indicates that the server 7484 refuses to perform the request using the current protocol but might 7485 be willing to do so after the client upgrades to a different 7486 protocol. The server MUST send an Upgrade header field in a 426 7487 response to indicate the required protocol(s) (Section 6.6). 7489 Example: 7491 HTTP/1.1 426 Upgrade Required 7492 Upgrade: HTTP/3.0 7493 Connection: Upgrade 7494 Content-Length: 53 7495 Content-Type: text/plain 7497 This service requires use of the HTTP/3.0 protocol. 7499 14.6. Server Error 5xx 7501 The 5xx (Server Error) class of status code indicates that the server 7502 is aware that it has erred or is incapable of performing the 7503 requested method. Except when responding to a HEAD request, the 7504 server SHOULD send a representation containing an explanation of the 7505 error situation, and whether it is a temporary or permanent 7506 condition. A user agent SHOULD display any included representation 7507 to the user. These response codes are applicable to any request 7508 method. 7510 14.6.1. 500 Internal Server Error 7512 The 500 (Internal Server Error) status code indicates that the server 7513 encountered an unexpected condition that prevented it from fulfilling 7514 the request. 7516 14.6.2. 501 Not Implemented 7518 The 501 (Not Implemented) status code indicates that the server does 7519 not support the functionality required to fulfill the request. This 7520 is the appropriate response when the server does not recognize the 7521 request method and is not capable of supporting it for any resource. 7523 A 501 response is heuristically cacheable; i.e., unless otherwise 7524 indicated by the method definition or explicit cache controls (see 7525 Section 4.2.2 of [Caching]). 7527 14.6.3. 502 Bad Gateway 7529 The 502 (Bad Gateway) status code indicates that the server, while 7530 acting as a gateway or proxy, received an invalid response from an 7531 inbound server it accessed while attempting to fulfill the request. 7533 14.6.4. 503 Service Unavailable 7535 The 503 (Service Unavailable) status code indicates that the server 7536 is currently unable to handle the request due to a temporary overload 7537 or scheduled maintenance, which will likely be alleviated after some 7538 delay. The server MAY send a Retry-After header field 7539 (Section 9.2.4) to suggest an appropriate amount of time for the 7540 client to wait before retrying the request. 7542 | *Note:* The existence of the 503 status code does not imply 7543 | that a server has to use it when becoming overloaded. Some 7544 | servers might simply refuse the connection. 7546 14.6.5. 504 Gateway Timeout 7548 The 504 (Gateway Timeout) status code indicates that the server, 7549 while acting as a gateway or proxy, did not receive a timely response 7550 from an upstream server it needed to access in order to complete the 7551 request. 7553 14.6.6. 505 HTTP Version Not Supported 7555 The 505 (HTTP Version Not Supported) status code indicates that the 7556 server does not support, or refuses to support, the major version of 7557 HTTP that was used in the request message. The server is indicating 7558 that it is unable or unwilling to complete the request using the same 7559 major version as the client, as described in Section 5.1, other than 7560 with this error message. The server SHOULD generate a representation 7561 for the 505 response that describes why that version is not supported 7562 and what other protocols are supported by that server. 7564 15. Extending HTTP 7566 HTTP defines a number of generic extension points that can be used to 7567 introduce capabilities to the protocol without introducing a new 7568 version, including methods, status codes, field names, and further 7569 extensibility points within defined fields, such as authentication 7570 schemes and cache-directives (see Cache-Control in Section 5.2.3 of 7571 [Caching]). Because the semantics of HTTP are not versioned, these 7572 extension points are persistent; the version of the protocol in use 7573 does not affect their semantics. 7575 Version-independent extensions are discouraged from depending on or 7576 interacting with the specific version of the protocol in use. When 7577 this is unavoidable, careful consideration needs to be given to how 7578 the extension can interoperate across versions. 7580 Additionally, specific versions of HTTP might have their own 7581 extensibility points, such as transfer-codings in HTTP/1.1 7582 (Section 6.1 of [Messaging]) and HTTP/2 ([RFC7540]) SETTINGS or frame 7583 types. These extension points are specific to the version of the 7584 protocol they occur within. 7586 Version-specific extensions cannot override or modify the semantics 7587 of a version-independent mechanism or extension point (like a method 7588 or header field) without explicitly being allowed by that protocol 7589 element. For example, the CONNECT method (Section 8.3.6) allows 7590 this. 7592 These guidelines assure that the protocol operates correctly and 7593 predictably, even when parts of the path implement different versions 7594 of HTTP. 7596 15.1. Method Extensibility 7598 15.1.1. Method Registry 7600 The "Hypertext Transfer Protocol (HTTP) Method Registry", maintained 7601 by IANA at , registers 7602 method names. 7604 HTTP method registrations MUST include the following fields: 7606 o Method Name (see Section 8) 7608 o Safe ("yes" or "no", see Section 8.2.1) 7610 o Idempotent ("yes" or "no", see Section 8.2.2) 7612 o Pointer to specification text 7614 Values to be added to this namespace require IETF Review (see 7615 [RFC8126], Section 4.8). 7617 15.1.2. Considerations for New Methods 7619 Standardized methods are generic; that is, they are potentially 7620 applicable to any resource, not just one particular media type, kind 7621 of resource, or application. As such, it is preferred that new 7622 methods be registered in a document that isn't specific to a single 7623 application or data format, since orthogonal technologies deserve 7624 orthogonal specification. 7626 Since message parsing (Section 6 of [Messaging]) needs to be 7627 independent of method semantics (aside from responses to HEAD), 7628 definitions of new methods cannot change the parsing algorithm or 7629 prohibit the presence of a message body on either the request or the 7630 response message. Definitions of new methods can specify that only a 7631 zero-length message body is allowed by requiring a Content-Length 7632 header field with a value of "0". 7634 A new method definition needs to indicate whether it is safe 7635 (Section 8.2.1), idempotent (Section 8.2.2), cacheable 7636 (Section 8.2.3), what semantics are to be associated with the payload 7637 body if any is present in the request and what refinements the method 7638 makes to header field or status code semantics. If the new method is 7639 cacheable, its definition ought to describe how, and under what 7640 conditions, a cache can store a response and use it to satisfy a 7641 subsequent request. The new method ought to describe whether it can 7642 be made conditional (Section 12.1) and, if so, how a server responds 7643 when the condition is false. Likewise, if the new method might have 7644 some use for partial response semantics (Section 13.2), it ought to 7645 document this, too. 7647 | *Note:* Avoid defining a method name that starts with "M-", 7648 | since that prefix might be misinterpreted as having the 7649 | semantics assigned to it by [RFC2774]. 7651 15.2. Status Code Extensibility 7653 15.2.1. Status Code Registry 7655 The "Hypertext Transfer Protocol (HTTP) Status Code Registry", 7656 maintained by IANA at , registers status code numbers. 7659 A registration MUST include the following fields: 7661 o Status Code (3 digits) 7663 o Short Description 7665 o Pointer to specification text 7667 Values to be added to the HTTP status code namespace require IETF 7668 Review (see [RFC8126], Section 4.8). 7670 15.2.2. Considerations for New Status Codes 7672 When it is necessary to express semantics for a response that are not 7673 defined by current status codes, a new status code can be registered. 7674 Status codes are generic; they are potentially applicable to any 7675 resource, not just one particular media type, kind of resource, or 7676 application of HTTP. As such, it is preferred that new status codes 7677 be registered in a document that isn't specific to a single 7678 application. 7680 New status codes are required to fall under one of the categories 7681 defined in Section 14. To allow existing parsers to process the 7682 response message, new status codes cannot disallow a payload, 7683 although they can mandate a zero-length payload body. 7685 Proposals for new status codes that are not yet widely deployed ought 7686 to avoid allocating a specific number for the code until there is 7687 clear consensus that it will be registered; instead, early drafts can 7688 use a notation such as "4NN", or "3N0" .. "3N9", to indicate the 7689 class of the proposed status code(s) without consuming a number 7690 prematurely. 7692 The definition of a new status code ought to explain the request 7693 conditions that would cause a response containing that status code 7694 (e.g., combinations of request header fields and/or method(s)) along 7695 with any dependencies on response header fields (e.g., what fields 7696 are required, what fields can modify the semantics, and what field 7697 semantics are further refined when used with the new status code). 7699 By default, a status code applies only to the request corresponding 7700 to the response it occurs within. If a status code applies to a 7701 larger scope of applicability - for example, all requests to the 7702 resource in question, or all requests to a server - this must be 7703 explicitly specified. When doing so, it should be noted that not all 7704 clients can be expected to consistently apply a larger scope, because 7705 they might not understand the new status code. 7707 The definition of a new status code ought to specify whether or not 7708 it is cacheable. Note that all status codes can be cached if the 7709 response they occur in has explicit freshness information; however, 7710 status codes that are defined as being cacheable are allowed to be 7711 cached without explicit freshness information. Likewise, the 7712 definition of a status code can place constraints upon cache 7713 behavior. See [Caching] for more information. 7715 Finally, the definition of a new status code ought to indicate 7716 whether the payload has any implied association with an identified 7717 resource (Section 5.5.2). 7719 15.3. Field Name Extensibility 7721 15.3.1. Field Name Registry 7723 The "Hypertext Transfer Protocol (HTTP) Field Name Registry" defines 7724 the namespace for HTTP field names. 7726 Any party can request registration of a HTTP field. See 7727 Section 15.3.3 for considerations to take into account when creating 7728 a new HTTP field. 7730 The "Hypertext Transfer Protocol (HTTP) Field Name Registry" is 7731 located at . 7732 Registration requests can be made by following the instructions 7733 located there or by sending an email to the "ietf-http-wg@ietf.org" 7734 mailing list. 7736 Field names are registered on the advice of a Designated Expert 7737 (appointed by the IESG or their delegate). Fields with the status 7738 'permanent' are Specification Required ([RFC8126], Section 4.6). 7740 Registration requests consist of at least the following information: 7742 Field name: 7743 The requested field name. It MUST conform to the field-name 7744 syntax defined in Section 5.4.3, and SHOULD be restricted to just 7745 letters, digits, hyphen ('-') and underscore ('_') characters, 7746 with the first character being a letter. 7748 Status: 7749 "permanent" or "provisional". 7751 Specification document(s): 7752 Reference to the document that specifies the field, preferably 7753 including a URI that can be used to retrieve a copy of the 7754 document. An indication of the relevant section(s) can also be 7755 included, but is not required. 7757 And, optionally: 7759 Comments: Additional information, such as about reserved entries. 7761 The Expert(s) can define additional fields to be collected in the 7762 registry, in consultation with the community. 7764 Standards-defined names have a status of "permanent". Other names 7765 can also be registered as permanent, if the Expert(s) find that they 7766 are in use, in consultation with the community. Other names should 7767 be registered as "provisional". 7769 Provisional entries can be removed by the Expert(s) if - in 7770 consultation with the community - the Expert(s) find that they are 7771 not in use. The Experts can change a provisional entry's status to 7772 permanent at any time. 7774 Note that names can be registered by third parties (including the 7775 Expert(s)), if the Expert(s) determines that an unregistered name is 7776 widely deployed and not likely to be registered in a timely manner 7777 otherwise. 7779 15.3.2. Considerations for New Field Names 7781 There is no limit on the introduction of new field names, each 7782 presumably defining new semantics. 7784 New fields can be defined such that, when they are understood by a 7785 recipient, they might override or enhance the interpretation of 7786 previously defined fields, define preconditions on request 7787 evaluation, or refine the meaning of responses. 7789 Authors of specifications defining new fields are advised to choose a 7790 short but descriptive field name. Short names avoid needless data 7791 transmission; descriptive names avoid confusion and "squatting" on 7792 names that might have broader uses. 7794 To that end, limited-use fields (such as a header confined to a 7795 single application or use case) are encouraged to use a name that 7796 includes its name (or an abbreviation) as a prefix; for example, if 7797 the Foo Application needs a Description field, it might use "Foo- 7798 Desc"; "Description" is too generic, and "Foo-Description" is 7799 needlessly long. 7801 While the field-name syntax is defined to allow any token character, 7802 in practice some implementations place limits on the characters they 7803 accept in field-names. To be interoperable, new field names SHOULD 7804 constrain themselves to alphanumeric characters, "-", and ".", and 7805 SHOULD begin with an alphanumeric character. 7807 Field names ought not be prefixed with "X-"; see [BCP178] for further 7808 information. 7810 Other prefixes are sometimes used in HTTP field names; for example, 7811 "Accept-" is used in many content negotiation headers. These 7812 prefixes are only an aid to recognizing the purpose of a field, and 7813 do not trigger automatic processing. 7815 15.3.3. Considerations for New Field Values 7817 Authors of specifications defining new fields are advised to consider 7818 documenting: 7820 o Whether the field has a singleton or list-based value (see 7821 Section 5.4.4). 7823 If it is a singleton field, document how to treat messages where 7824 the multiple members are present (a sensible default would be to 7825 ignore the field, but this might not always be the right choice). 7827 Note that intermediaries and software libraries might combine 7828 multiple field instances into a single one, despite the field 7829 being defined as a singleton. A robust format enables recipients 7830 to discover these situations (good example: "Content-Type", as the 7831 comma can only appear inside quoted strings; bad example: 7832 "Location", as a comma can occur inside a URI). 7834 o Under what conditions the field can be used; e.g., only in 7835 responses or requests, in all messages, only on responses to a 7836 particular request method, etc. 7838 o What the scope of applicability for the information conveyed in 7839 the field is. By default, fields apply only to the message they 7840 are associated with, but some response fields are designed to 7841 apply to all representations of a resource, the resource itself, 7842 or an even broader scope. Specifications that expand the scope of 7843 a response field will need to carefully consider issues such as 7844 content negotiation, the time period of applicability, and (in 7845 some cases) multi-tenant server deployments. 7847 o Whether the field should be stored by origin servers that 7848 understand it upon a PUT request. 7850 o Whether the field semantics are further refined by the context, 7851 such as by existing request methods or status codes. 7853 o Whether it is appropriate to list the field name in the Connection 7854 header field (i.e., if the field is to be hop-by-hop; see 7855 Section 6.4.1). 7857 o Under what conditions intermediaries are allowed to insert, 7858 delete, or modify the field's value. 7860 o Whether it is appropriate to list the field name in a Vary 7861 response header field (e.g., when the request header field is used 7862 by an origin server's content selection algorithm; see 7863 Section 11.2.1). 7865 o Whether the field is allowable in trailers (see Section 5.6). 7867 o Whether the field ought to be preserved across redirects. 7869 o Whether it introduces any additional security considerations, such 7870 as disclosure of privacy-related data. 7872 15.4. Authentication Scheme Extensibility 7874 15.4.1. Authentication Scheme Registry 7876 The "Hypertext Transfer Protocol (HTTP) Authentication Scheme 7877 Registry" defines the namespace for the authentication schemes in 7878 challenges and credentials. It is maintained at 7879 . 7881 Registrations MUST include the following fields: 7883 o Authentication Scheme Name 7885 o Pointer to specification text 7887 o Notes (optional) 7889 Values to be added to this namespace require IETF Review (see 7890 [RFC8126], Section 4.8). 7892 15.4.2. Considerations for New Authentication Schemes 7894 There are certain aspects of the HTTP Authentication framework that 7895 put constraints on how new authentication schemes can work: 7897 o HTTP authentication is presumed to be stateless: all of the 7898 information necessary to authenticate a request MUST be provided 7899 in the request, rather than be dependent on the server remembering 7900 prior requests. Authentication based on, or bound to, the 7901 underlying connection is outside the scope of this specification 7902 and inherently flawed unless steps are taken to ensure that the 7903 connection cannot be used by any party other than the 7904 authenticated user (see Section 3.7). 7906 o The authentication parameter "realm" is reserved for defining 7907 protection spaces as described in Section 10.5. New schemes MUST 7908 NOT use it in a way incompatible with that definition. 7910 o The "token68" notation was introduced for compatibility with 7911 existing authentication schemes and can only be used once per 7912 challenge or credential. Thus, new schemes ought to use the auth- 7913 param syntax instead, because otherwise future extensions will be 7914 impossible. 7916 o The parsing of challenges and credentials is defined by this 7917 specification and cannot be modified by new authentication 7918 schemes. When the auth-param syntax is used, all parameters ought 7919 to support both token and quoted-string syntax, and syntactical 7920 constraints ought to be defined on the field value after parsing 7921 (i.e., quoted-string processing). This is necessary so that 7922 recipients can use a generic parser that applies to all 7923 authentication schemes. 7925 *Note:* The fact that the value syntax for the "realm" parameter 7926 is restricted to quoted-string was a bad design choice not to be 7927 repeated for new parameters. 7929 o Definitions of new schemes ought to define the treatment of 7930 unknown extension parameters. In general, a "must-ignore" rule is 7931 preferable to a "must-understand" rule, because otherwise it will 7932 be hard to introduce new parameters in the presence of legacy 7933 recipients. Furthermore, it's good to describe the policy for 7934 defining new parameters (such as "update the specification" or 7935 "use this registry"). 7937 o Authentication schemes need to document whether they are usable in 7938 origin-server authentication (i.e., using WWW-Authenticate), and/ 7939 or proxy authentication (i.e., using Proxy-Authenticate). 7941 o The credentials carried in an Authorization header field are 7942 specific to the user agent and, therefore, have the same effect on 7943 HTTP caches as the "private" Cache-Control response directive 7944 (Section 5.2.2.7 of [Caching]), within the scope of the request in 7945 which they appear. 7947 Therefore, new authentication schemes that choose not to carry 7948 credentials in the Authorization header field (e.g., using a newly 7949 defined header field) will need to explicitly disallow caching, by 7950 mandating the use of Cache-Control response directives (e.g., 7951 "private"). 7953 o Schemes using Authentication-Info, Proxy-Authentication-Info, or 7954 any other authentication related response header field need to 7955 consider and document the related security considerations (see 7956 Section 16.15.4). 7958 15.5. Range Unit Extensibility 7960 15.5.1. Range Unit Registry 7962 The "HTTP Range Unit Registry" defines the namespace for the range 7963 unit names and refers to their corresponding specifications. It is 7964 maintained at . 7966 Registration of an HTTP Range Unit MUST include the following fields: 7968 o Name 7970 o Description 7972 o Pointer to specification text 7974 Values to be added to this namespace require IETF Review (see 7975 [RFC8126], Section 4.8). 7977 15.5.2. Considerations for New Range Units 7979 Other range units, such as format-specific boundaries like pages, 7980 sections, records, rows, or time, are potentially usable in HTTP for 7981 application-specific purposes, but are not commonly used in practice. 7982 Implementors of alternative range units ought to consider how they 7983 would work with content codings and general-purpose intermediaries. 7985 15.6. Content Coding Extensibility 7987 15.6.1. Content Coding Registry 7989 The "HTTP Content Coding Registry", maintained by IANA at 7990 , registers 7991 content-coding names. 7993 Content coding registrations MUST include the following fields: 7995 o Name 7997 o Description 7999 o Pointer to specification text 8001 Names of content codings MUST NOT overlap with names of transfer 8002 codings (Section 7 of [Messaging]), unless the encoding 8003 transformation is identical (as is the case for the compression 8004 codings defined in Section 7.5.1). 8006 Values to be added to this namespace require IETF Review (see 8007 Section 4.8 of [RFC8126]) and MUST conform to the purpose of content 8008 coding defined in Section 7.5.1. 8010 15.6.2. Considerations for New Content Codings 8012 New content codings ought to be self-descriptive whenever possible, 8013 with optional parameters discoverable within the coding format 8014 itself, rather than rely on external metadata that might be lost 8015 during transit. 8017 15.7. Upgrade Token Registry 8019 The "Hypertext Transfer Protocol (HTTP) Upgrade Token Registry" 8020 defines the namespace for protocol-name tokens used to identify 8021 protocols in the Upgrade header field. The registry is maintained at 8022 . 8024 Each registered protocol name is associated with contact information 8025 and an optional set of specifications that details how the connection 8026 will be processed after it has been upgraded. 8028 Registrations happen on a "First Come First Served" basis (see 8029 Section 4.4 of [RFC8126]) and are subject to the following rules: 8031 1. A protocol-name token, once registered, stays registered forever. 8033 2. A protocol-name token is case-insensitive and registered with the 8034 preferred case to be generated by senders. 8036 3. The registration MUST name a responsible party for the 8037 registration. 8039 4. The registration MUST name a point of contact. 8041 5. The registration MAY name a set of specifications associated with 8042 that token. Such specifications need not be publicly available. 8044 6. The registration SHOULD name a set of expected "protocol-version" 8045 tokens associated with that token at the time of registration. 8047 7. The responsible party MAY change the registration at any time. 8048 The IANA will keep a record of all such changes, and make them 8049 available upon request. 8051 8. The IESG MAY reassign responsibility for a protocol token. This 8052 will normally only be used in the case when a responsible party 8053 cannot be contacted. 8055 16. Security Considerations 8057 This section is meant to inform developers, information providers, 8058 and users of known security concerns relevant to HTTP semantics and 8059 its use for transferring information over the Internet. 8060 Considerations related to message syntax, parsing, and routing are 8061 discussed in Section 11 of [Messaging]. 8063 The list of considerations below is not exhaustive. Most security 8064 concerns related to HTTP semantics are about securing server-side 8065 applications (code behind the HTTP interface), securing user agent 8066 processing of payloads received via HTTP, or secure use of the 8067 Internet in general, rather than security of the protocol. Various 8068 organizations maintain topical information and links to current 8069 research on Web application security (e.g., [OWASP]). 8071 16.1. Establishing Authority 8073 HTTP relies on the notion of an authoritative response: a response 8074 that has been determined by (or at the direction of) the origin 8075 server identified within the target URI to be the most appropriate 8076 response for that request given the state of the target resource at 8077 the time of response message origination. 8079 When a registered name is used in the authority component, the "http" 8080 URI scheme (Section 4.2.1) relies on the user's local name resolution 8081 service to determine where it can find authoritative responses. This 8082 means that any attack on a user's network host table, cached names, 8083 or name resolution libraries becomes an avenue for attack on 8084 establishing authority for "http" URIs. Likewise, the user's choice 8085 of server for Domain Name Service (DNS), and the hierarchy of servers 8086 from which it obtains resolution results, could impact the 8087 authenticity of address mappings; DNS Security Extensions (DNSSEC, 8088 [RFC4033]) are one way to improve authenticity. 8090 Furthermore, after an IP address is obtained, establishing authority 8091 for an "http" URI is vulnerable to attacks on Internet Protocol 8092 routing. 8094 The "https" scheme (Section 4.2.2) is intended to prevent (or at 8095 least reveal) many of these potential attacks on establishing 8096 authority, provided that the negotiated connection is secured and the 8097 client properly verifies that the communicating server's identity 8098 matches the target URI's authority component (Section 4.3.4). 8099 Correctly implementing such verification can be difficult (see 8100 [Georgiev]). 8102 Authority for a given origin server can be delegated through protocol 8103 extensions; for example, [RFC7838]. Likewise, the set of servers 8104 that a connection is considered authoritative for can be changed with 8105 a protocol extension like [RFC8336]. 8107 Providing a response from a non-authoritative source, such as a 8108 shared proxy cache, is often useful to improve performance and 8109 availability, but only to the extent that the source can be trusted 8110 or the distrusted response can be safely used. 8112 Unfortunately, communicating authority to users can be difficult. 8113 For example, phishing is an attack on the user's perception of 8114 authority, where that perception can be misled by presenting similar 8115 branding in hypertext, possibly aided by userinfo obfuscating the 8116 authority component (see Section 4.2.1). User agents can reduce the 8117 impact of phishing attacks by enabling users to easily inspect a 8118 target URI prior to making an action, by prominently distinguishing 8119 (or rejecting) userinfo when present, and by not sending stored 8120 credentials and cookies when the referring document is from an 8121 unknown or untrusted source. 8123 16.2. Risks of Intermediaries 8125 HTTP intermediaries are inherently situated for on-path attacks. 8126 Compromise of the systems on which the intermediaries run can result 8127 in serious security and privacy problems. Intermediaries might have 8128 access to security-related information, personal information about 8129 individual users and organizations, and proprietary information 8130 belonging to users and content providers. A compromised 8131 intermediary, or an intermediary implemented or configured without 8132 regard to security and privacy considerations, might be used in the 8133 commission of a wide range of potential attacks. 8135 Intermediaries that contain a shared cache are especially vulnerable 8136 to cache poisoning attacks, as described in Section 7 of [Caching]. 8138 Implementers need to consider the privacy and security implications 8139 of their design and coding decisions, and of the configuration 8140 options they provide to operators (especially the default 8141 configuration). 8143 Users need to be aware that intermediaries are no more trustworthy 8144 than the people who run them; HTTP itself cannot solve this problem. 8146 16.3. Attacks Based on File and Path Names 8148 Origin servers frequently make use of their local file system to 8149 manage the mapping from target URI to resource representations. Most 8150 file systems are not designed to protect against malicious file or 8151 path names. Therefore, an origin server needs to avoid accessing 8152 names that have a special significance to the system when mapping the 8153 target resource to files, folders, or directories. 8155 For example, UNIX, Microsoft Windows, and other operating systems use 8156 ".." as a path component to indicate a directory level above the 8157 current one, and they use specially named paths or file names to send 8158 data to system devices. Similar naming conventions might exist 8159 within other types of storage systems. Likewise, local storage 8160 systems have an annoying tendency to prefer user-friendliness over 8161 security when handling invalid or unexpected characters, 8162 recomposition of decomposed characters, and case-normalization of 8163 case-insensitive names. 8165 Attacks based on such special names tend to focus on either denial- 8166 of-service (e.g., telling the server to read from a COM port) or 8167 disclosure of configuration and source files that are not meant to be 8168 served. 8170 16.4. Attacks Based on Command, Code, or Query Injection 8172 Origin servers often use parameters within the URI as a means of 8173 identifying system services, selecting database entries, or choosing 8174 a data source. However, data received in a request cannot be 8175 trusted. An attacker could construct any of the request data 8176 elements (method, target URI, header fields, or body) to contain data 8177 that might be misinterpreted as a command, code, or query when passed 8178 through a command invocation, language interpreter, or database 8179 interface. 8181 For example, SQL injection is a common attack wherein additional 8182 query language is inserted within some part of the target URI or 8183 header fields (e.g., Host, Referer, etc.). If the received data is 8184 used directly within a SELECT statement, the query language might be 8185 interpreted as a database command instead of a simple string value. 8186 This type of implementation vulnerability is extremely common, in 8187 spite of being easy to prevent. 8189 In general, resource implementations ought to avoid use of request 8190 data in contexts that are processed or interpreted as instructions. 8191 Parameters ought to be compared to fixed strings and acted upon as a 8192 result of that comparison, rather than passed through an interface 8193 that is not prepared for untrusted data. Received data that isn't 8194 based on fixed parameters ought to be carefully filtered or encoded 8195 to avoid being misinterpreted. 8197 Similar considerations apply to request data when it is stored and 8198 later processed, such as within log files, monitoring tools, or when 8199 included within a data format that allows embedded scripts. 8201 16.5. Attacks via Protocol Element Length 8203 Because HTTP uses mostly textual, character-delimited fields, parsers 8204 are often vulnerable to attacks based on sending very long (or very 8205 slow) streams of data, particularly where an implementation is 8206 expecting a protocol element with no predefined length (Section 2.3). 8208 To promote interoperability, specific recommendations are made for 8209 minimum size limits on fields (Section 5.4.2). These are minimum 8210 recommendations, chosen to be supportable even by implementations 8211 with limited resources; it is expected that most implementations will 8212 choose substantially higher limits. 8214 A server can reject a message that has a target URI that is too long 8215 (Section 14.5.15) or a request payload that is too large 8216 (Section 14.5.14). Additional status codes related to capacity 8217 limits have been defined by extensions to HTTP [RFC6585]. 8219 Recipients ought to carefully limit the extent to which they process 8220 other protocol elements, including (but not limited to) request 8221 methods, response status phrases, field names, numeric values, and 8222 body chunks. Failure to limit such processing can result in buffer 8223 overflows, arithmetic overflows, or increased vulnerability to 8224 denial-of-service attacks. 8226 16.6. Attacks using Shared-dictionary Compression 8228 Some attacks on encrypted protocols use the differences in size 8229 created by dynamic compression to reveal confidential information; 8230 for example, [BREACH]. These attacks rely on creating a redundancy 8231 between attacker-controlled content and the confidential information, 8232 such that a dynamic compression algorithm using the same dictionary 8233 for both content will compress more efficiently when the attacker- 8234 controlled content matches parts of the confidential content. 8236 HTTP messages can be compressed in a number of ways, including using 8237 TLS compression, content-codings, transfer-codings, and other 8238 extension or version-specific mechanisms. 8240 The most effective mitigation for this risk is to disable compression 8241 on sensitive data, or to strictly separate sensitive data from 8242 attacker-controlled data so that they cannot share the same 8243 compression dictionary. With careful design, a compression scheme 8244 can be designed in a way that is not considered exploitable in 8245 limited use cases, such as HPACK ([RFC7541]). 8247 16.7. Disclosure of Personal Information 8249 Clients are often privy to large amounts of personal information, 8250 including both information provided by the user to interact with 8251 resources (e.g., the user's name, location, mail address, passwords, 8252 encryption keys, etc.) and information about the user's browsing 8253 activity over time (e.g., history, bookmarks, etc.). Implementations 8254 need to prevent unintentional disclosure of personal information. 8256 16.8. Privacy of Server Log Information 8258 A server is in the position to save personal data about a user's 8259 requests over time, which might identify their reading patterns or 8260 subjects of interest. In particular, log information gathered at an 8261 intermediary often contains a history of user agent interaction, 8262 across a multitude of sites, that can be traced to individual users. 8264 HTTP log information is confidential in nature; its handling is often 8265 constrained by laws and regulations. Log information needs to be 8266 securely stored and appropriate guidelines followed for its analysis. 8267 Anonymization of personal information within individual entries 8268 helps, but it is generally not sufficient to prevent real log traces 8269 from being re-identified based on correlation with other access 8270 characteristics. As such, access traces that are keyed to a specific 8271 client are unsafe to publish even if the key is pseudonymous. 8273 To minimize the risk of theft or accidental publication, log 8274 information ought to be purged of personally identifiable 8275 information, including user identifiers, IP addresses, and user- 8276 provided query parameters, as soon as that information is no longer 8277 necessary to support operational needs for security, auditing, or 8278 fraud control. 8280 16.9. Disclosure of Sensitive Information in URIs 8282 URIs are intended to be shared, not secured, even when they identify 8283 secure resources. URIs are often shown on displays, added to 8284 templates when a page is printed, and stored in a variety of 8285 unprotected bookmark lists. Many servers, proxies, and user agents 8286 log or display the target URI in places where it might be visible to 8287 third parties. It is therefore unwise to include information within 8288 a URI that is sensitive, personally identifiable, or a risk to 8289 disclose. 8291 When an application uses client-side mechanisms to construct a target 8292 URI out of user-provided information, such as the query fields of a 8293 form using GET, potentially sensitive data might be provided that 8294 would not be appropriate for disclosure within a URI. POST is often 8295 preferred in such cases because it usually doesn't construct a URI; 8296 instead, POST of a form transmits the potentially sensitive data in 8297 the request body. However, this hinders caching and uses an unsafe 8298 method for what would otherwise be a safe request. Alternative 8299 workarounds include transforming the user-provided data prior to 8300 constructing the URI, or filtering the data to only include common 8301 values that are not sensitive. Likewise, redirecting the result of a 8302 query to a different (server-generated) URI can remove potentially 8303 sensitive data from later links and provide a cacheable response for 8304 later reuse. 8306 Since the Referer header field tells a target site about the context 8307 that resulted in a request, it has the potential to reveal 8308 information about the user's immediate browsing history and any 8309 personal information that might be found in the referring resource's 8310 URI. Limitations on the Referer header field are described in 8311 Section 9.1.3 to address some of its security considerations. 8313 16.10. Disclosure of Fragment after Redirects 8315 Although fragment identifiers used within URI references are not sent 8316 in requests, implementers ought to be aware that they will be visible 8317 to the user agent and any extensions or scripts running as a result 8318 of the response. In particular, when a redirect occurs and the 8319 original request's fragment identifier is inherited by the new 8320 reference in Location (Section 9.2.3), this might have the effect of 8321 disclosing one site's fragment to another site. If the first site 8322 uses personal information in fragments, it ought to ensure that 8323 redirects to other sites include a (possibly empty) fragment 8324 component in order to block that inheritance. 8326 16.11. Disclosure of Product Information 8328 The User-Agent (Section 9.1.6), Via (Section 6.4.3), and Server 8329 (Section 9.2.5) header fields often reveal information about the 8330 respective sender's software systems. In theory, this can make it 8331 easier for an attacker to exploit known security holes; in practice, 8332 attackers tend to try all potential holes regardless of the apparent 8333 software versions being used. 8335 Proxies that serve as a portal through a network firewall ought to 8336 take special precautions regarding the transfer of header information 8337 that might identify hosts behind the firewall. The Via header field 8338 allows intermediaries to replace sensitive machine names with 8339 pseudonyms. 8341 16.12. Browser Fingerprinting 8343 Browser fingerprinting is a set of techniques for identifying a 8344 specific user agent over time through its unique set of 8345 characteristics. These characteristics might include information 8346 related to its TCP behavior, feature capabilities, and scripting 8347 environment, though of particular interest here is the set of unique 8348 characteristics that might be communicated via HTTP. Fingerprinting 8349 is considered a privacy concern because it enables tracking of a user 8350 agent's behavior over time ([Bujlow]) without the corresponding 8351 controls that the user might have over other forms of data collection 8352 (e.g., cookies). Many general-purpose user agents (i.e., Web 8353 browsers) have taken steps to reduce their fingerprints. 8355 There are a number of request header fields that might reveal 8356 information to servers that is sufficiently unique to enable 8357 fingerprinting. The From header field is the most obvious, though it 8358 is expected that From will only be sent when self-identification is 8359 desired by the user. Likewise, Cookie header fields are deliberately 8360 designed to enable re-identification, so fingerprinting concerns only 8361 apply to situations where cookies are disabled or restricted by the 8362 user agent's configuration. 8364 The User-Agent header field might contain enough information to 8365 uniquely identify a specific device, usually when combined with other 8366 characteristics, particularly if the user agent sends excessive 8367 details about the user's system or extensions. However, the source 8368 of unique information that is least expected by users is proactive 8369 negotiation (Section 11.1), including the Accept, Accept-Charset, 8370 Accept-Encoding, and Accept-Language header fields. 8372 In addition to the fingerprinting concern, detailed use of the 8373 Accept-Language header field can reveal information the user might 8374 consider to be of a private nature. For example, understanding a 8375 given language set might be strongly correlated to membership in a 8376 particular ethnic group. An approach that limits such loss of 8377 privacy would be for a user agent to omit the sending of Accept- 8378 Language except for sites that have been whitelisted, perhaps via 8379 interaction after detecting a Vary header field that indicates 8380 language negotiation might be useful. 8382 In environments where proxies are used to enhance privacy, user 8383 agents ought to be conservative in sending proactive negotiation 8384 header fields. General-purpose user agents that provide a high 8385 degree of header field configurability ought to inform users about 8386 the loss of privacy that might result if too much detail is provided. 8387 As an extreme privacy measure, proxies could filter the proactive 8388 negotiation header fields in relayed requests. 8390 16.13. Validator Retention 8392 The validators defined by this specification are not intended to 8393 ensure the validity of a representation, guard against malicious 8394 changes, or detect on-path attacks. At best, they enable more 8395 efficient cache updates and optimistic concurrent writes when all 8396 participants are behaving nicely. At worst, the conditions will fail 8397 and the client will receive a response that is no more harmful than 8398 an HTTP exchange without conditional requests. 8400 An entity-tag can be abused in ways that create privacy risks. For 8401 example, a site might deliberately construct a semantically invalid 8402 entity-tag that is unique to the user or user agent, send it in a 8403 cacheable response with a long freshness time, and then read that 8404 entity-tag in later conditional requests as a means of re-identifying 8405 that user or user agent. Such an identifying tag would become a 8406 persistent identifier for as long as the user agent retained the 8407 original cache entry. User agents that cache representations ought 8408 to ensure that the cache is cleared or replaced whenever the user 8409 performs privacy-maintaining actions, such as clearing stored cookies 8410 or changing to a private browsing mode. 8412 16.14. Denial-of-Service Attacks Using Range 8414 Unconstrained multiple range requests are susceptible to denial-of- 8415 service attacks because the effort required to request many 8416 overlapping ranges of the same data is tiny compared to the time, 8417 memory, and bandwidth consumed by attempting to serve the requested 8418 data in many parts. Servers ought to ignore, coalesce, or reject 8419 egregious range requests, such as requests for more than two 8420 overlapping ranges or for many small ranges in a single set, 8421 particularly when the ranges are requested out of order for no 8422 apparent reason. Multipart range requests are not designed to 8423 support random access. 8425 16.15. Authentication Considerations 8427 Everything about the topic of HTTP authentication is a security 8428 consideration, so the list of considerations below is not exhaustive. 8429 Furthermore, it is limited to security considerations regarding the 8430 authentication framework, in general, rather than discussing all of 8431 the potential considerations for specific authentication schemes 8432 (which ought to be documented in the specifications that define those 8433 schemes). Various organizations maintain topical information and 8434 links to current research on Web application security (e.g., 8435 [OWASP]), including common pitfalls for implementing and using the 8436 authentication schemes found in practice. 8438 16.15.1. Confidentiality of Credentials 8440 The HTTP authentication framework does not define a single mechanism 8441 for maintaining the confidentiality of credentials; instead, each 8442 authentication scheme defines how the credentials are encoded prior 8443 to transmission. While this provides flexibility for the development 8444 of future authentication schemes, it is inadequate for the protection 8445 of existing schemes that provide no confidentiality on their own, or 8446 that do not sufficiently protect against replay attacks. 8447 Furthermore, if the server expects credentials that are specific to 8448 each individual user, the exchange of those credentials will have the 8449 effect of identifying that user even if the content within 8450 credentials remains confidential. 8452 HTTP depends on the security properties of the underlying transport- 8453 or session-level connection to provide confidential transmission of 8454 fields. In other words, if a server limits access to authenticated 8455 users using this framework, the server needs to ensure that the 8456 connection is properly secured in accordance with the nature of the 8457 authentication scheme used. For example, services that depend on 8458 individual user authentication often require a connection to be 8459 secured with TLS ("Transport Layer Security", [RFC8446]) prior to 8460 exchanging any credentials. 8462 16.15.2. Credentials and Idle Clients 8464 Existing HTTP clients and user agents typically retain authentication 8465 information indefinitely. HTTP does not provide a mechanism for the 8466 origin server to direct clients to discard these cached credentials, 8467 since the protocol has no awareness of how credentials are obtained 8468 or managed by the user agent. The mechanisms for expiring or 8469 revoking credentials can be specified as part of an authentication 8470 scheme definition. 8472 Circumstances under which credential caching can interfere with the 8473 application's security model include but are not limited to: 8475 o Clients that have been idle for an extended period, following 8476 which the server might wish to cause the client to re-prompt the 8477 user for credentials. 8479 o Applications that include a session termination indication (such 8480 as a "logout" or "commit" button on a page) after which the server 8481 side of the application "knows" that there is no further reason 8482 for the client to retain the credentials. 8484 User agents that cache credentials are encouraged to provide a 8485 readily accessible mechanism for discarding cached credentials under 8486 user control. 8488 16.15.3. Protection Spaces 8490 Authentication schemes that solely rely on the "realm" mechanism for 8491 establishing a protection space will expose credentials to all 8492 resources on an origin server. Clients that have successfully made 8493 authenticated requests with a resource can use the same 8494 authentication credentials for other resources on the same origin 8495 server. This makes it possible for a different resource to harvest 8496 authentication credentials for other resources. 8498 This is of particular concern when an origin server hosts resources 8499 for multiple parties under the same canonical root URI 8500 (Section 10.5). Possible mitigation strategies include restricting 8501 direct access to authentication credentials (i.e., not making the 8502 content of the Authorization request header field available), and 8503 separating protection spaces by using a different host name (or port 8504 number) for each party. 8506 16.15.4. Additional Response Fields 8508 Adding information to responses that are sent over an unencrypted 8509 channel can affect security and privacy. The presence of the 8510 Authentication-Info and Proxy-Authentication-Info header fields alone 8511 indicates that HTTP authentication is in use. Additional information 8512 could be exposed by the contents of the authentication-scheme 8513 specific parameters; this will have to be considered in the 8514 definitions of these schemes. 8516 17. IANA Considerations 8518 The change controller for the following registrations is: "IETF 8519 (iesg@ietf.org) - Internet Engineering Task Force". 8521 17.1. URI Scheme Registration 8523 Please update the registry of URI Schemes [BCP35] at 8524 with the permanent 8525 schemes listed in the first table of Section 3.1. 8527 17.2. Method Registration 8529 Please update the "Hypertext Transfer Protocol (HTTP) Method 8530 Registry" at with the 8531 registration procedure of Section 15.1.1 and the method names 8532 summarized in the following table. 8534 --------- ------ ------------ ------- 8535 Method Safe Idempotent Ref. 8536 --------- ------ ------------ ------- 8537 * no no 17.2 8538 CONNECT no no 8.3.6 8539 DELETE no yes 8.3.5 8540 GET yes yes 8.3.1 8541 HEAD yes yes 8.3.2 8542 OPTIONS yes yes 8.3.7 8543 POST no no 8.3.3 8544 PUT no yes 8.3.4 8545 TRACE yes yes 8.3.8 8546 --------- ------ ------------ ------- 8548 Table 14 8550 The method name "*" is reserved, since using that name as HTTP method 8551 name might conflict with special semantics in fields such as "Access- 8552 Control-Request-Method". 8554 17.3. Status Code Registration 8556 Please update the "Hypertext Transfer Protocol (HTTP) Status Code 8557 Registry" at 8558 with the registration procedure of Section 15.2.1 and the status code 8559 values summarized in the following table. 8561 ------- ------------------------------- --------- 8562 Value Description Ref. 8563 ------- ------------------------------- --------- 8564 100 Continue 14.2.1 8565 101 Switching Protocols 14.2.2 8566 200 OK 14.3.1 8567 201 Created 14.3.2 8568 202 Accepted 14.3.3 8569 203 Non-Authoritative Information 14.3.4 8570 204 No Content 14.3.5 8571 205 Reset Content 14.3.6 8572 206 Partial Content 14.3.7 8573 300 Multiple Choices 14.4.1 8574 301 Moved Permanently 14.4.2 8575 302 Found 14.4.3 8576 303 See Other 14.4.4 8577 304 Not Modified 14.4.5 8578 305 Use Proxy 14.4.6 8579 306 (Unused) 14.4.7 8580 307 Temporary Redirect 14.4.8 8581 308 Permanent Redirect 14.4.9 8582 400 Bad Request 14.5.1 8583 401 Unauthorized 14.5.2 8584 402 Payment Required 14.5.3 8585 403 Forbidden 14.5.4 8586 404 Not Found 14.5.5 8587 405 Method Not Allowed 14.5.6 8588 406 Not Acceptable 14.5.7 8589 407 Proxy Authentication Required 14.5.8 8590 408 Request Timeout 14.5.9 8591 409 Conflict 14.5.10 8592 410 Gone 14.5.11 8593 411 Length Required 14.5.12 8594 412 Precondition Failed 14.5.13 8595 413 Payload Too Large 14.5.14 8596 414 URI Too Long 14.5.15 8597 415 Unsupported Media Type 14.5.16 8598 416 Range Not Satisfiable 14.5.17 8599 417 Expectation Failed 14.5.18 8600 418 (Unused) 14.5.19 8601 422 Unprocessable Payload 14.5.20 8602 426 Upgrade Required 14.5.21 8603 500 Internal Server Error 14.6.1 8604 501 Not Implemented 14.6.2 8605 502 Bad Gateway 14.6.3 8606 503 Service Unavailable 14.6.4 8607 504 Gateway Timeout 14.6.5 8608 505 HTTP Version Not Supported 14.6.6 8609 ------- ------------------------------- --------- 8611 Table 15 8613 Additionally, please update the following entry in the Hypertext 8614 Transfer Protocol (HTTP) Status Code Registry: 8616 Value: 418 8617 Description: (Unused) 8619 Reference Section 14.5.19 8621 17.4. HTTP Field Name Registration 8623 Please create a new registry as outlined in Section 15.3.1. 8625 After creating the registry, all entries in the Permanent and 8626 Provisional Message Header Registries with the protocol 'http' are to 8627 be moved to it, with the following changes applied: 8629 1. The 'Applicable Protocol' field is to be omitted. 8631 2. Entries with a status of 'standard', 'experimental', 'reserved', 8632 or 'informational' are to have a status of 'permanent'. 8634 3. Provisional entries without a status are to have a status of 8635 'provisional'. 8637 4. Permanent entries without a status (after confirmation that the 8638 registration document did not define one) will have a status of 8639 'provisional'. The Expert(s) can choose to update their status 8640 if there is evidence that another is more appropriate. 8642 Please annotate the Permanent and Provisional Message Header 8643 registries to indicate that HTTP field name registrations have moved, 8644 with an appropriate link. 8646 After that is complete, please update the new registry with the field 8647 names listed in the following table. 8649 --------------------------- ------------ -------- 8650 Field Name Status Ref. 8651 --------------------------- ------------ -------- 8652 Accept standard 11.1.2 8653 Accept-Charset deprecated 11.1.3 8654 Accept-Encoding standard 11.1.4 8655 Accept-Language standard 11.1.5 8656 Accept-Ranges standard 13.3 8657 Allow standard 9.2.1 8658 Authentication-Info standard 10.6.3 8659 Authorization standard 10.6.2 8660 Connection standard 6.4.1 8661 Content-Encoding standard 7.5 8662 Content-Language standard 7.6 8663 Content-Length standard 7.7 8664 Content-Location standard 7.8 8665 Content-Range standard 13.4 8666 Content-Type standard 7.4 8667 Date standard 9.2.2 8668 ETag standard 7.9.3 8669 Expect standard 9.1.1 8670 From standard 9.1.2 8671 Host standard 6.1.2 8672 If-Match standard 12.1.1 8673 If-Modified-Since standard 12.1.3 8674 If-None-Match standard 12.1.2 8675 If-Range standard 12.1.5 8676 If-Unmodified-Since standard 12.1.4 8677 Last-Modified standard 7.9.2 8678 Location standard 9.2.3 8679 Max-Forwards standard 6.4.2 8680 Proxy-Authenticate standard 10.7.1 8681 Proxy-Authentication-Info standard 10.7.3 8682 Proxy-Authorization standard 10.7.2 8683 Range standard 13.2 8684 Referer standard 9.1.3 8685 Retry-After standard 9.2.4 8686 Server standard 9.2.5 8687 TE standard 9.1.4 8688 Trailer standard 9.1.5 8689 Upgrade standard 6.6 8690 User-Agent standard 9.1.6 8691 Vary standard 11.2.1 8692 Via standard 6.4.3 8693 WWW-Authenticate standard 10.6.1 8694 --------------------------- ------------ -------- 8696 Table 16 8698 Furthermore, the field name "*" is reserved, since using that name as 8699 an HTTP header field might conflict with its special semantics in the 8700 Vary header field (Section 11.2.1). 8702 ------------ ---------- -------- ------------ 8703 Field Name Status Ref. Comments 8704 ------------ ---------- -------- ------------ 8705 * standard 11.2.1 (reserved) 8706 ------------ ---------- -------- ------------ 8708 Table 17 8710 Finally, please update the "Content-MD5" entry in the new registry to 8711 have a status of 'obsoleted' with references to Section 14.15 of 8712 [RFC2616] (for the definition of the header field) and Appendix B of 8713 [RFC7231] (which removed the field definition from the updated 8714 specification). 8716 17.5. Authentication Scheme Registration 8718 Please update the "Hypertext Transfer Protocol (HTTP) Authentication 8719 Scheme Registry" at with the registration procedure of Section 15.4.1. No 8721 authentication schemes are defined in this document. 8723 17.6. Content Coding Registration 8725 Please update the "HTTP Content Coding Registry" at 8726 with the 8727 registration procedure of Section 15.6.1 and the content coding names 8728 summarized in the table of Section 7.5.1. 8730 17.7. Range Unit Registration 8732 Please update the "HTTP Range Unit Registry" at 8733 with the 8734 registration procedure of Section 15.5.1 and the range unit names 8735 summarized in the table of Section 13.1. 8737 17.8. Media Type Registration 8739 Please update the "Media Types" registry at 8740 with the registration 8741 information in Section 13.5 for the media type "multipart/ 8742 byteranges". 8744 17.9. Port Registration 8746 Please update the "Service Name and Transport Protocol Port Number" 8747 registry at for the services on ports 80 and 443 that use UDP or TCP 8749 to: 8751 1. use this document as "Reference", and 8753 2. when currently unspecified, set "Assignee" to "IESG" and 8754 "Contact" to "IETF_Chair". 8756 17.10. Upgrade Token Registration 8758 Please update the "Hypertext Transfer Protocol (HTTP) Upgrade Token 8759 Registry" at 8760 with the registration procedure of Section 15.7 and the upgrade token 8761 names summarized in the following table. 8763 ------ ------------------- ------------------------- ------ 8764 Name Description Expected Version Tokens Ref. 8765 ------ ------------------- ------------------------- ------ 8766 HTTP Hypertext any DIGIT.DIGIT (e.g, 5.1 8767 Transfer Protocol "2.0") 8768 ------ ------------------- ------------------------- ------ 8770 Table 18 8772 18. References 8774 18.1. Normative References 8776 [Caching] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 8777 Ed., "HTTP Caching", Work in Progress, Internet-Draft, 8778 draft-ietf-httpbis-cache-12, October 2, 2020, 8779 . 8781 [Messaging] 8782 Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 8783 Ed., "HTTP/1.1 Messaging", Work in Progress, Internet- 8784 Draft, draft-ietf-httpbis-messaging-12, October 2, 2020, 8785 . 8788 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 8789 RFC 793, DOI 10.17487/RFC0793, September 1981, 8790 . 8792 [RFC1950] Deutsch, L.P. and J-L. Gailly, "ZLIB Compressed Data 8793 Format Specification version 3.3", RFC 1950, 8794 DOI 10.17487/RFC1950, May 1996, 8795 . 8797 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 8798 version 1.3", RFC 1951, DOI 10.17487/RFC1951, May 1996, 8799 . 8801 [RFC1952] Deutsch, P., Gailly, J-L., Adler, M., Deutsch, L.P., and 8802 G. Randers-Pehrson, "GZIP file format specification 8803 version 4.3", RFC 1952, DOI 10.17487/RFC1952, May 1996, 8804 . 8806 [RFC2045] Freed, N. and N.S. Borenstein, "Multipurpose Internet Mail 8807 Extensions (MIME) Part One: Format of Internet Message 8808 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, 8809 . 8811 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 8812 Extensions (MIME) Part Two: Media Types", RFC 2046, 8813 DOI 10.17487/RFC2046, November 1996, 8814 . 8816 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 8817 Requirement Levels", BCP 14, RFC 2119, 8818 DOI 10.17487/RFC2119, March 1997, 8819 . 8821 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 8822 Resource Identifier (URI): Generic Syntax", STD 66, 8823 RFC 3986, DOI 10.17487/RFC3986, January 2005, 8824 . 8826 [RFC4647] Phillips, A., Ed. and M. Davis, Ed., "Matching of Language 8827 Tags", BCP 47, RFC 4647, DOI 10.17487/RFC4647, September 8828 2006, . 8830 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 8831 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 8832 . 8834 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 8835 Specifications: ABNF", STD 68, RFC 5234, 8836 DOI 10.17487/RFC5234, January 2008, 8837 . 8839 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 8840 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 8841 September 2009, . 8843 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 8844 Verification of Domain-Based Application Service Identity 8845 within Internet Public Key Infrastructure Using X.509 8846 (PKIX) Certificates in the Context of Transport Layer 8847 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 8848 2011, . 8850 [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in 8851 Internationalization in the IETF", BCP 166, RFC 6365, 8852 DOI 10.17487/RFC6365, September 2011, 8853 . 8855 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 8856 RFC 7405, DOI 10.17487/RFC7405, December 2014, 8857 . 8859 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 8860 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 8861 May 2017, . 8863 [USASCII] American National Standards Institute, "Coded Character 8864 Set -- 7-bit American Standard Code for Information 8865 Interchange", ANSI X3.4, 1986. 8867 [Welch] Welch, T. A., "A Technique for High-Performance Data 8868 Compression", IEEE Computer 17(6), 8869 DOI 10.1109/MC.1984.1659158, June 1984, 8870 . 8872 18.2. Informative References 8874 [BCP13] Freed, N., Klensin, J., and T. Hansen, "Media Type 8875 Specifications and Registration Procedures", BCP 13, 8876 RFC 6838, January 2013, 8877 . 8879 [BCP178] Saint-Andre, P., Crocker, D., and M. Nottingham, 8880 "Deprecating the "X-" Prefix and Similar Constructs in 8881 Application Protocols", BCP 178, RFC 6648, June 2012, 8882 . 8884 [BCP35] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 8885 and Registration Procedures for URI Schemes", BCP 35, 8886 RFC 7595, June 2015, 8887 . 8889 [BREACH] Gluck, Y., Harris, N., and A. Prado, "BREACH: Reviving the 8890 CRIME Attack", July 2013, 8891 . 8894 [Bujlow] Bujlow, T., Carela-Espanol, V., Sole-Pareta, J., and P. 8895 Barlet-Ros, "A Survey on Web Tracking: Mechanisms, 8896 Implications, and Defenses", 8897 DOI 10.1109/JPROC.2016.2637878, Proceedings of the 8898 IEEE 105(8), August 2017, 8899 . 8901 [Err1912] RFC Errata, Erratum ID 1912, RFC 2978, 8902 . 8904 [Err5433] RFC Errata, Erratum ID 5433, RFC 2978, 8905 . 8907 [Georgiev] Georgiev, M., Iyengar, S., Jana, S., Anubhai, R., Boneh, 8908 D., and V. Shmatikov, "The Most Dangerous Code in the 8909 World: Validating SSL Certificates in Non-browser 8910 Software", DOI 10.1145/2382196.2382204, In Proceedings of 8911 the 2012 ACM Conference on Computer and Communications 8912 Security (CCS '12), pp. 38-49, October 2012, 8913 . 8915 [HTTP3] Bishop, M., "Hypertext Transfer Protocol Version 3 8916 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 8917 quic-http-31, September 25, 2020, 8918 . 8920 [ISO-8859-1] 8921 International Organization for Standardization, 8922 "Information technology -- 8-bit single-byte coded graphic 8923 character sets -- Part 1: Latin alphabet No. 1", ISO/ 8924 IEC 8859-1:1998, 1998. 8926 [Kri2001] Kristol, D., "HTTP Cookies: Standards, Privacy, and 8927 Politics", ACM Transactions on Internet Technology 1(2), 8928 November 2001, . 8930 [OWASP] van der Stock, A., Ed., "A Guide to Building Secure Web 8931 Applications and Web Services", The Open Web Application 8932 Security Project (OWASP) 2.0.1, July 27, 2005, 8933 . 8935 [REST] Fielding, R.T., "Architectural Styles and the Design of 8936 Network-based Software Architectures", 8937 Doctoral Dissertation, University of California, Irvine, 8938 September 2000, 8939 . 8941 [RFC1919] Chatel, M., "Classical versus Transparent IP Proxies", 8942 RFC 1919, DOI 10.17487/RFC1919, March 1996, 8943 . 8945 [RFC1945] Berners-Lee, T., Fielding, R.T., and H.F. Nielsen, 8946 "Hypertext Transfer Protocol -- HTTP/1.0", RFC 1945, 8947 DOI 10.17487/RFC1945, May 1996, 8948 . 8950 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 8951 Part Three: Message Header Extensions for Non-ASCII Text", 8952 RFC 2047, DOI 10.17487/RFC2047, November 1996, 8953 . 8955 [RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and T. 8956 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", 8957 RFC 2068, DOI 10.17487/RFC2068, January 1997, 8958 . 8960 [RFC2145] Mogul, J.C., Fielding, R.T., Gettys, J., and H.F. Nielsen, 8961 "Use and Interpretation of HTTP Version Numbers", 8962 RFC 2145, DOI 10.17487/RFC2145, May 1997, 8963 . 8965 [RFC2295] Holtman, K. and A.H. Mutz, "Transparent Content 8966 Negotiation in HTTP", RFC 2295, DOI 10.17487/RFC2295, 8967 March 1998, . 8969 [RFC2324] Masinter, L., "Hyper Text Coffee Pot Control Protocol 8970 (HTCPCP/1.0)", RFC 2324, DOI 10.17487/RFC2324, April 1, 8971 1998, . 8973 [RFC2557] Palme, F., Hopmann, A., Shelness, N., and E. Stefferud, 8974 "MIME Encapsulation of Aggregate Documents, such as HTML 8975 (MHTML)", RFC 2557, DOI 10.17487/RFC2557, March 1999, 8976 . 8978 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 8979 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 8980 Transfer Protocol -- HTTP/1.1", RFC 2616, 8981 DOI 10.17487/RFC2616, June 1999, 8982 . 8984 [RFC2617] Franks, J., Hallam-Baker, P.M., Hostetler, J.L., Lawrence, 8985 S.D., Leach, P.J., Luotonen, A., and L. Stewart, "HTTP 8986 Authentication: Basic and Digest Access Authentication", 8987 RFC 2617, DOI 10.17487/RFC2617, June 1999, 8988 . 8990 [RFC2774] Frystyk, H., Leach, P., and S. Lawrence, "An HTTP 8991 Extension Framework", RFC 2774, DOI 10.17487/RFC2774, 8992 February 2000, . 8994 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 8995 DOI 10.17487/RFC2818, May 2000, 8996 . 8998 [RFC2978] Freed, N. and J. Postel, "IANA Charset Registration 8999 Procedures", BCP 19, RFC 2978, DOI 10.17487/RFC2978, 9000 October 2000, . 9002 [RFC3040] Cooper, I., Melve, I., and G. Tomlinson, "Internet Web 9003 Replication and Caching Taxonomy", RFC 3040, 9004 DOI 10.17487/RFC3040, January 2001, 9005 . 9007 [RFC4033] Arends, R., Austein, R., Larson, M., Massey, D., and S. 9008 Rose, "DNS Security Introduction and Requirements", 9009 RFC 4033, DOI 10.17487/RFC4033, March 2005, 9010 . 9012 [RFC4559] Jaganathan, K., Zhu, L., and J. Brezak, "SPNEGO-based 9013 Kerberos and NTLM HTTP Authentication in Microsoft 9014 Windows", RFC 4559, DOI 10.17487/RFC4559, June 2006, 9015 . 9017 [RFC4918] Dusseault, L.M., Ed., "HTTP Extensions for Web Distributed 9018 Authoring and Versioning (WebDAV)", RFC 4918, 9019 DOI 10.17487/RFC4918, June 2007, 9020 . 9022 [RFC5322] Resnick, P., "Internet Message Format", RFC 5322, 9023 DOI 10.17487/RFC5322, October 2008, 9024 . 9026 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 9027 RFC 5789, DOI 10.17487/RFC5789, March 2010, 9028 . 9030 [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, 9031 "Network Time Protocol Version 4: Protocol and Algorithms 9032 Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, 9033 . 9035 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 9036 DOI 10.17487/RFC6265, April 2011, 9037 . 9039 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 9040 DOI 10.17487/RFC6454, December 2011, 9041 . 9043 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 9044 Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012, 9045 . 9047 [RFC7230] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9048 Transfer Protocol (HTTP/1.1): Message Syntax and Routing", 9049 RFC 7230, DOI 10.17487/RFC7230, June 2014, 9050 . 9052 [RFC7231] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9053 Transfer Protocol (HTTP/1.1): Semantics and Content", 9054 RFC 7231, DOI 10.17487/RFC7231, June 2014, 9055 . 9057 [RFC7232] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9058 Transfer Protocol (HTTP/1.1): Conditional Requests", 9059 RFC 7232, DOI 10.17487/RFC7232, June 2014, 9060 . 9062 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. F. Reschke, Ed., 9063 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 9064 RFC 7233, DOI 10.17487/RFC7233, June 2014, 9065 . 9067 [RFC7235] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9068 Transfer Protocol (HTTP/1.1): Authentication", RFC 7235, 9069 DOI 10.17487/RFC7235, June 2014, 9070 . 9072 [RFC7538] Reschke, J. F., "The Hypertext Transfer Protocol Status 9073 Code 308 (Permanent Redirect)", RFC 7538, 9074 DOI 10.17487/RFC7538, April 2015, 9075 . 9077 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 9078 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 9079 DOI 10.17487/RFC7540, May 2015, 9080 . 9082 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 9083 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 9084 . 9086 [RFC7578] Masinter, L., "Returning Values from Forms: multipart/ 9087 form-data", RFC 7578, DOI 10.17487/RFC7578, July 2015, 9088 . 9090 [RFC7615] Reschke, J. F., "HTTP Authentication-Info and Proxy- 9091 Authentication-Info Response Header Fields", RFC 7615, 9092 DOI 10.17487/RFC7615, September 2015, 9093 . 9095 [RFC7616] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP 9096 Digest Access Authentication", RFC 7616, 9097 DOI 10.17487/RFC7616, September 2015, 9098 . 9100 [RFC7617] Reschke, J. F., "The 'Basic' HTTP Authentication Scheme", 9101 RFC 7617, DOI 10.17487/RFC7617, September 2015, 9102 . 9104 [RFC7694] Reschke, J. F., "Hypertext Transfer Protocol (HTTP) 9105 Client-Initiated Content-Encoding", RFC 7694, 9106 DOI 10.17487/RFC7694, November 2015, 9107 . 9109 [RFC7838] Nottingham, M., McManus, P., and J. Reschke, "HTTP 9110 Alternative Services", RFC 7838, DOI 10.17487/RFC7838, 9111 April 2016, . 9113 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 9114 Writing an IANA Considerations Section in RFCs", BCP 26, 9115 RFC 8126, DOI 10.17487/RFC8126, June 2017, 9116 . 9118 [RFC8187] Reschke, J. F., "Indicating Character Encoding and 9119 Language for HTTP Header Field Parameters", RFC 8187, 9120 DOI 10.17487/RFC8187, September 2017, 9121 . 9123 [RFC8246] McManus, P., "HTTP Immutable Responses", RFC 8246, 9124 DOI 10.17487/RFC8246, September 2017, 9125 . 9127 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 9128 DOI 10.17487/RFC8288, October 2017, 9129 . 9131 [RFC8336] Nottingham, M. and E. Nygren, "The ORIGIN HTTP/2 Frame", 9132 RFC 8336, DOI 10.17487/RFC8336, March 2018, 9133 . 9135 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 9136 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 9137 . 9139 [Sniffing] WHATWG, "MIME Sniffing", 9140 . 9142 Appendix A. Collected ABNF 9144 In the collected ABNF below, list rules are expanded as per 9145 Section 5.7.1.1. 9147 Accept = [ ( media-range [ accept-params ] ) *( OWS "," OWS ( 9148 media-range [ accept-params ] ) ) ] 9149 Accept-Charset = [ ( ( charset / "*" ) [ weight ] ) *( OWS "," OWS ( 9150 ( charset / "*" ) [ weight ] ) ) ] 9151 Accept-Encoding = [ ( codings [ weight ] ) *( OWS "," OWS ( codings [ 9152 weight ] ) ) ] 9153 Accept-Language = [ ( language-range [ weight ] ) *( OWS "," OWS ( 9154 language-range [ weight ] ) ) ] 9155 Accept-Ranges = acceptable-ranges 9156 Allow = [ method *( OWS "," OWS method ) ] 9157 Authentication-Info = [ auth-param *( OWS "," OWS auth-param ) ] 9158 Authorization = credentials 9160 BWS = OWS 9162 Connection = [ connection-option *( OWS "," OWS connection-option ) 9163 ] 9164 Content-Encoding = [ content-coding *( OWS "," OWS content-coding ) 9165 ] 9166 Content-Language = [ language-tag *( OWS "," OWS language-tag ) ] 9167 Content-Length = 1*DIGIT 9168 Content-Location = absolute-URI / partial-URI 9169 Content-Range = range-unit SP ( range-resp / unsatisfied-range ) 9170 Content-Type = media-type 9172 Date = HTTP-date 9174 ETag = entity-tag 9175 Expect = [ expectation *( OWS "," OWS expectation ) ] 9177 From = mailbox 9179 GMT = %x47.4D.54 ; GMT 9181 HTTP-date = IMF-fixdate / obs-date 9182 Host = uri-host [ ":" port ] 9183 IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT 9184 If-Match = "*" / [ entity-tag *( OWS "," OWS entity-tag ) ] 9185 If-Modified-Since = HTTP-date 9186 If-None-Match = "*" / [ entity-tag *( OWS "," OWS entity-tag ) ] 9187 If-Range = entity-tag / HTTP-date 9188 If-Unmodified-Since = HTTP-date 9190 Last-Modified = HTTP-date 9191 Location = URI-reference 9193 Max-Forwards = 1*DIGIT 9195 OWS = *( SP / HTAB ) 9197 Proxy-Authenticate = [ challenge *( OWS "," OWS challenge ) ] 9198 Proxy-Authentication-Info = [ auth-param *( OWS "," OWS auth-param ) 9199 ] 9200 Proxy-Authorization = credentials 9202 RWS = 1*( SP / HTAB ) 9203 Range = ranges-specifier 9204 Referer = absolute-URI / partial-URI 9205 Retry-After = HTTP-date / delay-seconds 9207 Server = product *( RWS ( product / comment ) ) 9209 TE = [ t-codings *( OWS "," OWS t-codings ) ] 9210 Trailer = [ field-name *( OWS "," OWS field-name ) ] 9212 URI-reference = 9213 Upgrade = [ protocol *( OWS "," OWS protocol ) ] 9214 User-Agent = product *( RWS ( product / comment ) ) 9216 Vary = [ ( "*" / field-name ) *( OWS "," OWS ( "*" / field-name ) ) 9217 ] 9218 Via = [ ( received-protocol RWS received-by [ RWS comment ] ) *( OWS 9219 "," OWS ( received-protocol RWS received-by [ RWS comment ] ) ) ] 9221 WWW-Authenticate = [ challenge *( OWS "," OWS challenge ) ] 9223 absolute-URI = 9224 absolute-path = 1*( "/" segment ) 9225 accept-ext = OWS ";" OWS token [ "=" ( token / quoted-string ) ] 9226 accept-params = weight *accept-ext 9227 acceptable-ranges = ( range-unit *( OWS "," OWS range-unit ) ) / 9228 "none" 9229 asctime-date = day-name SP date3 SP time-of-day SP year 9230 auth-param = token BWS "=" BWS ( token / quoted-string ) 9231 auth-scheme = token 9232 authority = 9234 challenge = auth-scheme [ 1*SP ( token68 / [ auth-param *( OWS "," 9235 OWS auth-param ) ] ) ] 9236 charset = token 9237 codings = content-coding / "identity" / "*" 9238 comment = "(" *( ctext / quoted-pair / comment ) ")" 9239 complete-length = 1*DIGIT 9240 connection-option = token 9241 content-coding = token 9242 credentials = auth-scheme [ 1*SP ( token68 / [ auth-param *( OWS "," 9243 OWS auth-param ) ] ) ] 9244 ctext = HTAB / SP / %x21-27 ; '!'-''' 9245 / %x2A-5B ; '*'-'[' 9246 / %x5D-7E ; ']'-'~' 9247 / obs-text 9249 date1 = day SP month SP year 9250 date2 = day "-" month "-" 2DIGIT 9251 date3 = month SP ( 2DIGIT / ( SP DIGIT ) ) 9252 day = 2DIGIT 9253 day-name = %x4D.6F.6E ; Mon 9254 / %x54.75.65 ; Tue 9255 / %x57.65.64 ; Wed 9256 / %x54.68.75 ; Thu 9257 / %x46.72.69 ; Fri 9258 / %x53.61.74 ; Sat 9259 / %x53.75.6E ; Sun 9260 day-name-l = %x4D.6F.6E.64.61.79 ; Monday 9261 / %x54.75.65.73.64.61.79 ; Tuesday 9262 / %x57.65.64.6E.65.73.64.61.79 ; Wednesday 9263 / %x54.68.75.72.73.64.61.79 ; Thursday 9264 / %x46.72.69.64.61.79 ; Friday 9265 / %x53.61.74.75.72.64.61.79 ; Saturday 9266 / %x53.75.6E.64.61.79 ; Sunday 9267 delay-seconds = 1*DIGIT 9269 entity-tag = [ weak ] opaque-tag 9270 etagc = "!" / %x23-7E ; '#'-'~' 9271 / obs-text 9272 expectation = token [ "=" ( token / quoted-string ) parameters ] 9274 field-content = field-vchar [ 1*( SP / HTAB / field-vchar ) 9275 field-vchar ] 9276 field-name = token 9277 field-value = *field-content 9278 field-vchar = VCHAR / obs-text 9279 first-pos = 1*DIGIT 9281 hour = 2DIGIT 9282 http-URI = "http://" authority path-abempty [ "?" query ] 9283 https-URI = "https://" authority path-abempty [ "?" query ] 9285 incl-range = first-pos "-" last-pos 9286 int-range = first-pos "-" [ last-pos ] 9288 language-range = 9289 language-tag = 9290 last-pos = 1*DIGIT 9292 mailbox = 9293 media-range = ( "*/*" / ( type "/*" ) / ( type "/" subtype ) ) 9294 parameters 9295 media-type = type "/" subtype parameters 9296 method = token 9297 minute = 2DIGIT 9298 month = %x4A.61.6E ; Jan 9299 / %x46.65.62 ; Feb 9300 / %x4D.61.72 ; Mar 9301 / %x41.70.72 ; Apr 9302 / %x4D.61.79 ; May 9303 / %x4A.75.6E ; Jun 9304 / %x4A.75.6C ; Jul 9305 / %x41.75.67 ; Aug 9306 / %x53.65.70 ; Sep 9307 / %x4F.63.74 ; Oct 9308 / %x4E.6F.76 ; Nov 9309 / %x44.65.63 ; Dec 9311 obs-date = rfc850-date / asctime-date 9312 obs-text = %x80-FF 9313 opaque-tag = DQUOTE *etagc DQUOTE 9314 other-range = 1*( %x21-2B ; '!'-'+' 9315 / %x2D-7E ; '-'-'~' 9316 ) 9318 parameter = parameter-name "=" parameter-value 9319 parameter-name = token 9320 parameter-value = ( token / quoted-string ) 9321 parameters = *( OWS ";" OWS [ parameter ] ) 9322 partial-URI = relative-part [ "?" query ] 9323 path-abempty = 9324 port = 9325 product = token [ "/" product-version ] 9326 product-version = token 9327 protocol = protocol-name [ "/" protocol-version ] 9328 protocol-name = token 9329 protocol-version = token 9330 pseudonym = token 9332 qdtext = HTAB / SP / "!" / %x23-5B ; '#'-'[' 9333 / %x5D-7E ; ']'-'~' 9334 / obs-text 9335 query = 9336 quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text ) 9337 quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE 9338 qvalue = ( "0" [ "." *3DIGIT ] ) / ( "1" [ "." *3"0" ] ) 9340 range-resp = incl-range "/" ( complete-length / "*" ) 9341 range-set = range-spec *( OWS "," OWS range-spec ) 9342 range-spec = int-range / suffix-range / other-range 9343 range-unit = token 9344 ranges-specifier = range-unit "=" range-set 9345 rank = ( "0" [ "." *3DIGIT ] ) / ( "1" [ "." *3"0" ] ) 9346 received-by = pseudonym [ ":" port ] 9347 received-protocol = [ protocol-name "/" ] protocol-version 9348 relative-part = 9349 rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT 9351 second = 2DIGIT 9352 segment = 9353 subtype = token 9354 suffix-length = 1*DIGIT 9355 suffix-range = "-" suffix-length 9357 t-codings = "trailers" / ( transfer-coding [ t-ranking ] ) 9358 t-ranking = OWS ";" OWS "q=" rank 9359 tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / 9360 "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA 9361 time-of-day = hour ":" minute ":" second 9362 token = 1*tchar 9363 token68 = 1*( ALPHA / DIGIT / "-" / "." / "_" / "~" / "+" / "/" ) 9364 *"=" 9365 transfer-coding = 9366 type = token 9368 unsatisfied-range = "*/" complete-length 9369 uri-host = 9371 weak = %x57.2F ; W/ 9372 weight = OWS ";" OWS "q=" qvalue 9374 year = 4DIGIT 9376 Appendix B. Changes from previous RFCs 9378 B.1. Changes from RFC 2818 9380 None yet. 9382 B.2. Changes from RFC 7230 9384 The sections introducing HTTP's design goals, history, architecture, 9385 conformance criteria, protocol versioning, URIs, message routing, and 9386 header fields have been moved here (without substantive change). 9388 The description of an origin and authoritative access to origin 9389 servers has been extended for both "http" and "https" URIs to account 9390 for alternative services and secured connections that are not 9391 necessarily based on TCP. (Section 4.2.1, Section 4.2.2, 9392 Section 4.3.1, Section 6.2.3) 9394 "Field value" now refers to the value after multiple instances are 9395 combined with commas - by far the most common use. To refer to a 9396 single header line's value, use "field line value". (Section 5.4) 9398 Parameters in media type, media range, and expectation can be empty 9399 via one or more trailing semicolons. (Section 5.7.6) 9401 Trailer field semantics now transcend the specifics of chunked 9402 encoding. Use of trailer fields has been further limited to only 9403 allow generation as a trailer field when the sender knows the field 9404 defines that usage and to only allow merging into the header section 9405 if the recipient knows the corresponding field definition permits and 9406 defines how to merge. In all other cases, implementations are 9407 encouraged to either store the trailer fields separately or discard 9408 them instead of merging. (Section 5.6.2) 9410 Trailer fields can now potentially appear as multiple trailer 9411 sections, if allowed by the HTTP version and framing in use, with 9412 processing described as being iterative as each section is received. 9413 (Section 5.6.3) 9415 Made the priority of the absolute form of the request URI over the 9416 Host header by origin servers explicit, to align with proxy handling. 9417 (Section 6.1.2) 9418 The grammar definition for the Via field's "received-by" was expanded 9419 in 7230 due to changes in the URI grammar for host [RFC3986] that are 9420 not desirable for Via. For simplicity, we have removed uri-host from 9421 the received-by production because it can be encompassed by the 9422 existing grammar for pseudonym. In particular, this change removed 9423 comma from the allowed set of charaters for a host name in received- 9424 by. (Section 6.4.3) 9426 Added status code 308 (previously defined in [RFC7538]) so that it's 9427 defined closer to status codes 301, 302, and 307. (Section 14.4.9) 9429 Added status code 422 (previously defined in Section 11.2 of 9430 [RFC4918]) because of its general applicability. (Section 14.5.20) 9432 The description of an origin and authoritative access to origin 9433 servers has been extended for both "http" and "https" URIs to account 9434 for alternative services and secured connections that are not 9435 necessarily based on TCP. (Section 4.2.1, Section 4.2.2, 9436 Section 4.3.1, Section 6.2.3) 9438 B.3. Changes from RFC 7231 9440 Minimum URI lengths to be supported by implementations are now 9441 recommended. (Section 3.1) 9443 Clarify that control characters in field values are to be rejected or 9444 mapped to SP. (Section 5.4.4) 9446 Parameters in media type, media range, and expectation can be empty 9447 via one or more trailing semicolons. (Section 5.7.6) 9449 The term "effective request URI" has been replaced with "target URI". 9450 (Section 6.1) 9452 Range units are compared in a case insensitive fashion. 9453 (Section 13.1) 9455 Restrictions on client retries have been loosened, to reflect 9456 implementation behavior. (Section 8.2.2) 9458 Clarified that request bodies on GET and DELETE are not 9459 interoperable. (Section 8.3.1, Section 8.3.5) 9461 Removed a superfluous requirement about setting Content-Length from 9462 the description of the OPTIONS method. (Section 8.3.7) 9464 Restore list-based grammar for Expect for compatibility with RFC 9465 2616. (Section 9.1.1) 9466 Allow Accept and Accept-Encoding in response messages; the latter was 9467 introduced by [RFC7694]. (Section 11.3) 9469 The process of creating a redirected request has been clarified. 9470 (Section 14.4) 9472 The semantics of "*" in the Vary header field when other values are 9473 present was clarified. (Section 11.2.1) 9475 B.4. Changes from RFC 7232 9477 Preconditions can now be evaluated before the request body is 9478 processed rather than waiting until the response would otherwise be 9479 successful. (Section 12.2) 9481 Removed edge case requirement on If-Match and If-Unmodified-Since 9482 that a validator not be sent in a 2xx response when validation fails 9483 and the server decides that the same change request has already been 9484 applied. (Section 12.1.1 and Section 12.1.4) 9486 Clarified that If-Unmodified-Since doesn't apply to a resource 9487 without a concept of modification time. (Section 12.1.4) 9489 B.5. Changes from RFC 7233 9491 Refactored the range-unit and ranges-specifier grammars to simplify 9492 and reduce artificial distinctions between bytes and other 9493 (extension) range units, removing the overlapping grammar of other- 9494 range-unit by defining range units generically as a token and placing 9495 extensions within the scope of a range-spec (other-range). This 9496 disambiguates the role of list syntax (commas) in all range sets, 9497 including extension range units, for indicating a range-set of more 9498 than one range. Moving the extension grammar into range specifiers 9499 also allows protocol specific to byte ranges to be specified 9500 separately. 9502 B.6. Changes from RFC 7235 9504 None yet. 9506 B.7. Changes from RFC 7538 9508 None yet. 9510 B.8. Changes from RFC 7615 9512 None yet. 9514 B.9. Changes from RFC 7694 9516 This specification includes the extension defined in [RFC7694], but 9517 leaves out examples and deployment considerations. 9519 Appendix C. Change Log 9521 This section is to be removed before publishing as an RFC. 9523 C.1. Between RFC723x and draft 00 9525 The changes were purely editorial: 9527 o Change boilerplate and abstract to indicate the "draft" status, 9528 and update references to ancestor specifications. 9530 o Remove version "1.1" from document title, indicating that this 9531 specification applies to all HTTP versions. 9533 o Adjust historical notes. 9535 o Update links to sibling specifications. 9537 o Replace sections listing changes from RFC 2616 by new empty 9538 sections referring to RFC 723x. 9540 o Remove acknowledgements specific to RFC 723x. 9542 o Move "Acknowledgements" to the very end and make them unnumbered. 9544 C.2. Since draft-ietf-httpbis-semantics-00 9546 The changes in this draft are editorial, with respect to HTTP as a 9547 whole, to merge core HTTP semantics into this document: 9549 o Merged introduction, architecture, conformance, and ABNF 9550 extensions from RFC 7230 (Messaging). 9552 o Rearranged architecture to extract conformance, http(s) schemes, 9553 and protocol versioning into a separate major section. 9555 o Moved discussion of MIME differences to [Messaging] since that is 9556 primarily concerned with transforming 1.1 messages. 9558 o Merged entire content of RFC 7232 (Conditional Requests). 9560 o Merged entire content of RFC 7233 (Range Requests). 9562 o Merged entire content of RFC 7235 (Auth Framework). 9564 o Moved all extensibility tips, registration procedures, and 9565 registry tables from the IANA considerations to normative 9566 sections, reducing the IANA considerations to just instructions 9567 that will be removed prior to publication as an RFC. 9569 C.3. Since draft-ietf-httpbis-semantics-01 9571 o Improve [Welch] citation () 9574 o Remove HTTP/1.1-ism about Range Requests 9575 () 9577 o Cite RFC 8126 instead of RFC 5226 () 9580 o Cite RFC 7538 instead of RFC 7238 () 9583 o Cite RFC 8288 instead of RFC 5988 () 9586 o Cite RFC 8187 instead of RFC 5987 () 9589 o Cite RFC 7578 instead of RFC 2388 () 9592 o Cite RFC 7595 instead of RFC 4395 () 9595 o improve ABNF readability for qdtext (, ) 9598 o Clarify "resource" vs "representation" in definition of status 9599 code 416 (, 9600 ) 9602 o Resolved erratum 4072, no change needed here 9603 (, 9604 ) 9606 o Clarify DELETE status code suggestions 9607 (, 9608 ) 9610 o In Section 13.4, fix ABNF for "other-range-resp" to use VCHAR 9611 instead of CHAR (, 9612 ) 9614 o Resolved erratum 5162, no change needed here 9615 (, 9616 ) 9618 o Replace "response code" with "response status code" and "status- 9619 code" (the ABNF production name from the HTTP/1.1 message format) 9620 by "status code" (, 9621 ) 9623 o Added a missing word in Section 14.4 (, ) 9626 o In Section 5.7.1, fixed an example that had trailing whitespace 9627 where it shouldn't (, ) 9630 o In Section 14.3.7, remove words that were potentially misleading 9631 with respect to the relation to the requested ranges 9632 (, 9633 ) 9635 C.4. Since draft-ietf-httpbis-semantics-02 9637 o Included (Proxy-)Auth-Info header field definition from RFC 7615 9638 () 9640 o In Section 8.3.3, clarify POST caching 9641 () 9643 o Add Section 14.5.19 to reserve the 418 status code 9644 () 9646 o In Section 3.3 and Section 9.1.1, clarified when a response can be 9647 sent () 9649 o In Section 7.4.2, explain the difference between the "token" 9650 production, the RFC 2978 ABNF for charset names, and the actual 9651 registration practice (, ) 9654 o In Section 3.1, removed the fragment component in the URI scheme 9655 definitions as per Section 4.3 of [RFC3986], furthermore moved 9656 fragment discussion into a separate section 9657 (, 9658 , ) 9661 o In Section 5.1, add language about minor HTTP version number 9662 defaulting () 9664 o Added Section 14.5.20 for status code 422, previously defined in 9665 Section 11.2 of [RFC4918] () 9668 o In Section 14.5.17, fixed prose about byte range comparison 9669 (, 9670 ) 9672 o In Section 3.3, explain that request/response correlation is 9673 version specific () 9676 C.5. Since draft-ietf-httpbis-semantics-03 9678 o In Section 14.4.9, include status code 308 from RFC 7538 9679 () 9681 o In Section 7.4.1, clarify that the charset parameter value is 9682 case-insensitive due to the definition in RFC 2046 9683 () 9685 o Define a separate registry for HTTP header field names 9686 () 9688 o In Section 11.1, refactor and clarify description of wildcard 9689 ("*") handling () 9691 o Deprecate Accept-Charset () 9694 o In Section 12.2, mention Cache-Control: immutable 9695 () 9697 o In Section 5.4.1, clarify when header field combination is allowed 9698 () 9700 o In Section 17.4, instruct IANA to mark Content-MD5 as obsolete 9701 () 9703 o Use RFC 7405 ABNF notation for case-sensitive string constants 9704 () 9706 o Rework Section 3.3 to be more version-independent 9707 () 9709 o In Section 8.3.5, clarify that DELETE needs to be successful to 9710 invalidate cache (, ) 9713 C.6. Since draft-ietf-httpbis-semantics-04 9715 o In Section 5.4.4, fix field-content ABNF 9716 (, 9717 ) 9719 o Move Section 5.7.6 into its own section 9720 () 9722 o In Section 7.4, reference MIME Sniffing 9723 () 9725 o In Section 5.7.1, simplify the #rule mapping for recipients 9726 (, 9727 ) 9729 o In Section 8.3.7, remove misleading text about "extension" of HTTP 9730 is needed to define method payloads () 9733 o Fix editorial issue in Section 7 () 9736 o In Section 14.5.20, rephrase language not to use "entity" anymore, 9737 and also avoid lowercase "may" () 9740 o Move discussion of retries from [Messaging] into Section 8.2.2 9741 () 9743 C.7. Since draft-ietf-httpbis-semantics-05 9745 o Moved transport-independent part of the description of trailers 9746 into Section 5.6 () 9748 o Loosen requirements on retries based upon implementation behavior 9749 () 9751 o In Section 17.9, update IANA port registry for TCP/UDP on ports 80 9752 and 443 () 9754 o In Section 15.3.3, revise guidelines for new header field names 9755 () 9757 o In Section 8.2.3, remove concept of "cacheable methods" in favor 9758 of prose (, 9759 ) 9761 o In Section 16.1, mention that the concept of authority can be 9762 modified by protocol extensions () 9765 o Create new subsection on payload body in Section 5.5.4, taken from 9766 portions of message body () 9769 o Moved definition of "Whitespace" into new container "Generic 9770 Syntax" () 9772 o In Section 3.1, recommend minimum URI size support for 9773 implementations () 9775 o In Section 13.1, refactored the range-unit and ranges-specifier 9776 grammars (, 9777 ) 9779 o In Section 8.3.1, caution against a request body more strongly 9780 () 9782 o Reorganized text in Section 15.3.3 () 9785 o In Section 14.5.4, replace "authorize" with "fulfill" 9786 () 9788 o In Section 8.3.7, removed a misleading statement about Content- 9789 Length (, 9790 ) 9792 o In Section 16.1, add text from RFC 2818 9793 () 9795 o Changed "cacheable by default" to "heuristically cacheable" 9796 throughout () 9798 C.8. Since draft-ietf-httpbis-semantics-06 9800 o In Section 6.4.3, simplify received-by grammar (and disallow comma 9801 character) () 9803 o In Section 5.4.3, give guidance on interoperable field names 9804 () 9806 o In Section 5.7.3, define the semantics and possible replacement of 9807 whitespace when it is known to occur (, ) 9810 o In Section 5.4, introduce field terminology and distinguish 9811 between field line values and field values; use terminology 9812 consistently throughout () 9815 o Moved #rule definition into Section 5.4.4 and whitespace into 9816 Section 2.1 () 9818 o In Section 13.1, explicitly call out range unit names as case- 9819 insensitive, and encourage registration 9820 () 9822 o In Section 7.5.1, explicitly call out content codings as case- 9823 insensitive, and encourage registration 9824 () 9826 o In Section 5.4.3, explicitly call out field names as case- 9827 insensitive () 9829 o In Section 16.12, cite [Bujlow] () 9832 o In Section 14, formally define "final" and "interim" status codes 9833 () 9835 o In Section 8.3.5, caution against a request body more strongly 9836 () 9838 o In Section 7.9.3, note that Etag can be used in trailers 9839 () 9841 o In Section 17.4, consider reserved fields as well 9842 () 9844 o In Section 4.2.4, be more correct about what was deprecated by RFC 9845 3986 (, 9846 ) 9848 o In Section 5.4.1, recommend comma SP when combining field lines 9849 () 9851 o In Section 6.1.2, make explicit requirements on origin server to 9852 use authority from absolute-form when available 9853 () 9855 o In Section 4.2.1, Section 4.2.2, Section 4.3.1, and Section 6.2.3, 9856 refactored schemes to define origin and authoritative access to an 9857 origin server for both "http" and "https" URIs to account for 9858 alternative services and secured connections that are not 9859 necessarily based on TCP () 9862 o In Section 2.2, reference RFC 8174 as well 9863 () 9865 C.9. Since draft-ietf-httpbis-semantics-07 9867 o In Section 13.2, explicitly reference the definition of 9868 representation data as including any content codings 9869 () 9871 o Move TE: trailers from [Messaging] into Section 5.6.2 9872 () 9874 o In Section 7.7, adjust requirements for handling multiple content- 9875 length values () 9877 o In Section 12.1.1 and Section 12.1.2, clarified condition 9878 evaluation () 9880 o In Section 5.4.4, remove concept of obs-fold, as that is 9881 HTTP/1-specific () 9883 o In Section 11, introduce the concept of request payload 9884 negotiation (Section 11.3) and define for Accept-Encoding 9885 () 9887 o In Section 14.3.6, Section 14.5.9, and Section 14.5.14, remove 9888 HTTP/1-specific, connection-related requirements 9889 () 9891 o In Section 8.3.6, correct language about what is forwarded 9892 () 9894 o Throughout, replace "effective request URI", "request-target" and 9895 similar with "target URI" () 9898 o In Section 15.3.3 and Section 15.2.2, describe how extensions 9899 should consider scope of applicability 9900 () 9902 o In Section 3.3, don't rely on the HTTP/1.1 Messaging specification 9903 to define "message" () 9906 o In Section 7.8 and Section 9.1.3, note that URL resolution is 9907 necessary () 9909 o In Section 7, explicitly reference 206 as one of the status codes 9910 that provide representation data () 9913 o In Section 12.1.4, refine requirements so that they don't apply to 9914 resources without a concept of modification time 9915 () 9917 o In Section 10.7.1, specify the scope as a request, not a target 9918 resource () 9920 o In Section 3.3, introduce concept of "complete" messages 9921 () 9923 o In Section 6.1, Section 8.3.6, and Section 8.3.7, refine use of 9924 "request target" () 9927 o Throughout, remove "status-line" and "request-line", as these are 9928 HTTP/1.1-specific () 9931 C.10. Since draft-ietf-httpbis-semantics-08 9933 o In Section 14.5.17, remove duplicate definition of what makes a 9934 range satisfiable and refer instead to each range unit's 9935 definition () 9937 o In Section 13.1.2 and Section 13.2, clarify that a selected 9938 representation of zero length can only be satisfiable as a suffix 9939 range and that a server can still ignore Range for that case 9940 () 9942 o In Section 11.1.2 and Section 14.5.16, allow "Accept" as response 9943 field () 9945 o Appendix A now uses the sender variant of the "#" list expansion 9946 () 9948 o In Section 11.2.1, make the field list-based even when "*" is 9949 present () 9951 o In Section 15.3.1, add optional "Comments" entry 9952 () 9954 o In Section 17.4, reserve "*" as field name 9955 () 9957 o In Section 17.2, reserve "*" as method name 9958 () 9960 o In Section 12.1.1 and Section 12.1.2, state that multiple "*" is 9961 unlikely to be interoperable () 9964 o In Section 11.1.2, avoid use of obsolete media type parameter on 9965 text/html (, 9966 ) 9968 o Rephrase prose in Section 3.3 to become version-agnostic 9969 () 9971 o In Section 5.4.4, instruct recipients how to deal with control 9972 characters in field values () 9975 o In Section 5.4.4, update note about field ABNF 9976 () 9978 o Add Section 15 about Extending and Versioning HTTP 9979 () 9981 o In Section 14.1, include status 308 in list of heuristically 9982 cacheable status codes () 9985 o In Section 7.5, make it clearer that "identity" is not to be 9986 included () 9988 C.11. Since draft-ietf-httpbis-semantics-09 9990 o Switch to xml2rfc v3 mode for draft generation 9991 () 9993 C.12. Since draft-ietf-httpbis-semantics-10 9995 o In Section 16.6, mention compression attacks 9996 () 9998 o In Section 15.6.1, advise to make new content codings self- 9999 descriptive () 10001 o In Section 5.7.6, introduced the "parameters" ABNF rule, allowing 10002 empty parameters and trailing semicolons within media type, media 10003 range, and expectation () 10006 o In Section 14.4, explain how to create a redirected request 10007 () 10009 o In Section 7.4, defined error handling for multiple members 10010 () 10012 o In Section 1, revise the introduction and introduce HTTP/2 and 10013 HTTP/3 () 10015 o In Section 7.7, added a definition for Content-Length that 10016 encompasses its various roles in describing message payload or 10017 selected representation length; in Section 14.3.7, noted that 10018 Content-Length counts only the message body (not the selected 10019 representation) and that the complete length is in each 10020 Content-Range () 10022 o Noted that "WWW-Authenticate" with more than one value on a line 10023 is sometimes not interoperable [Messaging] 10024 () 10026 o In Section 12.1.1 and Section 12.1.4, removed requirement that a 10027 validator not be sent in a 2xx response when validation fails and 10028 the server decides that the same change request has already been 10029 applied () 10031 o Moved requirements specific to HTTP/1.1 from Section 6.1.2 to 10032 [Messaging] () 10034 o In Section 5.4.4, introduce the terms "singleton field" and "list- 10035 based field" (also - in various places - discuss what to do when a 10036 singleton field is received as a list) 10037 () 10039 o In Section 9.1.1, change the ABNF back to be a list of 10040 expectations, as defined in RFC 2616 () 10043 o In Section 9.1.5 (Trailer), Section 6.4.3 (Via), Section 6.6 10044 (Upgrade), Section 6.4.1 (Connection), Section 7.5 10045 (Content-Encoding), Section 7.6 (Content-Language), Section 9.1.1 10046 (Expect), Section 12.1.1 (If-Match), Section 12.1.2 10047 (If-None-Match), Section 11.1.3 (Accept-Charset), Section 11.1.5 10048 (Accept-Language), Section 11.2.1 (Vary), Section 10.6.1 10049 (WWW-Authenticate), and Section 10.7.1 (Proxy-Authenticate), 10050 adjust ABNF to allow empty lists () 10053 o In Section 8.3.1 and Section 16.9, provide a more nuanced 10054 explanation of sensitive data in GET-based forms and describe 10055 workarounds () 10057 o In Section 12.2, allow preconditions to be evaluated before the 10058 request body (if any) is processed () 10061 o In Section 5.4 and Section 5.6.3, allow for trailer fields in 10062 multiple trailer sections, depending on the HTTP version and 10063 framing in use, with processing being iterative as each section is 10064 received () 10066 o Moved definitions of "TE" and "Upgrade" from [Messaging] 10067 () 10069 o Moved 1.1-specific discussion of TLS to Messaging and rewrote 10070 Section 4.3.4 to refer to RFC6125 () 10073 o Moved definition of "Connection" from [Messaging] 10074 () 10076 C.13. Since draft-ietf-httpbis-semantics-11 10078 o The entire document has been reorganized, with no changes to 10079 content except editorial for the reorganization 10080 () 10082 o Move IANA Upgrade Token Registry instructions from [Messaging] 10083 () 10085 Acknowledgments 10087 This edition of the HTTP specification builds on the many 10088 contributions that went into RFC 1945, RFC 2068, RFC 2145, RFC 2616, 10089 and RFC 2818, including substantial contributions made by the 10090 previous authors, editors, and Working Group Chairs: Tim Berners-Lee, 10091 Jean-François Groff, Ari Luotonen, Roy T. Fielding, Henrik Frystyk 10092 Nielsen, Jim Gettys, Jeffrey C. Mogul, Larry Masinter, Paul J. 10093 Leach, Eric Rescorla, and Yves Lafon. 10095 See Section 10 of [RFC7230] for further acknowledgements from prior 10096 revisions. 10098 In addition, this document has reincorporated the HTTP Authentication 10099 Framework, previously defined in RFC 7235 and RFC 2617. We thank 10100 John Franks, Phillip M. Hallam-Baker, Jeffery L. Hostetler, Scott 10101 D. Lawrence, Paul J. Leach, Ari Luotonen, and Lawrence C. Stewart 10102 for their work on that specification. See Section 6 of [RFC2617] for 10103 further acknowledgements. 10105 // New acks to be added here. 10107 Authors' Addresses 10109 Roy T. Fielding (editor) 10110 Adobe 10111 345 Park Ave 10112 San Jose, CA 95110 10113 United States of America 10115 Email: fielding@gbiv.com 10116 URI: https://roy.gbiv.com/ 10118 Mark Nottingham (editor) 10119 Fastly 10120 Prahran VIC 10121 Australia 10123 Email: mnot@mnot.net 10124 URI: https://www.mnot.net/ 10125 Julian Reschke (editor) 10126 greenbytes GmbH 10127 Hafenweg 16 10128 48155 Münster 10129 Germany 10131 Email: julian.reschke@greenbytes.de 10132 URI: https://greenbytes.de/tech/webdav/