1 | |
---|
2 | |
---|
3 | |
---|
4 | HTTPbis Working Group R. Fielding, Ed. |
---|
5 | Internet-Draft Adobe |
---|
6 | Obsoletes: 2616 (if approved) J. Reschke, Ed. |
---|
7 | Updates: 2817 (if approved) greenbytes |
---|
8 | Intended status: Standards Track May 6, 2014 |
---|
9 | Expires: November 7, 2014 |
---|
10 | |
---|
11 | |
---|
12 | Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content |
---|
13 | draft-ietf-httpbis-p2-semantics-latest |
---|
14 | |
---|
15 | Abstract |
---|
16 | |
---|
17 | The Hypertext Transfer Protocol (HTTP) is a stateless application- |
---|
18 | level protocol for distributed, collaborative, hypertext information |
---|
19 | systems. This document defines the semantics of HTTP/1.1 messages, |
---|
20 | as expressed by request methods, request header fields, response |
---|
21 | status codes, and response header fields, along with the payload of |
---|
22 | messages (metadata and body content) and mechanisms for content |
---|
23 | negotiation. |
---|
24 | |
---|
25 | Editorial Note (To be removed by RFC Editor) |
---|
26 | |
---|
27 | Discussion of this draft takes place on the HTTPBIS working group |
---|
28 | mailing list (ietf-http-wg@w3.org), which is archived at |
---|
29 | <http://lists.w3.org/Archives/Public/ietf-http-wg/>. |
---|
30 | |
---|
31 | The current issues list is at |
---|
32 | <http://tools.ietf.org/wg/httpbis/trac/report/3> and related |
---|
33 | documents (including fancy diffs) can be found at |
---|
34 | <http://tools.ietf.org/wg/httpbis/>. |
---|
35 | |
---|
36 | _This is a temporary document for the purpose of tracking the |
---|
37 | editorial changes made during the AUTH48 (RFC publication) phase._ |
---|
38 | |
---|
39 | Status of This Memo |
---|
40 | |
---|
41 | This Internet-Draft is submitted in full conformance with the |
---|
42 | provisions of BCP 78 and BCP 79. |
---|
43 | |
---|
44 | Internet-Drafts are working documents of the Internet Engineering |
---|
45 | Task Force (IETF). Note that other groups may also distribute |
---|
46 | working documents as Internet-Drafts. The list of current Internet- |
---|
47 | Drafts is at http://datatracker.ietf.org/drafts/current/. |
---|
48 | |
---|
49 | Internet-Drafts are draft documents valid for a maximum of six months |
---|
50 | and may be updated, replaced, or obsoleted by other documents at any |
---|
51 | time. It is inappropriate to use Internet-Drafts as reference |
---|
52 | |
---|
53 | |
---|
54 | |
---|
55 | Fielding & Reschke Expires November 7, 2014 [Page 1] |
---|
56 | |
---|
57 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
58 | |
---|
59 | |
---|
60 | material or to cite them other than as "work in progress." |
---|
61 | |
---|
62 | This Internet-Draft will expire on November 7, 2014. |
---|
63 | |
---|
64 | Copyright Notice |
---|
65 | |
---|
66 | Copyright (c) 2014 IETF Trust and the persons identified as the |
---|
67 | document authors. All rights reserved. |
---|
68 | |
---|
69 | This document is subject to BCP 78 and the IETF Trust's Legal |
---|
70 | Provisions Relating to IETF Documents |
---|
71 | (http://trustee.ietf.org/license-info) in effect on the date of |
---|
72 | publication of this document. Please review these documents |
---|
73 | carefully, as they describe your rights and restrictions with respect |
---|
74 | to this document. Code Components extracted from this document must |
---|
75 | include Simplified BSD License text as described in Section 4.e of |
---|
76 | the Trust Legal Provisions and are provided without warranty as |
---|
77 | described in the Simplified BSD License. |
---|
78 | |
---|
79 | This document may contain material from IETF Documents or IETF |
---|
80 | Contributions published or made publicly available before November |
---|
81 | 10, 2008. The person(s) controlling the copyright in some of this |
---|
82 | material may not have granted the IETF Trust the right to allow |
---|
83 | modifications of such material outside the IETF Standards Process. |
---|
84 | Without obtaining an adequate license from the person(s) controlling |
---|
85 | the copyright in such materials, this document may not be modified |
---|
86 | outside the IETF Standards Process, and derivative works of it may |
---|
87 | not be created outside the IETF Standards Process, except to format |
---|
88 | it for publication as an RFC or to translate it into languages other |
---|
89 | than English. |
---|
90 | |
---|
91 | Table of Contents |
---|
92 | |
---|
93 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 6 |
---|
94 | 1.1. Conformance and Error Handling . . . . . . . . . . . . . . 6 |
---|
95 | 1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 6 |
---|
96 | 2. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 7 |
---|
97 | 3. Representations . . . . . . . . . . . . . . . . . . . . . . . 7 |
---|
98 | 3.1. Representation Metadata . . . . . . . . . . . . . . . . . 8 |
---|
99 | 3.1.1. Processing Representation Data . . . . . . . . . . . . 8 |
---|
100 | 3.1.2. Encoding for Compression or Integrity . . . . . . . . 11 |
---|
101 | 3.1.3. Audience Language . . . . . . . . . . . . . . . . . . 13 |
---|
102 | 3.1.4. Identification . . . . . . . . . . . . . . . . . . . . 14 |
---|
103 | 3.2. Representation Data . . . . . . . . . . . . . . . . . . . 17 |
---|
104 | 3.3. Payload Semantics . . . . . . . . . . . . . . . . . . . . 17 |
---|
105 | 3.4. Content Negotiation . . . . . . . . . . . . . . . . . . . 18 |
---|
106 | 3.4.1. Proactive Negotiation . . . . . . . . . . . . . . . . 19 |
---|
107 | 3.4.2. Reactive Negotiation . . . . . . . . . . . . . . . . . 20 |
---|
108 | |
---|
109 | |
---|
110 | |
---|
111 | Fielding & Reschke Expires November 7, 2014 [Page 2] |
---|
112 | |
---|
113 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
114 | |
---|
115 | |
---|
116 | 4. Request Methods . . . . . . . . . . . . . . . . . . . . . . . 21 |
---|
117 | 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 21 |
---|
118 | 4.2. Common Method Properties . . . . . . . . . . . . . . . . . 22 |
---|
119 | 4.2.1. Safe Methods . . . . . . . . . . . . . . . . . . . . . 22 |
---|
120 | 4.2.2. Idempotent Methods . . . . . . . . . . . . . . . . . . 23 |
---|
121 | 4.2.3. Cacheable Methods . . . . . . . . . . . . . . . . . . 24 |
---|
122 | 4.3. Method Definitions . . . . . . . . . . . . . . . . . . . . 24 |
---|
123 | 4.3.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 24 |
---|
124 | 4.3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . 25 |
---|
125 | 4.3.3. POST . . . . . . . . . . . . . . . . . . . . . . . . . 25 |
---|
126 | 4.3.4. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 26 |
---|
127 | 4.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . . 29 |
---|
128 | 4.3.6. CONNECT . . . . . . . . . . . . . . . . . . . . . . . 30 |
---|
129 | 4.3.7. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . 31 |
---|
130 | 4.3.8. TRACE . . . . . . . . . . . . . . . . . . . . . . . . 32 |
---|
131 | 5. Request Header Fields . . . . . . . . . . . . . . . . . . . . 33 |
---|
132 | 5.1. Controls . . . . . . . . . . . . . . . . . . . . . . . . . 33 |
---|
133 | 5.1.1. Expect . . . . . . . . . . . . . . . . . . . . . . . . 34 |
---|
134 | 5.1.2. Max-Forwards . . . . . . . . . . . . . . . . . . . . . 36 |
---|
135 | 5.2. Conditionals . . . . . . . . . . . . . . . . . . . . . . . 36 |
---|
136 | 5.3. Content Negotiation . . . . . . . . . . . . . . . . . . . 37 |
---|
137 | 5.3.1. Quality Values . . . . . . . . . . . . . . . . . . . . 37 |
---|
138 | 5.3.2. Accept . . . . . . . . . . . . . . . . . . . . . . . . 38 |
---|
139 | 5.3.3. Accept-Charset . . . . . . . . . . . . . . . . . . . . 40 |
---|
140 | 5.3.4. Accept-Encoding . . . . . . . . . . . . . . . . . . . 41 |
---|
141 | 5.3.5. Accept-Language . . . . . . . . . . . . . . . . . . . 42 |
---|
142 | 5.4. Authentication Credentials . . . . . . . . . . . . . . . . 43 |
---|
143 | 5.5. Request Context . . . . . . . . . . . . . . . . . . . . . 44 |
---|
144 | 5.5.1. From . . . . . . . . . . . . . . . . . . . . . . . . . 44 |
---|
145 | 5.5.2. Referer . . . . . . . . . . . . . . . . . . . . . . . 45 |
---|
146 | 5.5.3. User-Agent . . . . . . . . . . . . . . . . . . . . . . 46 |
---|
147 | 6. Response Status Codes . . . . . . . . . . . . . . . . . . . . 47 |
---|
148 | 6.1. Overview of Status Codes . . . . . . . . . . . . . . . . . 48 |
---|
149 | 6.2. Informational 1xx . . . . . . . . . . . . . . . . . . . . 50 |
---|
150 | 6.2.1. 100 Continue . . . . . . . . . . . . . . . . . . . . . 50 |
---|
151 | 6.2.2. 101 Switching Protocols . . . . . . . . . . . . . . . 50 |
---|
152 | 6.3. Successful 2xx . . . . . . . . . . . . . . . . . . . . . . 51 |
---|
153 | 6.3.1. 200 OK . . . . . . . . . . . . . . . . . . . . . . . . 51 |
---|
154 | 6.3.2. 201 Created . . . . . . . . . . . . . . . . . . . . . 52 |
---|
155 | 6.3.3. 202 Accepted . . . . . . . . . . . . . . . . . . . . . 52 |
---|
156 | 6.3.4. 203 Non-Authoritative Information . . . . . . . . . . 52 |
---|
157 | 6.3.5. 204 No Content . . . . . . . . . . . . . . . . . . . . 53 |
---|
158 | 6.3.6. 205 Reset Content . . . . . . . . . . . . . . . . . . 53 |
---|
159 | 6.4. Redirection 3xx . . . . . . . . . . . . . . . . . . . . . 54 |
---|
160 | 6.4.1. 300 Multiple Choices . . . . . . . . . . . . . . . . . 55 |
---|
161 | 6.4.2. 301 Moved Permanently . . . . . . . . . . . . . . . . 56 |
---|
162 | 6.4.3. 302 Found . . . . . . . . . . . . . . . . . . . . . . 56 |
---|
163 | 6.4.4. 303 See Other . . . . . . . . . . . . . . . . . . . . 57 |
---|
164 | |
---|
165 | |
---|
166 | |
---|
167 | Fielding & Reschke Expires November 7, 2014 [Page 3] |
---|
168 | |
---|
169 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
170 | |
---|
171 | |
---|
172 | 6.4.5. 305 Use Proxy . . . . . . . . . . . . . . . . . . . . 57 |
---|
173 | 6.4.6. 306 (Unused) . . . . . . . . . . . . . . . . . . . . . 57 |
---|
174 | 6.4.7. 307 Temporary Redirect . . . . . . . . . . . . . . . . 58 |
---|
175 | 6.5. Client Error 4xx . . . . . . . . . . . . . . . . . . . . . 58 |
---|
176 | 6.5.1. 400 Bad Request . . . . . . . . . . . . . . . . . . . 58 |
---|
177 | 6.5.2. 402 Payment Required . . . . . . . . . . . . . . . . . 58 |
---|
178 | 6.5.3. 403 Forbidden . . . . . . . . . . . . . . . . . . . . 58 |
---|
179 | 6.5.4. 404 Not Found . . . . . . . . . . . . . . . . . . . . 59 |
---|
180 | 6.5.5. 405 Method Not Allowed . . . . . . . . . . . . . . . . 59 |
---|
181 | 6.5.6. 406 Not Acceptable . . . . . . . . . . . . . . . . . . 59 |
---|
182 | 6.5.7. 408 Request Timeout . . . . . . . . . . . . . . . . . 60 |
---|
183 | 6.5.8. 409 Conflict . . . . . . . . . . . . . . . . . . . . . 60 |
---|
184 | 6.5.9. 410 Gone . . . . . . . . . . . . . . . . . . . . . . . 60 |
---|
185 | 6.5.10. 411 Length Required . . . . . . . . . . . . . . . . . 61 |
---|
186 | 6.5.11. 413 Payload Too Large . . . . . . . . . . . . . . . . 61 |
---|
187 | 6.5.12. 414 URI Too Long . . . . . . . . . . . . . . . . . . . 61 |
---|
188 | 6.5.13. 415 Unsupported Media Type . . . . . . . . . . . . . . 61 |
---|
189 | 6.5.14. 417 Expectation Failed . . . . . . . . . . . . . . . . 62 |
---|
190 | 6.5.15. 426 Upgrade Required . . . . . . . . . . . . . . . . . 62 |
---|
191 | 6.6. Server Error 5xx . . . . . . . . . . . . . . . . . . . . . 62 |
---|
192 | 6.6.1. 500 Internal Server Error . . . . . . . . . . . . . . 62 |
---|
193 | 6.6.2. 501 Not Implemented . . . . . . . . . . . . . . . . . 63 |
---|
194 | 6.6.3. 502 Bad Gateway . . . . . . . . . . . . . . . . . . . 63 |
---|
195 | 6.6.4. 503 Service Unavailable . . . . . . . . . . . . . . . 63 |
---|
196 | 6.6.5. 504 Gateway Timeout . . . . . . . . . . . . . . . . . 63 |
---|
197 | 6.6.6. 505 HTTP Version Not Supported . . . . . . . . . . . . 63 |
---|
198 | 7. Response Header Fields . . . . . . . . . . . . . . . . . . . . 64 |
---|
199 | 7.1. Control Data . . . . . . . . . . . . . . . . . . . . . . . 64 |
---|
200 | 7.1.1. Origination Date . . . . . . . . . . . . . . . . . . . 64 |
---|
201 | 7.1.2. Location . . . . . . . . . . . . . . . . . . . . . . . 68 |
---|
202 | 7.1.3. Retry-After . . . . . . . . . . . . . . . . . . . . . 69 |
---|
203 | 7.1.4. Vary . . . . . . . . . . . . . . . . . . . . . . . . . 70 |
---|
204 | 7.2. Validator Header Fields . . . . . . . . . . . . . . . . . 71 |
---|
205 | 7.3. Authentication Challenges . . . . . . . . . . . . . . . . 72 |
---|
206 | 7.4. Response Context . . . . . . . . . . . . . . . . . . . . . 72 |
---|
207 | 7.4.1. Allow . . . . . . . . . . . . . . . . . . . . . . . . 72 |
---|
208 | 7.4.2. Server . . . . . . . . . . . . . . . . . . . . . . . . 73 |
---|
209 | 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 73 |
---|
210 | 8.1. Method Registry . . . . . . . . . . . . . . . . . . . . . 74 |
---|
211 | 8.1.1. Procedure . . . . . . . . . . . . . . . . . . . . . . 74 |
---|
212 | 8.1.2. Considerations for New Methods . . . . . . . . . . . . 74 |
---|
213 | 8.1.3. Registrations . . . . . . . . . . . . . . . . . . . . 75 |
---|
214 | 8.2. Status Code Registry . . . . . . . . . . . . . . . . . . . 75 |
---|
215 | 8.2.1. Procedure . . . . . . . . . . . . . . . . . . . . . . 75 |
---|
216 | 8.2.2. Considerations for New Status Codes . . . . . . . . . 76 |
---|
217 | 8.2.3. Registrations . . . . . . . . . . . . . . . . . . . . 76 |
---|
218 | 8.3. Header Field Registry . . . . . . . . . . . . . . . . . . 77 |
---|
219 | 8.3.1. Considerations for New Header Fields . . . . . . . . . 78 |
---|
220 | |
---|
221 | |
---|
222 | |
---|
223 | Fielding & Reschke Expires November 7, 2014 [Page 4] |
---|
224 | |
---|
225 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
226 | |
---|
227 | |
---|
228 | 8.3.2. Registrations . . . . . . . . . . . . . . . . . . . . 80 |
---|
229 | 8.4. Content Coding Registry . . . . . . . . . . . . . . . . . 80 |
---|
230 | 8.4.1. Procedure . . . . . . . . . . . . . . . . . . . . . . 81 |
---|
231 | 8.4.2. Registrations . . . . . . . . . . . . . . . . . . . . 81 |
---|
232 | 9. Security Considerations . . . . . . . . . . . . . . . . . . . 81 |
---|
233 | 9.1. Attacks Based On File and Path Names . . . . . . . . . . . 82 |
---|
234 | 9.2. Attacks Based On Command, Code, or Query Injection . . . . 82 |
---|
235 | 9.3. Disclosure of Personal Information . . . . . . . . . . . . 83 |
---|
236 | 9.4. Disclosure of Sensitive Information in URIs . . . . . . . 83 |
---|
237 | 9.5. Disclosure of Fragment after Redirects . . . . . . . . . . 83 |
---|
238 | 9.6. Disclosure of Product Information . . . . . . . . . . . . 84 |
---|
239 | 9.7. Browser Fingerprinting . . . . . . . . . . . . . . . . . . 84 |
---|
240 | 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 85 |
---|
241 | 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 85 |
---|
242 | 11.1. Normative References . . . . . . . . . . . . . . . . . . . 85 |
---|
243 | 11.2. Informative References . . . . . . . . . . . . . . . . . . 86 |
---|
244 | Appendix A. Differences between HTTP and MIME . . . . . . . . . . 88 |
---|
245 | A.1. MIME-Version . . . . . . . . . . . . . . . . . . . . . . . 89 |
---|
246 | A.2. Conversion to Canonical Form . . . . . . . . . . . . . . . 89 |
---|
247 | A.3. Conversion of Date Formats . . . . . . . . . . . . . . . . 89 |
---|
248 | A.4. Conversion of Content-Encoding . . . . . . . . . . . . . . 90 |
---|
249 | A.5. Conversion of Content-Transfer-Encoding . . . . . . . . . 90 |
---|
250 | A.6. MHTML and Line Length Limitations . . . . . . . . . . . . 90 |
---|
251 | Appendix B. Changes from RFC 2616 . . . . . . . . . . . . . . . . 90 |
---|
252 | Appendix C. Imported ABNF . . . . . . . . . . . . . . . . . . . . 93 |
---|
253 | Appendix D. Collected ABNF . . . . . . . . . . . . . . . . . . . 93 |
---|
254 | Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 |
---|
255 | |
---|
256 | |
---|
257 | |
---|
258 | |
---|
259 | |
---|
260 | |
---|
261 | |
---|
262 | |
---|
263 | |
---|
264 | |
---|
265 | |
---|
266 | |
---|
267 | |
---|
268 | |
---|
269 | |
---|
270 | |
---|
271 | |
---|
272 | |
---|
273 | |
---|
274 | |
---|
275 | |
---|
276 | |
---|
277 | |
---|
278 | |
---|
279 | Fielding & Reschke Expires November 7, 2014 [Page 5] |
---|
280 | |
---|
281 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
282 | |
---|
283 | |
---|
284 | 1. Introduction |
---|
285 | |
---|
286 | Each Hypertext Transfer Protocol (HTTP) message is either a request |
---|
287 | or a response. A server listens on a connection for a request, |
---|
288 | parses each message received, interprets the message semantics in |
---|
289 | relation to the identified request target, and responds to that |
---|
290 | request with one or more response messages. A client constructs |
---|
291 | request messages to communicate specific intentions, and examines |
---|
292 | received responses to see if the intentions were carried out and |
---|
293 | determine how to interpret the results. This document defines |
---|
294 | HTTP/1.1 request and response semantics in terms of the architecture |
---|
295 | defined in [RFC7230]. |
---|
296 | |
---|
297 | HTTP provides a uniform interface for interacting with a resource |
---|
298 | (Section 2), regardless of its type, nature, or implementation, via |
---|
299 | the manipulation and transfer of representations (Section 3). |
---|
300 | |
---|
301 | HTTP semantics include the intentions defined by each request method |
---|
302 | (Section 4), extensions to those semantics that might be described in |
---|
303 | request header fields (Section 5), the meaning of status codes to |
---|
304 | indicate a machine-readable response (Section 6), and the meaning of |
---|
305 | other control data and resource metadata that might be given in |
---|
306 | response header fields (Section 7). |
---|
307 | |
---|
308 | This document also defines representation metadata that describe how |
---|
309 | a payload is intended to be interpreted by a recipient, the request |
---|
310 | header fields that might influence content selection, and the various |
---|
311 | selection algorithms that are collectively referred to as "content |
---|
312 | negotiation" (Section 3.4). |
---|
313 | |
---|
314 | 1.1. Conformance and Error Handling |
---|
315 | |
---|
316 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", |
---|
317 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this |
---|
318 | document are to be interpreted as described in [RFC2119]. |
---|
319 | |
---|
320 | Conformance criteria and considerations regarding error handling are |
---|
321 | defined in Section 2.5 of [RFC7230]. |
---|
322 | |
---|
323 | 1.2. Syntax Notation |
---|
324 | |
---|
325 | This specification uses the Augmented Backus-Naur Form (ABNF) |
---|
326 | notation of [RFC5234] with a list extension, defined in Section 7 of |
---|
327 | [RFC7230], that allows for compact definition of comma-separated |
---|
328 | lists using a '#' operator (similar to how the '*' operator indicates |
---|
329 | repetition). Appendix C describes rules imported from other |
---|
330 | documents. Appendix D shows the collected grammar with all list |
---|
331 | operators expanded to standard ABNF notation. |
---|
332 | |
---|
333 | |
---|
334 | |
---|
335 | Fielding & Reschke Expires November 7, 2014 [Page 6] |
---|
336 | |
---|
337 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
338 | |
---|
339 | |
---|
340 | This specification uses the terms "character", "character encoding |
---|
341 | scheme", "charset", and "protocol element" as they are defined in |
---|
342 | [RFC6365]. |
---|
343 | |
---|
344 | 2. Resources |
---|
345 | |
---|
346 | The target of an HTTP request is called a resource. HTTP does not |
---|
347 | limit the nature of a resource; it merely defines an interface that |
---|
348 | might be used to interact with resources. Each resource is |
---|
349 | identified by a Uniform Resource Identifier (URI), as described in |
---|
350 | Section 2.7 of [RFC7230]. |
---|
351 | |
---|
352 | When a client constructs an HTTP/1.1 request message, it sends the |
---|
353 | target URI in one of various forms, as defined in (Section 5.3 of |
---|
354 | [RFC7230]). When a request is received, the server reconstructs an |
---|
355 | effective request URI for the target resource (Section 5.5 of |
---|
356 | [RFC7230]). |
---|
357 | |
---|
358 | One design goal of HTTP is to separate resource identification from |
---|
359 | request semantics, which is made possible by vesting the request |
---|
360 | semantics in the request method (Section 4) and a few request- |
---|
361 | modifying header fields (Section 5). If there is a conflict between |
---|
362 | the method semantics and any semantic implied by the URI itself, as |
---|
363 | described in Section 4.2.1, the method semantics take precedence. |
---|
364 | |
---|
365 | 3. Representations |
---|
366 | |
---|
367 | Considering that a resource could be anything, and that the uniform |
---|
368 | interface provided by HTTP is similar to a window through which one |
---|
369 | can observe and act upon such a thing only through the communication |
---|
370 | of messages to some independent actor on the other side, an |
---|
371 | abstraction is needed to represent ("take the place of") the current |
---|
372 | or desired state of that thing in our communications. That |
---|
373 | abstraction is called a representation [REST]. |
---|
374 | |
---|
375 | For the purposes of HTTP, a "representation" is information that is |
---|
376 | intended to reflect a past, current, or desired state of a given |
---|
377 | resource, in a format that can be readily communicated via the |
---|
378 | protocol, and that consists of a set of representation metadata and a |
---|
379 | potentially unbounded stream of representation data. |
---|
380 | |
---|
381 | An origin server might be provided with, or capable of generating, |
---|
382 | multiple representations that are each intended to reflect the |
---|
383 | current state of a target resource. In such cases, some algorithm is |
---|
384 | used by the origin server to select one of those representations as |
---|
385 | most applicable to a given request, usually based on content |
---|
386 | negotiation. This "selected representation" is used to provide the |
---|
387 | data and metadata for evaluating conditional requests [RFC7232] and |
---|
388 | |
---|
389 | |
---|
390 | |
---|
391 | Fielding & Reschke Expires November 7, 2014 [Page 7] |
---|
392 | |
---|
393 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
394 | |
---|
395 | |
---|
396 | constructing the payload for 200 (OK) and 304 (Not Modified) |
---|
397 | responses to GET (Section 4.3.1). |
---|
398 | |
---|
399 | 3.1. Representation Metadata |
---|
400 | |
---|
401 | Representation header fields provide metadata about the |
---|
402 | representation. When a message includes a payload body, the |
---|
403 | representation header fields describe how to interpret the |
---|
404 | representation data enclosed in the payload body. In a response to a |
---|
405 | HEAD request, the representation header fields describe the |
---|
406 | representation data that would have been enclosed in the payload body |
---|
407 | if the same request had been a GET. |
---|
408 | |
---|
409 | The following header fields convey representation metadata: |
---|
410 | |
---|
411 | +-------------------+-----------------+ |
---|
412 | | Header Field Name | Defined in... | |
---|
413 | +-------------------+-----------------+ |
---|
414 | | Content-Type | Section 3.1.1.5 | |
---|
415 | | Content-Encoding | Section 3.1.2.2 | |
---|
416 | | Content-Language | Section 3.1.3.2 | |
---|
417 | | Content-Location | Section 3.1.4.2 | |
---|
418 | +-------------------+-----------------+ |
---|
419 | |
---|
420 | 3.1.1. Processing Representation Data |
---|
421 | |
---|
422 | 3.1.1.1. Media Type |
---|
423 | |
---|
424 | HTTP uses Internet Media Types [RFC2046] in the Content-Type |
---|
425 | (Section 3.1.1.5) and Accept (Section 5.3.2) header fields in order |
---|
426 | to provide open and extensible data typing and type negotiation. |
---|
427 | Media types define both a data format and various processing models: |
---|
428 | how to process that data in accordance with each context in which it |
---|
429 | is received. |
---|
430 | |
---|
431 | media-type = type "/" subtype *( OWS ";" OWS parameter ) |
---|
432 | type = token |
---|
433 | subtype = token |
---|
434 | |
---|
435 | The type/subtype MAY be followed by parameters in the form of |
---|
436 | name=value pairs. |
---|
437 | |
---|
438 | parameter = token "=" ( token / quoted-string ) |
---|
439 | |
---|
440 | The type, subtype, and parameter name tokens are case-insensitive. |
---|
441 | Parameter values might or might not be case-sensitive, depending on |
---|
442 | the semantics of the parameter name. The presence or absence of a |
---|
443 | parameter might be significant to the processing of a media-type, |
---|
444 | |
---|
445 | |
---|
446 | |
---|
447 | Fielding & Reschke Expires November 7, 2014 [Page 8] |
---|
448 | |
---|
449 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
450 | |
---|
451 | |
---|
452 | depending on its definition within the media type registry. |
---|
453 | |
---|
454 | A parameter value that matches the token production can be |
---|
455 | transmitted as either a token or within a quoted-string. The quoted |
---|
456 | and unquoted values are equivalent. For example, the following |
---|
457 | examples are all equivalent, but the first is preferred for |
---|
458 | consistency: |
---|
459 | |
---|
460 | text/html;charset=utf-8 |
---|
461 | text/html;charset=UTF-8 |
---|
462 | Text/HTML;Charset="utf-8" |
---|
463 | text/html; charset="utf-8" |
---|
464 | |
---|
465 | Internet media types ought to be registered with IANA according to |
---|
466 | the procedures defined in [BCP13]. |
---|
467 | |
---|
468 | Note: Unlike some similar constructs in other header fields, media |
---|
469 | type parameters do not allow whitespace (even "bad" whitespace) |
---|
470 | around the "=" character. |
---|
471 | |
---|
472 | 3.1.1.2. Charset |
---|
473 | |
---|
474 | HTTP uses charset names to indicate or negotiate the character |
---|
475 | encoding scheme of a textual representation [RFC6365]. A charset is |
---|
476 | identified by a case-insensitive token. |
---|
477 | |
---|
478 | charset = token |
---|
479 | |
---|
480 | Charset names ought to be registered in IANA Character Set registry |
---|
481 | (<http://www.iana.org/assignments/character-sets>) according to the |
---|
482 | procedures defined in [RFC2978]. |
---|
483 | |
---|
484 | 3.1.1.3. Canonicalization and Text Defaults |
---|
485 | |
---|
486 | Internet media types are registered with a canonical form in order to |
---|
487 | be interoperable among systems with varying native encoding formats. |
---|
488 | Representations selected or transferred via HTTP ought to be in |
---|
489 | canonical form, for many of the same reasons described by the |
---|
490 | Multipurpose Internet Mail Extensions (MIME) [RFC2045]. However, the |
---|
491 | performance characteristics of email deployments (i.e., store and |
---|
492 | forward messages to peers) are significantly different from those |
---|
493 | common to HTTP and the Web (server-based information services). |
---|
494 | Furthermore, MIME's constraints for the sake of compatibility with |
---|
495 | older mail transfer protocols do not apply to HTTP (see Appendix A). |
---|
496 | |
---|
497 | MIME's canonical form requires that media subtypes of the "text" type |
---|
498 | use CRLF as the text line break. HTTP allows the transfer of text |
---|
499 | media with plain CR or LF alone representing a line break, when such |
---|
500 | |
---|
501 | |
---|
502 | |
---|
503 | Fielding & Reschke Expires November 7, 2014 [Page 9] |
---|
504 | |
---|
505 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
506 | |
---|
507 | |
---|
508 | line breaks are consistent for an entire representation. An HTTP |
---|
509 | sender MAY generate, and a recipient MUST be able to parse, line |
---|
510 | breaks in text media that consist of CRLF, bare CR, or bare LF. In |
---|
511 | addition, text media in HTTP is not limited to charsets that use |
---|
512 | octets 13 and 10 for CR and LF, respectively. This flexibility |
---|
513 | regarding line breaks applies only to text within a representation |
---|
514 | that has been assigned a "text" media type; it does not apply to |
---|
515 | "multipart" types or HTTP elements outside the payload body (e.g., |
---|
516 | header fields). |
---|
517 | |
---|
518 | If a representation is encoded with a content-coding, the underlying |
---|
519 | data ought to be in a form defined above prior to being encoded. |
---|
520 | |
---|
521 | 3.1.1.4. Multipart Types |
---|
522 | |
---|
523 | MIME provides for a number of "multipart" types -- encapsulations of |
---|
524 | one or more representations within a single message body. All |
---|
525 | multipart types share a common syntax, as defined in Section 5.1.1 of |
---|
526 | [RFC2046], and include a boundary parameter as part of the media type |
---|
527 | value. The message body is itself a protocol element; a sender MUST |
---|
528 | generate only CRLF to represent line breaks between body parts. |
---|
529 | |
---|
530 | HTTP message framing does not use the multipart boundary as an |
---|
531 | indicator of message body length, though it might be used by |
---|
532 | implementations that generate or process the payload. For example, |
---|
533 | the "multipart/form-data" type is often used for carrying form data |
---|
534 | in a request, as described in [RFC2388], and the "multipart/ |
---|
535 | byteranges" type is defined by this specification for use in some 206 |
---|
536 | (Partial Content) responses [RFC7233]. |
---|
537 | |
---|
538 | 3.1.1.5. Content-Type |
---|
539 | |
---|
540 | The "Content-Type" header field indicates the media type of the |
---|
541 | associated representation: either the representation enclosed in the |
---|
542 | message payload or the selected representation, as determined by the |
---|
543 | message semantics. The indicated media type defines both the data |
---|
544 | format and how that data is intended to be processed by a recipient, |
---|
545 | within the scope of the received message semantics, after any content |
---|
546 | codings indicated by Content-Encoding are decoded. |
---|
547 | |
---|
548 | Content-Type = media-type |
---|
549 | |
---|
550 | Media types are defined in Section 3.1.1.1. An example of the field |
---|
551 | is |
---|
552 | |
---|
553 | Content-Type: text/html; charset=ISO-8859-4 |
---|
554 | |
---|
555 | A sender that generates a message containing a payload body SHOULD |
---|
556 | |
---|
557 | |
---|
558 | |
---|
559 | Fielding & Reschke Expires November 7, 2014 [Page 10] |
---|
560 | |
---|
561 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
562 | |
---|
563 | |
---|
564 | generate a Content-Type header field in that message unless the |
---|
565 | intended media type of the enclosed representation is unknown to the |
---|
566 | sender. If a Content-Type header field is not present, the recipient |
---|
567 | MAY either assume a media type of "application/octet-stream" |
---|
568 | ([RFC2046], Section 4.5.1) or examine the data to determine its type. |
---|
569 | |
---|
570 | In practice, resource owners do not always properly configure their |
---|
571 | origin server to provide the correct Content-Type for a given |
---|
572 | representation, with the result that some clients will examine a |
---|
573 | payload's content and override the specified type. Clients that do |
---|
574 | so risk drawing incorrect conclusions, which might expose additional |
---|
575 | security risks (e.g., "privilege escalation"). Furthermore, it is |
---|
576 | impossible to determine the sender's intent by examining the data |
---|
577 | format: many data formats match multiple media types that differ only |
---|
578 | in processing semantics. Implementers are encouraged to provide a |
---|
579 | means of disabling such "content sniffing" when it is used. |
---|
580 | |
---|
581 | 3.1.2. Encoding for Compression or Integrity |
---|
582 | |
---|
583 | 3.1.2.1. Content Codings |
---|
584 | |
---|
585 | Content coding values indicate an encoding transformation that has |
---|
586 | been or can be applied to a representation. Content codings are |
---|
587 | primarily used to allow a representation to be compressed or |
---|
588 | otherwise usefully transformed without losing the identity of its |
---|
589 | underlying media type and without loss of information. Frequently, |
---|
590 | the representation is stored in coded form, transmitted directly, and |
---|
591 | only decoded by the final recipient. |
---|
592 | |
---|
593 | content-coding = token |
---|
594 | |
---|
595 | All content-coding values are case-insensitive and ought to be |
---|
596 | registered within the HTTP Content Coding registry, as defined in |
---|
597 | Section 8.4. They are used in the Accept-Encoding (Section 5.3.4) |
---|
598 | and Content-Encoding (Section 3.1.2.2) header fields. |
---|
599 | |
---|
600 | The following content-coding values are defined by this |
---|
601 | specification: |
---|
602 | |
---|
603 | compress (and x-compress): See Section 4.2.1 of [RFC7230]. |
---|
604 | |
---|
605 | deflate: See Section 4.2.2 of [RFC7230]. |
---|
606 | |
---|
607 | gzip (and x-gzip): See Section 4.2.3 of [RFC7230]. |
---|
608 | |
---|
609 | |
---|
610 | |
---|
611 | |
---|
612 | |
---|
613 | |
---|
614 | |
---|
615 | Fielding & Reschke Expires November 7, 2014 [Page 11] |
---|
616 | |
---|
617 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
618 | |
---|
619 | |
---|
620 | 3.1.2.2. Content-Encoding |
---|
621 | |
---|
622 | The "Content-Encoding" header field indicates what content codings |
---|
623 | have been applied to the representation, beyond those inherent in the |
---|
624 | media type, and thus what decoding mechanisms have to be applied in |
---|
625 | order to obtain data in the media type referenced by the Content-Type |
---|
626 | header field. Content-Encoding is primarily used to allow a |
---|
627 | representation's data to be compressed without losing the identity of |
---|
628 | its underlying media type. |
---|
629 | |
---|
630 | Content-Encoding = 1#content-coding |
---|
631 | |
---|
632 | An example of its use is |
---|
633 | |
---|
634 | Content-Encoding: gzip |
---|
635 | |
---|
636 | If one or more encodings have been applied to a representation, the |
---|
637 | sender that applied the encodings MUST generate a Content-Encoding |
---|
638 | header field that lists the content codings in the order in which |
---|
639 | they were applied. Additional information about the encoding |
---|
640 | parameters can be provided by other header fields not defined by this |
---|
641 | specification. |
---|
642 | |
---|
643 | Unlike Transfer-Encoding (Section 3.3.1 of [RFC7230]), the codings |
---|
644 | listed in Content-Encoding are a characteristic of the |
---|
645 | representation; the representation is defined in terms of the coded |
---|
646 | form, and all other metadata about the representation is about the |
---|
647 | coded form unless otherwise noted in the metadata definition. |
---|
648 | Typically, the representation is only decoded just prior to rendering |
---|
649 | or analogous usage. |
---|
650 | |
---|
651 | If the media type includes an inherent encoding, such as a data |
---|
652 | format that is always compressed, then that encoding would not be |
---|
653 | restated in Content-Encoding even if it happens to be the same |
---|
654 | algorithm as one of the content codings. Such a content coding would |
---|
655 | only be listed if, for some bizarre reason, it is applied a second |
---|
656 | time to form the representation. Likewise, an origin server might |
---|
657 | choose to publish the same data as multiple representations that |
---|
658 | differ only in whether the coding is defined as part of Content-Type |
---|
659 | or Content-Encoding, since some user agents will behave differently |
---|
660 | in their handling of each response (e.g., open a "Save as ..." dialog |
---|
661 | instead of automatic decompression and rendering of content). |
---|
662 | |
---|
663 | An origin server MAY respond with a status code of 415 (Unsupported |
---|
664 | Media Type) if a representation in the request message has a content |
---|
665 | coding that is not acceptable. |
---|
666 | |
---|
667 | |
---|
668 | |
---|
669 | |
---|
670 | |
---|
671 | Fielding & Reschke Expires November 7, 2014 [Page 12] |
---|
672 | |
---|
673 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
674 | |
---|
675 | |
---|
676 | 3.1.3. Audience Language |
---|
677 | |
---|
678 | 3.1.3.1. Language Tags |
---|
679 | |
---|
680 | A language tag, as defined in [RFC5646], identifies a natural |
---|
681 | language spoken, written, or otherwise conveyed by human beings for |
---|
682 | communication of information to other human beings. Computer |
---|
683 | languages are explicitly excluded. |
---|
684 | |
---|
685 | HTTP uses language tags within the Accept-Language and Content- |
---|
686 | Language header fields. Accept-Language uses the broader language- |
---|
687 | range production defined in Section 5.3.5, whereas Content-Language |
---|
688 | uses the language-tag production defined below. |
---|
689 | |
---|
690 | language-tag = <Language-Tag, defined in [RFC5646], Section 2.1> |
---|
691 | |
---|
692 | A language tag is a sequence of one or more case-insensitive subtags, |
---|
693 | each separated by a hyphen character ("-", %x2D). In most cases, a |
---|
694 | language tag consists of a primary language subtag that identifies a |
---|
695 | broad family of related languages (e.g., "en" = English) which is |
---|
696 | optionally followed by a series of subtags that refine or narrow that |
---|
697 | language's range (e.g., "en-CA" = the variety of English as |
---|
698 | communicated in Canada). Whitespace is not allowed within a language |
---|
699 | tag. Example tags include: |
---|
700 | |
---|
701 | fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN |
---|
702 | |
---|
703 | See [RFC5646] for further information. |
---|
704 | |
---|
705 | 3.1.3.2. Content-Language |
---|
706 | |
---|
707 | The "Content-Language" header field describes the natural language(s) |
---|
708 | of the intended audience for the representation. Note that this |
---|
709 | might not be equivalent to all the languages used within the |
---|
710 | representation. |
---|
711 | |
---|
712 | Content-Language = 1#language-tag |
---|
713 | |
---|
714 | Language tags are defined in Section 3.1.3.1. The primary purpose of |
---|
715 | Content-Language is to allow a user to identify and differentiate |
---|
716 | representations according to the users' own preferred language. |
---|
717 | Thus, if the content is intended only for a Danish-literate audience, |
---|
718 | the appropriate field is |
---|
719 | |
---|
720 | Content-Language: da |
---|
721 | |
---|
722 | If no Content-Language is specified, the default is that the content |
---|
723 | is intended for all language audiences. This might mean that the |
---|
724 | |
---|
725 | |
---|
726 | |
---|
727 | Fielding & Reschke Expires November 7, 2014 [Page 13] |
---|
728 | |
---|
729 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
730 | |
---|
731 | |
---|
732 | sender does not consider it to be specific to any natural language, |
---|
733 | or that the sender does not know for which language it is intended. |
---|
734 | |
---|
735 | Multiple languages MAY be listed for content that is intended for |
---|
736 | multiple audiences. For example, a rendition of the "Treaty of |
---|
737 | Waitangi", presented simultaneously in the original Maori and English |
---|
738 | versions, would call for |
---|
739 | |
---|
740 | Content-Language: mi, en |
---|
741 | |
---|
742 | However, just because multiple languages are present within a |
---|
743 | representation does not mean that it is intended for multiple |
---|
744 | linguistic audiences. An example would be a beginner's language |
---|
745 | primer, such as "A First Lesson in Latin", which is clearly intended |
---|
746 | to be used by an English-literate audience. In this case, the |
---|
747 | Content-Language would properly only include "en". |
---|
748 | |
---|
749 | Content-Language MAY be applied to any media type -- it is not |
---|
750 | limited to textual documents. |
---|
751 | |
---|
752 | 3.1.4. Identification |
---|
753 | |
---|
754 | 3.1.4.1. Identifying a Representation |
---|
755 | |
---|
756 | When a complete or partial representation is transferred in a message |
---|
757 | payload, it is often desirable for the sender to supply, or the |
---|
758 | recipient to determine, an identifier for a resource corresponding to |
---|
759 | that representation. |
---|
760 | |
---|
761 | For a request message: |
---|
762 | |
---|
763 | o If the request has a Content-Location header field, then the |
---|
764 | sender asserts that the payload is a representation of the |
---|
765 | resource identified by the Content-Location field-value. However, |
---|
766 | such an assertion cannot be trusted unless it can be verified by |
---|
767 | other means (not defined by this specification). The information |
---|
768 | might still be useful for revision history links. |
---|
769 | |
---|
770 | o Otherwise, the payload is unidentified. |
---|
771 | |
---|
772 | For a response message, the following rules are applied in order |
---|
773 | until a match is found: |
---|
774 | |
---|
775 | 1. If the request method is GET or HEAD and the response status code |
---|
776 | is 200 (OK), 204 (No Content), 206 (Partial Content), or 304 (Not |
---|
777 | Modified), the payload is a representation of the resource |
---|
778 | identified by the effective request URI (Section 5.5 of |
---|
779 | [RFC7230]). |
---|
780 | |
---|
781 | |
---|
782 | |
---|
783 | Fielding & Reschke Expires November 7, 2014 [Page 14] |
---|
784 | |
---|
785 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
786 | |
---|
787 | |
---|
788 | 2. If the request method is GET or HEAD and the response status code |
---|
789 | is 203 (Non-Authoritative Information), the payload is a |
---|
790 | potentially modified or enhanced representation of the target |
---|
791 | resource as provided by an intermediary. |
---|
792 | |
---|
793 | 3. If the response has a Content-Location header field and its |
---|
794 | field-value is a reference to the same URI as the effective |
---|
795 | request URI, the payload is a representation of the resource |
---|
796 | identified by the effective request URI. |
---|
797 | |
---|
798 | 4. If the response has a Content-Location header field and its |
---|
799 | field-value is a reference to a URI different from the effective |
---|
800 | request URI, then the sender asserts that the payload is a |
---|
801 | representation of the resource identified by the Content-Location |
---|
802 | field-value. However, such an assertion cannot be trusted unless |
---|
803 | it can be verified by other means (not defined by this |
---|
804 | specification). |
---|
805 | |
---|
806 | 5. Otherwise, the payload is unidentified. |
---|
807 | |
---|
808 | 3.1.4.2. Content-Location |
---|
809 | |
---|
810 | The "Content-Location" header field references a URI that can be used |
---|
811 | as an identifier for a specific resource corresponding to the |
---|
812 | representation in this message's payload. In other words, if one |
---|
813 | were to perform a GET request on this URI at the time of this |
---|
814 | message's generation, then a 200 (OK) response would contain the same |
---|
815 | representation that is enclosed as payload in this message. |
---|
816 | |
---|
817 | Content-Location = absolute-URI / partial-URI |
---|
818 | |
---|
819 | The Content-Location value is not a replacement for the effective |
---|
820 | Request URI (Section 5.5 of [RFC7230]). It is representation |
---|
821 | metadata. It has the same syntax and semantics as the header field |
---|
822 | of the same name defined for MIME body parts in Section 4 of |
---|
823 | [RFC2557]. However, its appearance in an HTTP message has some |
---|
824 | special implications for HTTP recipients. |
---|
825 | |
---|
826 | If Content-Location is included in a 2xx (Successful) response |
---|
827 | message and its value refers (after conversion to absolute form) to a |
---|
828 | URI that is the same as the effective request URI, then the recipient |
---|
829 | MAY consider the payload to be a current representation of that |
---|
830 | resource at the time indicated by the message origination date. For |
---|
831 | a GET (Section 4.3.1) or HEAD (Section 4.3.2) request, this is the |
---|
832 | same as the default semantics when no Content-Location is provided by |
---|
833 | the server. For a state-changing request like PUT (Section 4.3.4) or |
---|
834 | POST (Section 4.3.3), it implies that the server's response contains |
---|
835 | the new representation of that resource, thereby distinguishing it |
---|
836 | |
---|
837 | |
---|
838 | |
---|
839 | Fielding & Reschke Expires November 7, 2014 [Page 15] |
---|
840 | |
---|
841 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
842 | |
---|
843 | |
---|
844 | from representations that might only report about the action (e.g., |
---|
845 | "It worked!"). This allows authoring applications to update their |
---|
846 | local copies without the need for a subsequent GET request. |
---|
847 | |
---|
848 | If Content-Location is included in a 2xx (Successful) response |
---|
849 | message and its field-value refers to a URI that differs from the |
---|
850 | effective request URI, then the origin server claims that the URI is |
---|
851 | an identifier for a different resource corresponding to the enclosed |
---|
852 | representation. Such a claim can only be trusted if both identifiers |
---|
853 | share the same resource owner, which cannot be programmatically |
---|
854 | determined via HTTP. |
---|
855 | |
---|
856 | o For a response to a GET or HEAD request, this is an indication |
---|
857 | that the effective request URI refers to a resource that is |
---|
858 | subject to content negotiation and the Content-Location field- |
---|
859 | value is a more specific identifier for the selected |
---|
860 | representation. |
---|
861 | |
---|
862 | o For a 201 (Created) response to a state-changing method, a |
---|
863 | Content-Location field-value that is identical to the Location |
---|
864 | field-value indicates that this payload is a current |
---|
865 | representation of the newly created resource. |
---|
866 | |
---|
867 | o Otherwise, such a Content-Location indicates that this payload is |
---|
868 | a representation reporting on the requested action's status and |
---|
869 | that the same report is available (for future access with GET) at |
---|
870 | the given URI. For example, a purchase transaction made via a |
---|
871 | POST request might include a receipt document as the payload of |
---|
872 | the 200 (OK) response; the Content-Location field-value provides |
---|
873 | an identifier for retrieving a copy of that same receipt in the |
---|
874 | future. |
---|
875 | |
---|
876 | A user agent that sends Content-Location in a request message is |
---|
877 | stating that its value refers to where the user agent originally |
---|
878 | obtained the content of the enclosed representation (prior to any |
---|
879 | modifications made by that user agent). In other words, the user |
---|
880 | agent is providing a back link to the source of the original |
---|
881 | representation. |
---|
882 | |
---|
883 | An origin server that receives a Content-Location field in a request |
---|
884 | message MUST treat the information as transitory request context |
---|
885 | rather than as metadata to be saved verbatim as part of the |
---|
886 | representation. An origin server MAY use that context to guide in |
---|
887 | processing the request or to save it for other uses, such as within |
---|
888 | source links or versioning metadata. However, an origin server MUST |
---|
889 | NOT use such context information to alter the request semantics. |
---|
890 | |
---|
891 | For example, if a client makes a PUT request on a negotiated resource |
---|
892 | |
---|
893 | |
---|
894 | |
---|
895 | Fielding & Reschke Expires November 7, 2014 [Page 16] |
---|
896 | |
---|
897 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
898 | |
---|
899 | |
---|
900 | and the origin server accepts that PUT (without redirection), then |
---|
901 | the new state of that resource is expected to be consistent with the |
---|
902 | one representation supplied in that PUT; the Content-Location cannot |
---|
903 | be used as a form of reverse content selection identifier to update |
---|
904 | only one of the negotiated representations. If the user agent had |
---|
905 | wanted the latter semantics, it would have applied the PUT directly |
---|
906 | to the Content-Location URI. |
---|
907 | |
---|
908 | 3.2. Representation Data |
---|
909 | |
---|
910 | The representation data associated with an HTTP message is either |
---|
911 | provided as the payload body of the message or referred to by the |
---|
912 | message semantics and the effective request URI. The representation |
---|
913 | data is in a format and encoding defined by the representation |
---|
914 | metadata header fields. |
---|
915 | |
---|
916 | The data type of the representation data is determined via the header |
---|
917 | fields Content-Type and Content-Encoding. These define a two-layer, |
---|
918 | ordered encoding model: |
---|
919 | |
---|
920 | representation-data := Content-Encoding( Content-Type( bits ) ) |
---|
921 | |
---|
922 | 3.3. Payload Semantics |
---|
923 | |
---|
924 | Some HTTP messages transfer a complete or partial representation as |
---|
925 | the message "payload". In some cases, a payload might contain only |
---|
926 | the associated representation's header fields (e.g., responses to |
---|
927 | HEAD) or only some part(s) of the representation data (e.g., the 206 |
---|
928 | (Partial Content) status code). |
---|
929 | |
---|
930 | The purpose of a payload in a request is defined by the method |
---|
931 | semantics. For example, a representation in the payload of a PUT |
---|
932 | request (Section 4.3.4) represents the desired state of the target |
---|
933 | resource if the request is successfully applied, whereas a |
---|
934 | representation in the payload of a POST request (Section 4.3.3) |
---|
935 | represents information to be processed by the target resource. |
---|
936 | |
---|
937 | In a response, the payload's purpose is defined by both the request |
---|
938 | method and the response status code. For example, the payload of a |
---|
939 | 200 (OK) response to GET (Section 4.3.1) represents the current state |
---|
940 | of the target resource, as observed at the time of the message |
---|
941 | origination date (Section 7.1.1.2), whereas the payload of the same |
---|
942 | status code in a response to POST might represent either the |
---|
943 | processing result or the new state of the target resource after |
---|
944 | applying the processing. Response messages with an error status code |
---|
945 | usually contain a payload that represents the error condition, such |
---|
946 | that it describes the error state and what next steps are suggested |
---|
947 | for resolving it. |
---|
948 | |
---|
949 | |
---|
950 | |
---|
951 | Fielding & Reschke Expires November 7, 2014 [Page 17] |
---|
952 | |
---|
953 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
954 | |
---|
955 | |
---|
956 | Header fields that specifically describe the payload, rather than the |
---|
957 | associated representation, are referred to as "payload header |
---|
958 | fields". Payload header fields are defined in other parts of this |
---|
959 | specification, due to their impact on message parsing. |
---|
960 | |
---|
961 | +-------------------+----------------------------+ |
---|
962 | | Header Field Name | Defined in... | |
---|
963 | +-------------------+----------------------------+ |
---|
964 | | Content-Length | Section 3.3.2 of [RFC7230] | |
---|
965 | | Content-Range | Section 4.2 of [RFC7233] | |
---|
966 | | Trailer | Section 4.4 of [RFC7230] | |
---|
967 | | Transfer-Encoding | Section 3.3.1 of [RFC7230] | |
---|
968 | +-------------------+----------------------------+ |
---|
969 | |
---|
970 | 3.4. Content Negotiation |
---|
971 | |
---|
972 | When responses convey payload information, whether indicating a |
---|
973 | success or an error, the origin server often has different ways of |
---|
974 | representing that information; for example, in different formats, |
---|
975 | languages, or encodings. Likewise, different users or user agents |
---|
976 | might have differing capabilities, characteristics, or preferences |
---|
977 | that could influence which representation, among those available, |
---|
978 | would be best to deliver. For this reason, HTTP provides mechanisms |
---|
979 | for content negotiation. |
---|
980 | |
---|
981 | This specification defines two patterns of content negotiation that |
---|
982 | can be made visible within the protocol: "proactive", where the |
---|
983 | server selects the representation based upon the user agent's stated |
---|
984 | preferences, and "reactive" negotiation, where the server provides a |
---|
985 | list of representations for the user agent to choose from. Other |
---|
986 | patterns of content negotiation include "conditional content", where |
---|
987 | the representation consists of multiple parts that are selectively |
---|
988 | rendered based on user agent parameters, "active content", where the |
---|
989 | representation contains a script that makes additional (more |
---|
990 | specific) requests based on the user agent characteristics, and |
---|
991 | "Transparent Content Negotiation" ([RFC2295]), where content |
---|
992 | selection is performed by an intermediary. These patterns are not |
---|
993 | mutually exclusive, and each has trade-offs in applicability and |
---|
994 | practicality. |
---|
995 | |
---|
996 | Note that, in all cases, HTTP is not aware of the resource semantics. |
---|
997 | The consistency with which an origin server responds to requests, |
---|
998 | over time and over the varying dimensions of content negotiation, and |
---|
999 | thus the "sameness" of a resource's observed representations over |
---|
1000 | time, is determined entirely by whatever entity or algorithm selects |
---|
1001 | or generates those responses. HTTP pays no attention to the man |
---|
1002 | behind the curtain. |
---|
1003 | |
---|
1004 | |
---|
1005 | |
---|
1006 | |
---|
1007 | Fielding & Reschke Expires November 7, 2014 [Page 18] |
---|
1008 | |
---|
1009 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
1010 | |
---|
1011 | |
---|
1012 | 3.4.1. Proactive Negotiation |
---|
1013 | |
---|
1014 | When content negotiation preferences are sent by the user agent in a |
---|
1015 | request to encourage an algorithm located at the server to select the |
---|
1016 | preferred representation, it is called proactive negotiation (a.k.a., |
---|
1017 | server-driven negotiation). Selection is based on the available |
---|
1018 | representations for a response (the dimensions over which it might |
---|
1019 | vary, such as language, content-coding, etc.) compared to various |
---|
1020 | information supplied in the request, including both the explicit |
---|
1021 | negotiation fields of Section 5.3 and implicit characteristics, such |
---|
1022 | as the client's network address or parts of the User-Agent field. |
---|
1023 | |
---|
1024 | Proactive negotiation is advantageous when the algorithm for |
---|
1025 | selecting from among the available representations is difficult to |
---|
1026 | describe to a user agent, or when the server desires to send its |
---|
1027 | "best guess" to the user agent along with the first response (hoping |
---|
1028 | to avoid the round-trip delay of a subsequent request if the "best |
---|
1029 | guess" is good enough for the user). In order to improve the |
---|
1030 | server's guess, a user agent MAY send request header fields that |
---|
1031 | describe its preferences. |
---|
1032 | |
---|
1033 | Proactive negotiation has serious disadvantages: |
---|
1034 | |
---|
1035 | o It is impossible for the server to accurately determine what might |
---|
1036 | be "best" for any given user, since that would require complete |
---|
1037 | knowledge of both the capabilities of the user agent and the |
---|
1038 | intended use for the response (e.g., does the user want to view it |
---|
1039 | on screen or print it on paper?); |
---|
1040 | |
---|
1041 | o Having the user agent describe its capabilities in every request |
---|
1042 | can be both very inefficient (given that only a small percentage |
---|
1043 | of responses have multiple representations) and a potential risk |
---|
1044 | to the user's privacy; |
---|
1045 | |
---|
1046 | o It complicates the implementation of an origin server and the |
---|
1047 | algorithms for generating responses to a request; and, |
---|
1048 | |
---|
1049 | o It limits the reusability of responses for shared caching. |
---|
1050 | |
---|
1051 | A user agent cannot rely on proactive negotiation preferences being |
---|
1052 | consistently honored, since the origin server might not implement |
---|
1053 | proactive negotiation for the requested resource or might decide that |
---|
1054 | sending a response that doesn't conform to the user agent's |
---|
1055 | preferences is better than sending a 406 (Not Acceptable) response. |
---|
1056 | |
---|
1057 | A Vary header field (Section 7.1.4) is often sent in a response |
---|
1058 | subject to proactive negotiation to indicate what parts of the |
---|
1059 | request information were used in the selection algorithm. |
---|
1060 | |
---|
1061 | |
---|
1062 | |
---|
1063 | Fielding & Reschke Expires November 7, 2014 [Page 19] |
---|
1064 | |
---|
1065 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
1066 | |
---|
1067 | |
---|
1068 | 3.4.2. Reactive Negotiation |
---|
1069 | |
---|
1070 | With reactive negotiation (a.k.a., agent-driven negotiation), |
---|
1071 | selection of the best response representation (regardless of the |
---|
1072 | status code) is performed by the user agent after receiving an |
---|
1073 | initial response from the origin server that contains a list of |
---|
1074 | resources for alternative representations. If the user agent is not |
---|
1075 | satisfied by the initial response representation, it can perform a |
---|
1076 | GET request on one or more of the alternative resources, selected |
---|
1077 | based on metadata included in the list, to obtain a different form of |
---|
1078 | representation for that response. Selection of alternatives might be |
---|
1079 | performed automatically by the user agent or manually by the user |
---|
1080 | selecting from a generated (possibly hypertext) menu. |
---|
1081 | |
---|
1082 | Note that the above refers to representations of the response, in |
---|
1083 | general, not representations of the resource. The alternative |
---|
1084 | representations are only considered representations of the target |
---|
1085 | resource if the response in which those alternatives are provided has |
---|
1086 | the semantics of being a representation of the target resource (e.g., |
---|
1087 | a 200 (OK) response to a GET request) or has the semantics of |
---|
1088 | providing links to alternative representations for the target |
---|
1089 | resource (e.g., a 300 (Multiple Choices) response to a GET request). |
---|
1090 | |
---|
1091 | A server might choose not to send an initial representation, other |
---|
1092 | than the list of alternatives, and thereby indicate that reactive |
---|
1093 | negotiation by the user agent is preferred. For example, the |
---|
1094 | alternatives listed in responses with the 300 (Multiple Choices) and |
---|
1095 | 406 (Not Acceptable) status codes include information about the |
---|
1096 | available representations so that the user or user agent can react by |
---|
1097 | making a selection. |
---|
1098 | |
---|
1099 | Reactive negotiation is advantageous when the response would vary |
---|
1100 | over commonly-used dimensions (such as type, language, or encoding), |
---|
1101 | when the origin server is unable to determine a user agent's |
---|
1102 | capabilities from examining the request, and generally when public |
---|
1103 | caches are used to distribute server load and reduce network usage. |
---|
1104 | |
---|
1105 | Reactive negotiation suffers from the disadvantages of transmitting a |
---|
1106 | list of alternatives to the user agent, which degrades user-perceived |
---|
1107 | latency if transmitted in the header section, and needing a second |
---|
1108 | request to obtain an alternate representation. Furthermore, this |
---|
1109 | specification does not define a mechanism for supporting automatic |
---|
1110 | selection, though it does not prevent such a mechanism from being |
---|
1111 | developed as an extension. |
---|
1112 | |
---|
1113 | |
---|
1114 | |
---|
1115 | |
---|
1116 | |
---|
1117 | |
---|
1118 | |
---|
1119 | Fielding & Reschke Expires November 7, 2014 [Page 20] |
---|
1120 | |
---|
1121 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
1122 | |
---|
1123 | |
---|
1124 | 4. Request Methods |
---|
1125 | |
---|
1126 | 4.1. Overview |
---|
1127 | |
---|
1128 | The request method token is the primary source of request semantics; |
---|
1129 | it indicates the purpose for which the client has made this request |
---|
1130 | and what is expected by the client as a successful result. |
---|
1131 | |
---|
1132 | The request method's semantics might be further specialized by the |
---|
1133 | semantics of some header fields when present in a request (Section 5) |
---|
1134 | if those additional semantics do not conflict with the method. For |
---|
1135 | example, a client can send conditional request header fields |
---|
1136 | (Section 5.2) to make the requested action conditional on the current |
---|
1137 | state of the target resource ([RFC7232]). |
---|
1138 | |
---|
1139 | method = token |
---|
1140 | |
---|
1141 | HTTP was originally designed to be usable as an interface to |
---|
1142 | distributed object systems. The request method was envisioned as |
---|
1143 | applying semantics to a target resource in much the same way as |
---|
1144 | invoking a defined method on an identified object would apply |
---|
1145 | semantics. The method token is case-sensitive because it might be |
---|
1146 | used as a gateway to object-based systems with case-sensitive method |
---|
1147 | names. |
---|
1148 | |
---|
1149 | Unlike distributed objects, the standardized request methods in HTTP |
---|
1150 | are not resource-specific, since uniform interfaces provide for |
---|
1151 | better visibility and reuse in network-based systems [REST]. Once |
---|
1152 | defined, a standardized method ought to have the same semantics when |
---|
1153 | applied to any resource, though each resource determines for itself |
---|
1154 | whether those semantics are implemented or allowed. |
---|
1155 | |
---|
1156 | This specification defines a number of standardized methods that are |
---|
1157 | commonly used in HTTP, as outlined by the following table. By |
---|
1158 | convention, standardized methods are defined in all-uppercase ASCII |
---|
1159 | letters. |
---|
1160 | |
---|
1161 | |
---|
1162 | |
---|
1163 | |
---|
1164 | |
---|
1165 | |
---|
1166 | |
---|
1167 | |
---|
1168 | |
---|
1169 | |
---|
1170 | |
---|
1171 | |
---|
1172 | |
---|
1173 | |
---|
1174 | |
---|
1175 | Fielding & Reschke Expires November 7, 2014 [Page 21] |
---|
1176 | |
---|
1177 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
1178 | |
---|
1179 | |
---|
1180 | +---------+-------------------------------------------------+-------+ |
---|
1181 | | Method | Description | Sec. | |
---|
1182 | +---------+-------------------------------------------------+-------+ |
---|
1183 | | GET | Transfer a current representation of the target | 4.3.1 | |
---|
1184 | | | resource. | | |
---|
1185 | | HEAD | Same as GET, but only transfer the status line | 4.3.2 | |
---|
1186 | | | and header section. | | |
---|
1187 | | POST | Perform resource-specific processing on the | 4.3.3 | |
---|
1188 | | | request payload. | | |
---|
1189 | | PUT | Replace all current representations of the | 4.3.4 | |
---|
1190 | | | target resource with the request payload. | | |
---|
1191 | | DELETE | Remove all current representations of the | 4.3.5 | |
---|
1192 | | | target resource. | | |
---|
1193 | | CONNECT | Establish a tunnel to the server identified by | 4.3.6 | |
---|
1194 | | | the target resource. | | |
---|
1195 | | OPTIONS | Describe the communication options for the | 4.3.7 | |
---|
1196 | | | target resource. | | |
---|
1197 | | TRACE | Perform a message loop-back test along the path | 4.3.8 | |
---|
1198 | | | to the target resource. | | |
---|
1199 | +---------+-------------------------------------------------+-------+ |
---|
1200 | |
---|
1201 | All general-purpose servers MUST support the methods GET and HEAD. |
---|
1202 | All other methods are OPTIONAL. |
---|
1203 | |
---|
1204 | Additional methods, outside the scope of this specification, have |
---|
1205 | been standardized for use in HTTP. All such methods ought to be |
---|
1206 | registered within the HTTP Method Registry maintained by IANA, as |
---|
1207 | defined in Section 8.1. |
---|
1208 | |
---|
1209 | The set of methods allowed by a target resource can be listed in an |
---|
1210 | Allow header field (Section 7.4.1). However, the set of allowed |
---|
1211 | methods can change dynamically. When a request method is received |
---|
1212 | that is unrecognized or not implemented by an origin server, the |
---|
1213 | origin server SHOULD respond with the 501 (Not Implemented) status |
---|
1214 | code. When a request method is received that is known by an origin |
---|
1215 | server but not allowed for the target resource, the origin server |
---|
1216 | SHOULD respond with the 405 (Method Not Allowed) status code. |
---|
1217 | |
---|
1218 | 4.2. Common Method Properties |
---|
1219 | |
---|
1220 | 4.2.1. Safe Methods |
---|
1221 | |
---|
1222 | Request methods are considered "safe" if their defined semantics are |
---|
1223 | essentially read-only; i.e., the client does not request, and does |
---|
1224 | not expect, any state change on the origin server as a result of |
---|
1225 | applying a safe method to a target resource. Likewise, reasonable |
---|
1226 | use of a safe method is not expected to cause any harm, loss of |
---|
1227 | property, or unusual burden on the origin server. |
---|
1228 | |
---|
1229 | |
---|
1230 | |
---|
1231 | Fielding & Reschke Expires November 7, 2014 [Page 22] |
---|
1232 | |
---|
1233 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
1234 | |
---|
1235 | |
---|
1236 | This definition of safe methods does not prevent an implementation |
---|
1237 | from including behavior that is potentially harmful, not entirely |
---|
1238 | read-only, or which causes side-effects while invoking a safe method. |
---|
1239 | What is important, however, is that the client did not request that |
---|
1240 | additional behavior and cannot be held accountable for it. For |
---|
1241 | example, most servers append request information to access log files |
---|
1242 | at the completion of every response, regardless of the method, and |
---|
1243 | that is considered safe even though the log storage might become full |
---|
1244 | and crash the server. Likewise, a safe request initiated by |
---|
1245 | selecting an advertisement on the Web will often have the side-effect |
---|
1246 | of charging an advertising account. |
---|
1247 | |
---|
1248 | Of the request methods defined by this specification, the GET, HEAD, |
---|
1249 | OPTIONS, and TRACE methods are defined to be safe. |
---|
1250 | |
---|
1251 | The purpose of distinguishing between safe and unsafe methods is to |
---|
1252 | allow automated retrieval processes (spiders) and cache performance |
---|
1253 | optimization (pre-fetching) to work without fear of causing harm. In |
---|
1254 | addition, it allows a user agent to apply appropriate constraints on |
---|
1255 | the automated use of unsafe methods when processing potentially |
---|
1256 | untrusted content. |
---|
1257 | |
---|
1258 | A user agent SHOULD distinguish between safe and unsafe methods when |
---|
1259 | presenting potential actions to a user, such that the user can be |
---|
1260 | made aware of an unsafe action before it is requested. |
---|
1261 | |
---|
1262 | When a resource is constructed such that parameters within the |
---|
1263 | effective request URI have the effect of selecting an action, it is |
---|
1264 | the resource owner's responsibility to ensure that the action is |
---|
1265 | consistent with the request method semantics. For example, it is |
---|
1266 | common for Web-based content editing software to use actions within |
---|
1267 | query parameters, such as "page?do=delete". If the purpose of such a |
---|
1268 | resource is to perform an unsafe action, then the resource owner MUST |
---|
1269 | disable or disallow that action when it is accessed using a safe |
---|
1270 | request method. Failure to do so will result in unfortunate side- |
---|
1271 | effects when automated processes perform a GET on every URI reference |
---|
1272 | for the sake of link maintenance, pre-fetching, building a search |
---|
1273 | index, etc. |
---|
1274 | |
---|
1275 | 4.2.2. Idempotent Methods |
---|
1276 | |
---|
1277 | A request method is considered "idempotent" if the intended effect on |
---|
1278 | the server of multiple identical requests with that method is the |
---|
1279 | same as the effect for a single such request. Of the request methods |
---|
1280 | defined by this specification, PUT, DELETE, and safe request methods |
---|
1281 | are idempotent. |
---|
1282 | |
---|
1283 | Like the definition of safe, the idempotent property only applies to |
---|
1284 | |
---|
1285 | |
---|
1286 | |
---|
1287 | Fielding & Reschke Expires November 7, 2014 [Page 23] |
---|
1288 | |
---|
1289 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
1290 | |
---|
1291 | |
---|
1292 | what has been requested by the user; a server is free to log each |
---|
1293 | request separately, retain a revision control history, or implement |
---|
1294 | other non-idempotent side-effects for each idempotent request. |
---|
1295 | |
---|
1296 | Idempotent methods are distinguished because the request can be |
---|
1297 | repeated automatically if a communication failure occurs before the |
---|
1298 | client is able to read the server's response. For example, if a |
---|
1299 | client sends a PUT request and the underlying connection is closed |
---|
1300 | before any response is received, then the client can establish a new |
---|
1301 | connection and retry the idempotent request. It knows that repeating |
---|
1302 | the request will have the same intended effect, even if the original |
---|
1303 | request succeeded, though the response might differ. |
---|
1304 | |
---|
1305 | 4.2.3. Cacheable Methods |
---|
1306 | |
---|
1307 | Request methods can be defined as "cacheable" to indicate that |
---|
1308 | responses to them are allowed to be stored for future reuse; for |
---|
1309 | specific requirements see [RFC7234]. In general, safe methods that |
---|
1310 | do not depend on a current or authoritative response are defined as |
---|
1311 | cacheable; this specification defines GET, HEAD and POST as |
---|
1312 | cacheable, although the overwhelming majority of cache |
---|
1313 | implementations only support GET and HEAD. |
---|
1314 | |
---|
1315 | 4.3. Method Definitions |
---|
1316 | |
---|
1317 | 4.3.1. GET |
---|
1318 | |
---|
1319 | The GET method requests transfer of a current selected representation |
---|
1320 | for the target resource. GET is the primary mechanism of information |
---|
1321 | retrieval and the focus of almost all performance optimizations. |
---|
1322 | Hence, when people speak of retrieving some identifiable information |
---|
1323 | via HTTP, they are generally referring to making a GET request. |
---|
1324 | |
---|
1325 | It is tempting to think of resource identifiers as remote file system |
---|
1326 | pathnames, and of representations as being a copy of the contents of |
---|
1327 | such files. In fact, that is how many resources are implemented (see |
---|
1328 | Section 9.1 for related security considerations). However, there are |
---|
1329 | no such limitations in practice. The HTTP interface for a resource |
---|
1330 | is just as likely to be implemented as a tree of content objects, a |
---|
1331 | programmatic view on various database records, or a gateway to other |
---|
1332 | information systems. Even when the URI mapping mechanism is tied to |
---|
1333 | a file system, an origin server might be configured to execute the |
---|
1334 | files with the request as input and send the output as the |
---|
1335 | representation, rather than transfer the files directly. Regardless, |
---|
1336 | only the origin server needs to know how each of its resource |
---|
1337 | identifiers corresponds to an implementation, and how each |
---|
1338 | implementation manages to select and send a current representation of |
---|
1339 | the target resource in a response to GET. |
---|
1340 | |
---|
1341 | |
---|
1342 | |
---|
1343 | Fielding & Reschke Expires November 7, 2014 [Page 24] |
---|
1344 | |
---|
1345 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
1346 | |
---|
1347 | |
---|
1348 | A client can alter the semantics of GET to be a "range request", |
---|
1349 | requesting transfer of only some part(s) of the selected |
---|
1350 | representation, by sending a Range header field in the request |
---|
1351 | ([RFC7233]). |
---|
1352 | |
---|
1353 | A payload within a GET request message has no defined semantics; |
---|
1354 | sending a payload body on a GET request might cause some existing |
---|
1355 | implementations to reject the request. |
---|
1356 | |
---|
1357 | The response to a GET request is cacheable; a cache MAY use it to |
---|
1358 | satisfy subsequent GET and HEAD requests unless otherwise indicated |
---|
1359 | by the Cache-Control header field (Section 5.2 of [RFC7234]). |
---|
1360 | |
---|
1361 | 4.3.2. HEAD |
---|
1362 | |
---|
1363 | The HEAD method is identical to GET except that the server MUST NOT |
---|
1364 | send a message body in the response (i.e., the response terminates at |
---|
1365 | the end of the header section). The server SHOULD send the same |
---|
1366 | header fields in response to a HEAD request as it would have sent if |
---|
1367 | the request had been a GET, except that the payload header fields |
---|
1368 | (Section 3.3) MAY be omitted. This method can be used for obtaining |
---|
1369 | metadata about the selected representation without transferring the |
---|
1370 | representation data and is often used for testing hypertext links for |
---|
1371 | validity, accessibility, and recent modification. |
---|
1372 | |
---|
1373 | A payload within a HEAD request message has no defined semantics; |
---|
1374 | sending a payload body on a HEAD request might cause some existing |
---|
1375 | implementations to reject the request. |
---|
1376 | |
---|
1377 | The response to a HEAD request is cacheable; a cache MAY use it to |
---|
1378 | satisfy subsequent HEAD requests unless otherwise indicated by the |
---|
1379 | Cache-Control header field (Section 5.2 of [RFC7234]). A HEAD |
---|
1380 | response might also have an effect on previously cached responses to |
---|
1381 | GET; see Section 4.3.5 of [RFC7234]. |
---|
1382 | |
---|
1383 | 4.3.3. POST |
---|
1384 | |
---|
1385 | The POST method requests that the target resource process the |
---|
1386 | representation enclosed in the request according to the resource's |
---|
1387 | own specific semantics. For example, POST is used for the following |
---|
1388 | functions (among others): |
---|
1389 | |
---|
1390 | o Providing a block of data, such as the fields entered into an HTML |
---|
1391 | form, to a data-handling process; |
---|
1392 | |
---|
1393 | o Posting a message to a bulletin board, newsgroup, mailing list, |
---|
1394 | blog, or similar group of articles; |
---|
1395 | |
---|
1396 | |
---|
1397 | |
---|
1398 | |
---|
1399 | Fielding & Reschke Expires November 7, 2014 [Page 25] |
---|
1400 | |
---|
1401 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
1402 | |
---|
1403 | |
---|
1404 | o Creating a new resource that has yet to be identified by the |
---|
1405 | origin server; and |
---|
1406 | |
---|
1407 | o Appending data to a resource's existing representation(s). |
---|
1408 | |
---|
1409 | An origin server indicates response semantics by choosing an |
---|
1410 | appropriate status code depending on the result of processing the |
---|
1411 | POST request; almost all of the status codes defined by this |
---|
1412 | specification might be received in a response to POST (the exceptions |
---|
1413 | being 206, 304, and 416). |
---|
1414 | |
---|
1415 | If one or more resources has been created on the origin server as a |
---|
1416 | result of successfully processing a POST request, the origin server |
---|
1417 | SHOULD send a 201 (Created) response containing a Location header |
---|
1418 | field that provides an identifier for the primary resource created |
---|
1419 | (Section 7.1.2) and a representation that describes the status of the |
---|
1420 | request while referring to the new resource(s). |
---|
1421 | |
---|
1422 | Responses to POST requests are only cacheable when they include |
---|
1423 | explicit freshness information (see Section 4.2.1 of [RFC7234]). |
---|
1424 | However, POST caching is not widely implemented. For cases where an |
---|
1425 | origin server wishes the client to be able to cache the result of a |
---|
1426 | POST in a way that can be reused by a later GET, the origin server |
---|
1427 | MAY send a 200 (OK) response containing the result and a Content- |
---|
1428 | Location header field that has the same value as the POST's effective |
---|
1429 | request URI (Section 3.1.4.2). |
---|
1430 | |
---|
1431 | If the result of processing a POST would be equivalent to a |
---|
1432 | representation of an existing resource, an origin server MAY redirect |
---|
1433 | the user agent to that resource by sending a 303 (See Other) response |
---|
1434 | with the existing resource's identifier in the Location field. This |
---|
1435 | has the benefits of providing the user agent a resource identifier |
---|
1436 | and transferring the representation via a method more amenable to |
---|
1437 | shared caching, though at the cost of an extra request if the user |
---|
1438 | agent does not already have the representation cached. |
---|
1439 | |
---|
1440 | 4.3.4. PUT |
---|
1441 | |
---|
1442 | The PUT method requests that the state of the target resource be |
---|
1443 | created or replaced with the state defined by the representation |
---|
1444 | enclosed in the request message payload. A successful PUT of a given |
---|
1445 | representation would suggest that a subsequent GET on that same |
---|
1446 | target resource will result in an equivalent representation being |
---|
1447 | sent in a 200 (OK) response. However, there is no guarantee that |
---|
1448 | such a state change will be observable, since the target resource |
---|
1449 | might be acted upon by other user agents in parallel, or might be |
---|
1450 | subject to dynamic processing by the origin server, before any |
---|
1451 | subsequent GET is received. A successful response only implies that |
---|
1452 | |
---|
1453 | |
---|
1454 | |
---|
1455 | Fielding & Reschke Expires November 7, 2014 [Page 26] |
---|
1456 | |
---|
1457 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
1458 | |
---|
1459 | |
---|
1460 | the user agent's intent was achieved at the time of its processing by |
---|
1461 | the origin server. |
---|
1462 | |
---|
1463 | If the target resource does not have a current representation and the |
---|
1464 | PUT successfully creates one, then the origin server MUST inform the |
---|
1465 | user agent by sending a 201 (Created) response. If the target |
---|
1466 | resource does have a current representation and that representation |
---|
1467 | is successfully modified in accordance with the state of the enclosed |
---|
1468 | representation, then the origin server MUST send either a 200 (OK) or |
---|
1469 | a 204 (No Content) response to indicate successful completion of the |
---|
1470 | request. |
---|
1471 | |
---|
1472 | An origin server SHOULD ignore unrecognized header fields received in |
---|
1473 | a PUT request (i.e., do not save them as part of the resource state). |
---|
1474 | |
---|
1475 | An origin server SHOULD verify that the PUT representation is |
---|
1476 | consistent with any constraints the server has for the target |
---|
1477 | resource that cannot or will not be changed by the PUT. This is |
---|
1478 | particularly important when the origin server uses internal |
---|
1479 | configuration information related to the URI in order to set the |
---|
1480 | values for representation metadata on GET responses. When a PUT |
---|
1481 | representation is inconsistent with the target resource, the origin |
---|
1482 | server SHOULD either make them consistent, by transforming the |
---|
1483 | representation or changing the resource configuration, or respond |
---|
1484 | with an appropriate error message containing sufficient information |
---|
1485 | to explain why the representation is unsuitable. The 409 (Conflict) |
---|
1486 | or 415 (Unsupported Media Type) status codes are suggested, with the |
---|
1487 | latter being specific to constraints on Content-Type values. |
---|
1488 | |
---|
1489 | For example, if the target resource is configured to always have a |
---|
1490 | Content-Type of "text/html" and the representation being PUT has a |
---|
1491 | Content-Type of "image/jpeg", the origin server ought to do one of: |
---|
1492 | |
---|
1493 | a. reconfigure the target resource to reflect the new media type; |
---|
1494 | |
---|
1495 | b. transform the PUT representation to a format consistent with that |
---|
1496 | of the resource before saving it as the new resource state; or, |
---|
1497 | |
---|
1498 | c. reject the request with a 415 (Unsupported Media Type) response |
---|
1499 | indicating that the target resource is limited to "text/html", |
---|
1500 | perhaps including a link to a different resource that would be a |
---|
1501 | suitable target for the new representation. |
---|
1502 | |
---|
1503 | HTTP does not define exactly how a PUT method affects the state of an |
---|
1504 | origin server beyond what can be expressed by the intent of the user |
---|
1505 | agent request and the semantics of the origin server response. It |
---|
1506 | does not define what a resource might be, in any sense of that word, |
---|
1507 | beyond the interface provided via HTTP. It does not define how |
---|
1508 | |
---|
1509 | |
---|
1510 | |
---|
1511 | Fielding & Reschke Expires November 7, 2014 [Page 27] |
---|
1512 | |
---|
1513 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
1514 | |
---|
1515 | |
---|
1516 | resource state is "stored", nor how such storage might change as a |
---|
1517 | result of a change in resource state, nor how the origin server |
---|
1518 | translates resource state into representations. Generally speaking, |
---|
1519 | all implementation details behind the resource interface are |
---|
1520 | intentionally hidden by the server. |
---|
1521 | |
---|
1522 | An origin server MUST NOT send a validator header field |
---|
1523 | (Section 7.2), such as an ETag or Last-Modified field, in a |
---|
1524 | successful response to PUT unless the request's representation data |
---|
1525 | was saved without any transformation applied to the body (i.e., the |
---|
1526 | resource's new representation data is identical to the representation |
---|
1527 | data received in the PUT request) and the validator field value |
---|
1528 | reflects the new representation. This requirement allows a user |
---|
1529 | agent to know when the representation body it has in memory remains |
---|
1530 | current as a result of the PUT, thus not in need of retrieving again |
---|
1531 | from the origin server, and that the new validator(s) received in the |
---|
1532 | response can be used for future conditional requests in order to |
---|
1533 | prevent accidental overwrites (Section 5.2). |
---|
1534 | |
---|
1535 | The fundamental difference between the POST and PUT methods is |
---|
1536 | highlighted by the different intent for the enclosed representation. |
---|
1537 | The target resource in a POST request is intended to handle the |
---|
1538 | enclosed representation according to the resource's own semantics, |
---|
1539 | whereas the enclosed representation in a PUT request is defined as |
---|
1540 | replacing the state of the target resource. Hence, the intent of PUT |
---|
1541 | is idempotent and visible to intermediaries, even though the exact |
---|
1542 | effect is only known by the origin server. |
---|
1543 | |
---|
1544 | Proper interpretation of a PUT request presumes that the user agent |
---|
1545 | knows which target resource is desired. A service that selects a |
---|
1546 | proper URI on behalf of the client, after receiving a state-changing |
---|
1547 | request, SHOULD be implemented using the POST method rather than PUT. |
---|
1548 | If the origin server will not make the requested PUT state change to |
---|
1549 | the target resource and instead wishes to have it applied to a |
---|
1550 | different resource, such as when the resource has been moved to a |
---|
1551 | different URI, then the origin server MUST send an appropriate 3xx |
---|
1552 | (Redirection) response; the user agent MAY then make its own decision |
---|
1553 | regarding whether or not to redirect the request. |
---|
1554 | |
---|
1555 | A PUT request applied to the target resource can have side-effects on |
---|
1556 | other resources. For example, an article might have a URI for |
---|
1557 | identifying "the current version" (a resource) that is separate from |
---|
1558 | the URIs identifying each particular version (different resources |
---|
1559 | that at one point shared the same state as the current version |
---|
1560 | resource). A successful PUT request on "the current version" URI |
---|
1561 | might therefore create a new version resource in addition to changing |
---|
1562 | the state of the target resource, and might also cause links to be |
---|
1563 | added between the related resources. |
---|
1564 | |
---|
1565 | |
---|
1566 | |
---|
1567 | Fielding & Reschke Expires November 7, 2014 [Page 28] |
---|
1568 | |
---|
1569 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
1570 | |
---|
1571 | |
---|
1572 | An origin server that allows PUT on a given target resource MUST send |
---|
1573 | a 400 (Bad Request) response to a PUT request that contains a |
---|
1574 | Content-Range header field (Section 4.2 of [RFC7233]), since the |
---|
1575 | payload is likely to be partial content that has been mistakenly PUT |
---|
1576 | as a full representation. Partial content updates are possible by |
---|
1577 | targeting a separately identified resource with state that overlaps a |
---|
1578 | portion of the larger resource, or by using a different method that |
---|
1579 | has been specifically defined for partial updates (for example, the |
---|
1580 | PATCH method defined in [RFC5789]). |
---|
1581 | |
---|
1582 | Responses to the PUT method are not cacheable. If a successful PUT |
---|
1583 | request passes through a cache that has one or more stored responses |
---|
1584 | for the effective request URI, those stored responses will be |
---|
1585 | invalidated (see Section 4.4 of [RFC7234]). |
---|
1586 | |
---|
1587 | 4.3.5. DELETE |
---|
1588 | |
---|
1589 | The DELETE method requests that the origin server remove the |
---|
1590 | association between the target resource and its current |
---|
1591 | functionality. In effect, this method is similar to the rm command |
---|
1592 | in UNIX: it expresses a deletion operation on the URI mapping of the |
---|
1593 | origin server, rather than an expectation that the previously |
---|
1594 | associated information be deleted. |
---|
1595 | |
---|
1596 | If the target resource has one or more current representations, they |
---|
1597 | might or might not be destroyed by the origin server, and the |
---|
1598 | associated storage might or might not be reclaimed, depending |
---|
1599 | entirely on the nature of the resource and its implementation by the |
---|
1600 | origin server (which are beyond the scope of this specification). |
---|
1601 | Likewise, other implementation aspects of a resource might need to be |
---|
1602 | deactivated or archived as a result of a DELETE, such as database or |
---|
1603 | gateway connections. In general, it is assumed that the origin |
---|
1604 | server will only allow DELETE on resources for which it has a |
---|
1605 | prescribed mechanism for accomplishing the deletion. |
---|
1606 | |
---|
1607 | Relatively few resources allow the DELETE method -- its primary use |
---|
1608 | is for remote authoring environments, where the user has some |
---|
1609 | direction regarding its effect. For example, a resource that was |
---|
1610 | previously created using a PUT request, or identified via the |
---|
1611 | Location header field after a 201 (Created) response to a POST |
---|
1612 | request, might allow a corresponding DELETE request to undo those |
---|
1613 | actions. Similarly, custom user agent implementations that implement |
---|
1614 | an authoring function, such as revision control clients using HTTP |
---|
1615 | for remote operations, might use DELETE based on an assumption that |
---|
1616 | the server's URI space has been crafted to correspond to a version |
---|
1617 | repository. |
---|
1618 | |
---|
1619 | If a DELETE method is successfully applied, the origin server SHOULD |
---|
1620 | |
---|
1621 | |
---|
1622 | |
---|
1623 | Fielding & Reschke Expires November 7, 2014 [Page 29] |
---|
1624 | |
---|
1625 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
1626 | |
---|
1627 | |
---|
1628 | send a 202 (Accepted) status code if the action will likely succeed |
---|
1629 | but has not yet been enacted, a 204 (No Content) status code if the |
---|
1630 | action has been enacted and no further information is to be supplied, |
---|
1631 | or a 200 (OK) status code if the action has been enacted and the |
---|
1632 | response message includes a representation describing the status. |
---|
1633 | |
---|
1634 | A payload within a DELETE request message has no defined semantics; |
---|
1635 | sending a payload body on a DELETE request might cause some existing |
---|
1636 | implementations to reject the request. |
---|
1637 | |
---|
1638 | Responses to the DELETE method are not cacheable. If a DELETE |
---|
1639 | request passes through a cache that has one or more stored responses |
---|
1640 | for the effective request URI, those stored responses will be |
---|
1641 | invalidated (see Section 4.4 of [RFC7234]). |
---|
1642 | |
---|
1643 | 4.3.6. CONNECT |
---|
1644 | |
---|
1645 | The CONNECT method requests that the recipient establish a tunnel to |
---|
1646 | the destination origin server identified by the request-target and, |
---|
1647 | if successful, thereafter restrict its behavior to blind forwarding |
---|
1648 | of packets, in both directions, until the tunnel is closed. Tunnels |
---|
1649 | are commonly used to create an end-to-end virtual connection, through |
---|
1650 | one or more proxies, which can then be secured using TLS (Transport |
---|
1651 | Layer Security, [RFC5246]). |
---|
1652 | |
---|
1653 | CONNECT is intended only for use in requests to a proxy. An origin |
---|
1654 | server that receives a CONNECT request for itself MAY respond with a |
---|
1655 | 2xx status code to indicate that a connection is established. |
---|
1656 | However, most origin servers do not implement CONNECT. |
---|
1657 | |
---|
1658 | A client sending a CONNECT request MUST send the authority form of |
---|
1659 | request-target (Section 5.3 of [RFC7230]); i.e., the request-target |
---|
1660 | consists of only the host name and port number of the tunnel |
---|
1661 | destination, separated by a colon. For example, |
---|
1662 | |
---|
1663 | CONNECT server.example.com:80 HTTP/1.1 |
---|
1664 | Host: server.example.com:80 |
---|
1665 | |
---|
1666 | |
---|
1667 | The recipient proxy can establish a tunnel either by directly |
---|
1668 | connecting to the request-target or, if configured to use another |
---|
1669 | proxy, by forwarding the CONNECT request to the next inbound proxy. |
---|
1670 | Any 2xx (Successful) response indicates that the sender (and all |
---|
1671 | inbound proxies) will switch to tunnel mode immediately after the |
---|
1672 | blank line that concludes the successful response's header section; |
---|
1673 | data received after that blank line is from the server identified by |
---|
1674 | the request-target. Any response other than a successful response |
---|
1675 | indicates that the tunnel has not yet been formed and that the |
---|
1676 | |
---|
1677 | |
---|
1678 | |
---|
1679 | Fielding & Reschke Expires November 7, 2014 [Page 30] |
---|
1680 | |
---|
1681 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
1682 | |
---|
1683 | |
---|
1684 | connection remains governed by HTTP. |
---|
1685 | |
---|
1686 | A tunnel is closed when a tunnel intermediary detects that either |
---|
1687 | side has closed its connection: the intermediary MUST attempt to send |
---|
1688 | any outstanding data that came from the closed side to the other |
---|
1689 | side, close both connections, and then discard any remaining data |
---|
1690 | left undelivered. |
---|
1691 | |
---|
1692 | Proxy authentication might be used to establish the authority to |
---|
1693 | create a tunnel. For example, |
---|
1694 | |
---|
1695 | CONNECT server.example.com:80 HTTP/1.1 |
---|
1696 | Host: server.example.com:80 |
---|
1697 | Proxy-Authorization: basic aGVsbG86d29ybGQ= |
---|
1698 | |
---|
1699 | |
---|
1700 | There are significant risks in establishing a tunnel to arbitrary |
---|
1701 | servers, particularly when the destination is a well-known or |
---|
1702 | reserved TCP port that is not intended for Web traffic. For example, |
---|
1703 | a CONNECT to a request-target of "example.com:25" would suggest that |
---|
1704 | the proxy connect to the reserved port for SMTP traffic; if allowed, |
---|
1705 | that could trick the proxy into relaying spam email. Proxies that |
---|
1706 | support CONNECT SHOULD restrict its use to a limited set of known |
---|
1707 | ports or a configurable whitelist of safe request targets. |
---|
1708 | |
---|
1709 | A server MUST NOT send any Transfer-Encoding or Content-Length header |
---|
1710 | fields in a 2xx (Successful) response to CONNECT. A client MUST |
---|
1711 | ignore any Content-Length or Transfer-Encoding header fields received |
---|
1712 | in a successful response to CONNECT. |
---|
1713 | |
---|
1714 | A payload within a CONNECT request message has no defined semantics; |
---|
1715 | sending a payload body on a CONNECT request might cause some existing |
---|
1716 | implementations to reject the request. |
---|
1717 | |
---|
1718 | Responses to the CONNECT method are not cacheable. |
---|
1719 | |
---|
1720 | 4.3.7. OPTIONS |
---|
1721 | |
---|
1722 | The OPTIONS method requests information about the communication |
---|
1723 | options available for the target resource, either at the origin |
---|
1724 | server or an intervening intermediary. This method allows a client |
---|
1725 | to determine the options and/or requirements associated with a |
---|
1726 | resource, or the capabilities of a server, without implying a |
---|
1727 | resource action. |
---|
1728 | |
---|
1729 | An OPTIONS request with an asterisk ("*") as the request-target |
---|
1730 | (Section 5.3 of [RFC7230]) applies to the server in general rather |
---|
1731 | than to a specific resource. Since a server's communication options |
---|
1732 | |
---|
1733 | |
---|
1734 | |
---|
1735 | Fielding & Reschke Expires November 7, 2014 [Page 31] |
---|
1736 | |
---|
1737 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
1738 | |
---|
1739 | |
---|
1740 | typically depend on the resource, the "*" request is only useful as a |
---|
1741 | "ping" or "no-op" type of method; it does nothing beyond allowing the |
---|
1742 | client to test the capabilities of the server. For example, this can |
---|
1743 | be used to test a proxy for HTTP/1.1 conformance (or lack thereof). |
---|
1744 | |
---|
1745 | If the request-target is not an asterisk, the OPTIONS request applies |
---|
1746 | to the options that are available when communicating with the target |
---|
1747 | resource. |
---|
1748 | |
---|
1749 | A server generating a successful response to OPTIONS SHOULD send any |
---|
1750 | header fields that might indicate optional features implemented by |
---|
1751 | the server and applicable to the target resource (e.g., Allow), |
---|
1752 | including potential extensions not defined by this specification. |
---|
1753 | The response payload, if any, might also describe the communication |
---|
1754 | options in a machine or human-readable representation. A standard |
---|
1755 | format for such a representation is not defined by this |
---|
1756 | specification, but might be defined by future extensions to HTTP. A |
---|
1757 | server MUST generate a Content-Length field with a value of "0" if no |
---|
1758 | payload body is to be sent in the response. |
---|
1759 | |
---|
1760 | A client MAY send a Max-Forwards header field in an OPTIONS request |
---|
1761 | to target a specific recipient in the request chain (see |
---|
1762 | Section 5.1.2). A proxy MUST NOT generate a Max-Forwards header |
---|
1763 | field while forwarding a request unless that request was received |
---|
1764 | with a Max-Forwards field. |
---|
1765 | |
---|
1766 | A client that generates an OPTIONS request containing a payload body |
---|
1767 | MUST send a valid Content-Type header field describing the |
---|
1768 | representation media type. Although this specification does not |
---|
1769 | define any use for such a payload, future extensions to HTTP might |
---|
1770 | use the OPTIONS body to make more detailed queries about the target |
---|
1771 | resource. |
---|
1772 | |
---|
1773 | Responses to the OPTIONS method are not cacheable. |
---|
1774 | |
---|
1775 | 4.3.8. TRACE |
---|
1776 | |
---|
1777 | The TRACE method requests a remote, application-level loop-back of |
---|
1778 | the request message. The final recipient of the request SHOULD |
---|
1779 | reflect the message received, excluding some fields described below, |
---|
1780 | back to the client as the message body of a 200 (OK) response with a |
---|
1781 | Content-Type of "message/http" (Section 8.3.1 of [RFC7230]). The |
---|
1782 | final recipient is either the origin server or the first server to |
---|
1783 | receive a Max-Forwards value of zero (0) in the request |
---|
1784 | (Section 5.1.2). |
---|
1785 | |
---|
1786 | A client MUST NOT generate header fields in a TRACE request |
---|
1787 | containing sensitive data that might be disclosed by the response. |
---|
1788 | |
---|
1789 | |
---|
1790 | |
---|
1791 | Fielding & Reschke Expires November 7, 2014 [Page 32] |
---|
1792 | |
---|
1793 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
1794 | |
---|
1795 | |
---|
1796 | For example, it would be foolish for a user agent to send stored user |
---|
1797 | credentials [RFC7235] or cookies [RFC6265] in a TRACE request. The |
---|
1798 | final recipient of the request SHOULD exclude any request header |
---|
1799 | fields that are likely to contain sensitive data when that recipient |
---|
1800 | generates the response body. |
---|
1801 | |
---|
1802 | TRACE allows the client to see what is being received at the other |
---|
1803 | end of the request chain and use that data for testing or diagnostic |
---|
1804 | information. The value of the Via header field (Section 5.7.1 of |
---|
1805 | [RFC7230]) is of particular interest, since it acts as a trace of the |
---|
1806 | request chain. Use of the Max-Forwards header field allows the |
---|
1807 | client to limit the length of the request chain, which is useful for |
---|
1808 | testing a chain of proxies forwarding messages in an infinite loop. |
---|
1809 | |
---|
1810 | A client MUST NOT send a message body in a TRACE request. |
---|
1811 | |
---|
1812 | Responses to the TRACE method are not cacheable. |
---|
1813 | |
---|
1814 | 5. Request Header Fields |
---|
1815 | |
---|
1816 | A client sends request header fields to provide more information |
---|
1817 | about the request context, make the request conditional based on the |
---|
1818 | target resource state, suggest preferred formats for the response, |
---|
1819 | supply authentication credentials, or modify the expected request |
---|
1820 | processing. These fields act as request modifiers, similar to the |
---|
1821 | parameters on a programming language method invocation. |
---|
1822 | |
---|
1823 | 5.1. Controls |
---|
1824 | |
---|
1825 | Controls are request header fields that direct specific handling of |
---|
1826 | the request. |
---|
1827 | |
---|
1828 | +-------------------+--------------------------+ |
---|
1829 | | Header Field Name | Defined in... | |
---|
1830 | +-------------------+--------------------------+ |
---|
1831 | | Cache-Control | Section 5.2 of [RFC7234] | |
---|
1832 | | Expect | Section 5.1.1 | |
---|
1833 | | Host | Section 5.4 of [RFC7230] | |
---|
1834 | | Max-Forwards | Section 5.1.2 | |
---|
1835 | | Pragma | Section 5.4 of [RFC7234] | |
---|
1836 | | Range | Section 3.1 of [RFC7233] | |
---|
1837 | | TE | Section 4.3 of [RFC7230] | |
---|
1838 | +-------------------+--------------------------+ |
---|
1839 | |
---|
1840 | |
---|
1841 | |
---|
1842 | |
---|
1843 | |
---|
1844 | |
---|
1845 | |
---|
1846 | |
---|
1847 | Fielding & Reschke Expires November 7, 2014 [Page 33] |
---|
1848 | |
---|
1849 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
1850 | |
---|
1851 | |
---|
1852 | 5.1.1. Expect |
---|
1853 | |
---|
1854 | The "Expect" header field in a request indicates a certain set of |
---|
1855 | behaviors (expectations) that need to be supported by the server in |
---|
1856 | order to properly handle this request. The only such expectation |
---|
1857 | defined by this specification is 100-continue. |
---|
1858 | |
---|
1859 | Expect = "100-continue" |
---|
1860 | |
---|
1861 | The Expect field-value is case-insensitive. |
---|
1862 | |
---|
1863 | A server that receives an Expect field-value other than 100-continue |
---|
1864 | MAY respond with a 417 (Expectation Failed) status code to indicate |
---|
1865 | that the unexpected expectation cannot be met. |
---|
1866 | |
---|
1867 | A 100-continue expectation informs recipients that the client is |
---|
1868 | about to send a (presumably large) message body in this request and |
---|
1869 | wishes to receive a 100 (Continue) interim response if the request- |
---|
1870 | line and header fields are not sufficient to cause an immediate |
---|
1871 | success, redirect, or error response. This allows the client to wait |
---|
1872 | for an indication that it is worthwhile to send the message body |
---|
1873 | before actually doing so, which can improve efficiency when the |
---|
1874 | message body is huge or when the client anticipates that an error is |
---|
1875 | likely (e.g., when sending a state-changing method, for the first |
---|
1876 | time, without previously verified authentication credentials). |
---|
1877 | |
---|
1878 | For example, a request that begins with |
---|
1879 | |
---|
1880 | PUT /somewhere/fun HTTP/1.1 |
---|
1881 | Host: origin.example.com |
---|
1882 | Content-Type: video/h264 |
---|
1883 | Content-Length: 1234567890987 |
---|
1884 | Expect: 100-continue |
---|
1885 | |
---|
1886 | |
---|
1887 | allows the origin server to immediately respond with an error |
---|
1888 | message, such as 401 (Unauthorized) or 405 (Method Not Allowed), |
---|
1889 | before the client starts filling the pipes with an unnecessary data |
---|
1890 | transfer. |
---|
1891 | |
---|
1892 | Requirements for clients: |
---|
1893 | |
---|
1894 | o A client MUST NOT generate a 100-continue expectation in a request |
---|
1895 | that does not include a message body. |
---|
1896 | |
---|
1897 | o A client that will wait for a 100 (Continue) response before |
---|
1898 | sending the request message body MUST send an Expect header field |
---|
1899 | containing a 100-continue expectation. |
---|
1900 | |
---|
1901 | |
---|
1902 | |
---|
1903 | Fielding & Reschke Expires November 7, 2014 [Page 34] |
---|
1904 | |
---|
1905 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
1906 | |
---|
1907 | |
---|
1908 | o A client that sends a 100-continue expectation is not required to |
---|
1909 | wait for any specific length of time; such a client MAY proceed to |
---|
1910 | send the message body even if it has not yet received a response. |
---|
1911 | Furthermore, since 100 (Continue) responses cannot be sent through |
---|
1912 | an HTTP/1.0 intermediary, such a client SHOULD NOT wait for an |
---|
1913 | indefinite period before sending the message body. |
---|
1914 | |
---|
1915 | o A client that receives a 417 (Expectation Failed) status code in |
---|
1916 | response to a request containing a 100-continue expectation SHOULD |
---|
1917 | repeat that request without a 100-continue expectation, since the |
---|
1918 | 417 response merely indicates that the response chain does not |
---|
1919 | support expectations (e.g., it passes through an HTTP/1.0 server). |
---|
1920 | |
---|
1921 | Requirements for servers: |
---|
1922 | |
---|
1923 | o A server that receives a 100-continue expectation in an HTTP/1.0 |
---|
1924 | request MUST ignore that expectation. |
---|
1925 | |
---|
1926 | o A server MAY omit sending a 100 (Continue) response if it has |
---|
1927 | already received some or all of the message body for the |
---|
1928 | corresponding request, or if the framing indicates that there is |
---|
1929 | no message body. |
---|
1930 | |
---|
1931 | o A server that sends a 100 (Continue) response MUST ultimately send |
---|
1932 | a final status code, once the message body is received and |
---|
1933 | processed, unless the connection is closed prematurely. |
---|
1934 | |
---|
1935 | o A server that responds with a final status code before reading the |
---|
1936 | entire message body SHOULD indicate in that response whether it |
---|
1937 | intends to close the connection or continue reading and discarding |
---|
1938 | the request message (see Section 6.6 of [RFC7230]). |
---|
1939 | |
---|
1940 | An origin server MUST, upon receiving an HTTP/1.1 (or later) request- |
---|
1941 | line and a complete header section that contains a 100-continue |
---|
1942 | expectation and indicates a request message body will follow, either |
---|
1943 | send an immediate response with a final status code, if that status |
---|
1944 | can be determined by examining just the request-line and header |
---|
1945 | fields, or send an immediate 100 (Continue) response to encourage the |
---|
1946 | client to send the request's message body. The origin server MUST |
---|
1947 | NOT wait for the message body before sending the 100 (Continue) |
---|
1948 | response. |
---|
1949 | |
---|
1950 | A proxy MUST, upon receiving an HTTP/1.1 (or later) request-line and |
---|
1951 | a complete header section that contains a 100-continue expectation |
---|
1952 | and indicates a request message body will follow, either send an |
---|
1953 | immediate response with a final status code, if that status can be |
---|
1954 | determined by examining just the request-line and header fields, or |
---|
1955 | begin forwarding the request toward the origin server by sending a |
---|
1956 | |
---|
1957 | |
---|
1958 | |
---|
1959 | Fielding & Reschke Expires November 7, 2014 [Page 35] |
---|
1960 | |
---|
1961 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
1962 | |
---|
1963 | |
---|
1964 | corresponding request-line and header section to the next inbound |
---|
1965 | server. If the proxy believes (from configuration or past |
---|
1966 | interaction) that the next inbound server only supports HTTP/1.0, the |
---|
1967 | proxy MAY generate an immediate 100 (Continue) response to encourage |
---|
1968 | the client to begin sending the message body. |
---|
1969 | |
---|
1970 | Note: The Expect header field was added after the original |
---|
1971 | publication of HTTP/1.1 [RFC2068] as both the means to request an |
---|
1972 | interim 100 response and the general mechanism for indicating |
---|
1973 | must-understand extensions. However, the extension mechanism has |
---|
1974 | not been used by clients and the must-understand requirements have |
---|
1975 | not been implemented by many servers, rendering the extension |
---|
1976 | mechanism useless. This specification has removed the extension |
---|
1977 | mechanism in order to simplify the definition and processing of |
---|
1978 | 100-continue. |
---|
1979 | |
---|
1980 | 5.1.2. Max-Forwards |
---|
1981 | |
---|
1982 | The "Max-Forwards" header field provides a mechanism with the TRACE |
---|
1983 | (Section 4.3.8) and OPTIONS (Section 4.3.7) request methods to limit |
---|
1984 | the number of times that the request is forwarded by proxies. This |
---|
1985 | can be useful when the client is attempting to trace a request that |
---|
1986 | appears to be failing or looping mid-chain. |
---|
1987 | |
---|
1988 | Max-Forwards = 1*DIGIT |
---|
1989 | |
---|
1990 | The Max-Forwards value is a decimal integer indicating the remaining |
---|
1991 | number of times this request message can be forwarded. |
---|
1992 | |
---|
1993 | Each intermediary that receives a TRACE or OPTIONS request containing |
---|
1994 | a Max-Forwards header field MUST check and update its value prior to |
---|
1995 | forwarding the request. If the received value is zero (0), the |
---|
1996 | intermediary MUST NOT forward the request; instead, the intermediary |
---|
1997 | MUST respond as the final recipient. If the received Max-Forwards |
---|
1998 | value is greater than zero, the intermediary MUST generate an updated |
---|
1999 | Max-Forwards field in the forwarded message with a field-value that |
---|
2000 | is the lesser of: a) the received value decremented by one (1), or b) |
---|
2001 | the recipient's maximum supported value for Max-Forwards. |
---|
2002 | |
---|
2003 | A recipient MAY ignore a Max-Forwards header field received with any |
---|
2004 | other request methods. |
---|
2005 | |
---|
2006 | 5.2. Conditionals |
---|
2007 | |
---|
2008 | The HTTP conditional request header fields [RFC7232] allow a client |
---|
2009 | to place a precondition on the state of the target resource, so that |
---|
2010 | the action corresponding to the method semantics will not be applied |
---|
2011 | if the precondition evaluates to false. Each precondition defined by |
---|
2012 | |
---|
2013 | |
---|
2014 | |
---|
2015 | Fielding & Reschke Expires November 7, 2014 [Page 36] |
---|
2016 | |
---|
2017 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
2018 | |
---|
2019 | |
---|
2020 | this specification consists of a comparison between a set of |
---|
2021 | validators obtained from prior representations of the target resource |
---|
2022 | to the current state of validators for the selected representation |
---|
2023 | (Section 7.2). Hence, these preconditions evaluate whether the state |
---|
2024 | of the target resource has changed since a given state known by the |
---|
2025 | client. The effect of such an evaluation depends on the method |
---|
2026 | semantics and choice of conditional, as defined in Section 5 of |
---|
2027 | [RFC7232]. |
---|
2028 | |
---|
2029 | +---------------------+--------------------------+ |
---|
2030 | | Header Field Name | Defined in... | |
---|
2031 | +---------------------+--------------------------+ |
---|
2032 | | If-Match | Section 3.1 of [RFC7232] | |
---|
2033 | | If-None-Match | Section 3.2 of [RFC7232] | |
---|
2034 | | If-Modified-Since | Section 3.3 of [RFC7232] | |
---|
2035 | | If-Unmodified-Since | Section 3.4 of [RFC7232] | |
---|
2036 | | If-Range | Section 3.2 of [RFC7233] | |
---|
2037 | +---------------------+--------------------------+ |
---|
2038 | |
---|
2039 | 5.3. Content Negotiation |
---|
2040 | |
---|
2041 | The following request header fields are sent by a user agent to |
---|
2042 | engage in proactive negotiation of the response content, as defined |
---|
2043 | in Section 3.4.1. The preferences sent in these fields apply to any |
---|
2044 | content in the response, including representations of the target |
---|
2045 | resource, representations of error or processing status, and |
---|
2046 | potentially even the miscellaneous text strings that might appear |
---|
2047 | within the protocol. |
---|
2048 | |
---|
2049 | +-------------------+---------------+ |
---|
2050 | | Header Field Name | Defined in... | |
---|
2051 | +-------------------+---------------+ |
---|
2052 | | Accept | Section 5.3.2 | |
---|
2053 | | Accept-Charset | Section 5.3.3 | |
---|
2054 | | Accept-Encoding | Section 5.3.4 | |
---|
2055 | | Accept-Language | Section 5.3.5 | |
---|
2056 | +-------------------+---------------+ |
---|
2057 | |
---|
2058 | 5.3.1. Quality Values |
---|
2059 | |
---|
2060 | Many of the request header fields for proactive negotiation use a |
---|
2061 | common parameter, named "q" (case-insensitive), to assign a relative |
---|
2062 | "weight" to the preference for that associated kind of content. This |
---|
2063 | weight is referred to as a "quality value" (or "qvalue") because the |
---|
2064 | same parameter name is often used within server configurations to |
---|
2065 | assign a weight to the relative quality of the various |
---|
2066 | representations that can be selected for a resource. |
---|
2067 | |
---|
2068 | |
---|
2069 | |
---|
2070 | |
---|
2071 | Fielding & Reschke Expires November 7, 2014 [Page 37] |
---|
2072 | |
---|
2073 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
2074 | |
---|
2075 | |
---|
2076 | The weight is normalized to a real number in the range 0 through 1, |
---|
2077 | where 0.001 is the least preferred and 1 is the most preferred; a |
---|
2078 | value of 0 means "not acceptable". If no "q" parameter is present, |
---|
2079 | the default weight is 1. |
---|
2080 | |
---|
2081 | weight = OWS ";" OWS "q=" qvalue |
---|
2082 | qvalue = ( "0" [ "." 0*3DIGIT ] ) |
---|
2083 | / ( "1" [ "." 0*3("0") ] ) |
---|
2084 | |
---|
2085 | A sender of qvalue MUST NOT generate more than three digits after the |
---|
2086 | decimal point. User configuration of these values ought to be |
---|
2087 | limited in the same fashion. |
---|
2088 | |
---|
2089 | 5.3.2. Accept |
---|
2090 | |
---|
2091 | The "Accept" header field can be used by user agents to specify |
---|
2092 | response media types that are acceptable. Accept header fields can |
---|
2093 | be used to indicate that the request is specifically limited to a |
---|
2094 | small set of desired types, as in the case of a request for an in- |
---|
2095 | line image. |
---|
2096 | |
---|
2097 | Accept = #( media-range [ accept-params ] ) |
---|
2098 | |
---|
2099 | media-range = ( "*/*" |
---|
2100 | / ( type "/" "*" ) |
---|
2101 | / ( type "/" subtype ) |
---|
2102 | ) *( OWS ";" OWS parameter ) |
---|
2103 | accept-params = weight *( accept-ext ) |
---|
2104 | accept-ext = OWS ";" OWS token [ "=" ( token / quoted-string ) ] |
---|
2105 | |
---|
2106 | The asterisk "*" character is used to group media types into ranges, |
---|
2107 | with "*/*" indicating all media types and "type/*" indicating all |
---|
2108 | subtypes of that type. The media-range can include media type |
---|
2109 | parameters that are applicable to that range. |
---|
2110 | |
---|
2111 | Each media-range might be followed by zero or more applicable media |
---|
2112 | type parameters (e.g., charset), an optional "q" parameter for |
---|
2113 | indicating a relative weight (Section 5.3.1), and then zero or more |
---|
2114 | extension parameters. The "q" parameter is necessary if any |
---|
2115 | extensions (accept-ext) are present, since it acts as a separator |
---|
2116 | between the two parameter sets. |
---|
2117 | |
---|
2118 | Note: Use of the "q" parameter name to separate media type |
---|
2119 | parameters from Accept extension parameters is due to historical |
---|
2120 | practice. Although this prevents any media type parameter named |
---|
2121 | "q" from being used with a media range, such an event is believed |
---|
2122 | to be unlikely given the lack of any "q" parameters in the IANA |
---|
2123 | media type registry and the rare usage of any media type |
---|
2124 | |
---|
2125 | |
---|
2126 | |
---|
2127 | Fielding & Reschke Expires November 7, 2014 [Page 38] |
---|
2128 | |
---|
2129 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
2130 | |
---|
2131 | |
---|
2132 | parameters in Accept. Future media types are discouraged from |
---|
2133 | registering any parameter named "q". |
---|
2134 | |
---|
2135 | The example |
---|
2136 | |
---|
2137 | Accept: audio/*; q=0.2, audio/basic |
---|
2138 | |
---|
2139 | is interpreted as "I prefer audio/basic, but send me any audio type |
---|
2140 | if it is the best available after an 80% mark-down in quality". |
---|
2141 | |
---|
2142 | A request without any Accept header field implies that the user agent |
---|
2143 | will accept any media type in response. If the header field is |
---|
2144 | present in a request and none of the available representations for |
---|
2145 | the response have a media type that is listed as acceptable, the |
---|
2146 | origin server can either honor the header field by sending a 406 (Not |
---|
2147 | Acceptable) response or disregard the header field by treating the |
---|
2148 | response as if it is not subject to content negotiation. |
---|
2149 | |
---|
2150 | A more elaborate example is |
---|
2151 | |
---|
2152 | Accept: text/plain; q=0.5, text/html, |
---|
2153 | text/x-dvi; q=0.8, text/x-c |
---|
2154 | |
---|
2155 | Verbally, this would be interpreted as "text/html and text/x-c are |
---|
2156 | the equally preferred media types, but if they do not exist, then |
---|
2157 | send the text/x-dvi representation, and if that does not exist, send |
---|
2158 | the text/plain representation". |
---|
2159 | |
---|
2160 | Media ranges can be overridden by more specific media ranges or |
---|
2161 | specific media types. If more than one media range applies to a |
---|
2162 | given type, the most specific reference has precedence. For example, |
---|
2163 | |
---|
2164 | Accept: text/*, text/plain, text/plain;format=flowed, */* |
---|
2165 | |
---|
2166 | have the following precedence: |
---|
2167 | |
---|
2168 | 1. text/plain;format=flowed |
---|
2169 | |
---|
2170 | 2. text/plain |
---|
2171 | |
---|
2172 | 3. text/* |
---|
2173 | |
---|
2174 | 4. */* |
---|
2175 | |
---|
2176 | The media type quality factor associated with a given type is |
---|
2177 | determined by finding the media range with the highest precedence |
---|
2178 | that matches the type. For example, |
---|
2179 | |
---|
2180 | |
---|
2181 | |
---|
2182 | |
---|
2183 | Fielding & Reschke Expires November 7, 2014 [Page 39] |
---|
2184 | |
---|
2185 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
2186 | |
---|
2187 | |
---|
2188 | Accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1, |
---|
2189 | text/html;level=2;q=0.4, */*;q=0.5 |
---|
2190 | |
---|
2191 | would cause the following values to be associated: |
---|
2192 | |
---|
2193 | +-------------------+---------------+ |
---|
2194 | | Media Type | Quality Value | |
---|
2195 | +-------------------+---------------+ |
---|
2196 | | text/html;level=1 | 1 | |
---|
2197 | | text/html | 0.7 | |
---|
2198 | | text/plain | 0.3 | |
---|
2199 | | image/jpeg | 0.5 | |
---|
2200 | | text/html;level=2 | 0.4 | |
---|
2201 | | text/html;level=3 | 0.7 | |
---|
2202 | +-------------------+---------------+ |
---|
2203 | |
---|
2204 | Note: A user agent might be provided with a default set of quality |
---|
2205 | values for certain media ranges. However, unless the user agent is a |
---|
2206 | closed system that cannot interact with other rendering agents, this |
---|
2207 | default set ought to be configurable by the user. |
---|
2208 | |
---|
2209 | 5.3.3. Accept-Charset |
---|
2210 | |
---|
2211 | The "Accept-Charset" header field can be sent by a user agent to |
---|
2212 | indicate what charsets are acceptable in textual response content. |
---|
2213 | This field allows user agents capable of understanding more |
---|
2214 | comprehensive or special-purpose charsets to signal that capability |
---|
2215 | to an origin server that is capable of representing information in |
---|
2216 | those charsets. |
---|
2217 | |
---|
2218 | Accept-Charset = 1#( ( charset / "*" ) [ weight ] ) |
---|
2219 | |
---|
2220 | Charset names are defined in Section 3.1.1.2. A user agent MAY |
---|
2221 | associate a quality value with each charset to indicate the user's |
---|
2222 | relative preference for that charset, as defined in Section 5.3.1. |
---|
2223 | An example is |
---|
2224 | |
---|
2225 | Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 |
---|
2226 | |
---|
2227 | The special value "*", if present in the Accept-Charset field, |
---|
2228 | matches every charset that is not mentioned elsewhere in the Accept- |
---|
2229 | Charset field. If no "*" is present in an Accept-Charset field, then |
---|
2230 | any charsets not explicitly mentioned in the field are considered |
---|
2231 | "not acceptable" to the client. |
---|
2232 | |
---|
2233 | A request without any Accept-Charset header field implies that the |
---|
2234 | user agent will accept any charset in response. Most general-purpose |
---|
2235 | user agents do not send Accept-Charset, unless specifically |
---|
2236 | |
---|
2237 | |
---|
2238 | |
---|
2239 | Fielding & Reschke Expires November 7, 2014 [Page 40] |
---|
2240 | |
---|
2241 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
2242 | |
---|
2243 | |
---|
2244 | configured to do so, because a detailed list of supported charsets |
---|
2245 | makes it easier for a server to identify an individual by virtue of |
---|
2246 | the user agent's request characteristics (Section 9.7). |
---|
2247 | |
---|
2248 | If an Accept-Charset header field is present in a request and none of |
---|
2249 | the available representations for the response has a charset that is |
---|
2250 | listed as acceptable, the origin server can either honor the header |
---|
2251 | field, by sending a 406 (Not Acceptable) response, or disregard the |
---|
2252 | header field by treating the resource as if it is not subject to |
---|
2253 | content negotiation. |
---|
2254 | |
---|
2255 | 5.3.4. Accept-Encoding |
---|
2256 | |
---|
2257 | The "Accept-Encoding" header field can be used by user agents to |
---|
2258 | indicate what response content-codings (Section 3.1.2.1) are |
---|
2259 | acceptable in the response. An "identity" token is used as a synonym |
---|
2260 | for "no encoding" in order to communicate when no encoding is |
---|
2261 | preferred. |
---|
2262 | |
---|
2263 | Accept-Encoding = #( codings [ weight ] ) |
---|
2264 | codings = content-coding / "identity" / "*" |
---|
2265 | |
---|
2266 | Each codings value MAY be given an associated quality value |
---|
2267 | representing the preference for that encoding, as defined in |
---|
2268 | Section 5.3.1. The asterisk "*" symbol in an Accept-Encoding field |
---|
2269 | matches any available content-coding not explicitly listed in the |
---|
2270 | header field. |
---|
2271 | |
---|
2272 | For example, |
---|
2273 | |
---|
2274 | Accept-Encoding: compress, gzip |
---|
2275 | Accept-Encoding: |
---|
2276 | Accept-Encoding: * |
---|
2277 | Accept-Encoding: compress;q=0.5, gzip;q=1.0 |
---|
2278 | Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0 |
---|
2279 | |
---|
2280 | A request without an Accept-Encoding header field implies that the |
---|
2281 | user agent has no preferences regarding content-codings. Although |
---|
2282 | this allows the server to use any content-coding in a response, it |
---|
2283 | does not imply that the user agent will be able to correctly process |
---|
2284 | all encodings. |
---|
2285 | |
---|
2286 | A server tests whether a content-coding for a given representation is |
---|
2287 | acceptable using these rules: |
---|
2288 | |
---|
2289 | 1. If no Accept-Encoding field is in the request, any content-coding |
---|
2290 | is considered acceptable by the user agent. |
---|
2291 | |
---|
2292 | |
---|
2293 | |
---|
2294 | |
---|
2295 | Fielding & Reschke Expires November 7, 2014 [Page 41] |
---|
2296 | |
---|
2297 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
2298 | |
---|
2299 | |
---|
2300 | 2. If the representation has no content-coding, then it is |
---|
2301 | acceptable by default unless specifically excluded by the Accept- |
---|
2302 | Encoding field stating either "identity;q=0" or "*;q=0" without a |
---|
2303 | more specific entry for "identity". |
---|
2304 | |
---|
2305 | 3. If the representation's content-coding is one of the content- |
---|
2306 | codings listed in the Accept-Encoding field, then it is |
---|
2307 | acceptable unless it is accompanied by a qvalue of 0. (As |
---|
2308 | defined in Section 5.3.1, a qvalue of 0 means "not acceptable".) |
---|
2309 | |
---|
2310 | 4. If multiple content-codings are acceptable, then the acceptable |
---|
2311 | content-coding with the highest non-zero qvalue is preferred. |
---|
2312 | |
---|
2313 | An Accept-Encoding header field with a combined field-value that is |
---|
2314 | empty implies that the user agent does not want any content-coding in |
---|
2315 | response. If an Accept-Encoding header field is present in a request |
---|
2316 | and none of the available representations for the response have a |
---|
2317 | content-coding that is listed as acceptable, the origin server SHOULD |
---|
2318 | send a response without any content-coding. |
---|
2319 | |
---|
2320 | Note: Most HTTP/1.0 applications do not recognize or obey qvalues |
---|
2321 | associated with content-codings. This means that qvalues might |
---|
2322 | not work and are not permitted with x-gzip or x-compress. |
---|
2323 | |
---|
2324 | 5.3.5. Accept-Language |
---|
2325 | |
---|
2326 | The "Accept-Language" header field can be used by user agents to |
---|
2327 | indicate the set of natural languages that are preferred in the |
---|
2328 | response. Language tags are defined in Section 3.1.3.1. |
---|
2329 | |
---|
2330 | Accept-Language = 1#( language-range [ weight ] ) |
---|
2331 | language-range = |
---|
2332 | <language-range, defined in [RFC4647], Section 2.1> |
---|
2333 | |
---|
2334 | Each language-range can be given an associated quality value |
---|
2335 | representing an estimate of the user's preference for the languages |
---|
2336 | specified by that range, as defined in Section 5.3.1. For example, |
---|
2337 | |
---|
2338 | Accept-Language: da, en-gb;q=0.8, en;q=0.7 |
---|
2339 | |
---|
2340 | would mean: "I prefer Danish, but will accept British English and |
---|
2341 | other types of English". |
---|
2342 | |
---|
2343 | A request without any Accept-Language header field implies that the |
---|
2344 | user agent will accept any language in response. If the header field |
---|
2345 | is present in a request and none of the available representations for |
---|
2346 | the response have a matching language tag, the origin server can |
---|
2347 | either disregard the header field by treating the response as if it |
---|
2348 | |
---|
2349 | |
---|
2350 | |
---|
2351 | Fielding & Reschke Expires November 7, 2014 [Page 42] |
---|
2352 | |
---|
2353 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
2354 | |
---|
2355 | |
---|
2356 | is not subject to content negotiation, or honor the header field by |
---|
2357 | sending a 406 (Not Acceptable) response. However, the latter is not |
---|
2358 | encouraged, as doing so can prevent users from accessing content that |
---|
2359 | they might be able to use (with translation software, for example). |
---|
2360 | |
---|
2361 | Note that some recipients treat the order in which language tags are |
---|
2362 | listed as an indication of descending priority, particularly for tags |
---|
2363 | that are assigned equal quality values (no value is the same as q=1). |
---|
2364 | However, this behavior cannot be relied upon. For consistency and to |
---|
2365 | maximize interoperability, many user agents assign each language tag |
---|
2366 | a unique quality value while also listing them in order of decreasing |
---|
2367 | quality. Additional discussion of language priority lists can be |
---|
2368 | found in Section 2.3 of [RFC4647]. |
---|
2369 | |
---|
2370 | For matching, Section 3 of [RFC4647] defines several matching |
---|
2371 | schemes. Implementations can offer the most appropriate matching |
---|
2372 | scheme for their requirements. The "Basic Filtering" scheme |
---|
2373 | ([RFC4647], Section 3.3.1) is identical to the matching scheme that |
---|
2374 | was previously defined for HTTP in Section 14.4 of [RFC2616]. |
---|
2375 | |
---|
2376 | It might be contrary to the privacy expectations of the user to send |
---|
2377 | an Accept-Language header field with the complete linguistic |
---|
2378 | preferences of the user in every request (Section 9.7). |
---|
2379 | |
---|
2380 | Since intelligibility is highly dependent on the individual user, |
---|
2381 | user agents need to allow user control over the linguistic preference |
---|
2382 | (either through configuration of the user agent itself, or by |
---|
2383 | defaulting to a user controllable system setting). A user agent that |
---|
2384 | does not provide such control to the user MUST NOT send an Accept- |
---|
2385 | Language header field. |
---|
2386 | |
---|
2387 | Note: User agents ought to provide guidance to users when setting |
---|
2388 | a preference, since users are rarely familiar with the details of |
---|
2389 | language matching as described above. For example, users might |
---|
2390 | assume that on selecting "en-gb", they will be served any kind of |
---|
2391 | English document if British English is not available. A user |
---|
2392 | agent might suggest, in such a case, to add "en" to the list for |
---|
2393 | better matching behavior. |
---|
2394 | |
---|
2395 | 5.4. Authentication Credentials |
---|
2396 | |
---|
2397 | Two header fields are used for carrying authentication credentials, |
---|
2398 | as defined in [RFC7235]. Note that various custom mechanisms for |
---|
2399 | user authentication use the Cookie header field for this purpose, as |
---|
2400 | defined in [RFC6265]. |
---|
2401 | |
---|
2402 | |
---|
2403 | |
---|
2404 | |
---|
2405 | |
---|
2406 | |
---|
2407 | Fielding & Reschke Expires November 7, 2014 [Page 43] |
---|
2408 | |
---|
2409 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
2410 | |
---|
2411 | |
---|
2412 | +---------------------+--------------------------+ |
---|
2413 | | Header Field Name | Defined in... | |
---|
2414 | +---------------------+--------------------------+ |
---|
2415 | | Authorization | Section 4.2 of [RFC7235] | |
---|
2416 | | Proxy-Authorization | Section 4.4 of [RFC7235] | |
---|
2417 | +---------------------+--------------------------+ |
---|
2418 | |
---|
2419 | 5.5. Request Context |
---|
2420 | |
---|
2421 | The following request header fields provide additional information |
---|
2422 | about the request context, including information about the user, user |
---|
2423 | agent, and resource behind the request. |
---|
2424 | |
---|
2425 | +-------------------+---------------+ |
---|
2426 | | Header Field Name | Defined in... | |
---|
2427 | +-------------------+---------------+ |
---|
2428 | | From | Section 5.5.1 | |
---|
2429 | | Referer | Section 5.5.2 | |
---|
2430 | | User-Agent | Section 5.5.3 | |
---|
2431 | +-------------------+---------------+ |
---|
2432 | |
---|
2433 | 5.5.1. From |
---|
2434 | |
---|
2435 | The "From" header field contains an Internet email address for a |
---|
2436 | human user who controls the requesting user agent. The address ought |
---|
2437 | to be machine-usable, as defined by "mailbox" in Section 3.4 of |
---|
2438 | [RFC5322]: |
---|
2439 | |
---|
2440 | From = mailbox |
---|
2441 | |
---|
2442 | mailbox = <mailbox, defined in [RFC5322], Section 3.4> |
---|
2443 | |
---|
2444 | An example is: |
---|
2445 | |
---|
2446 | From: webmaster@example.org |
---|
2447 | |
---|
2448 | The From header field is rarely sent by non-robotic user agents. A |
---|
2449 | user agent SHOULD NOT send a From header field without explicit |
---|
2450 | configuration by the user, since that might conflict with the user's |
---|
2451 | privacy interests or their site's security policy. |
---|
2452 | |
---|
2453 | A robotic user agent SHOULD send a valid From header field so that |
---|
2454 | the person responsible for running the robot can be contacted if |
---|
2455 | problems occur on servers, such as if the robot is sending excessive, |
---|
2456 | unwanted, or invalid requests. |
---|
2457 | |
---|
2458 | A server SHOULD NOT use the From header field for access control or |
---|
2459 | authentication, since most recipients will assume that the field |
---|
2460 | |
---|
2461 | |
---|
2462 | |
---|
2463 | Fielding & Reschke Expires November 7, 2014 [Page 44] |
---|
2464 | |
---|
2465 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
2466 | |
---|
2467 | |
---|
2468 | value is public information. |
---|
2469 | |
---|
2470 | 5.5.2. Referer |
---|
2471 | |
---|
2472 | The "Referer" [sic] header field allows the user agent to specify a |
---|
2473 | URI reference for the resource from which the target URI was obtained |
---|
2474 | (i.e., the "referrer", though the field name is misspelled). A user |
---|
2475 | agent MUST NOT include the fragment and userinfo components of the |
---|
2476 | URI reference [RFC3986], if any, when generating the Referer field |
---|
2477 | value. |
---|
2478 | |
---|
2479 | Referer = absolute-URI / partial-URI |
---|
2480 | |
---|
2481 | The Referer header field allows servers to generate back-links to |
---|
2482 | other resources for simple analytics, logging, optimized caching, |
---|
2483 | etc. It also allows obsolete or mistyped links to be found for |
---|
2484 | maintenance. Some servers use the Referer header field as a means of |
---|
2485 | denying links from other sites (so-called "deep linking") or |
---|
2486 | restricting cross-site request forgery (CSRF), but not all requests |
---|
2487 | contain it. |
---|
2488 | |
---|
2489 | Example: |
---|
2490 | |
---|
2491 | Referer: http://www.example.org/hypertext/Overview.html |
---|
2492 | |
---|
2493 | If the target URI was obtained from a source that does not have its |
---|
2494 | own URI (e.g., input from the user keyboard, or an entry within the |
---|
2495 | user's bookmarks/favorites), the user agent MUST either exclude |
---|
2496 | Referer or send it with a value of "about:blank". |
---|
2497 | |
---|
2498 | The Referer field has the potential to reveal information about the |
---|
2499 | request context or browsing history of the user, which is a privacy |
---|
2500 | concern if the referring resource's identifier reveals personal |
---|
2501 | information (such as an account name) or a resource that is supposed |
---|
2502 | to be confidential (such as behind a firewall or internal to a |
---|
2503 | secured service). Most general-purpose user agents do not send the |
---|
2504 | Referer header field when the referring resource is a local "file" or |
---|
2505 | "data" URI. A user agent MUST NOT send a Referer header field in an |
---|
2506 | unsecured HTTP request if the referring page was received with a |
---|
2507 | secure protocol. See Section 9.4 for additional security |
---|
2508 | considerations. |
---|
2509 | |
---|
2510 | Some intermediaries have been known to indiscriminately remove |
---|
2511 | Referer header fields from outgoing requests. This has the |
---|
2512 | unfortunate side-effect of interfering with protection against CSRF |
---|
2513 | attacks, which can be far more harmful to their users. |
---|
2514 | Intermediaries and user agent extensions that wish to limit |
---|
2515 | information disclosure in Referer ought to restrict their changes to |
---|
2516 | |
---|
2517 | |
---|
2518 | |
---|
2519 | Fielding & Reschke Expires November 7, 2014 [Page 45] |
---|
2520 | |
---|
2521 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
2522 | |
---|
2523 | |
---|
2524 | specific edits, such as replacing internal domain names with |
---|
2525 | pseudonyms or truncating the query and/or path components. An |
---|
2526 | intermediary SHOULD NOT modify or delete the Referer header field |
---|
2527 | when the field value shares the same scheme and host as the request |
---|
2528 | target. |
---|
2529 | |
---|
2530 | 5.5.3. User-Agent |
---|
2531 | |
---|
2532 | The "User-Agent" header field contains information about the user |
---|
2533 | agent originating the request, which is often used by servers to help |
---|
2534 | identify the scope of reported interoperability problems, to work |
---|
2535 | around or tailor responses to avoid particular user agent |
---|
2536 | limitations, and for analytics regarding browser or operating system |
---|
2537 | use. A user agent SHOULD send a User-Agent field in each request |
---|
2538 | unless specifically configured not to do so. |
---|
2539 | |
---|
2540 | User-Agent = product *( RWS ( product / comment ) ) |
---|
2541 | |
---|
2542 | The User-Agent field-value consists of one or more product |
---|
2543 | identifiers, each followed by zero or more comments (Section 3.2 of |
---|
2544 | [RFC7230]), which together identify the user agent software and its |
---|
2545 | significant subproducts. By convention, the product identifiers are |
---|
2546 | listed in decreasing order of their significance for identifying the |
---|
2547 | user agent software. Each product identifier consists of a name and |
---|
2548 | optional version. |
---|
2549 | |
---|
2550 | product = token ["/" product-version] |
---|
2551 | product-version = token |
---|
2552 | |
---|
2553 | A sender SHOULD limit generated product identifiers to what is |
---|
2554 | necessary to identify the product; a sender MUST NOT generate |
---|
2555 | advertising or other non-essential information within the product |
---|
2556 | identifier. A sender SHOULD NOT generate information in product- |
---|
2557 | version that is not a version identifier (i.e., successive versions |
---|
2558 | of the same product name ought to only differ in the product-version |
---|
2559 | portion of the product identifier). |
---|
2560 | |
---|
2561 | Example: |
---|
2562 | |
---|
2563 | User-Agent: CERN-LineMode/2.15 libwww/2.17b3 |
---|
2564 | |
---|
2565 | A user agent SHOULD NOT generate a User-Agent field containing |
---|
2566 | needlessly fine-grained detail and SHOULD limit the addition of |
---|
2567 | subproducts by third parties. Overly long and detailed User-Agent |
---|
2568 | field values increase request latency and the risk of a user being |
---|
2569 | identified against their wishes ("fingerprinting"). |
---|
2570 | |
---|
2571 | Likewise, implementations are encouraged not to use the product |
---|
2572 | |
---|
2573 | |
---|
2574 | |
---|
2575 | Fielding & Reschke Expires November 7, 2014 [Page 46] |
---|
2576 | |
---|
2577 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
2578 | |
---|
2579 | |
---|
2580 | tokens of other implementations in order to declare compatibility |
---|
2581 | with them, as this circumvents the purpose of the field. If a user |
---|
2582 | agent masquerades as a different user agent, recipients can assume |
---|
2583 | that the user intentionally desires to see responses tailored for |
---|
2584 | that identified user agent, even if they might not work as well for |
---|
2585 | the actual user agent being used. |
---|
2586 | |
---|
2587 | 6. Response Status Codes |
---|
2588 | |
---|
2589 | The status-code element is a 3-digit integer code giving the result |
---|
2590 | of the attempt to understand and satisfy the request. |
---|
2591 | |
---|
2592 | HTTP status codes are extensible. HTTP clients are not required to |
---|
2593 | understand the meaning of all registered status codes, though such |
---|
2594 | understanding is obviously desirable. However, a client MUST |
---|
2595 | understand the class of any status code, as indicated by the first |
---|
2596 | digit, and treat an unrecognized status code as being equivalent to |
---|
2597 | the x00 status code of that class, with the exception that a |
---|
2598 | recipient MUST NOT cache a response with an unrecognized status code. |
---|
2599 | |
---|
2600 | For example, if an unrecognized status code of 471 is received by a |
---|
2601 | client, the client can assume that there was something wrong with its |
---|
2602 | request and treat the response as if it had received a 400 status |
---|
2603 | code. The response message will usually contain a representation |
---|
2604 | that explains the status. |
---|
2605 | |
---|
2606 | The first digit of the status-code defines the class of response. |
---|
2607 | The last two digits do not have any categorization role. There are 5 |
---|
2608 | values for the first digit: |
---|
2609 | |
---|
2610 | o 1xx (Informational): The request was received, continuing process |
---|
2611 | |
---|
2612 | o 2xx (Successful): The request was successfully received, |
---|
2613 | understood, and accepted |
---|
2614 | |
---|
2615 | o 3xx (Redirection): Further action needs to be taken in order to |
---|
2616 | complete the request |
---|
2617 | |
---|
2618 | o 4xx (Client Error): The request contains bad syntax or cannot be |
---|
2619 | fulfilled |
---|
2620 | |
---|
2621 | o 5xx (Server Error): The server failed to fulfill an apparently |
---|
2622 | valid request |
---|
2623 | |
---|
2624 | |
---|
2625 | |
---|
2626 | |
---|
2627 | |
---|
2628 | |
---|
2629 | |
---|
2630 | |
---|
2631 | Fielding & Reschke Expires November 7, 2014 [Page 47] |
---|
2632 | |
---|
2633 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
2634 | |
---|
2635 | |
---|
2636 | 6.1. Overview of Status Codes |
---|
2637 | |
---|
2638 | The status codes listed below are defined in this specification, |
---|
2639 | Section 4 of [RFC7232], Section 4 of [RFC7233], and Section 3 of |
---|
2640 | [RFC7235]. The reason phrases listed here are only recommendations |
---|
2641 | -- they can be replaced by local equivalents without affecting the |
---|
2642 | protocol. |
---|
2643 | |
---|
2644 | Responses with status codes that are defined as cacheable by default |
---|
2645 | (e.g., 200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501 in this |
---|
2646 | specification) can be reused by a cache with heuristic expiration |
---|
2647 | unless otherwise indicated by the method definition or explicit cache |
---|
2648 | controls [RFC7234]; all other status codes are not cacheable by |
---|
2649 | default. |
---|
2650 | |
---|
2651 | |
---|
2652 | |
---|
2653 | |
---|
2654 | |
---|
2655 | |
---|
2656 | |
---|
2657 | |
---|
2658 | |
---|
2659 | |
---|
2660 | |
---|
2661 | |
---|
2662 | |
---|
2663 | |
---|
2664 | |
---|
2665 | |
---|
2666 | |
---|
2667 | |
---|
2668 | |
---|
2669 | |
---|
2670 | |
---|
2671 | |
---|
2672 | |
---|
2673 | |
---|
2674 | |
---|
2675 | |
---|
2676 | |
---|
2677 | |
---|
2678 | |
---|
2679 | |
---|
2680 | |
---|
2681 | |
---|
2682 | |
---|
2683 | |
---|
2684 | |
---|
2685 | |
---|
2686 | |
---|
2687 | Fielding & Reschke Expires November 7, 2014 [Page 48] |
---|
2688 | |
---|
2689 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
2690 | |
---|
2691 | |
---|
2692 | +------+-------------------------------+--------------------------+ |
---|
2693 | | code | reason-phrase | Defined in... | |
---|
2694 | +------+-------------------------------+--------------------------+ |
---|
2695 | | 100 | Continue | Section 6.2.1 | |
---|
2696 | | 101 | Switching Protocols | Section 6.2.2 | |
---|
2697 | | 200 | OK | Section 6.3.1 | |
---|
2698 | | 201 | Created | Section 6.3.2 | |
---|
2699 | | 202 | Accepted | Section 6.3.3 | |
---|
2700 | | 203 | Non-Authoritative Information | Section 6.3.4 | |
---|
2701 | | 204 | No Content | Section 6.3.5 | |
---|
2702 | | 205 | Reset Content | Section 6.3.6 | |
---|
2703 | | 206 | Partial Content | Section 4.1 of [RFC7233] | |
---|
2704 | | 300 | Multiple Choices | Section 6.4.1 | |
---|
2705 | | 301 | Moved Permanently | Section 6.4.2 | |
---|
2706 | | 302 | Found | Section 6.4.3 | |
---|
2707 | | 303 | See Other | Section 6.4.4 | |
---|
2708 | | 304 | Not Modified | Section 4.1 of [RFC7232] | |
---|
2709 | | 305 | Use Proxy | Section 6.4.5 | |
---|
2710 | | 307 | Temporary Redirect | Section 6.4.7 | |
---|
2711 | | 400 | Bad Request | Section 6.5.1 | |
---|
2712 | | 401 | Unauthorized | Section 3.1 of [RFC7235] | |
---|
2713 | | 402 | Payment Required | Section 6.5.2 | |
---|
2714 | | 403 | Forbidden | Section 6.5.3 | |
---|
2715 | | 404 | Not Found | Section 6.5.4 | |
---|
2716 | | 405 | Method Not Allowed | Section 6.5.5 | |
---|
2717 | | 406 | Not Acceptable | Section 6.5.6 | |
---|
2718 | | 407 | Proxy Authentication Required | Section 3.2 of [RFC7235] | |
---|
2719 | | 408 | Request Time-out | Section 6.5.7 | |
---|
2720 | | 409 | Conflict | Section 6.5.8 | |
---|
2721 | | 410 | Gone | Section 6.5.9 | |
---|
2722 | | 411 | Length Required | Section 6.5.10 | |
---|
2723 | | 412 | Precondition Failed | Section 4.2 of [RFC7232] | |
---|
2724 | | 413 | Payload Too Large | Section 6.5.11 | |
---|
2725 | | 414 | URI Too Long | Section 6.5.12 | |
---|
2726 | | 415 | Unsupported Media Type | Section 6.5.13 | |
---|
2727 | | 416 | Range Not Satisfiable | Section 4.4 of [RFC7233] | |
---|
2728 | | 417 | Expectation Failed | Section 6.5.14 | |
---|
2729 | | 426 | Upgrade Required | Section 6.5.15 | |
---|
2730 | | 500 | Internal Server Error | Section 6.6.1 | |
---|
2731 | | 501 | Not Implemented | Section 6.6.2 | |
---|
2732 | | 502 | Bad Gateway | Section 6.6.3 | |
---|
2733 | | 503 | Service Unavailable | Section 6.6.4 | |
---|
2734 | | 504 | Gateway Time-out | Section 6.6.5 | |
---|
2735 | | 505 | HTTP Version Not Supported | Section 6.6.6 | |
---|
2736 | +------+-------------------------------+--------------------------+ |
---|
2737 | |
---|
2738 | Note that this list is not exhaustive -- it does not include |
---|
2739 | extension status codes defined in other specifications. The complete |
---|
2740 | |
---|
2741 | |
---|
2742 | |
---|
2743 | Fielding & Reschke Expires November 7, 2014 [Page 49] |
---|
2744 | |
---|
2745 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
2746 | |
---|
2747 | |
---|
2748 | list of status codes is maintained by IANA. See Section 8.2 for |
---|
2749 | details. |
---|
2750 | |
---|
2751 | 6.2. Informational 1xx |
---|
2752 | |
---|
2753 | The 1xx (Informational) class of status code indicates an interim |
---|
2754 | response for communicating connection status or request progress |
---|
2755 | prior to completing the requested action and sending a final |
---|
2756 | response. All 1xx responses consist of only the status-line and |
---|
2757 | optional header fields, and thus are terminated by the empty line at |
---|
2758 | the end of the header section. Since HTTP/1.0 did not define any 1xx |
---|
2759 | status codes, a server MUST NOT send a 1xx response to an HTTP/1.0 |
---|
2760 | client. |
---|
2761 | |
---|
2762 | A client MUST be able to parse one or more 1xx responses received |
---|
2763 | prior to a final response, even if the client does not expect one. A |
---|
2764 | user agent MAY ignore unexpected 1xx responses. |
---|
2765 | |
---|
2766 | A proxy MUST forward 1xx responses unless the proxy itself requested |
---|
2767 | the generation of the 1xx response. For example, if a proxy adds an |
---|
2768 | "Expect: 100-continue" field when it forwards a request, then it need |
---|
2769 | not forward the corresponding 100 (Continue) response(s). |
---|
2770 | |
---|
2771 | 6.2.1. 100 Continue |
---|
2772 | |
---|
2773 | The 100 (Continue) status code indicates that the initial part of a |
---|
2774 | request has been received and has not yet been rejected by the |
---|
2775 | server. The server intends to send a final response after the |
---|
2776 | request has been fully received and acted upon. |
---|
2777 | |
---|
2778 | When the request contains an Expect header field that includes a 100- |
---|
2779 | continue expectation, the 100 response indicates that the server |
---|
2780 | wishes to receive the request payload body, as described in |
---|
2781 | Section 5.1.1. The client ought to continue sending the request and |
---|
2782 | discard the 100 response. |
---|
2783 | |
---|
2784 | If the request did not contain an Expect header field containing the |
---|
2785 | 100-continue expectation, the client can simply discard this interim |
---|
2786 | response. |
---|
2787 | |
---|
2788 | 6.2.2. 101 Switching Protocols |
---|
2789 | |
---|
2790 | The 101 (Switching Protocols) status code indicates that the server |
---|
2791 | understands and is willing to comply with the client's request, via |
---|
2792 | the Upgrade header field (Section 6.7 of [RFC7230]), for a change in |
---|
2793 | the application protocol being used on this connection. The server |
---|
2794 | MUST generate an Upgrade header field in the response that indicates |
---|
2795 | which protocol(s) will be switched to immediately after the empty |
---|
2796 | |
---|
2797 | |
---|
2798 | |
---|
2799 | Fielding & Reschke Expires November 7, 2014 [Page 50] |
---|
2800 | |
---|
2801 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
2802 | |
---|
2803 | |
---|
2804 | line that terminates the 101 response. |
---|
2805 | |
---|
2806 | It is assumed that the server will only agree to switch protocols |
---|
2807 | when it is advantageous to do so. For example, switching to a newer |
---|
2808 | version of HTTP might be advantageous over older versions, and |
---|
2809 | switching to a real-time, synchronous protocol might be advantageous |
---|
2810 | when delivering resources that use such features. |
---|
2811 | |
---|
2812 | 6.3. Successful 2xx |
---|
2813 | |
---|
2814 | The 2xx (Successful) class of status code indicates that the client's |
---|
2815 | request was successfully received, understood, and accepted. |
---|
2816 | |
---|
2817 | 6.3.1. 200 OK |
---|
2818 | |
---|
2819 | The 200 (OK) status code indicates that the request has succeeded. |
---|
2820 | The payload sent in a 200 response depends on the request method. |
---|
2821 | For the methods defined by this specification, the intended meaning |
---|
2822 | of the payload can be summarized as: |
---|
2823 | |
---|
2824 | GET a representation of the target resource; |
---|
2825 | |
---|
2826 | HEAD the same representation as GET, but without the representation |
---|
2827 | data; |
---|
2828 | |
---|
2829 | POST a representation of the status of, or results obtained from, |
---|
2830 | the action; |
---|
2831 | |
---|
2832 | PUT, DELETE a representation of the status of the action; |
---|
2833 | |
---|
2834 | OPTIONS a representation of the communications options; |
---|
2835 | |
---|
2836 | TRACE a representation of the request message as received by the end |
---|
2837 | server. |
---|
2838 | |
---|
2839 | Aside from responses to CONNECT, a 200 response always has a payload, |
---|
2840 | though an origin server MAY generate a payload body of zero length. |
---|
2841 | If no payload is desired, an origin server ought to send 204 (No |
---|
2842 | Content) instead. For CONNECT, no payload is allowed because the |
---|
2843 | successful result is a tunnel, which begins immediately after the 200 |
---|
2844 | response header section. |
---|
2845 | |
---|
2846 | A 200 response is cacheable by default; i.e., unless otherwise |
---|
2847 | indicated by the method definition or explicit cache controls (see |
---|
2848 | Section 4.2.2 of [RFC7234]). |
---|
2849 | |
---|
2850 | |
---|
2851 | |
---|
2852 | |
---|
2853 | |
---|
2854 | |
---|
2855 | Fielding & Reschke Expires November 7, 2014 [Page 51] |
---|
2856 | |
---|
2857 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
2858 | |
---|
2859 | |
---|
2860 | 6.3.2. 201 Created |
---|
2861 | |
---|
2862 | The 201 (Created) status code indicates that the request has been |
---|
2863 | fulfilled and has resulted in one or more new resources being |
---|
2864 | created. The primary resource created by the request is identified |
---|
2865 | by either a Location header field in the response or, if no Location |
---|
2866 | field is received, by the effective request URI. |
---|
2867 | |
---|
2868 | The 201 response payload typically describes and links to the |
---|
2869 | resource(s) created. See Section 7.2 for a discussion of the meaning |
---|
2870 | and purpose of validator header fields, such as ETag and Last- |
---|
2871 | Modified, in a 201 response. |
---|
2872 | |
---|
2873 | 6.3.3. 202 Accepted |
---|
2874 | |
---|
2875 | The 202 (Accepted) status code indicates that the request has been |
---|
2876 | accepted for processing, but the processing has not been completed. |
---|
2877 | The request might or might not eventually be acted upon, as it might |
---|
2878 | be disallowed when processing actually takes place. There is no |
---|
2879 | facility in HTTP for re-sending a status code from an asynchronous |
---|
2880 | operation. |
---|
2881 | |
---|
2882 | The 202 response is intentionally non-committal. Its purpose is to |
---|
2883 | allow a server to accept a request for some other process (perhaps a |
---|
2884 | batch-oriented process that is only run once per day) without |
---|
2885 | requiring that the user agent's connection to the server persist |
---|
2886 | until the process is completed. The representation sent with this |
---|
2887 | response ought to describe the request's current status and point to |
---|
2888 | (or embed) a status monitor that can provide the user with an |
---|
2889 | estimate of when the request will be fulfilled. |
---|
2890 | |
---|
2891 | 6.3.4. 203 Non-Authoritative Information |
---|
2892 | |
---|
2893 | The 203 (Non-Authoritative Information) status code indicates that |
---|
2894 | the request was successful but the enclosed payload has been modified |
---|
2895 | from that of the origin server's 200 (OK) response by a transforming |
---|
2896 | proxy (Section 5.7.2 of [RFC7230]). This status code allows the |
---|
2897 | proxy to notify recipients when a transformation has been applied, |
---|
2898 | since that knowledge might impact later decisions regarding the |
---|
2899 | content. For example, future cache validation requests for the |
---|
2900 | content might only be applicable along the same request path (through |
---|
2901 | the same proxies). |
---|
2902 | |
---|
2903 | The 203 response is similar to the Warning code of 214 Transformation |
---|
2904 | Applied (Section 5.5 of [RFC7234]), which has the advantage of being |
---|
2905 | applicable to responses with any status code. |
---|
2906 | |
---|
2907 | A 203 response is cacheable by default; i.e., unless otherwise |
---|
2908 | |
---|
2909 | |
---|
2910 | |
---|
2911 | Fielding & Reschke Expires November 7, 2014 [Page 52] |
---|
2912 | |
---|
2913 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
2914 | |
---|
2915 | |
---|
2916 | indicated by the method definition or explicit cache controls (see |
---|
2917 | Section 4.2.2 of [RFC7234]). |
---|
2918 | |
---|
2919 | 6.3.5. 204 No Content |
---|
2920 | |
---|
2921 | The 204 (No Content) status code indicates that the server has |
---|
2922 | successfully fulfilled the request and that there is no additional |
---|
2923 | content to send in the response payload body. Metadata in the |
---|
2924 | response header fields refer to the target resource and its selected |
---|
2925 | representation after the requested action was applied. |
---|
2926 | |
---|
2927 | For example, if a 204 status code is received in response to a PUT |
---|
2928 | request and the response contains an ETag header field, then the PUT |
---|
2929 | was successful and the ETag field-value contains the entity-tag for |
---|
2930 | the new representation of that target resource. |
---|
2931 | |
---|
2932 | The 204 response allows a server to indicate that the action has been |
---|
2933 | successfully applied to the target resource, while implying that the |
---|
2934 | user agent does not need to traverse away from its current "document |
---|
2935 | view" (if any). The server assumes that the user agent will provide |
---|
2936 | some indication of the success to its user, in accord with its own |
---|
2937 | interface, and apply any new or updated metadata in the response to |
---|
2938 | its active representation. |
---|
2939 | |
---|
2940 | For example, a 204 status code is commonly used with document editing |
---|
2941 | interfaces corresponding to a "save" action, such that the document |
---|
2942 | being saved remains available to the user for editing. It is also |
---|
2943 | frequently used with interfaces that expect automated data transfers |
---|
2944 | to be prevalent, such as within distributed version control systems. |
---|
2945 | |
---|
2946 | A 204 response is terminated by the first empty line after the header |
---|
2947 | fields because it cannot contain a message body. |
---|
2948 | |
---|
2949 | A 204 response is cacheable by default; i.e., unless otherwise |
---|
2950 | indicated by the method definition or explicit cache controls (see |
---|
2951 | Section 4.2.2 of [RFC7234]). |
---|
2952 | |
---|
2953 | 6.3.6. 205 Reset Content |
---|
2954 | |
---|
2955 | The 205 (Reset Content) status code indicates that the server has |
---|
2956 | fulfilled the request and desires that the user agent reset the |
---|
2957 | "document view", which caused the request to be sent, to its original |
---|
2958 | state as received from the origin server. |
---|
2959 | |
---|
2960 | This response is intended to support a common data entry use case |
---|
2961 | where the user receives content that supports data entry (a form, |
---|
2962 | notepad, canvas, etc.), enters or manipulates data in that space, |
---|
2963 | causes the entered data to be submitted in a request, and then the |
---|
2964 | |
---|
2965 | |
---|
2966 | |
---|
2967 | Fielding & Reschke Expires November 7, 2014 [Page 53] |
---|
2968 | |
---|
2969 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
2970 | |
---|
2971 | |
---|
2972 | data entry mechanism is reset for the next entry so that the user can |
---|
2973 | easily initiate another input action. |
---|
2974 | |
---|
2975 | Since the 205 status code implies that no additional content will be |
---|
2976 | provided, a server MUST NOT generate a payload in a 205 response. In |
---|
2977 | other words, a server MUST do one of the following for a 205 |
---|
2978 | response: a) indicate a zero-length body for the response by |
---|
2979 | including a Content-Length header field with a value of 0; b) |
---|
2980 | indicate a zero-length payload for the response by including a |
---|
2981 | Transfer-Encoding header field with a value of chunked and a message |
---|
2982 | body consisting of a single chunk of zero-length; or, c) close the |
---|
2983 | connection immediately after sending the blank line terminating the |
---|
2984 | header section. |
---|
2985 | |
---|
2986 | 6.4. Redirection 3xx |
---|
2987 | |
---|
2988 | The 3xx (Redirection) class of status code indicates that further |
---|
2989 | action needs to be taken by the user agent in order to fulfill the |
---|
2990 | request. If a Location header field (Section 7.1.2) is provided, the |
---|
2991 | user agent MAY automatically redirect its request to the URI |
---|
2992 | referenced by the Location field value, even if the specific status |
---|
2993 | code is not understood. Automatic redirection needs to done with |
---|
2994 | care for methods not known to be safe, as defined in Section 4.2.1, |
---|
2995 | since the user might not wish to redirect an unsafe request. |
---|
2996 | |
---|
2997 | There are several types of redirects: |
---|
2998 | |
---|
2999 | 1. Redirects that indicate the resource might be available at a |
---|
3000 | different URI, as provided by the Location field, as in the |
---|
3001 | status codes 301 (Moved Permanently), 302 (Found), and 307 |
---|
3002 | (Temporary Redirect). |
---|
3003 | |
---|
3004 | 2. Redirection that offers a choice of matching resources, each |
---|
3005 | capable of representing the original request target, as in the |
---|
3006 | 300 (Multiple Choices) status code. |
---|
3007 | |
---|
3008 | 3. Redirection to a different resource, identified by the Location |
---|
3009 | field, that can represent an indirect response to the request, as |
---|
3010 | in the 303 (See Other) status code. |
---|
3011 | |
---|
3012 | 4. Redirection to a previously cached result, as in the 304 (Not |
---|
3013 | Modified) status code. |
---|
3014 | |
---|
3015 | Note: In HTTP/1.0, the status codes 301 (Moved Permanently) and |
---|
3016 | 302 (Found) were defined for the first type of redirect |
---|
3017 | ([RFC1945], Section 9.3). Early user agents split on whether the |
---|
3018 | method applied to the redirect target would be the same as the |
---|
3019 | original request or would be rewritten as GET. Although HTTP |
---|
3020 | |
---|
3021 | |
---|
3022 | |
---|
3023 | Fielding & Reschke Expires November 7, 2014 [Page 54] |
---|
3024 | |
---|
3025 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
3026 | |
---|
3027 | |
---|
3028 | originally defined the former semantics for 301 and 302 (to match |
---|
3029 | its original implementation at CERN), and defined 303 (See Other) |
---|
3030 | to match the latter semantics, prevailing practice gradually |
---|
3031 | converged on the latter semantics for 301 and 302 as well. The |
---|
3032 | first revision of HTTP/1.1 added 307 (Temporary Redirect) to |
---|
3033 | indicate the former semantics without being impacted by divergent |
---|
3034 | practice. Over 10 years later, most user agents still do method |
---|
3035 | rewriting for 301 and 302; therefore, this specification makes |
---|
3036 | that behavior conformant when the original request is POST. |
---|
3037 | |
---|
3038 | A client SHOULD detect and intervene in cyclical redirections (i.e., |
---|
3039 | "infinite" redirection loops). |
---|
3040 | |
---|
3041 | Note: An earlier version of this specification recommended a |
---|
3042 | maximum of five redirections ([RFC2068], Section 10.3). Content |
---|
3043 | developers need to be aware that some clients might implement such |
---|
3044 | a fixed limitation. |
---|
3045 | |
---|
3046 | 6.4.1. 300 Multiple Choices |
---|
3047 | |
---|
3048 | The 300 (Multiple Choices) status code indicates that the target |
---|
3049 | resource has more than one representation, each with its own more |
---|
3050 | specific identifier, and information about the alternatives is being |
---|
3051 | provided so that the user (or user agent) can select a preferred |
---|
3052 | representation by redirecting its request to one or more of those |
---|
3053 | identifiers. In other words, the server desires that the user agent |
---|
3054 | engage in reactive negotiation to select the most appropriate |
---|
3055 | representation(s) for its needs (Section 3.4). |
---|
3056 | |
---|
3057 | If the server has a preferred choice, the server SHOULD generate a |
---|
3058 | Location header field containing a preferred choice's URI reference. |
---|
3059 | The user agent MAY use the Location field value for automatic |
---|
3060 | redirection. |
---|
3061 | |
---|
3062 | For request methods other than HEAD, the server SHOULD generate a |
---|
3063 | payload in the 300 response containing a list of representation |
---|
3064 | metadata and URI reference(s) from which the user or user agent can |
---|
3065 | choose the one most preferred. The user agent MAY make a selection |
---|
3066 | from that list automatically if it understands the provided media |
---|
3067 | type. A specific format for automatic selection is not defined by |
---|
3068 | this specification because HTTP tries to remain orthogonal to the |
---|
3069 | definition of its payloads. In practice, the representation is |
---|
3070 | provided in some easily parsed format believed to be acceptable to |
---|
3071 | the user agent, as determined by shared design or content |
---|
3072 | negotiation, or in some commonly accepted hypertext format. |
---|
3073 | |
---|
3074 | A 300 response is cacheable by default; i.e., unless otherwise |
---|
3075 | indicated by the method definition or explicit cache controls (see |
---|
3076 | |
---|
3077 | |
---|
3078 | |
---|
3079 | Fielding & Reschke Expires November 7, 2014 [Page 55] |
---|
3080 | |
---|
3081 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
3082 | |
---|
3083 | |
---|
3084 | Section 4.2.2 of [RFC7234]). |
---|
3085 | |
---|
3086 | Note: The original proposal for 300 defined the URI header field |
---|
3087 | as providing a list of alternative representations, such that it |
---|
3088 | would be usable for 200, 300, and 406 responses and be transferred |
---|
3089 | in responses to the HEAD method. However, lack of deployment and |
---|
3090 | disagreement over syntax led to both URI and Alternates (a |
---|
3091 | subsequent proposal) being dropped from this specification. It is |
---|
3092 | possible to communicate the list using a set of Link header fields |
---|
3093 | [RFC5988], each with a relationship of "alternate", though |
---|
3094 | deployment is a chicken-and-egg problem. |
---|
3095 | |
---|
3096 | 6.4.2. 301 Moved Permanently |
---|
3097 | |
---|
3098 | The 301 (Moved Permanently) status code indicates that the target |
---|
3099 | resource has been assigned a new permanent URI and any future |
---|
3100 | references to this resource ought to use one of the enclosed URIs. |
---|
3101 | Clients with link editing capabilities ought to automatically re-link |
---|
3102 | references to the effective request URI to one or more of the new |
---|
3103 | references sent by the server, where possible. |
---|
3104 | |
---|
3105 | The server SHOULD generate a Location header field in the response |
---|
3106 | containing a preferred URI reference for the new permanent URI. The |
---|
3107 | user agent MAY use the Location field value for automatic |
---|
3108 | redirection. The server's response payload usually contains a short |
---|
3109 | hypertext note with a hyperlink to the new URI(s). |
---|
3110 | |
---|
3111 | Note: For historical reasons, a user agent MAY change the request |
---|
3112 | method from POST to GET for the subsequent request. If this |
---|
3113 | behavior is undesired, the 307 (Temporary Redirect) status code |
---|
3114 | can be used instead. |
---|
3115 | |
---|
3116 | A 301 response is cacheable by default; i.e., unless otherwise |
---|
3117 | indicated by the method definition or explicit cache controls (see |
---|
3118 | Section 4.2.2 of [RFC7234]). |
---|
3119 | |
---|
3120 | 6.4.3. 302 Found |
---|
3121 | |
---|
3122 | The 302 (Found) status code indicates that the target resource |
---|
3123 | resides temporarily under a different URI. Since the redirection |
---|
3124 | might be altered on occasion, the client ought to continue to use the |
---|
3125 | effective request URI for future requests. |
---|
3126 | |
---|
3127 | The server SHOULD generate a Location header field in the response |
---|
3128 | containing a URI reference for the different URI. The user agent MAY |
---|
3129 | use the Location field value for automatic redirection. The server's |
---|
3130 | response payload usually contains a short hypertext note with a |
---|
3131 | hyperlink to the different URI(s). |
---|
3132 | |
---|
3133 | |
---|
3134 | |
---|
3135 | Fielding & Reschke Expires November 7, 2014 [Page 56] |
---|
3136 | |
---|
3137 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
3138 | |
---|
3139 | |
---|
3140 | Note: For historical reasons, a user agent MAY change the request |
---|
3141 | method from POST to GET for the subsequent request. If this |
---|
3142 | behavior is undesired, the 307 (Temporary Redirect) status code |
---|
3143 | can be used instead. |
---|
3144 | |
---|
3145 | 6.4.4. 303 See Other |
---|
3146 | |
---|
3147 | The 303 (See Other) status code indicates that the server is |
---|
3148 | redirecting the user agent to a different resource, as indicated by a |
---|
3149 | URI in the Location header field, which is intended to provide an |
---|
3150 | indirect response to the original request. A user agent can perform |
---|
3151 | a retrieval request targeting that URI (a GET or HEAD request if |
---|
3152 | using HTTP), which might also be redirected, and present the eventual |
---|
3153 | result as an answer to the original request. Note that the new URI |
---|
3154 | in the Location header field is not considered equivalent to the |
---|
3155 | effective request URI. |
---|
3156 | |
---|
3157 | This status code is applicable to any HTTP method. It is primarily |
---|
3158 | used to allow the output of a POST action to redirect the user agent |
---|
3159 | to a selected resource, since doing so provides the information |
---|
3160 | corresponding to the POST response in a form that can be separately |
---|
3161 | identified, bookmarked, and cached independent of the original |
---|
3162 | request. |
---|
3163 | |
---|
3164 | A 303 response to a GET request indicates that the origin server does |
---|
3165 | not have a representation of the target resource that can be |
---|
3166 | transferred by the server over HTTP. However, the Location field |
---|
3167 | value refers to a resource that is descriptive of the target |
---|
3168 | resource, such that making a retrieval request on that other resource |
---|
3169 | might result in a representation that is useful to recipients without |
---|
3170 | implying that it represents the original target resource. Note that |
---|
3171 | answers to the questions of what can be represented, what |
---|
3172 | representations are adequate, and what might be a useful description |
---|
3173 | are outside the scope of HTTP. |
---|
3174 | |
---|
3175 | Except for responses to a HEAD request, the representation of a 303 |
---|
3176 | response ought to contain a short hypertext note with a hyperlink to |
---|
3177 | the same URI reference provided in the Location header field. |
---|
3178 | |
---|
3179 | 6.4.5. 305 Use Proxy |
---|
3180 | |
---|
3181 | The 305 (Use Proxy) status code was defined in a previous version of |
---|
3182 | this specification and is now deprecated (Appendix B). |
---|
3183 | |
---|
3184 | 6.4.6. 306 (Unused) |
---|
3185 | |
---|
3186 | The 306 status code was defined in a previous version of this |
---|
3187 | specification, is no longer used, and the code is reserved. |
---|
3188 | |
---|
3189 | |
---|
3190 | |
---|
3191 | Fielding & Reschke Expires November 7, 2014 [Page 57] |
---|
3192 | |
---|
3193 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
3194 | |
---|
3195 | |
---|
3196 | 6.4.7. 307 Temporary Redirect |
---|
3197 | |
---|
3198 | The 307 (Temporary Redirect) status code indicates that the target |
---|
3199 | resource resides temporarily under a different URI and the user agent |
---|
3200 | MUST NOT change the request method if it performs an automatic |
---|
3201 | redirection to that URI. Since the redirection can change over time, |
---|
3202 | the client ought to continue using the original effective request URI |
---|
3203 | for future requests. |
---|
3204 | |
---|
3205 | The server SHOULD generate a Location header field in the response |
---|
3206 | containing a URI reference for the different URI. The user agent MAY |
---|
3207 | use the Location field value for automatic redirection. The server's |
---|
3208 | response payload usually contains a short hypertext note with a |
---|
3209 | hyperlink to the different URI(s). |
---|
3210 | |
---|
3211 | Note: This status code is similar to 302 (Found), except that it |
---|
3212 | does not allow changing the request method from POST to GET. This |
---|
3213 | specification defines no equivalent counterpart for 301 (Moved |
---|
3214 | Permanently) ([status-308], however, defines the status code 308 |
---|
3215 | (Permanent Redirect) for this purpose). |
---|
3216 | |
---|
3217 | 6.5. Client Error 4xx |
---|
3218 | |
---|
3219 | The 4xx (Client Error) class of status code indicates that the client |
---|
3220 | seems to have erred. Except when responding to a HEAD request, the |
---|
3221 | server SHOULD send a representation containing an explanation of the |
---|
3222 | error situation, and whether it is a temporary or permanent |
---|
3223 | condition. These status codes are applicable to any request method. |
---|
3224 | User agents SHOULD display any included representation to the user. |
---|
3225 | |
---|
3226 | 6.5.1. 400 Bad Request |
---|
3227 | |
---|
3228 | The 400 (Bad Request) status code indicates that the server cannot or |
---|
3229 | will not process the request due to something which is perceived to |
---|
3230 | be a client error (e.g., malformed request syntax, invalid request |
---|
3231 | message framing, or deceptive request routing). |
---|
3232 | |
---|
3233 | 6.5.2. 402 Payment Required |
---|
3234 | |
---|
3235 | The 402 (Payment Required) status code is reserved for future use. |
---|
3236 | |
---|
3237 | 6.5.3. 403 Forbidden |
---|
3238 | |
---|
3239 | The 403 (Forbidden) status code indicates that the server understood |
---|
3240 | the request but refuses to authorize it. A server that wishes to |
---|
3241 | make public why the request has been forbidden can describe that |
---|
3242 | reason in the response payload (if any). |
---|
3243 | |
---|
3244 | |
---|
3245 | |
---|
3246 | |
---|
3247 | Fielding & Reschke Expires November 7, 2014 [Page 58] |
---|
3248 | |
---|
3249 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
3250 | |
---|
3251 | |
---|
3252 | If authentication credentials were provided in the request, the |
---|
3253 | server considers them insufficient to grant access. The client |
---|
3254 | SHOULD NOT automatically repeat the request with the same |
---|
3255 | credentials. The client MAY repeat the request with new or different |
---|
3256 | credentials. However, a request might be forbidden for reasons |
---|
3257 | unrelated to the credentials. |
---|
3258 | |
---|
3259 | An origin server that wishes to "hide" the current existence of a |
---|
3260 | forbidden target resource MAY instead respond with a status code of |
---|
3261 | 404 (Not Found). |
---|
3262 | |
---|
3263 | 6.5.4. 404 Not Found |
---|
3264 | |
---|
3265 | The 404 (Not Found) status code indicates that the origin server did |
---|
3266 | not find a current representation for the target resource or is not |
---|
3267 | willing to disclose that one exists. A 404 status code does not |
---|
3268 | indicate whether this lack of representation is temporary or |
---|
3269 | permanent; the 410 (Gone) status code is preferred over 404 if the |
---|
3270 | origin server knows, presumably through some configurable means, that |
---|
3271 | the condition is likely to be permanent. |
---|
3272 | |
---|
3273 | A 404 response is cacheable by default; i.e., unless otherwise |
---|
3274 | indicated by the method definition or explicit cache controls (see |
---|
3275 | Section 4.2.2 of [RFC7234]). |
---|
3276 | |
---|
3277 | 6.5.5. 405 Method Not Allowed |
---|
3278 | |
---|
3279 | The 405 (Method Not Allowed) status code indicates that the method |
---|
3280 | received in the request-line is known by the origin server but not |
---|
3281 | supported by the target resource. The origin server MUST generate an |
---|
3282 | Allow header field in a 405 response containing a list of the target |
---|
3283 | resource's currently supported methods. |
---|
3284 | |
---|
3285 | A 405 response is cacheable by default; i.e., unless otherwise |
---|
3286 | indicated by the method definition or explicit cache controls (see |
---|
3287 | Section 4.2.2 of [RFC7234]). |
---|
3288 | |
---|
3289 | 6.5.6. 406 Not Acceptable |
---|
3290 | |
---|
3291 | The 406 (Not Acceptable) status code indicates that the target |
---|
3292 | resource does not have a current representation that would be |
---|
3293 | acceptable to the user agent, according to the proactive negotiation |
---|
3294 | header fields received in the request (Section 5.3), and the server |
---|
3295 | is unwilling to supply a default representation. |
---|
3296 | |
---|
3297 | The server SHOULD generate a payload containing a list of available |
---|
3298 | representation characteristics and corresponding resource identifiers |
---|
3299 | from which the user or user agent can choose the one most |
---|
3300 | |
---|
3301 | |
---|
3302 | |
---|
3303 | Fielding & Reschke Expires November 7, 2014 [Page 59] |
---|
3304 | |
---|
3305 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
3306 | |
---|
3307 | |
---|
3308 | appropriate. A user agent MAY automatically select the most |
---|
3309 | appropriate choice from that list. However, this specification does |
---|
3310 | not define any standard for such automatic selection, as described in |
---|
3311 | Section 6.4.1. |
---|
3312 | |
---|
3313 | 6.5.7. 408 Request Timeout |
---|
3314 | |
---|
3315 | The 408 (Request Timeout) status code indicates that the server did |
---|
3316 | not receive a complete request message within the time that it was |
---|
3317 | prepared to wait. A server SHOULD send the close connection option |
---|
3318 | (Section 6.1 of [RFC7230]) in the response, since 408 implies that |
---|
3319 | the server has decided to close the connection rather than continue |
---|
3320 | waiting. If the client has an outstanding request in transit, the |
---|
3321 | client MAY repeat that request on a new connection. |
---|
3322 | |
---|
3323 | 6.5.8. 409 Conflict |
---|
3324 | |
---|
3325 | The 409 (Conflict) status code indicates that the request could not |
---|
3326 | be completed due to a conflict with the current state of the target |
---|
3327 | resource. This code is used in situations where the user might be |
---|
3328 | able to resolve the conflict and resubmit the request. The server |
---|
3329 | SHOULD generate a payload that includes enough information for a user |
---|
3330 | to recognize the source of the conflict. |
---|
3331 | |
---|
3332 | Conflicts are most likely to occur in response to a PUT request. For |
---|
3333 | example, if versioning were being used and the representation being |
---|
3334 | PUT included changes to a resource that conflict with those made by |
---|
3335 | an earlier (third-party) request, the origin server might use a 409 |
---|
3336 | response to indicate that it can't complete the request. In this |
---|
3337 | case, the response representation would likely contain information |
---|
3338 | useful for merging the differences based on the revision history. |
---|
3339 | |
---|
3340 | 6.5.9. 410 Gone |
---|
3341 | |
---|
3342 | The 410 (Gone) status code indicates that access to the target |
---|
3343 | resource is no longer available at the origin server and that this |
---|
3344 | condition is likely to be permanent. If the origin server does not |
---|
3345 | know, or has no facility to determine, whether or not the condition |
---|
3346 | is permanent, the status code 404 (Not Found) ought to be used |
---|
3347 | instead. |
---|
3348 | |
---|
3349 | The 410 response is primarily intended to assist the task of web |
---|
3350 | maintenance by notifying the recipient that the resource is |
---|
3351 | intentionally unavailable and that the server owners desire that |
---|
3352 | remote links to that resource be removed. Such an event is common |
---|
3353 | for limited-time, promotional services and for resources belonging to |
---|
3354 | individuals no longer associated with the origin server's site. It |
---|
3355 | is not necessary to mark all permanently unavailable resources as |
---|
3356 | |
---|
3357 | |
---|
3358 | |
---|
3359 | Fielding & Reschke Expires November 7, 2014 [Page 60] |
---|
3360 | |
---|
3361 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
3362 | |
---|
3363 | |
---|
3364 | "gone" or to keep the mark for any length of time -- that is left to |
---|
3365 | the discretion of the server owner. |
---|
3366 | |
---|
3367 | A 410 response is cacheable by default; i.e., unless otherwise |
---|
3368 | indicated by the method definition or explicit cache controls (see |
---|
3369 | Section 4.2.2 of [RFC7234]). |
---|
3370 | |
---|
3371 | 6.5.10. 411 Length Required |
---|
3372 | |
---|
3373 | The 411 (Length Required) status code indicates that the server |
---|
3374 | refuses to accept the request without a defined Content-Length |
---|
3375 | (Section 3.3.2 of [RFC7230]). The client MAY repeat the request if |
---|
3376 | it adds a valid Content-Length header field containing the length of |
---|
3377 | the message body in the request message. |
---|
3378 | |
---|
3379 | 6.5.11. 413 Payload Too Large |
---|
3380 | |
---|
3381 | The 413 (Payload Too Large) status code indicates that the server is |
---|
3382 | refusing to process a request because the request payload is larger |
---|
3383 | than the server is willing or able to process. The server MAY close |
---|
3384 | the connection to prevent the client from continuing the request. |
---|
3385 | |
---|
3386 | If the condition is temporary, the server SHOULD generate a Retry- |
---|
3387 | After header field to indicate that it is temporary and after what |
---|
3388 | time the client MAY try again. |
---|
3389 | |
---|
3390 | 6.5.12. 414 URI Too Long |
---|
3391 | |
---|
3392 | The 414 (URI Too Long) status code indicates that the server is |
---|
3393 | refusing to service the request because the request-target (Section |
---|
3394 | 5.3 of [RFC7230]) is longer than the server is willing to interpret. |
---|
3395 | This rare condition is only likely to occur when a client has |
---|
3396 | improperly converted a POST request to a GET request with long query |
---|
3397 | information, when the client has descended into a "black hole" of |
---|
3398 | redirection (e.g., a redirected URI prefix that points to a suffix of |
---|
3399 | itself), or when the server is under attack by a client attempting to |
---|
3400 | exploit potential security holes. |
---|
3401 | |
---|
3402 | A 414 response is cacheable by default; i.e., unless otherwise |
---|
3403 | indicated by the method definition or explicit cache controls (see |
---|
3404 | Section 4.2.2 of [RFC7234]). |
---|
3405 | |
---|
3406 | 6.5.13. 415 Unsupported Media Type |
---|
3407 | |
---|
3408 | The 415 (Unsupported Media Type) status code indicates that the |
---|
3409 | origin server is refusing to service the request because the payload |
---|
3410 | is in a format not supported by this method on the target resource. |
---|
3411 | The format problem might be due to the request's indicated Content- |
---|
3412 | |
---|
3413 | |
---|
3414 | |
---|
3415 | Fielding & Reschke Expires November 7, 2014 [Page 61] |
---|
3416 | |
---|
3417 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
3418 | |
---|
3419 | |
---|
3420 | Type or Content-Encoding, or as a result of inspecting the data |
---|
3421 | directly. |
---|
3422 | |
---|
3423 | 6.5.14. 417 Expectation Failed |
---|
3424 | |
---|
3425 | The 417 (Expectation Failed) status code indicates that the |
---|
3426 | expectation given in the request's Expect header field |
---|
3427 | (Section 5.1.1) could not be met by at least one of the inbound |
---|
3428 | servers. |
---|
3429 | |
---|
3430 | 6.5.15. 426 Upgrade Required |
---|
3431 | |
---|
3432 | The 426 (Upgrade Required) status code indicates that the server |
---|
3433 | refuses to perform the request using the current protocol but might |
---|
3434 | be willing to do so after the client upgrades to a different |
---|
3435 | protocol. The server MUST send an Upgrade header field in a 426 |
---|
3436 | response to indicate the required protocol(s) (Section 6.7 of |
---|
3437 | [RFC7230]). |
---|
3438 | |
---|
3439 | Example: |
---|
3440 | |
---|
3441 | HTTP/1.1 426 Upgrade Required |
---|
3442 | Upgrade: HTTP/3.0 |
---|
3443 | Connection: Upgrade |
---|
3444 | Content-Length: 53 |
---|
3445 | Content-Type: text/plain |
---|
3446 | |
---|
3447 | This service requires use of the HTTP/3.0 protocol. |
---|
3448 | |
---|
3449 | 6.6. Server Error 5xx |
---|
3450 | |
---|
3451 | The 5xx (Server Error) class of status code indicates that the server |
---|
3452 | is aware that it has erred or is incapable of performing the |
---|
3453 | requested method. Except when responding to a HEAD request, the |
---|
3454 | server SHOULD send a representation containing an explanation of the |
---|
3455 | error situation, and whether it is a temporary or permanent |
---|
3456 | condition. A user agent SHOULD display any included representation |
---|
3457 | to the user. These response codes are applicable to any request |
---|
3458 | method. |
---|
3459 | |
---|
3460 | 6.6.1. 500 Internal Server Error |
---|
3461 | |
---|
3462 | The 500 (Internal Server Error) status code indicates that the server |
---|
3463 | encountered an unexpected condition that prevented it from fulfilling |
---|
3464 | the request. |
---|
3465 | |
---|
3466 | |
---|
3467 | |
---|
3468 | |
---|
3469 | |
---|
3470 | |
---|
3471 | Fielding & Reschke Expires November 7, 2014 [Page 62] |
---|
3472 | |
---|
3473 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
3474 | |
---|
3475 | |
---|
3476 | 6.6.2. 501 Not Implemented |
---|
3477 | |
---|
3478 | The 501 (Not Implemented) status code indicates that the server does |
---|
3479 | not support the functionality required to fulfill the request. This |
---|
3480 | is the appropriate response when the server does not recognize the |
---|
3481 | request method and is not capable of supporting it for any resource. |
---|
3482 | |
---|
3483 | A 501 response is cacheable by default; i.e., unless otherwise |
---|
3484 | indicated by the method definition or explicit cache controls (see |
---|
3485 | Section 4.2.2 of [RFC7234]). |
---|
3486 | |
---|
3487 | 6.6.3. 502 Bad Gateway |
---|
3488 | |
---|
3489 | The 502 (Bad Gateway) status code indicates that the server, while |
---|
3490 | acting as a gateway or proxy, received an invalid response from an |
---|
3491 | inbound server it accessed while attempting to fulfill the request. |
---|
3492 | |
---|
3493 | 6.6.4. 503 Service Unavailable |
---|
3494 | |
---|
3495 | The 503 (Service Unavailable) status code indicates that the server |
---|
3496 | is currently unable to handle the request due to a temporary overload |
---|
3497 | or scheduled maintenance, which will likely be alleviated after some |
---|
3498 | delay. The server MAY send a Retry-After header field |
---|
3499 | (Section 7.1.3) to suggest an appropriate amount of time for the |
---|
3500 | client to wait before retrying the request. |
---|
3501 | |
---|
3502 | Note: The existence of the 503 status code does not imply that a |
---|
3503 | server has to use it when becoming overloaded. Some servers might |
---|
3504 | simply refuse the connection. |
---|
3505 | |
---|
3506 | 6.6.5. 504 Gateway Timeout |
---|
3507 | |
---|
3508 | The 504 (Gateway Timeout) status code indicates that the server, |
---|
3509 | while acting as a gateway or proxy, did not receive a timely response |
---|
3510 | from an upstream server it needed to access in order to complete the |
---|
3511 | request. |
---|
3512 | |
---|
3513 | 6.6.6. 505 HTTP Version Not Supported |
---|
3514 | |
---|
3515 | The 505 (HTTP Version Not Supported) status code indicates that the |
---|
3516 | server does not support, or refuses to support, the major version of |
---|
3517 | HTTP that was used in the request message. The server is indicating |
---|
3518 | that it is unable or unwilling to complete the request using the same |
---|
3519 | major version as the client, as described in Section 2.6 of |
---|
3520 | [RFC7230], other than with this error message. The server SHOULD |
---|
3521 | generate a representation for the 505 response that describes why |
---|
3522 | that version is not supported and what other protocols are supported |
---|
3523 | by that server. |
---|
3524 | |
---|
3525 | |
---|
3526 | |
---|
3527 | Fielding & Reschke Expires November 7, 2014 [Page 63] |
---|
3528 | |
---|
3529 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
3530 | |
---|
3531 | |
---|
3532 | 7. Response Header Fields |
---|
3533 | |
---|
3534 | The response header fields allow the server to pass additional |
---|
3535 | information about the response beyond what is placed in the status- |
---|
3536 | line. These header fields give information about the server, about |
---|
3537 | further access to the target resource, or about related resources. |
---|
3538 | |
---|
3539 | Although each response header field has a defined meaning, in |
---|
3540 | general, the precise semantics might be further refined by the |
---|
3541 | semantics of the request method and/or response status code. |
---|
3542 | |
---|
3543 | 7.1. Control Data |
---|
3544 | |
---|
3545 | Response header fields can supply control data that supplements the |
---|
3546 | status code, directs caching, or instructs the client where to go |
---|
3547 | next. |
---|
3548 | |
---|
3549 | +-------------------+--------------------------+ |
---|
3550 | | Header Field Name | Defined in... | |
---|
3551 | +-------------------+--------------------------+ |
---|
3552 | | Age | Section 5.1 of [RFC7234] | |
---|
3553 | | Cache-Control | Section 5.2 of [RFC7234] | |
---|
3554 | | Expires | Section 5.3 of [RFC7234] | |
---|
3555 | | Date | Section 7.1.1.2 | |
---|
3556 | | Location | Section 7.1.2 | |
---|
3557 | | Retry-After | Section 7.1.3 | |
---|
3558 | | Vary | Section 7.1.4 | |
---|
3559 | | Warning | Section 5.5 of [RFC7234] | |
---|
3560 | +-------------------+--------------------------+ |
---|
3561 | |
---|
3562 | 7.1.1. Origination Date |
---|
3563 | |
---|
3564 | 7.1.1.1. Date/Time Formats |
---|
3565 | |
---|
3566 | Prior to 1995, there were three different formats commonly used by |
---|
3567 | servers to communicate timestamps. For compatibility with old |
---|
3568 | implementations, all three are defined here. The preferred format is |
---|
3569 | a fixed-length and single-zone subset of the date and time |
---|
3570 | specification used by the Internet Message Format [RFC5322]. |
---|
3571 | |
---|
3572 | HTTP-date = IMF-fixdate / obs-date |
---|
3573 | |
---|
3574 | An example of the preferred format is |
---|
3575 | |
---|
3576 | Sun, 06 Nov 1994 08:49:37 GMT ; IMF-fixdate |
---|
3577 | |
---|
3578 | |
---|
3579 | |
---|
3580 | |
---|
3581 | |
---|
3582 | |
---|
3583 | Fielding & Reschke Expires November 7, 2014 [Page 64] |
---|
3584 | |
---|
3585 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
3586 | |
---|
3587 | |
---|
3588 | Examples of the two obsolete formats are |
---|
3589 | |
---|
3590 | Sunday, 06-Nov-94 08:49:37 GMT ; obsolete RFC 850 format |
---|
3591 | Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format |
---|
3592 | |
---|
3593 | A recipient that parses a timestamp value in an HTTP header field |
---|
3594 | MUST accept all three HTTP-date formats. When a sender generates a |
---|
3595 | header field that contains one or more timestamps defined as HTTP- |
---|
3596 | date, the sender MUST generate those timestamps in the IMF-fixdate |
---|
3597 | format. |
---|
3598 | |
---|
3599 | An HTTP-date value represents time as an instance of Coordinated |
---|
3600 | Universal Time (UTC). The first two formats indicate UTC by the |
---|
3601 | three-letter abbreviation for Greenwich Mean Time, "GMT", a |
---|
3602 | predecessor of the UTC name; values in the asctime format are assumed |
---|
3603 | to be in UTC. A sender that generates HTTP-date values from a local |
---|
3604 | clock ought to use NTP ([RFC5905]) or some similar protocol to |
---|
3605 | synchronize its clock to UTC. |
---|
3606 | |
---|
3607 | Preferred format: |
---|
3608 | |
---|
3609 | |
---|
3610 | |
---|
3611 | |
---|
3612 | |
---|
3613 | |
---|
3614 | |
---|
3615 | |
---|
3616 | |
---|
3617 | |
---|
3618 | |
---|
3619 | |
---|
3620 | |
---|
3621 | |
---|
3622 | |
---|
3623 | |
---|
3624 | |
---|
3625 | |
---|
3626 | |
---|
3627 | |
---|
3628 | |
---|
3629 | |
---|
3630 | |
---|
3631 | |
---|
3632 | |
---|
3633 | |
---|
3634 | |
---|
3635 | |
---|
3636 | |
---|
3637 | |
---|
3638 | |
---|
3639 | Fielding & Reschke Expires November 7, 2014 [Page 65] |
---|
3640 | |
---|
3641 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
3642 | |
---|
3643 | |
---|
3644 | IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT |
---|
3645 | ; fixed length/zone/capitalization subset of the format |
---|
3646 | ; defined in Section 3.3 of [RFC5322] |
---|
3647 | |
---|
3648 | day-name = %x4D.6F.6E ; "Mon", case-sensitive |
---|
3649 | / %x54.75.65 ; "Tue", case-sensitive |
---|
3650 | / %x57.65.64 ; "Wed", case-sensitive |
---|
3651 | / %x54.68.75 ; "Thu", case-sensitive |
---|
3652 | / %x46.72.69 ; "Fri", case-sensitive |
---|
3653 | / %x53.61.74 ; "Sat", case-sensitive |
---|
3654 | / %x53.75.6E ; "Sun", case-sensitive |
---|
3655 | |
---|
3656 | date1 = day SP month SP year |
---|
3657 | ; e.g., 02 Jun 1982 |
---|
3658 | |
---|
3659 | day = 2DIGIT |
---|
3660 | month = %x4A.61.6E ; "Jan", case-sensitive |
---|
3661 | / %x46.65.62 ; "Feb", case-sensitive |
---|
3662 | / %x4D.61.72 ; "Mar", case-sensitive |
---|
3663 | / %x41.70.72 ; "Apr", case-sensitive |
---|
3664 | / %x4D.61.79 ; "May", case-sensitive |
---|
3665 | / %x4A.75.6E ; "Jun", case-sensitive |
---|
3666 | / %x4A.75.6C ; "Jul", case-sensitive |
---|
3667 | / %x41.75.67 ; "Aug", case-sensitive |
---|
3668 | / %x53.65.70 ; "Sep", case-sensitive |
---|
3669 | / %x4F.63.74 ; "Oct", case-sensitive |
---|
3670 | / %x4E.6F.76 ; "Nov", case-sensitive |
---|
3671 | / %x44.65.63 ; "Dec", case-sensitive |
---|
3672 | year = 4DIGIT |
---|
3673 | |
---|
3674 | GMT = %x47.4D.54 ; "GMT", case-sensitive |
---|
3675 | |
---|
3676 | time-of-day = hour ":" minute ":" second |
---|
3677 | ; 00:00:00 - 23:59:60 (leap second) |
---|
3678 | |
---|
3679 | hour = 2DIGIT |
---|
3680 | minute = 2DIGIT |
---|
3681 | second = 2DIGIT |
---|
3682 | |
---|
3683 | Obsolete formats: |
---|
3684 | |
---|
3685 | obs-date = rfc850-date / asctime-date |
---|
3686 | |
---|
3687 | |
---|
3688 | |
---|
3689 | |
---|
3690 | |
---|
3691 | |
---|
3692 | |
---|
3693 | |
---|
3694 | |
---|
3695 | Fielding & Reschke Expires November 7, 2014 [Page 66] |
---|
3696 | |
---|
3697 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
3698 | |
---|
3699 | |
---|
3700 | rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT |
---|
3701 | date2 = day "-" month "-" 2DIGIT |
---|
3702 | ; e.g., 02-Jun-82 |
---|
3703 | |
---|
3704 | day-name-l = %x4D.6F.6E.64.61.79 ; "Monday", case-sensitive |
---|
3705 | / %x54.75.65.73.64.61.79 ; "Tuesday", case-sensitive |
---|
3706 | / %x57.65.64.6E.65.73.64.61.79 ; "Wednesday", case-sensitive |
---|
3707 | / %x54.68.75.72.73.64.61.79 ; "Thursday", case-sensitive |
---|
3708 | / %x46.72.69.64.61.79 ; "Friday", case-sensitive |
---|
3709 | / %x53.61.74.75.72.64.61.79 ; "Saturday", case-sensitive |
---|
3710 | / %x53.75.6E.64.61.79 ; "Sunday", case-sensitive |
---|
3711 | |
---|
3712 | |
---|
3713 | asctime-date = day-name SP date3 SP time-of-day SP year |
---|
3714 | date3 = month SP ( 2DIGIT / ( SP 1DIGIT )) |
---|
3715 | ; e.g., Jun 2 |
---|
3716 | |
---|
3717 | HTTP-date is case sensitive. A sender MUST NOT generate additional |
---|
3718 | whitespace in an HTTP-date beyond that specifically included as SP in |
---|
3719 | the grammar. The semantics of day-name, day, month, year, and time- |
---|
3720 | of-day are the same as those defined for the Internet Message Format |
---|
3721 | constructs with the corresponding name ([RFC5322], Section 3.3). |
---|
3722 | |
---|
3723 | Recipients of a timestamp value in rfc850-date format, which uses a |
---|
3724 | two-digit year, MUST interpret a timestamp that appears to be more |
---|
3725 | than 50 years in the future as representing the most recent year in |
---|
3726 | the past that had the same last two digits. |
---|
3727 | |
---|
3728 | Recipients of timestamp values are encouraged to be robust in parsing |
---|
3729 | timestamps unless otherwise restricted by the field definition. For |
---|
3730 | example, messages are occasionally forwarded over HTTP from a non- |
---|
3731 | HTTP source that might generate any of the date and time |
---|
3732 | specifications defined by the Internet Message Format. |
---|
3733 | |
---|
3734 | Note: HTTP requirements for the date/time stamp format apply only |
---|
3735 | to their usage within the protocol stream. Implementations are |
---|
3736 | not required to use these formats for user presentation, request |
---|
3737 | logging, etc. |
---|
3738 | |
---|
3739 | 7.1.1.2. Date |
---|
3740 | |
---|
3741 | The "Date" header field represents the date and time at which the |
---|
3742 | message was originated, having the same semantics as the Origination |
---|
3743 | Date Field (orig-date) defined in Section 3.6.1 of [RFC5322]. The |
---|
3744 | field value is an HTTP-date, as defined in Section 7.1.1.1. |
---|
3745 | |
---|
3746 | Date = HTTP-date |
---|
3747 | |
---|
3748 | |
---|
3749 | |
---|
3750 | |
---|
3751 | Fielding & Reschke Expires November 7, 2014 [Page 67] |
---|
3752 | |
---|
3753 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
3754 | |
---|
3755 | |
---|
3756 | An example is |
---|
3757 | |
---|
3758 | Date: Tue, 15 Nov 1994 08:12:31 GMT |
---|
3759 | |
---|
3760 | When a Date header field is generated, the sender SHOULD generate its |
---|
3761 | field value as the best available approximation of the date and time |
---|
3762 | of message generation. In theory, the date ought to represent the |
---|
3763 | moment just before the payload is generated. In practice, the date |
---|
3764 | can be generated at any time during message origination. |
---|
3765 | |
---|
3766 | An origin server MUST NOT send a Date header field if it does not |
---|
3767 | have a clock capable of providing a reasonable approximation of the |
---|
3768 | current instance in Coordinated Universal Time. An origin server MAY |
---|
3769 | send a Date header field if the response is in the 1xx |
---|
3770 | (Informational) or 5xx (Server Error) class of status codes. An |
---|
3771 | origin server MUST send a Date header field in all other cases. |
---|
3772 | |
---|
3773 | A recipient with a clock that receives a response message without a |
---|
3774 | Date header field MUST record the time it was received and append a |
---|
3775 | corresponding Date header field to the message's header section if it |
---|
3776 | is cached or forwarded downstream. |
---|
3777 | |
---|
3778 | A user agent MAY send a Date header field in a request, though |
---|
3779 | generally will not do so unless it is believed to convey useful |
---|
3780 | information to the server. For example, custom applications of HTTP |
---|
3781 | might convey a Date if the server is expected to adjust its |
---|
3782 | interpretation of the user's request based on differences between the |
---|
3783 | user agent and server clocks. |
---|
3784 | |
---|
3785 | 7.1.2. Location |
---|
3786 | |
---|
3787 | The "Location" header field is used in some responses to refer to a |
---|
3788 | specific resource in relation to the response. The type of |
---|
3789 | relationship is defined by the combination of request method and |
---|
3790 | status code semantics. |
---|
3791 | |
---|
3792 | Location = URI-reference |
---|
3793 | |
---|
3794 | The field value consists of a single URI-reference. When it has the |
---|
3795 | form of a relative reference ([RFC3986], Section 4.2), the final |
---|
3796 | value is computed by resolving it against the effective request URI |
---|
3797 | ([RFC3986], Section 5). |
---|
3798 | |
---|
3799 | For 201 (Created) responses, the Location value refers to the primary |
---|
3800 | resource created by the request. For 3xx (Redirection) responses, |
---|
3801 | the Location value refers to the preferred target resource for |
---|
3802 | automatically redirecting the request. |
---|
3803 | |
---|
3804 | |
---|
3805 | |
---|
3806 | |
---|
3807 | Fielding & Reschke Expires November 7, 2014 [Page 68] |
---|
3808 | |
---|
3809 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
3810 | |
---|
3811 | |
---|
3812 | If the Location value provided in a 3xx (Redirection) does not have a |
---|
3813 | fragment component, a user agent MUST process the redirection as if |
---|
3814 | the value inherits the fragment component of the URI reference used |
---|
3815 | to generate the request target (i.e., the redirection inherits the |
---|
3816 | original reference's fragment, if any). |
---|
3817 | |
---|
3818 | For example, a GET request generated for the URI reference |
---|
3819 | "http://www.example.org/~tim" might result in a 303 (See Other) |
---|
3820 | response containing the header field: |
---|
3821 | |
---|
3822 | Location: /People.html#tim |
---|
3823 | |
---|
3824 | which suggests that the user agent redirect to |
---|
3825 | "http://www.example.org/People.html#tim" |
---|
3826 | |
---|
3827 | Likewise, a GET request generated for the URI reference |
---|
3828 | "http://www.example.org/index.html#larry" might result in a 301 |
---|
3829 | (Moved Permanently) response containing the header field: |
---|
3830 | |
---|
3831 | Location: http://www.example.net/index.html |
---|
3832 | |
---|
3833 | which suggests that the user agent redirect to |
---|
3834 | "http://www.example.net/index.html#larry", preserving the original |
---|
3835 | fragment identifier. |
---|
3836 | |
---|
3837 | There are circumstances in which a fragment identifier in a Location |
---|
3838 | value would not be appropriate. For example, the Location header |
---|
3839 | field in a 201 (Created) response is supposed to provide a URI that |
---|
3840 | is specific to the created resource. |
---|
3841 | |
---|
3842 | Note: Some recipients attempt to recover from Location fields that |
---|
3843 | are not valid URI references. This specification does not mandate |
---|
3844 | or define such processing, but does allow it for the sake of |
---|
3845 | robustness. |
---|
3846 | |
---|
3847 | Note: The Content-Location header field (Section 3.1.4.2) differs |
---|
3848 | from Location in that the Content-Location refers to the most |
---|
3849 | specific resource corresponding to the enclosed representation. |
---|
3850 | It is therefore possible for a response to contain both the |
---|
3851 | Location and Content-Location header fields. |
---|
3852 | |
---|
3853 | 7.1.3. Retry-After |
---|
3854 | |
---|
3855 | Servers send the "Retry-After" header field to indicate how long the |
---|
3856 | user agent ought to wait before making a follow-up request. When |
---|
3857 | sent with a 503 (Service Unavailable) response, Retry-After indicates |
---|
3858 | how long the service is expected to be unavailable to the client. |
---|
3859 | When sent with any 3xx (Redirection) response, Retry-After indicates |
---|
3860 | |
---|
3861 | |
---|
3862 | |
---|
3863 | Fielding & Reschke Expires November 7, 2014 [Page 69] |
---|
3864 | |
---|
3865 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
3866 | |
---|
3867 | |
---|
3868 | the minimum time that the user agent is asked to wait before issuing |
---|
3869 | the redirected request. |
---|
3870 | |
---|
3871 | The value of this field can be either an HTTP-date or a number of |
---|
3872 | seconds to delay after the response is received. |
---|
3873 | |
---|
3874 | Retry-After = HTTP-date / delay-seconds |
---|
3875 | |
---|
3876 | A delay-seconds value is a non-negative decimal integer, representing |
---|
3877 | time in seconds. |
---|
3878 | |
---|
3879 | delay-seconds = 1*DIGIT |
---|
3880 | |
---|
3881 | Two examples of its use are |
---|
3882 | |
---|
3883 | Retry-After: Fri, 31 Dec 1999 23:59:59 GMT |
---|
3884 | Retry-After: 120 |
---|
3885 | |
---|
3886 | In the latter example, the delay is 2 minutes. |
---|
3887 | |
---|
3888 | 7.1.4. Vary |
---|
3889 | |
---|
3890 | The "Vary" header field in a response describes what parts of a |
---|
3891 | request message, aside from the method, Host header field, and |
---|
3892 | request target, might influence the origin server's process for |
---|
3893 | selecting and representing this response. The value consists of |
---|
3894 | either a single asterisk ("*") or a list of header field names (case- |
---|
3895 | insensitive). |
---|
3896 | |
---|
3897 | Vary = "*" / 1#field-name |
---|
3898 | |
---|
3899 | A Vary field value of "*" signals that anything about the request |
---|
3900 | might play a role in selecting the response representation, possibly |
---|
3901 | including elements outside the message syntax (e.g., the client's |
---|
3902 | network address). A recipient will not be able to determine whether |
---|
3903 | this response is appropriate for a later request without forwarding |
---|
3904 | the request to the origin server. A proxy MUST NOT generate a Vary |
---|
3905 | field with a "*" value. |
---|
3906 | |
---|
3907 | A Vary field value consisting of a comma-separated list of names |
---|
3908 | indicates that the named request header fields, known as the |
---|
3909 | selecting header fields, might have a role in selecting the |
---|
3910 | representation. The potential selecting header fields are not |
---|
3911 | limited to those defined by this specification. |
---|
3912 | |
---|
3913 | |
---|
3914 | |
---|
3915 | |
---|
3916 | |
---|
3917 | |
---|
3918 | |
---|
3919 | Fielding & Reschke Expires November 7, 2014 [Page 70] |
---|
3920 | |
---|
3921 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
3922 | |
---|
3923 | |
---|
3924 | For example, a response that contains |
---|
3925 | |
---|
3926 | Vary: accept-encoding, accept-language |
---|
3927 | |
---|
3928 | indicates that the origin server might have used the request's |
---|
3929 | Accept-Encoding and Accept-Language fields (or lack thereof) as |
---|
3930 | determining factors while choosing the content for this response. |
---|
3931 | |
---|
3932 | An origin server might send Vary with a list of fields for two |
---|
3933 | purposes: |
---|
3934 | |
---|
3935 | 1. To inform cache recipients that they MUST NOT use this response |
---|
3936 | to satisfy a later request unless the later request has the same |
---|
3937 | values for the listed fields as the original request (Section 4.1 |
---|
3938 | of [RFC7234]). In other words, Vary expands the cache key |
---|
3939 | required to match a new request to the stored cache entry. |
---|
3940 | |
---|
3941 | 2. To inform user agent recipients that this response is subject to |
---|
3942 | content negotiation (Section 5.3) and that a different |
---|
3943 | representation might be sent in a subsequent request if |
---|
3944 | additional parameters are provided in the listed header fields |
---|
3945 | (proactive negotiation). |
---|
3946 | |
---|
3947 | An origin server SHOULD send a Vary header field when its algorithm |
---|
3948 | for selecting a representation varies based on aspects of the request |
---|
3949 | message other than the method and request target, unless the variance |
---|
3950 | cannot be crossed or the origin server has been deliberately |
---|
3951 | configured to prevent cache transparency. For example, there is no |
---|
3952 | need to send the Authorization field name in Vary because reuse |
---|
3953 | across users is constrained by the field definition (Section 4.2 of |
---|
3954 | [RFC7235]). Likewise, an origin server might use Cache-Control |
---|
3955 | directives (Section 5.2 of [RFC7234]) to supplant Vary if it |
---|
3956 | considers the variance less significant than the performance cost of |
---|
3957 | Vary's impact on caching. |
---|
3958 | |
---|
3959 | 7.2. Validator Header Fields |
---|
3960 | |
---|
3961 | Validator header fields convey metadata about the selected |
---|
3962 | representation (Section 3). In responses to safe requests, validator |
---|
3963 | fields describe the selected representation chosen by the origin |
---|
3964 | server while handling the response. Note that, depending on the |
---|
3965 | status code semantics, the selected representation for a given |
---|
3966 | response is not necessarily the same as the representation enclosed |
---|
3967 | as response payload. |
---|
3968 | |
---|
3969 | In a successful response to a state-changing request, validator |
---|
3970 | fields describe the new representation that has replaced the prior |
---|
3971 | selected representation as a result of processing the request. |
---|
3972 | |
---|
3973 | |
---|
3974 | |
---|
3975 | Fielding & Reschke Expires November 7, 2014 [Page 71] |
---|
3976 | |
---|
3977 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
3978 | |
---|
3979 | |
---|
3980 | For example, an ETag header field in a 201 response communicates the |
---|
3981 | entity-tag of the newly created resource's representation, so that it |
---|
3982 | can be used in later conditional requests to prevent the "lost |
---|
3983 | update" problem [RFC7232]. |
---|
3984 | |
---|
3985 | +-------------------+--------------------------+ |
---|
3986 | | Header Field Name | Defined in... | |
---|
3987 | +-------------------+--------------------------+ |
---|
3988 | | ETag | Section 2.3 of [RFC7232] | |
---|
3989 | | Last-Modified | Section 2.2 of [RFC7232] | |
---|
3990 | +-------------------+--------------------------+ |
---|
3991 | |
---|
3992 | 7.3. Authentication Challenges |
---|
3993 | |
---|
3994 | Authentication challenges indicate what mechanisms are available for |
---|
3995 | the client to provide authentication credentials in future requests. |
---|
3996 | |
---|
3997 | +--------------------+--------------------------+ |
---|
3998 | | Header Field Name | Defined in... | |
---|
3999 | +--------------------+--------------------------+ |
---|
4000 | | WWW-Authenticate | Section 4.1 of [RFC7235] | |
---|
4001 | | Proxy-Authenticate | Section 4.3 of [RFC7235] | |
---|
4002 | +--------------------+--------------------------+ |
---|
4003 | |
---|
4004 | 7.4. Response Context |
---|
4005 | |
---|
4006 | The remaining response header fields provide more information about |
---|
4007 | the target resource for potential use in later requests. |
---|
4008 | |
---|
4009 | +-------------------+--------------------------+ |
---|
4010 | | Header Field Name | Defined in... | |
---|
4011 | +-------------------+--------------------------+ |
---|
4012 | | Accept-Ranges | Section 2.3 of [RFC7233] | |
---|
4013 | | Allow | Section 7.4.1 | |
---|
4014 | | Server | Section 7.4.2 | |
---|
4015 | +-------------------+--------------------------+ |
---|
4016 | |
---|
4017 | 7.4.1. Allow |
---|
4018 | |
---|
4019 | The "Allow" header field lists the set of methods advertised as |
---|
4020 | supported by the target resource. The purpose of this field is |
---|
4021 | strictly to inform the recipient of valid request methods associated |
---|
4022 | with the resource. |
---|
4023 | |
---|
4024 | Allow = #method |
---|
4025 | |
---|
4026 | Example of use: |
---|
4027 | |
---|
4028 | |
---|
4029 | |
---|
4030 | |
---|
4031 | Fielding & Reschke Expires November 7, 2014 [Page 72] |
---|
4032 | |
---|
4033 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
4034 | |
---|
4035 | |
---|
4036 | Allow: GET, HEAD, PUT |
---|
4037 | |
---|
4038 | The actual set of allowed methods is defined by the origin server at |
---|
4039 | the time of each request. An origin server MUST generate an Allow |
---|
4040 | field in a 405 (Method Not Allowed) response and MAY do so in any |
---|
4041 | other response. An empty Allow field value indicates that the |
---|
4042 | resource allows no methods, which might occur in a 405 response if |
---|
4043 | the resource has been temporarily disabled by configuration. |
---|
4044 | |
---|
4045 | A proxy MUST NOT modify the Allow header field -- it does not need to |
---|
4046 | understand all of the indicated methods in order to handle them |
---|
4047 | according to the generic message handling rules. |
---|
4048 | |
---|
4049 | 7.4.2. Server |
---|
4050 | |
---|
4051 | The "Server" header field contains information about the software |
---|
4052 | used by the origin server to handle the request, which is often used |
---|
4053 | by clients to help identify the scope of reported interoperability |
---|
4054 | problems, to work around or tailor requests to avoid particular |
---|
4055 | server limitations, and for analytics regarding server or operating |
---|
4056 | system use. An origin server MAY generate a Server field in its |
---|
4057 | responses. |
---|
4058 | |
---|
4059 | Server = product *( RWS ( product / comment ) ) |
---|
4060 | |
---|
4061 | The Server field-value consists of one or more product identifiers, |
---|
4062 | each followed by zero or more comments (Section 3.2 of [RFC7230]), |
---|
4063 | which together identify the origin server software and its |
---|
4064 | significant subproducts. By convention, the product identifiers are |
---|
4065 | listed in decreasing order of their significance for identifying the |
---|
4066 | origin server software. Each product identifier consists of a name |
---|
4067 | and optional version, as defined in Section 5.5.3. |
---|
4068 | |
---|
4069 | Example: |
---|
4070 | |
---|
4071 | Server: CERN/3.0 libwww/2.17 |
---|
4072 | |
---|
4073 | An origin server SHOULD NOT generate a Server field containing |
---|
4074 | needlessly fine-grained detail and SHOULD limit the addition of |
---|
4075 | subproducts by third parties. Overly long and detailed Server field |
---|
4076 | values increase response latency and potentially reveal internal |
---|
4077 | implementation details that might make it (slightly) easier for |
---|
4078 | attackers to find and exploit known security holes. |
---|
4079 | |
---|
4080 | 8. IANA Considerations |
---|
4081 | |
---|
4082 | |
---|
4083 | |
---|
4084 | |
---|
4085 | |
---|
4086 | |
---|
4087 | Fielding & Reschke Expires November 7, 2014 [Page 73] |
---|
4088 | |
---|
4089 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
4090 | |
---|
4091 | |
---|
4092 | 8.1. Method Registry |
---|
4093 | |
---|
4094 | The HTTP Method Registry defines the name space for the request |
---|
4095 | method token (Section 4). The method registry will be created and |
---|
4096 | maintained at (the suggested URI) |
---|
4097 | <http://www.iana.org/assignments/http-methods>. |
---|
4098 | |
---|
4099 | 8.1.1. Procedure |
---|
4100 | |
---|
4101 | HTTP method registrations MUST include the following fields: |
---|
4102 | |
---|
4103 | o Method Name (see Section 4) |
---|
4104 | |
---|
4105 | o Safe ("yes" or "no", see Section 4.2.1) |
---|
4106 | |
---|
4107 | o Idempotent ("yes" or "no", see Section 4.2.2) |
---|
4108 | |
---|
4109 | o Pointer to specification text |
---|
4110 | |
---|
4111 | Values to be added to this name space require IETF Review (see |
---|
4112 | [RFC5226], Section 4.1). |
---|
4113 | |
---|
4114 | 8.1.2. Considerations for New Methods |
---|
4115 | |
---|
4116 | Standardized methods are generic; that is, they are potentially |
---|
4117 | applicable to any resource, not just one particular media type, kind |
---|
4118 | of resource, or application. As such, it is preferred that new |
---|
4119 | methods be registered in a document that isn't specific to a single |
---|
4120 | application or data format, since orthogonal technologies deserve |
---|
4121 | orthogonal specification. |
---|
4122 | |
---|
4123 | Since message parsing (Section 3.3 of [RFC7230]) needs to be |
---|
4124 | independent of method semantics (aside from responses to HEAD), |
---|
4125 | definitions of new methods cannot change the parsing algorithm or |
---|
4126 | prohibit the presence of a message body on either the request or the |
---|
4127 | response message. Definitions of new methods can specify that only a |
---|
4128 | zero-length message body is allowed by requiring a Content-Length |
---|
4129 | header field with a value of "0". |
---|
4130 | |
---|
4131 | A new method definition needs to indicate whether it is safe |
---|
4132 | (Section 4.2.1), idempotent (Section 4.2.2), cacheable |
---|
4133 | (Section 4.2.3), what semantics are to be associated with the payload |
---|
4134 | body if any is present in the request, and what refinements the |
---|
4135 | method makes to header field or status code semantics. If the new |
---|
4136 | method is cacheable, its definition ought to describe how, and under |
---|
4137 | what conditions, a cache can store a response and use it to satisfy a |
---|
4138 | subsequent request. The new method ought to describe whether it can |
---|
4139 | be made conditional (Section 5.2) and, if so, how a server responds |
---|
4140 | |
---|
4141 | |
---|
4142 | |
---|
4143 | Fielding & Reschke Expires November 7, 2014 [Page 74] |
---|
4144 | |
---|
4145 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
4146 | |
---|
4147 | |
---|
4148 | when the condition is false. Likewise, if the new method might have |
---|
4149 | some use for partial response semantics ([RFC7233]), it ought to |
---|
4150 | document this too. |
---|
4151 | |
---|
4152 | Note: Avoid defining a method name that starts with "M-", since |
---|
4153 | that prefix might be misinterpreted as having the semantics |
---|
4154 | assigned to it by [RFC2774]. |
---|
4155 | |
---|
4156 | 8.1.3. Registrations |
---|
4157 | |
---|
4158 | The HTTP Method Registry shall be populated with the registrations |
---|
4159 | below: |
---|
4160 | |
---|
4161 | +---------+------+------------+---------------+ |
---|
4162 | | Method | Safe | Idempotent | Reference | |
---|
4163 | +---------+------+------------+---------------+ |
---|
4164 | | CONNECT | no | no | Section 4.3.6 | |
---|
4165 | | DELETE | no | yes | Section 4.3.5 | |
---|
4166 | | GET | yes | yes | Section 4.3.1 | |
---|
4167 | | HEAD | yes | yes | Section 4.3.2 | |
---|
4168 | | OPTIONS | yes | yes | Section 4.3.7 | |
---|
4169 | | POST | no | no | Section 4.3.3 | |
---|
4170 | | PUT | no | yes | Section 4.3.4 | |
---|
4171 | | TRACE | yes | yes | Section 4.3.8 | |
---|
4172 | +---------+------+------------+---------------+ |
---|
4173 | |
---|
4174 | 8.2. Status Code Registry |
---|
4175 | |
---|
4176 | The HTTP Status Code Registry defines the name space for the response |
---|
4177 | status-code token (Section 6). The status code registry is |
---|
4178 | maintained at <http://www.iana.org/assignments/http-status-codes>. |
---|
4179 | |
---|
4180 | This Section replaces the registration procedure for HTTP Status |
---|
4181 | Codes previously defined in Section 7.1 of [RFC2817]. |
---|
4182 | |
---|
4183 | 8.2.1. Procedure |
---|
4184 | |
---|
4185 | A registration MUST include the following fields: |
---|
4186 | |
---|
4187 | o Status Code (3 digits) |
---|
4188 | |
---|
4189 | o Short Description |
---|
4190 | |
---|
4191 | o Pointer to specification text |
---|
4192 | |
---|
4193 | Values to be added to the HTTP status code name space require IETF |
---|
4194 | Review (see [RFC5226], Section 4.1). |
---|
4195 | |
---|
4196 | |
---|
4197 | |
---|
4198 | |
---|
4199 | Fielding & Reschke Expires November 7, 2014 [Page 75] |
---|
4200 | |
---|
4201 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
4202 | |
---|
4203 | |
---|
4204 | 8.2.2. Considerations for New Status Codes |
---|
4205 | |
---|
4206 | When it is necessary to express semantics for a response that are not |
---|
4207 | defined by current status codes, a new status code can be registered. |
---|
4208 | Status codes are generic; they are potentially applicable to any |
---|
4209 | resource, not just one particular media type, kind of resource, or |
---|
4210 | application of HTTP. As such, it is preferred that new status codes |
---|
4211 | be registered in a document that isn't specific to a single |
---|
4212 | application. |
---|
4213 | |
---|
4214 | New status codes are required to fall under one of the categories |
---|
4215 | defined in Section 6. To allow existing parsers to process the |
---|
4216 | response message, new status codes cannot disallow a payload, |
---|
4217 | although they can mandate a zero-length payload body. |
---|
4218 | |
---|
4219 | Proposals for new status codes that are not yet widely deployed ought |
---|
4220 | to avoid allocating a specific number for the code until there is |
---|
4221 | clear consensus that it will be registered; instead, early drafts can |
---|
4222 | use a notation such as "4NN", or "3N0" .. "3N9", to indicate the |
---|
4223 | class of the proposed status code(s) without consuming a number |
---|
4224 | prematurely. |
---|
4225 | |
---|
4226 | The definition of a new status code ought to explain the request |
---|
4227 | conditions that would cause a response containing that status code |
---|
4228 | (e.g., combinations of request header fields and/or method(s)) along |
---|
4229 | with any dependencies on response header fields (e.g., what fields |
---|
4230 | are required, what fields can modify the semantics, and what header |
---|
4231 | field semantics are further refined when used with the new status |
---|
4232 | code). |
---|
4233 | |
---|
4234 | The definition of a new status code ought to specify whether or not |
---|
4235 | it is cacheable. Note that all status codes can be cached if the |
---|
4236 | response they occur in has explicit freshness information; however, |
---|
4237 | status codes that are defined as being cacheable are allowed to be |
---|
4238 | cached without explicit freshness information. Likewise, the |
---|
4239 | definition of a status code can place constraints upon cache |
---|
4240 | behavior. See [RFC7234] for more information. |
---|
4241 | |
---|
4242 | Finally, the definition of a new status code ought to indicate |
---|
4243 | whether the payload has any implied association with an identified |
---|
4244 | resource (Section 3.1.4.1). |
---|
4245 | |
---|
4246 | 8.2.3. Registrations |
---|
4247 | |
---|
4248 | The HTTP Status Code Registry shall be updated with the registrations |
---|
4249 | below: |
---|
4250 | |
---|
4251 | |
---|
4252 | |
---|
4253 | |
---|
4254 | |
---|
4255 | Fielding & Reschke Expires November 7, 2014 [Page 76] |
---|
4256 | |
---|
4257 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
4258 | |
---|
4259 | |
---|
4260 | +-------+-------------------------------+----------------+ |
---|
4261 | | Value | Description | Reference | |
---|
4262 | +-------+-------------------------------+----------------+ |
---|
4263 | | 100 | Continue | Section 6.2.1 | |
---|
4264 | | 101 | Switching Protocols | Section 6.2.2 | |
---|
4265 | | 200 | OK | Section 6.3.1 | |
---|
4266 | | 201 | Created | Section 6.3.2 | |
---|
4267 | | 202 | Accepted | Section 6.3.3 | |
---|
4268 | | 203 | Non-Authoritative Information | Section 6.3.4 | |
---|
4269 | | 204 | No Content | Section 6.3.5 | |
---|
4270 | | 205 | Reset Content | Section 6.3.6 | |
---|
4271 | | 300 | Multiple Choices | Section 6.4.1 | |
---|
4272 | | 301 | Moved Permanently | Section 6.4.2 | |
---|
4273 | | 302 | Found | Section 6.4.3 | |
---|
4274 | | 303 | See Other | Section 6.4.4 | |
---|
4275 | | 305 | Use Proxy | Section 6.4.5 | |
---|
4276 | | 306 | (Unused) | Section 6.4.6 | |
---|
4277 | | 307 | Temporary Redirect | Section 6.4.7 | |
---|
4278 | | 400 | Bad Request | Section 6.5.1 | |
---|
4279 | | 402 | Payment Required | Section 6.5.2 | |
---|
4280 | | 403 | Forbidden | Section 6.5.3 | |
---|
4281 | | 404 | Not Found | Section 6.5.4 | |
---|
4282 | | 405 | Method Not Allowed | Section 6.5.5 | |
---|
4283 | | 406 | Not Acceptable | Section 6.5.6 | |
---|
4284 | | 408 | Request Timeout | Section 6.5.7 | |
---|
4285 | | 409 | Conflict | Section 6.5.8 | |
---|
4286 | | 410 | Gone | Section 6.5.9 | |
---|
4287 | | 411 | Length Required | Section 6.5.10 | |
---|
4288 | | 413 | Payload Too Large | Section 6.5.11 | |
---|
4289 | | 414 | URI Too Long | Section 6.5.12 | |
---|
4290 | | 415 | Unsupported Media Type | Section 6.5.13 | |
---|
4291 | | 417 | Expectation Failed | Section 6.5.14 | |
---|
4292 | | 426 | Upgrade Required | Section 6.5.15 | |
---|
4293 | | 500 | Internal Server Error | Section 6.6.1 | |
---|
4294 | | 501 | Not Implemented | Section 6.6.2 | |
---|
4295 | | 502 | Bad Gateway | Section 6.6.3 | |
---|
4296 | | 503 | Service Unavailable | Section 6.6.4 | |
---|
4297 | | 504 | Gateway Timeout | Section 6.6.5 | |
---|
4298 | | 505 | HTTP Version Not Supported | Section 6.6.6 | |
---|
4299 | +-------+-------------------------------+----------------+ |
---|
4300 | |
---|
4301 | 8.3. Header Field Registry |
---|
4302 | |
---|
4303 | HTTP header fields are registered within the Message Header Field |
---|
4304 | Registry located at <http://www.iana.org/assignments/message-headers/ |
---|
4305 | message-header-index.html>, as defined by [BCP90]. |
---|
4306 | |
---|
4307 | |
---|
4308 | |
---|
4309 | |
---|
4310 | |
---|
4311 | Fielding & Reschke Expires November 7, 2014 [Page 77] |
---|
4312 | |
---|
4313 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
4314 | |
---|
4315 | |
---|
4316 | 8.3.1. Considerations for New Header Fields |
---|
4317 | |
---|
4318 | Header fields are key:value pairs that can be used to communicate |
---|
4319 | data about the message, its payload, the target resource, or the |
---|
4320 | connection (i.e., control data). See Section 3.2 of [RFC7230] for a |
---|
4321 | general definition of header field syntax in HTTP messages. |
---|
4322 | |
---|
4323 | The requirements for header field names are defined in [BCP90]. |
---|
4324 | |
---|
4325 | Authors of specifications defining new fields are advised to keep the |
---|
4326 | name as short as practical and to not prefix the name with "X-" |
---|
4327 | unless the header field will never be used on the Internet. (The |
---|
4328 | "x-" prefix idiom has been extensively misused in practice; it was |
---|
4329 | intended to only be used as a mechanism for avoiding name collisions |
---|
4330 | inside proprietary software or intranet processing, since the prefix |
---|
4331 | would ensure that private names never collide with a newly registered |
---|
4332 | Internet name; see [BCP178] for further information) |
---|
4333 | |
---|
4334 | New header field values typically have their syntax defined using |
---|
4335 | ABNF ([RFC5234]), using the extension defined in Section 7 of |
---|
4336 | [RFC7230] as necessary, and are usually constrained to the range of |
---|
4337 | ASCII characters. Header fields needing a greater range of |
---|
4338 | characters can use an encoding such as the one defined in [RFC5987]. |
---|
4339 | |
---|
4340 | Leading and trailing whitespace in raw field values is removed upon |
---|
4341 | field parsing (Section 3.2.4 of [RFC7230]). Field definitions where |
---|
4342 | leading or trailing whitespace in values is significant will have to |
---|
4343 | use a container syntax such as quoted-string (Section 3.2.6 of |
---|
4344 | [RFC7230]). |
---|
4345 | |
---|
4346 | Because commas (",") are used as a generic delimiter between field- |
---|
4347 | values, they need to be treated with care if they are allowed in the |
---|
4348 | field-value. Typically, components that might contain a comma are |
---|
4349 | protected with double-quotes using the quoted-string ABNF production. |
---|
4350 | |
---|
4351 | For example, a textual date and a URI (either of which might contain |
---|
4352 | a comma) could be safely carried in field-values like these: |
---|
4353 | |
---|
4354 | Example-URI-Field: "http://example.com/a.html,foo", |
---|
4355 | "http://without-a-comma.example.com/" |
---|
4356 | Example-Date-Field: "Sat, 04 May 1996", "Wed, 14 Sep 2005" |
---|
4357 | |
---|
4358 | Note that double-quote delimiters almost always are used with the |
---|
4359 | quoted-string production; using a different syntax inside double- |
---|
4360 | quotes will likely cause unnecessary confusion. |
---|
4361 | |
---|
4362 | Many header fields use a format including (case-insensitively) named |
---|
4363 | parameters (for instance, Content-Type, defined in Section 3.1.1.5). |
---|
4364 | |
---|
4365 | |
---|
4366 | |
---|
4367 | Fielding & Reschke Expires November 7, 2014 [Page 78] |
---|
4368 | |
---|
4369 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
4370 | |
---|
4371 | |
---|
4372 | Allowing both unquoted (token) and quoted (quoted-string) syntax for |
---|
4373 | the parameter value enables recipients to use existing parser |
---|
4374 | components. When allowing both forms, the meaning of a parameter |
---|
4375 | value ought to be independent of the syntax used for it (for an |
---|
4376 | example, see the notes on parameter handling for media types in |
---|
4377 | Section 3.1.1.1). |
---|
4378 | |
---|
4379 | Authors of specifications defining new header fields are advised to |
---|
4380 | consider documenting: |
---|
4381 | |
---|
4382 | o Whether the field is a single value, or whether it can be a list |
---|
4383 | (delimited by commas; see Section 3.2 of [RFC7230]). |
---|
4384 | |
---|
4385 | If it does not use the list syntax, document how to treat messages |
---|
4386 | where the field occurs multiple times (a sensible default would be |
---|
4387 | to ignore the field, but this might not always be the right |
---|
4388 | choice). |
---|
4389 | |
---|
4390 | Note that intermediaries and software libraries might combine |
---|
4391 | multiple header field instances into a single one, despite the |
---|
4392 | field's definition not allowing the list syntax. A robust format |
---|
4393 | enables recipients to discover these situations (good example: |
---|
4394 | "Content-Type", as the comma can only appear inside quoted |
---|
4395 | strings; bad example: "Location", as a comma can occur inside a |
---|
4396 | URI). |
---|
4397 | |
---|
4398 | o Under what conditions the header field can be used; e.g., only in |
---|
4399 | responses or requests, in all messages, only on responses to a |
---|
4400 | particular request method, etc. |
---|
4401 | |
---|
4402 | o Whether the field should be stored by origin servers that |
---|
4403 | understand it upon a PUT request. |
---|
4404 | |
---|
4405 | o Whether the field semantics are further refined by the context, |
---|
4406 | such as by existing request methods or status codes. |
---|
4407 | |
---|
4408 | o Whether it is appropriate to list the field-name in the Connection |
---|
4409 | header field (i.e., if the header field is to be hop-by-hop; see |
---|
4410 | Section 6.1 of [RFC7230]). |
---|
4411 | |
---|
4412 | o Under what conditions intermediaries are allowed to insert, |
---|
4413 | delete, or modify the field's value. |
---|
4414 | |
---|
4415 | o Whether it is appropriate to list the field-name in a Vary |
---|
4416 | response header field (e.g., when the request header field is used |
---|
4417 | by an origin server's content selection algorithm; see |
---|
4418 | Section 7.1.4). |
---|
4419 | |
---|
4420 | |
---|
4421 | |
---|
4422 | |
---|
4423 | Fielding & Reschke Expires November 7, 2014 [Page 79] |
---|
4424 | |
---|
4425 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
4426 | |
---|
4427 | |
---|
4428 | o Whether the header field is useful or allowable in trailers (see |
---|
4429 | Section 4.1 of [RFC7230]). |
---|
4430 | |
---|
4431 | o Whether the header field ought to be preserved across redirects. |
---|
4432 | |
---|
4433 | o Whether it introduces any additional security considerations, such |
---|
4434 | as disclosure of privacy-related data. |
---|
4435 | |
---|
4436 | 8.3.2. Registrations |
---|
4437 | |
---|
4438 | The Message Header Field Registry shall be updated with the following |
---|
4439 | permanent registrations: |
---|
4440 | |
---|
4441 | +-------------------+----------+----------+-----------------+ |
---|
4442 | | Header Field Name | Protocol | Status | Reference | |
---|
4443 | +-------------------+----------+----------+-----------------+ |
---|
4444 | | Accept | http | standard | Section 5.3.2 | |
---|
4445 | | Accept-Charset | http | standard | Section 5.3.3 | |
---|
4446 | | Accept-Encoding | http | standard | Section 5.3.4 | |
---|
4447 | | Accept-Language | http | standard | Section 5.3.5 | |
---|
4448 | | Allow | http | standard | Section 7.4.1 | |
---|
4449 | | Content-Encoding | http | standard | Section 3.1.2.2 | |
---|
4450 | | Content-Language | http | standard | Section 3.1.3.2 | |
---|
4451 | | Content-Location | http | standard | Section 3.1.4.2 | |
---|
4452 | | Content-Type | http | standard | Section 3.1.1.5 | |
---|
4453 | | Date | http | standard | Section 7.1.1.2 | |
---|
4454 | | Expect | http | standard | Section 5.1.1 | |
---|
4455 | | From | http | standard | Section 5.5.1 | |
---|
4456 | | Location | http | standard | Section 7.1.2 | |
---|
4457 | | MIME-Version | http | standard | Appendix A.1 | |
---|
4458 | | Max-Forwards | http | standard | Section 5.1.2 | |
---|
4459 | | Referer | http | standard | Section 5.5.2 | |
---|
4460 | | Retry-After | http | standard | Section 7.1.3 | |
---|
4461 | | Server | http | standard | Section 7.4.2 | |
---|
4462 | | User-Agent | http | standard | Section 5.5.3 | |
---|
4463 | | Vary | http | standard | Section 7.1.4 | |
---|
4464 | +-------------------+----------+----------+-----------------+ |
---|
4465 | |
---|
4466 | The change controller for the above registrations is: "IETF |
---|
4467 | (iesg@ietf.org) - Internet Engineering Task Force". |
---|
4468 | |
---|
4469 | 8.4. Content Coding Registry |
---|
4470 | |
---|
4471 | The HTTP Content Coding Registry defines the name space for content |
---|
4472 | coding names (Section 4.2 of [RFC7230]). The content coding registry |
---|
4473 | is maintained at <http://www.iana.org/assignments/http-parameters>. |
---|
4474 | |
---|
4475 | |
---|
4476 | |
---|
4477 | |
---|
4478 | |
---|
4479 | Fielding & Reschke Expires November 7, 2014 [Page 80] |
---|
4480 | |
---|
4481 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
4482 | |
---|
4483 | |
---|
4484 | 8.4.1. Procedure |
---|
4485 | |
---|
4486 | Content Coding registrations MUST include the following fields: |
---|
4487 | |
---|
4488 | o Name |
---|
4489 | |
---|
4490 | o Description |
---|
4491 | |
---|
4492 | o Pointer to specification text |
---|
4493 | |
---|
4494 | Names of content codings MUST NOT overlap with names of transfer |
---|
4495 | codings (Section 4 of [RFC7230]), unless the encoding transformation |
---|
4496 | is identical (as is the case for the compression codings defined in |
---|
4497 | Section 4.2 of [RFC7230]). |
---|
4498 | |
---|
4499 | Values to be added to this name space require IETF Review (see |
---|
4500 | Section 4.1 of [RFC5226]), and MUST conform to the purpose of content |
---|
4501 | coding defined in this section. |
---|
4502 | |
---|
4503 | 8.4.2. Registrations |
---|
4504 | |
---|
4505 | The HTTP Content Codings Registry shall be updated with the |
---|
4506 | registrations below: |
---|
4507 | |
---|
4508 | +----------+----------------------------------------+---------------+ |
---|
4509 | | Name | Description | Reference | |
---|
4510 | +----------+----------------------------------------+---------------+ |
---|
4511 | | identity | Reserved (synonym for "no encoding" in | Section 5.3.4 | |
---|
4512 | | | Accept-Encoding) | | |
---|
4513 | +----------+----------------------------------------+---------------+ |
---|
4514 | |
---|
4515 | 9. Security Considerations |
---|
4516 | |
---|
4517 | This section is meant to inform developers, information providers, |
---|
4518 | and users of known security concerns relevant to HTTP semantics and |
---|
4519 | its use for transferring information over the Internet. |
---|
4520 | Considerations related to message syntax, parsing, and routing are |
---|
4521 | discussed in Section 9 of [RFC7230]. |
---|
4522 | |
---|
4523 | The list of considerations below is not exhaustive. Most security |
---|
4524 | concerns related to HTTP semantics are about securing server-side |
---|
4525 | applications (code behind the HTTP interface), securing user agent |
---|
4526 | processing of payloads received via HTTP, or secure use of the |
---|
4527 | Internet in general, rather than security of the protocol. Various |
---|
4528 | organizations maintain topical information and links to current |
---|
4529 | research on Web application security (e.g., [OWASP]). |
---|
4530 | |
---|
4531 | |
---|
4532 | |
---|
4533 | |
---|
4534 | |
---|
4535 | Fielding & Reschke Expires November 7, 2014 [Page 81] |
---|
4536 | |
---|
4537 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
4538 | |
---|
4539 | |
---|
4540 | 9.1. Attacks Based On File and Path Names |
---|
4541 | |
---|
4542 | Origin servers frequently make use of their local file system to |
---|
4543 | manage the mapping from effective request URI to resource |
---|
4544 | representations. Implementers need to be aware that most file |
---|
4545 | systems are not designed to protect against malicious file or path |
---|
4546 | names, and thus depend on the origin server to avoid mapping to file |
---|
4547 | names, folders, or directories that have special significance to the |
---|
4548 | system. |
---|
4549 | |
---|
4550 | For example, UNIX, Microsoft Windows, and other operating systems use |
---|
4551 | ".." as a path component to indicate a directory level above the |
---|
4552 | current one, and use specially named paths or file names to send data |
---|
4553 | to system devices. Similar naming conventions might exist within |
---|
4554 | other types of storage systems. Likewise, local storage systems have |
---|
4555 | an annoying tendency to prefer user-friendliness over security when |
---|
4556 | handling invalid or unexpected characters, recomposition of |
---|
4557 | decomposed characters, and case-normalization of case-insensitive |
---|
4558 | names. |
---|
4559 | |
---|
4560 | Attacks based on such special names tend to focus on either denial of |
---|
4561 | service (e.g., telling the server to read from a COM port) or |
---|
4562 | disclosure of configuration and source files that are not meant to be |
---|
4563 | served. |
---|
4564 | |
---|
4565 | 9.2. Attacks Based On Command, Code, or Query Injection |
---|
4566 | |
---|
4567 | Origin servers often use parameters within the URI as a means of |
---|
4568 | identifying system services, selecting database entries, or choosing |
---|
4569 | a data source. However, data received in a request cannot be |
---|
4570 | trusted. An attacker could construct any of the request data |
---|
4571 | elements (method, request-target, header fields, or body) to contain |
---|
4572 | data that might be misinterpreted as a command, code, or query when |
---|
4573 | passed through a command invocation, language interpreter, or |
---|
4574 | database interface. |
---|
4575 | |
---|
4576 | For example, SQL injection is a common attack wherein additional |
---|
4577 | query language is inserted within some part of the request-target or |
---|
4578 | header fields (e.g., Host, Referer, etc.). If the received data is |
---|
4579 | used directly within a SELECT statement, the query language might be |
---|
4580 | interpreted as a database command instead of a simple string value. |
---|
4581 | This type of implementation vulnerability is extremely common, in |
---|
4582 | spite of being easy to prevent. |
---|
4583 | |
---|
4584 | In general, resource implementations ought to avoid use of request |
---|
4585 | data in contexts that are processed or interpreted as instructions. |
---|
4586 | Parameters ought to be compared to fixed strings and acted upon as a |
---|
4587 | result of that comparison, rather than passed through an interface |
---|
4588 | |
---|
4589 | |
---|
4590 | |
---|
4591 | Fielding & Reschke Expires November 7, 2014 [Page 82] |
---|
4592 | |
---|
4593 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
4594 | |
---|
4595 | |
---|
4596 | that is not prepared for untrusted data. Received data that isn't |
---|
4597 | based on fixed parameters ought to be carefully filtered or encoded |
---|
4598 | to avoid being misinterpreted. |
---|
4599 | |
---|
4600 | Similar considerations apply to request data when it is stored and |
---|
4601 | later processed, such as within log files, monitoring tools, or when |
---|
4602 | included within a data format that allows embedded scripts. |
---|
4603 | |
---|
4604 | 9.3. Disclosure of Personal Information |
---|
4605 | |
---|
4606 | Clients are often privy to large amounts of personal information, |
---|
4607 | including both information provided by the user to interact with |
---|
4608 | resources (e.g., the user's name, location, mail address, passwords, |
---|
4609 | encryption keys, etc.) and information about the user's browsing |
---|
4610 | activity over time (e.g., history, bookmarks, etc.). Implementations |
---|
4611 | need to prevent unintentional disclosure of personal information. |
---|
4612 | |
---|
4613 | 9.4. Disclosure of Sensitive Information in URIs |
---|
4614 | |
---|
4615 | URIs are intended to be shared, not secured, even when they identify |
---|
4616 | secure resources. URIs are often shown on displays, added to |
---|
4617 | templates when a page is printed, and stored in a variety of |
---|
4618 | unprotected bookmark lists. It is therefore unwise to include |
---|
4619 | information within a URI that is sensitive, personally identifiable, |
---|
4620 | or a risk to disclose. |
---|
4621 | |
---|
4622 | Authors of services ought to avoid GET-based forms for the submission |
---|
4623 | of sensitive data because that data will be placed in the request- |
---|
4624 | target. Many existing servers, proxies, and user agents log or |
---|
4625 | display the request-target in places where it might be visible to |
---|
4626 | third parties. Such services ought to use POST-based form submission |
---|
4627 | instead. |
---|
4628 | |
---|
4629 | Since the Referer header field tells a target site about the context |
---|
4630 | that resulted in a request, it has the potential to reveal |
---|
4631 | information about the user's immediate browsing history and any |
---|
4632 | personal information that might be found in the referring resource's |
---|
4633 | URI. Limitations on Referer are described in Section 5.5.2 to |
---|
4634 | address some of its security considerations. |
---|
4635 | |
---|
4636 | 9.5. Disclosure of Fragment after Redirects |
---|
4637 | |
---|
4638 | Although fragment identifiers used within URI references are not sent |
---|
4639 | in requests, implementers ought to be aware that they will be visible |
---|
4640 | to the user agent and any extensions or scripts running as a result |
---|
4641 | of the response. In particular, when a redirect occurs and the |
---|
4642 | original request's fragment identifier is inherited by the new |
---|
4643 | reference in Location (Section 7.1.2), this might have the effect of |
---|
4644 | |
---|
4645 | |
---|
4646 | |
---|
4647 | Fielding & Reschke Expires November 7, 2014 [Page 83] |
---|
4648 | |
---|
4649 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
4650 | |
---|
4651 | |
---|
4652 | disclosing one site's fragment to another site. If the first site |
---|
4653 | uses personal information in fragments, it ought to ensure that |
---|
4654 | redirects to other sites include a (possibly empty) fragment |
---|
4655 | component in order to block that inheritance. |
---|
4656 | |
---|
4657 | 9.6. Disclosure of Product Information |
---|
4658 | |
---|
4659 | The User-Agent (Section 5.5.3), Via (Section 5.7.1 of [RFC7230]), and |
---|
4660 | Server (Section 7.4.2) header fields often reveal information about |
---|
4661 | the respective sender's software systems. In theory, this can make |
---|
4662 | it easier for an attacker to exploit known security holes; in |
---|
4663 | practice, attackers tend to try all potential holes regardless of the |
---|
4664 | apparent software versions being used. |
---|
4665 | |
---|
4666 | Proxies that serve as a portal through a network firewall ought to |
---|
4667 | take special precautions regarding the transfer of header information |
---|
4668 | that might identify hosts behind the firewall. The Via header field |
---|
4669 | allows intermediaries to replace sensitive machine names with |
---|
4670 | pseudonyms. |
---|
4671 | |
---|
4672 | 9.7. Browser Fingerprinting |
---|
4673 | |
---|
4674 | Browser fingerprinting is a set of techniques for identifying a |
---|
4675 | specific user agent over time through its unique set of |
---|
4676 | characteristics. These characteristics might include information |
---|
4677 | related to its TCP behavior, feature capabilities, and scripting |
---|
4678 | environment, though of particular interest here is the set of unique |
---|
4679 | characteristics that might be communicated via HTTP. Fingerprinting |
---|
4680 | is considered a privacy concern because it enables tracking of a user |
---|
4681 | agent's behavior over time without the corresponding controls that |
---|
4682 | the user might have over other forms of data collection (e.g., |
---|
4683 | cookies). Many general-purpose user agents (i.e., Web browsers) have |
---|
4684 | taken steps to reduce their fingerprints. |
---|
4685 | |
---|
4686 | There are a number of request header fields that might reveal |
---|
4687 | information to servers that is sufficiently unique to enable |
---|
4688 | fingerprinting. The From header field is the most obvious, though it |
---|
4689 | is expected that From will only be sent when self-identification is |
---|
4690 | desired by the user. Likewise, Cookie header fields are deliberately |
---|
4691 | designed to enable re-identification, so fingerprinting concerns only |
---|
4692 | apply to situations where cookies are disabled or restricted by the |
---|
4693 | user agent's configuration. |
---|
4694 | |
---|
4695 | The User-Agent header field might contain enough information to |
---|
4696 | uniquely identify a specific device, usually when combined with other |
---|
4697 | characteristics, particularly if the user agent sends excessive |
---|
4698 | details about the user's system or extensions. However, the source |
---|
4699 | of unique information that is least expected by users is proactive |
---|
4700 | |
---|
4701 | |
---|
4702 | |
---|
4703 | Fielding & Reschke Expires November 7, 2014 [Page 84] |
---|
4704 | |
---|
4705 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
4706 | |
---|
4707 | |
---|
4708 | negotiation (Section 5.3), including the Accept, Accept-Charset, |
---|
4709 | Accept-Encoding, and Accept-Language header fields. |
---|
4710 | |
---|
4711 | In addition to the fingerprinting concern, detailed use of the |
---|
4712 | Accept-Language header field can reveal information the user might |
---|
4713 | consider to be of a private nature. For example, understanding a |
---|
4714 | given language set might be strongly correlated to membership in a |
---|
4715 | particular ethnic group. An approach that limits such loss of |
---|
4716 | privacy would be for a user agent to omit the sending of Accept- |
---|
4717 | Language except for sites that have been whitelisted, perhaps via |
---|
4718 | interaction after detecting a Vary header field that indicates |
---|
4719 | language negotiation might be useful. |
---|
4720 | |
---|
4721 | In environments where proxies are used to enhance privacy, user |
---|
4722 | agents ought to be conservative in sending proactive negotiation |
---|
4723 | header fields. General-purpose user agents that provide a high |
---|
4724 | degree of header field configurability ought to inform users about |
---|
4725 | the loss of privacy that might result if too much detail is provided. |
---|
4726 | As an extreme privacy measure, proxies could filter the proactive |
---|
4727 | negotiation header fields in relayed requests. |
---|
4728 | |
---|
4729 | 10. Acknowledgments |
---|
4730 | |
---|
4731 | See Section 10 of [RFC7230]. |
---|
4732 | |
---|
4733 | 11. References |
---|
4734 | |
---|
4735 | 11.1. Normative References |
---|
4736 | |
---|
4737 | [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet |
---|
4738 | Mail Extensions (MIME) Part One: Format of Internet |
---|
4739 | Message Bodies", RFC 2045, November 1996. |
---|
4740 | |
---|
4741 | [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet |
---|
4742 | Mail Extensions (MIME) Part Two: Media Types", |
---|
4743 | RFC 2046, November 1996. |
---|
4744 | |
---|
4745 | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate |
---|
4746 | Requirement Levels", BCP 14, RFC 2119, March 1997. |
---|
4747 | |
---|
4748 | [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, |
---|
4749 | "Uniform Resource Identifier (URI): Generic Syntax", |
---|
4750 | STD 66, RFC 3986, January 2005. |
---|
4751 | |
---|
4752 | [RFC4647] Phillips, A., Ed. and M. Davis, Ed., "Matching of |
---|
4753 | Language Tags", BCP 47, RFC 4647, September 2006. |
---|
4754 | |
---|
4755 | [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for |
---|
4756 | |
---|
4757 | |
---|
4758 | |
---|
4759 | Fielding & Reschke Expires November 7, 2014 [Page 85] |
---|
4760 | |
---|
4761 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
4762 | |
---|
4763 | |
---|
4764 | Syntax Specifications: ABNF", STD 68, RFC 5234, |
---|
4765 | January 2008. |
---|
4766 | |
---|
4767 | [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for |
---|
4768 | Identifying Languages", BCP 47, RFC 5646, |
---|
4769 | September 2009. |
---|
4770 | |
---|
4771 | [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in |
---|
4772 | Internationalization in the IETF", BCP 166, RFC 6365, |
---|
4773 | September 2011. |
---|
4774 | |
---|
4775 | [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext |
---|
4776 | Transfer Protocol (HTTP/1.1): Message Syntax and |
---|
4777 | Routing", draft-ietf-httpbis-p1-messaging-latest (work |
---|
4778 | in progress), May 2014. |
---|
4779 | |
---|
4780 | [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext |
---|
4781 | Transfer Protocol (HTTP/1.1): Conditional Requests", |
---|
4782 | draft-ietf-httpbis-p4-conditional-latest (work in |
---|
4783 | progress), May 2014. |
---|
4784 | |
---|
4785 | [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., |
---|
4786 | "Hypertext Transfer Protocol (HTTP/1.1): Range |
---|
4787 | Requests", draft-ietf-httpbis-p5-range-latest (work in |
---|
4788 | progress), May 2014. |
---|
4789 | |
---|
4790 | [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, |
---|
4791 | Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", |
---|
4792 | draft-ietf-httpbis-p6-cache-latest (work in progress), |
---|
4793 | May 2014. |
---|
4794 | |
---|
4795 | [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext |
---|
4796 | Transfer Protocol (HTTP/1.1): Authentication", |
---|
4797 | draft-ietf-httpbis-p7-auth-latest (work in progress), |
---|
4798 | May 2014. |
---|
4799 | |
---|
4800 | 11.2. Informative References |
---|
4801 | |
---|
4802 | [BCP13] Freed, N., Klensin, J., and T. Hansen, "Media Type |
---|
4803 | Specifications and Registration Procedures", BCP 13, |
---|
4804 | RFC 6838, January 2013. |
---|
4805 | |
---|
4806 | [BCP178] Saint-Andre, P., Crocker, D., and M. Nottingham, |
---|
4807 | "Deprecating the "X-" Prefix and Similar Constructs in |
---|
4808 | Application Protocols", BCP 178, RFC 6648, June 2012. |
---|
4809 | |
---|
4810 | [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration |
---|
4811 | Procedures for Message Header Fields", BCP 90, |
---|
4812 | |
---|
4813 | |
---|
4814 | |
---|
4815 | Fielding & Reschke Expires November 7, 2014 [Page 86] |
---|
4816 | |
---|
4817 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
4818 | |
---|
4819 | |
---|
4820 | RFC 3864, September 2004. |
---|
4821 | |
---|
4822 | [OWASP] van der Stock, A., Ed., "A Guide to Building Secure Web |
---|
4823 | Applications and Web Services", The Open Web |
---|
4824 | Application Security Project (OWASP) 2.0.1, July 2005, |
---|
4825 | <https://www.owasp.org/>. |
---|
4826 | |
---|
4827 | [REST] Fielding, R., "Architectural Styles and the Design of |
---|
4828 | Network-based Software Architectures", |
---|
4829 | Doctoral Dissertation, University of California, |
---|
4830 | Irvine, September 2000, |
---|
4831 | <http://roy.gbiv.com/pubs/dissertation/top.htm>. |
---|
4832 | |
---|
4833 | [RFC1945] Berners-Lee, T., Fielding, R., and H. Nielsen, |
---|
4834 | "Hypertext Transfer Protocol -- HTTP/1.0", RFC 1945, |
---|
4835 | May 1996. |
---|
4836 | |
---|
4837 | [RFC2049] Freed, N. and N. Borenstein, "Multipurpose Internet |
---|
4838 | Mail Extensions (MIME) Part Five: Conformance Criteria |
---|
4839 | and Examples", RFC 2049, November 1996. |
---|
4840 | |
---|
4841 | [RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and |
---|
4842 | T. Berners-Lee, "Hypertext Transfer Protocol -- |
---|
4843 | HTTP/1.1", RFC 2068, January 1997. |
---|
4844 | |
---|
4845 | [RFC2295] Holtman, K. and A. Mutz, "Transparent Content |
---|
4846 | Negotiation in HTTP", RFC 2295, March 1998. |
---|
4847 | |
---|
4848 | [RFC2388] Masinter, L., "Returning Values from Forms: multipart/ |
---|
4849 | form-data", RFC 2388, August 1998. |
---|
4850 | |
---|
4851 | [RFC2557] Palme, F., Hopmann, A., Shelness, N., and E. Stefferud, |
---|
4852 | "MIME Encapsulation of Aggregate Documents, such as |
---|
4853 | HTML (MHTML)", RFC 2557, March 1999. |
---|
4854 | |
---|
4855 | [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., |
---|
4856 | Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext |
---|
4857 | Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. |
---|
4858 | |
---|
4859 | [RFC2774] Frystyk, H., Leach, P., and S. Lawrence, "An HTTP |
---|
4860 | Extension Framework", RFC 2774, February 2000. |
---|
4861 | |
---|
4862 | [RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within |
---|
4863 | HTTP/1.1", RFC 2817, May 2000. |
---|
4864 | |
---|
4865 | [RFC2978] Freed, N. and J. Postel, "IANA Charset Registration |
---|
4866 | Procedures", BCP 19, RFC 2978, October 2000. |
---|
4867 | |
---|
4868 | |
---|
4869 | |
---|
4870 | |
---|
4871 | Fielding & Reschke Expires November 7, 2014 [Page 87] |
---|
4872 | |
---|
4873 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
4874 | |
---|
4875 | |
---|
4876 | [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing |
---|
4877 | an IANA Considerations Section in RFCs", BCP 26, |
---|
4878 | RFC 5226, May 2008. |
---|
4879 | |
---|
4880 | [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer |
---|
4881 | Security (TLS) Protocol Version 1.2", RFC 5246, |
---|
4882 | August 2008. |
---|
4883 | |
---|
4884 | [RFC5322] Resnick, P., "Internet Message Format", RFC 5322, |
---|
4885 | October 2008. |
---|
4886 | |
---|
4887 | [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", |
---|
4888 | RFC 5789, March 2010. |
---|
4889 | |
---|
4890 | [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, |
---|
4891 | "Network Time Protocol Version 4: Protocol and |
---|
4892 | Algorithms Specification", RFC 5905, June 2010. |
---|
4893 | |
---|
4894 | [RFC5987] Reschke, J., "Character Set and Language Encoding for |
---|
4895 | Hypertext Transfer Protocol (HTTP) Header Field |
---|
4896 | Parameters", RFC 5987, August 2010. |
---|
4897 | |
---|
4898 | [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. |
---|
4899 | |
---|
4900 | [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, |
---|
4901 | April 2011. |
---|
4902 | |
---|
4903 | [RFC6266] Reschke, J., "Use of the Content-Disposition Header |
---|
4904 | Field in the Hypertext Transfer Protocol (HTTP)", |
---|
4905 | RFC 6266, June 2011. |
---|
4906 | |
---|
4907 | [status-308] Reschke, J., "The Hypertext Transfer Protocol (HTTP) |
---|
4908 | Status Code 308 (Permanent Redirect)", |
---|
4909 | draft-reschke-http-status-308-07 (work in progress), |
---|
4910 | March 2012. |
---|
4911 | |
---|
4912 | Appendix A. Differences between HTTP and MIME |
---|
4913 | |
---|
4914 | HTTP/1.1 uses many of the constructs defined for the Internet Message |
---|
4915 | Format [RFC5322] and the Multipurpose Internet Mail Extensions (MIME) |
---|
4916 | [RFC2045] to allow a message body to be transmitted in an open |
---|
4917 | variety of representations and with extensible header fields. |
---|
4918 | However, RFC 2045 is focused only on email; applications of HTTP have |
---|
4919 | many characteristics that differ from email, and hence HTTP has |
---|
4920 | features that differ from MIME. These differences were carefully |
---|
4921 | chosen to optimize performance over binary connections, to allow |
---|
4922 | greater freedom in the use of new media types, to make date |
---|
4923 | comparisons easier, and to acknowledge the practice of some early |
---|
4924 | |
---|
4925 | |
---|
4926 | |
---|
4927 | Fielding & Reschke Expires November 7, 2014 [Page 88] |
---|
4928 | |
---|
4929 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
4930 | |
---|
4931 | |
---|
4932 | HTTP servers and clients. |
---|
4933 | |
---|
4934 | This appendix describes specific areas where HTTP differs from MIME. |
---|
4935 | Proxies and gateways to and from strict MIME environments need to be |
---|
4936 | aware of these differences and provide the appropriate conversions |
---|
4937 | where necessary. |
---|
4938 | |
---|
4939 | A.1. MIME-Version |
---|
4940 | |
---|
4941 | HTTP is not a MIME-compliant protocol. However, messages can include |
---|
4942 | a single MIME-Version header field to indicate what version of the |
---|
4943 | MIME protocol was used to construct the message. Use of the MIME- |
---|
4944 | Version header field indicates that the message is in full |
---|
4945 | conformance with the MIME protocol (as defined in [RFC2045]). |
---|
4946 | Senders are responsible for ensuring full conformance (where |
---|
4947 | possible) when exporting HTTP messages to strict MIME environments. |
---|
4948 | |
---|
4949 | A.2. Conversion to Canonical Form |
---|
4950 | |
---|
4951 | MIME requires that an Internet mail body part be converted to |
---|
4952 | canonical form prior to being transferred, as described in Section 4 |
---|
4953 | of [RFC2049]. Section 3.1.1.3 of this document describes the forms |
---|
4954 | allowed for subtypes of the "text" media type when transmitted over |
---|
4955 | HTTP. [RFC2046] requires that content with a type of "text" |
---|
4956 | represent line breaks as CRLF and forbids the use of CR or LF outside |
---|
4957 | of line break sequences. HTTP allows CRLF, bare CR, and bare LF to |
---|
4958 | indicate a line break within text content. |
---|
4959 | |
---|
4960 | A proxy or gateway from HTTP to a strict MIME environment ought to |
---|
4961 | translate all line breaks within the text media types described in |
---|
4962 | Section 3.1.1.3 of this document to the RFC 2049 canonical form of |
---|
4963 | CRLF. Note, however, this might be complicated by the presence of a |
---|
4964 | Content-Encoding and by the fact that HTTP allows the use of some |
---|
4965 | charsets that do not use octets 13 and 10 to represent CR and LF, |
---|
4966 | respectively. |
---|
4967 | |
---|
4968 | Conversion will break any cryptographic checksums applied to the |
---|
4969 | original content unless the original content is already in canonical |
---|
4970 | form. Therefore, the canonical form is recommended for any content |
---|
4971 | that uses such checksums in HTTP. |
---|
4972 | |
---|
4973 | A.3. Conversion of Date Formats |
---|
4974 | |
---|
4975 | HTTP/1.1 uses a restricted set of date formats (Section 7.1.1.1) to |
---|
4976 | simplify the process of date comparison. Proxies and gateways from |
---|
4977 | other protocols ought to ensure that any Date header field present in |
---|
4978 | a message conforms to one of the HTTP/1.1 formats and rewrite the |
---|
4979 | date if necessary. |
---|
4980 | |
---|
4981 | |
---|
4982 | |
---|
4983 | Fielding & Reschke Expires November 7, 2014 [Page 89] |
---|
4984 | |
---|
4985 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
4986 | |
---|
4987 | |
---|
4988 | A.4. Conversion of Content-Encoding |
---|
4989 | |
---|
4990 | MIME does not include any concept equivalent to HTTP/1.1's Content- |
---|
4991 | Encoding header field. Since this acts as a modifier on the media |
---|
4992 | type, proxies and gateways from HTTP to MIME-compliant protocols |
---|
4993 | ought to either change the value of the Content-Type header field or |
---|
4994 | decode the representation before forwarding the message. (Some |
---|
4995 | experimental applications of Content-Type for Internet mail have used |
---|
4996 | a media-type parameter of ";conversions=<content-coding>" to perform |
---|
4997 | a function equivalent to Content-Encoding. However, this parameter |
---|
4998 | is not part of the MIME standards). |
---|
4999 | |
---|
5000 | A.5. Conversion of Content-Transfer-Encoding |
---|
5001 | |
---|
5002 | HTTP does not use the Content-Transfer-Encoding field of MIME. |
---|
5003 | Proxies and gateways from MIME-compliant protocols to HTTP need to |
---|
5004 | remove any Content-Transfer-Encoding prior to delivering the response |
---|
5005 | message to an HTTP client. |
---|
5006 | |
---|
5007 | Proxies and gateways from HTTP to MIME-compliant protocols are |
---|
5008 | responsible for ensuring that the message is in the correct format |
---|
5009 | and encoding for safe transport on that protocol, where "safe |
---|
5010 | transport" is defined by the limitations of the protocol being used. |
---|
5011 | Such a proxy or gateway ought to transform and label the data with an |
---|
5012 | appropriate Content-Transfer-Encoding if doing so will improve the |
---|
5013 | likelihood of safe transport over the destination protocol. |
---|
5014 | |
---|
5015 | A.6. MHTML and Line Length Limitations |
---|
5016 | |
---|
5017 | HTTP implementations that share code with MHTML [RFC2557] |
---|
5018 | implementations need to be aware of MIME line length limitations. |
---|
5019 | Since HTTP does not have this limitation, HTTP does not fold long |
---|
5020 | lines. MHTML messages being transported by HTTP follow all |
---|
5021 | conventions of MHTML, including line length limitations and folding, |
---|
5022 | canonicalization, etc., since HTTP transfers message-bodies as |
---|
5023 | payload and, aside from the "multipart/byteranges" type (Appendix A |
---|
5024 | of [RFC7233]), does not interpret the content or any MIME header |
---|
5025 | lines that might be contained therein. |
---|
5026 | |
---|
5027 | Appendix B. Changes from RFC 2616 |
---|
5028 | |
---|
5029 | The primary changes in this revision have been editorial in nature: |
---|
5030 | extracting the messaging syntax and partitioning HTTP semantics into |
---|
5031 | separate documents for the core features, conditional requests, |
---|
5032 | partial requests, caching, and authentication. The conformance |
---|
5033 | language has been revised to clearly target requirements and the |
---|
5034 | terminology has been improved to distinguish payload from |
---|
5035 | representations and representations from resources. |
---|
5036 | |
---|
5037 | |
---|
5038 | |
---|
5039 | Fielding & Reschke Expires November 7, 2014 [Page 90] |
---|
5040 | |
---|
5041 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
5042 | |
---|
5043 | |
---|
5044 | A new requirement has been added that semantics embedded in a URI |
---|
5045 | should be disabled when those semantics are inconsistent with the |
---|
5046 | request method, since this is a common cause of interoperability |
---|
5047 | failure. (Section 2) |
---|
5048 | |
---|
5049 | An algorithm has been added for determining if a payload is |
---|
5050 | associated with a specific identifier. (Section 3.1.4.1) |
---|
5051 | |
---|
5052 | The default charset of ISO-8859-1 for text media types has been |
---|
5053 | removed; the default is now whatever the media type definition says. |
---|
5054 | Likewise, special treatment of ISO-8859-1 has been removed from the |
---|
5055 | Accept-Charset header field. (Section 3.1.1.3 and Section 5.3.3) |
---|
5056 | |
---|
5057 | The definition of Content-Location has been changed to no longer |
---|
5058 | affect the base URI for resolving relative URI references, due to |
---|
5059 | poor implementation support and the undesirable effect of potentially |
---|
5060 | breaking relative links in content-negotiated resources. |
---|
5061 | (Section 3.1.4.2) |
---|
5062 | |
---|
5063 | To be consistent with the method-neutral parsing algorithm of |
---|
5064 | [RFC7230], the definition of GET has been relaxed so that requests |
---|
5065 | can have a body, even though a body has no meaning for GET. |
---|
5066 | (Section 4.3.1) |
---|
5067 | |
---|
5068 | Servers are no longer required to handle all Content-* header fields |
---|
5069 | and use of Content-Range has been explicitly banned in PUT requests. |
---|
5070 | (Section 4.3.4) |
---|
5071 | |
---|
5072 | Definition of the CONNECT method has been moved from [RFC2817] to |
---|
5073 | this specification. (Section 4.3.6) |
---|
5074 | |
---|
5075 | The OPTIONS and TRACE request methods have been defined as being |
---|
5076 | safe. (Section 4.3.7 and Section 4.3.8) |
---|
5077 | |
---|
5078 | The Expect header field's extension mechanism has been removed due to |
---|
5079 | widely-deployed broken implementations. (Section 5.1.1) |
---|
5080 | |
---|
5081 | The Max-Forwards header field has been restricted to the OPTIONS and |
---|
5082 | TRACE methods; previously, extension methods could have used it as |
---|
5083 | well. (Section 5.1.2) |
---|
5084 | |
---|
5085 | The "about:blank" URI has been suggested as a value for the Referer |
---|
5086 | header field when no referring URI is applicable, which distinguishes |
---|
5087 | that case from others where the Referer field is not sent or has been |
---|
5088 | removed. (Section 5.5.2) |
---|
5089 | |
---|
5090 | The following status codes are now cacheable (that is, they can be |
---|
5091 | stored and reused by a cache without explicit freshness information |
---|
5092 | |
---|
5093 | |
---|
5094 | |
---|
5095 | Fielding & Reschke Expires November 7, 2014 [Page 91] |
---|
5096 | |
---|
5097 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
5098 | |
---|
5099 | |
---|
5100 | present): 204, 404, 405, 414, 501. (Section 6) |
---|
5101 | |
---|
5102 | The 201 (Created) status description has been changed to allow for |
---|
5103 | the possibility that more than one resource has been created. |
---|
5104 | (Section 6.3.2) |
---|
5105 | |
---|
5106 | The definition of 203 (Non-Authoritative Information) has been |
---|
5107 | broadened to include cases of payload transformations as well. |
---|
5108 | (Section 6.3.4) |
---|
5109 | |
---|
5110 | The set of request methods that are safe to automatically redirect is |
---|
5111 | no longer closed; user agents are able to make that determination |
---|
5112 | based upon the request method semantics. The redirect status codes |
---|
5113 | 301, 302, and 307 no longer have normative requirements on response |
---|
5114 | payloads and user interaction. (Section 6.4) |
---|
5115 | |
---|
5116 | The status codes 301 and 302 have been changed to allow user agents |
---|
5117 | to rewrite the method from POST to GET. (Sections 6.4.2 and 6.4.3) |
---|
5118 | |
---|
5119 | The description of 303 (See Other) status code has been changed to |
---|
5120 | allow it to be cached if explicit freshness information is given, and |
---|
5121 | a specific definition has been added for a 303 response to GET. |
---|
5122 | (Section 6.4.4) |
---|
5123 | |
---|
5124 | The 305 (Use Proxy) status code has been deprecated due to security |
---|
5125 | concerns regarding in-band configuration of a proxy. (Section 6.4.5) |
---|
5126 | |
---|
5127 | The 400 (Bad Request) status code has been relaxed so that it isn't |
---|
5128 | limited to syntax errors. (Section 6.5.1) |
---|
5129 | |
---|
5130 | The 426 (Upgrade Required) status code has been incorporated from |
---|
5131 | [RFC2817]. (Section 6.5.15) |
---|
5132 | |
---|
5133 | The target of requirements on HTTP-date and the Date header field |
---|
5134 | have been reduced to those systems generating the date, rather than |
---|
5135 | all systems sending a date. (Section 7.1.1) |
---|
5136 | |
---|
5137 | The syntax of the Location header field has been changed to allow all |
---|
5138 | URI references, including relative references and fragments, along |
---|
5139 | with some clarifications as to when use of fragments would not be |
---|
5140 | appropriate. (Section 7.1.2) |
---|
5141 | |
---|
5142 | Allow has been reclassified as a response header field, removing the |
---|
5143 | option to specify it in a PUT request. Requirements relating to the |
---|
5144 | content of Allow have been relaxed; correspondingly, clients are not |
---|
5145 | required to always trust its value. (Section 7.4.1) |
---|
5146 | |
---|
5147 | A Method Registry has been defined. (Section 8.1) |
---|
5148 | |
---|
5149 | |
---|
5150 | |
---|
5151 | Fielding & Reschke Expires November 7, 2014 [Page 92] |
---|
5152 | |
---|
5153 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
5154 | |
---|
5155 | |
---|
5156 | The Status Code Registry has been redefined by this specification; |
---|
5157 | previously, it was defined in Section 7.1 of [RFC2817]. |
---|
5158 | (Section 8.2) |
---|
5159 | |
---|
5160 | Registration of Content Codings has been changed to require IETF |
---|
5161 | Review. (Section 8.4) |
---|
5162 | |
---|
5163 | The Content-Disposition header field has been removed since it is now |
---|
5164 | defined by [RFC6266]. |
---|
5165 | |
---|
5166 | The Content-MD5 header field has been removed because it was |
---|
5167 | inconsistently implemented with respect to partial responses. |
---|
5168 | |
---|
5169 | Appendix C. Imported ABNF |
---|
5170 | |
---|
5171 | The following core rules are included by reference, as defined in |
---|
5172 | Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), |
---|
5173 | CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double |
---|
5174 | quote), HEXDIG (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF |
---|
5175 | (line feed), OCTET (any 8-bit sequence of data), SP (space), and |
---|
5176 | VCHAR (any visible US-ASCII character). |
---|
5177 | |
---|
5178 | The rules below are defined in [RFC7230]: |
---|
5179 | |
---|
5180 | BWS = <BWS, defined in [RFC7230], Section 3.2.3> |
---|
5181 | OWS = <OWS, defined in [RFC7230], Section 3.2.3> |
---|
5182 | RWS = <RWS, defined in [RFC7230], Section 3.2.3> |
---|
5183 | URI-reference = <URI-reference, defined in [RFC7230], Section 2.7> |
---|
5184 | absolute-URI = <absolute-URI, defined in [RFC7230], Section 2.7> |
---|
5185 | comment = <comment, defined in [RFC7230], Section 3.2.6> |
---|
5186 | field-name = <comment, defined in [RFC7230], Section 3.2> |
---|
5187 | partial-URI = <partial-URI, defined in [RFC7230], Section 2.7> |
---|
5188 | quoted-string = <quoted-string, defined in [RFC7230], Section 3.2.6> |
---|
5189 | token = <token, defined in [RFC7230], Section 3.2.6> |
---|
5190 | |
---|
5191 | Appendix D. Collected ABNF |
---|
5192 | |
---|
5193 | In the collected ABNF below, list rules are expanded as per Section |
---|
5194 | 1.2 of [RFC7230]. |
---|
5195 | |
---|
5196 | Accept = [ ( "," / ( media-range [ accept-params ] ) ) *( OWS "," [ |
---|
5197 | OWS ( media-range [ accept-params ] ) ] ) ] |
---|
5198 | Accept-Charset = *( "," OWS ) ( ( charset / "*" ) [ weight ] ) *( OWS |
---|
5199 | "," [ OWS ( ( charset / "*" ) [ weight ] ) ] ) |
---|
5200 | Accept-Encoding = [ ( "," / ( codings [ weight ] ) ) *( OWS "," [ OWS |
---|
5201 | ( codings [ weight ] ) ] ) ] |
---|
5202 | Accept-Language = *( "," OWS ) ( language-range [ weight ] ) *( OWS |
---|
5203 | "," [ OWS ( language-range [ weight ] ) ] ) |
---|
5204 | |
---|
5205 | |
---|
5206 | |
---|
5207 | Fielding & Reschke Expires November 7, 2014 [Page 93] |
---|
5208 | |
---|
5209 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
5210 | |
---|
5211 | |
---|
5212 | Allow = [ ( "," / method ) *( OWS "," [ OWS method ] ) ] |
---|
5213 | |
---|
5214 | BWS = <BWS, defined in [RFC7230], Section 3.2.3> |
---|
5215 | |
---|
5216 | Content-Encoding = *( "," OWS ) content-coding *( OWS "," [ OWS |
---|
5217 | content-coding ] ) |
---|
5218 | Content-Language = *( "," OWS ) language-tag *( OWS "," [ OWS |
---|
5219 | language-tag ] ) |
---|
5220 | Content-Location = absolute-URI / partial-URI |
---|
5221 | Content-Type = media-type |
---|
5222 | |
---|
5223 | Date = HTTP-date |
---|
5224 | |
---|
5225 | Expect = "100-continue" |
---|
5226 | |
---|
5227 | From = mailbox |
---|
5228 | |
---|
5229 | GMT = %x47.4D.54 ; GMT |
---|
5230 | |
---|
5231 | HTTP-date = IMF-fixdate / obs-date |
---|
5232 | |
---|
5233 | IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT |
---|
5234 | |
---|
5235 | Location = URI-reference |
---|
5236 | |
---|
5237 | Max-Forwards = 1*DIGIT |
---|
5238 | |
---|
5239 | OWS = <OWS, defined in [RFC7230], Section 3.2.3> |
---|
5240 | |
---|
5241 | RWS = <RWS, defined in [RFC7230], Section 3.2.3> |
---|
5242 | Referer = absolute-URI / partial-URI |
---|
5243 | Retry-After = HTTP-date / delay-seconds |
---|
5244 | |
---|
5245 | Server = product *( RWS ( product / comment ) ) |
---|
5246 | |
---|
5247 | URI-reference = <URI-reference, defined in [RFC7230], Section 2.7> |
---|
5248 | User-Agent = product *( RWS ( product / comment ) ) |
---|
5249 | |
---|
5250 | Vary = "*" / ( *( "," OWS ) field-name *( OWS "," [ OWS field-name ] |
---|
5251 | ) ) |
---|
5252 | |
---|
5253 | absolute-URI = <absolute-URI, defined in [RFC7230], Section 2.7> |
---|
5254 | accept-ext = OWS ";" OWS token [ "=" ( token / quoted-string ) ] |
---|
5255 | accept-params = weight *accept-ext |
---|
5256 | asctime-date = day-name SP date3 SP time-of-day SP year |
---|
5257 | |
---|
5258 | charset = token |
---|
5259 | codings = content-coding / "identity" / "*" |
---|
5260 | |
---|
5261 | |
---|
5262 | |
---|
5263 | Fielding & Reschke Expires November 7, 2014 [Page 94] |
---|
5264 | |
---|
5265 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
5266 | |
---|
5267 | |
---|
5268 | comment = <comment, defined in [RFC7230], Section 3.2.6> |
---|
5269 | content-coding = token |
---|
5270 | |
---|
5271 | date1 = day SP month SP year |
---|
5272 | date2 = day "-" month "-" 2DIGIT |
---|
5273 | date3 = month SP ( 2DIGIT / ( SP DIGIT ) ) |
---|
5274 | day = 2DIGIT |
---|
5275 | day-name = %x4D.6F.6E ; Mon |
---|
5276 | / %x54.75.65 ; Tue |
---|
5277 | / %x57.65.64 ; Wed |
---|
5278 | / %x54.68.75 ; Thu |
---|
5279 | / %x46.72.69 ; Fri |
---|
5280 | / %x53.61.74 ; Sat |
---|
5281 | / %x53.75.6E ; Sun |
---|
5282 | day-name-l = %x4D.6F.6E.64.61.79 ; Monday |
---|
5283 | / %x54.75.65.73.64.61.79 ; Tuesday |
---|
5284 | / %x57.65.64.6E.65.73.64.61.79 ; Wednesday |
---|
5285 | / %x54.68.75.72.73.64.61.79 ; Thursday |
---|
5286 | / %x46.72.69.64.61.79 ; Friday |
---|
5287 | / %x53.61.74.75.72.64.61.79 ; Saturday |
---|
5288 | / %x53.75.6E.64.61.79 ; Sunday |
---|
5289 | delay-seconds = 1*DIGIT |
---|
5290 | |
---|
5291 | field-name = <comment, defined in [RFC7230], Section 3.2> |
---|
5292 | |
---|
5293 | hour = 2DIGIT |
---|
5294 | |
---|
5295 | language-range = <language-range, defined in [RFC4647], Section 2.1> |
---|
5296 | language-tag = <Language-Tag, defined in [RFC5646], Section 2.1> |
---|
5297 | |
---|
5298 | mailbox = <mailbox, defined in [RFC5322], Section 3.4> |
---|
5299 | media-range = ( "*/*" / ( type "/*" ) / ( type "/" subtype ) ) *( OWS |
---|
5300 | ";" OWS parameter ) |
---|
5301 | media-type = type "/" subtype *( OWS ";" OWS parameter ) |
---|
5302 | method = token |
---|
5303 | minute = 2DIGIT |
---|
5304 | month = %x4A.61.6E ; Jan |
---|
5305 | / %x46.65.62 ; Feb |
---|
5306 | / %x4D.61.72 ; Mar |
---|
5307 | / %x41.70.72 ; Apr |
---|
5308 | / %x4D.61.79 ; May |
---|
5309 | / %x4A.75.6E ; Jun |
---|
5310 | / %x4A.75.6C ; Jul |
---|
5311 | / %x41.75.67 ; Aug |
---|
5312 | / %x53.65.70 ; Sep |
---|
5313 | / %x4F.63.74 ; Oct |
---|
5314 | / %x4E.6F.76 ; Nov |
---|
5315 | / %x44.65.63 ; Dec |
---|
5316 | |
---|
5317 | |
---|
5318 | |
---|
5319 | Fielding & Reschke Expires November 7, 2014 [Page 95] |
---|
5320 | |
---|
5321 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
5322 | |
---|
5323 | |
---|
5324 | obs-date = rfc850-date / asctime-date |
---|
5325 | |
---|
5326 | parameter = token "=" ( token / quoted-string ) |
---|
5327 | partial-URI = <partial-URI, defined in [RFC7230], Section 2.7> |
---|
5328 | product = token [ "/" product-version ] |
---|
5329 | product-version = token |
---|
5330 | |
---|
5331 | quoted-string = <quoted-string, defined in [RFC7230], Section 3.2.6> |
---|
5332 | qvalue = ( "0" [ "." *3DIGIT ] ) / ( "1" [ "." *3"0" ] ) |
---|
5333 | |
---|
5334 | rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT |
---|
5335 | |
---|
5336 | second = 2DIGIT |
---|
5337 | subtype = token |
---|
5338 | |
---|
5339 | time-of-day = hour ":" minute ":" second |
---|
5340 | token = <token, defined in [RFC7230], Section 3.2.6> |
---|
5341 | type = token |
---|
5342 | |
---|
5343 | weight = OWS ";" OWS "q=" qvalue |
---|
5344 | |
---|
5345 | year = 4DIGIT |
---|
5346 | |
---|
5347 | Index |
---|
5348 | |
---|
5349 | 1 |
---|
5350 | 1xx Informational (status code class) 50 |
---|
5351 | |
---|
5352 | 2 |
---|
5353 | 2xx Successful (status code class) 51 |
---|
5354 | |
---|
5355 | 3 |
---|
5356 | 3xx Redirection (status code class) 54 |
---|
5357 | |
---|
5358 | 4 |
---|
5359 | 4xx Client Error (status code class) 58 |
---|
5360 | |
---|
5361 | 5 |
---|
5362 | 5xx Server Error (status code class) 62 |
---|
5363 | |
---|
5364 | 1 |
---|
5365 | 100 Continue (status code) 50 |
---|
5366 | 100-continue (expect value) 34 |
---|
5367 | 101 Switching Protocols (status code) 50 |
---|
5368 | |
---|
5369 | 2 |
---|
5370 | 200 OK (status code) 51 |
---|
5371 | 201 Created (status code) 52 |
---|
5372 | |
---|
5373 | |
---|
5374 | |
---|
5375 | Fielding & Reschke Expires November 7, 2014 [Page 96] |
---|
5376 | |
---|
5377 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
5378 | |
---|
5379 | |
---|
5380 | 202 Accepted (status code) 52 |
---|
5381 | 203 Non-Authoritative Information (status code) 52 |
---|
5382 | 204 No Content (status code) 53 |
---|
5383 | 205 Reset Content (status code) 53 |
---|
5384 | |
---|
5385 | 3 |
---|
5386 | 300 Multiple Choices (status code) 55 |
---|
5387 | 301 Moved Permanently (status code) 56 |
---|
5388 | 302 Found (status code) 56 |
---|
5389 | 303 See Other (status code) 57 |
---|
5390 | 305 Use Proxy (status code) 57 |
---|
5391 | 306 (Unused) (status code) 57 |
---|
5392 | 307 Temporary Redirect (status code) 58 |
---|
5393 | |
---|
5394 | 4 |
---|
5395 | 400 Bad Request (status code) 58 |
---|
5396 | 402 Payment Required (status code) 58 |
---|
5397 | 403 Forbidden (status code) 58 |
---|
5398 | 404 Not Found (status code) 59 |
---|
5399 | 405 Method Not Allowed (status code) 59 |
---|
5400 | 406 Not Acceptable (status code) 59 |
---|
5401 | 408 Request Timeout (status code) 60 |
---|
5402 | 409 Conflict (status code) 60 |
---|
5403 | 410 Gone (status code) 60 |
---|
5404 | 411 Length Required (status code) 61 |
---|
5405 | 413 Payload Too Large (status code) 61 |
---|
5406 | 414 URI Too Long (status code) 61 |
---|
5407 | 415 Unsupported Media Type (status code) 61 |
---|
5408 | 417 Expectation Failed (status code) 62 |
---|
5409 | 426 Upgrade Required (status code) 62 |
---|
5410 | |
---|
5411 | 5 |
---|
5412 | 500 Internal Server Error (status code) 62 |
---|
5413 | 501 Not Implemented (status code) 63 |
---|
5414 | 502 Bad Gateway (status code) 63 |
---|
5415 | 503 Service Unavailable (status code) 63 |
---|
5416 | 504 Gateway Timeout (status code) 63 |
---|
5417 | 505 HTTP Version Not Supported (status code) 63 |
---|
5418 | |
---|
5419 | A |
---|
5420 | Accept header field 38 |
---|
5421 | Accept-Charset header field 40 |
---|
5422 | Accept-Encoding header field 41 |
---|
5423 | Accept-Language header field 42 |
---|
5424 | Allow header field 72 |
---|
5425 | |
---|
5426 | C |
---|
5427 | cacheable 24 |
---|
5428 | |
---|
5429 | |
---|
5430 | |
---|
5431 | Fielding & Reschke Expires November 7, 2014 [Page 97] |
---|
5432 | |
---|
5433 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
5434 | |
---|
5435 | |
---|
5436 | compress (content coding) 11 |
---|
5437 | conditional request 36 |
---|
5438 | CONNECT method 30 |
---|
5439 | content coding 11 |
---|
5440 | content negotiation 6 |
---|
5441 | Content-Encoding header field 12 |
---|
5442 | Content-Language header field 13 |
---|
5443 | Content-Location header field 15 |
---|
5444 | Content-Transfer-Encoding header field 90 |
---|
5445 | Content-Type header field 10 |
---|
5446 | |
---|
5447 | D |
---|
5448 | Date header field 67 |
---|
5449 | deflate (content coding) 11 |
---|
5450 | DELETE method 29 |
---|
5451 | |
---|
5452 | E |
---|
5453 | Expect header field 34 |
---|
5454 | |
---|
5455 | F |
---|
5456 | From header field 44 |
---|
5457 | |
---|
5458 | G |
---|
5459 | GET method 24 |
---|
5460 | Grammar |
---|
5461 | Accept 38 |
---|
5462 | Accept-Charset 40 |
---|
5463 | Accept-Encoding 41 |
---|
5464 | accept-ext 38 |
---|
5465 | Accept-Language 42 |
---|
5466 | accept-params 38 |
---|
5467 | Allow 72 |
---|
5468 | asctime-date 67 |
---|
5469 | charset 9 |
---|
5470 | codings 41 |
---|
5471 | content-coding 11 |
---|
5472 | Content-Encoding 12 |
---|
5473 | Content-Language 13 |
---|
5474 | Content-Location 15 |
---|
5475 | Content-Type 10 |
---|
5476 | Date 67 |
---|
5477 | date1 66 |
---|
5478 | day 66 |
---|
5479 | day-name 66 |
---|
5480 | day-name-l 66 |
---|
5481 | delay-seconds 70 |
---|
5482 | Expect 34 |
---|
5483 | From 44 |
---|
5484 | |
---|
5485 | |
---|
5486 | |
---|
5487 | Fielding & Reschke Expires November 7, 2014 [Page 98] |
---|
5488 | |
---|
5489 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
5490 | |
---|
5491 | |
---|
5492 | GMT 66 |
---|
5493 | hour 66 |
---|
5494 | HTTP-date 64 |
---|
5495 | IMF-fixdate 66 |
---|
5496 | language-range 42 |
---|
5497 | language-tag 13 |
---|
5498 | Location 68 |
---|
5499 | Max-Forwards 36 |
---|
5500 | media-range 38 |
---|
5501 | media-type 8 |
---|
5502 | method 21 |
---|
5503 | minute 66 |
---|
5504 | month 66 |
---|
5505 | obs-date 66 |
---|
5506 | parameter 8 |
---|
5507 | product 46 |
---|
5508 | product-version 46 |
---|
5509 | qvalue 38 |
---|
5510 | Referer 45 |
---|
5511 | Retry-After 70 |
---|
5512 | rfc850-date 67 |
---|
5513 | second 66 |
---|
5514 | Server 73 |
---|
5515 | subtype 8 |
---|
5516 | time-of-day 66 |
---|
5517 | type 8 |
---|
5518 | User-Agent 46 |
---|
5519 | Vary 70 |
---|
5520 | weight 38 |
---|
5521 | year 66 |
---|
5522 | gzip (content coding) 11 |
---|
5523 | |
---|
5524 | H |
---|
5525 | HEAD method 25 |
---|
5526 | |
---|
5527 | I |
---|
5528 | idempotent 23 |
---|
5529 | |
---|
5530 | L |
---|
5531 | Location header field 68 |
---|
5532 | |
---|
5533 | M |
---|
5534 | Max-Forwards header field 36 |
---|
5535 | MIME-Version header field 89 |
---|
5536 | |
---|
5537 | O |
---|
5538 | OPTIONS method 31 |
---|
5539 | |
---|
5540 | |
---|
5541 | |
---|
5542 | |
---|
5543 | Fielding & Reschke Expires November 7, 2014 [Page 99] |
---|
5544 | |
---|
5545 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
5546 | |
---|
5547 | |
---|
5548 | P |
---|
5549 | payload 17 |
---|
5550 | POST method 25 |
---|
5551 | PUT method 26 |
---|
5552 | |
---|
5553 | R |
---|
5554 | Referer header field 45 |
---|
5555 | representation 7 |
---|
5556 | Retry-After header field 69 |
---|
5557 | |
---|
5558 | S |
---|
5559 | safe 22 |
---|
5560 | selected representation 7, 71 |
---|
5561 | Server header field 73 |
---|
5562 | Status Codes Classes |
---|
5563 | 1xx Informational 50 |
---|
5564 | 2xx Successful 51 |
---|
5565 | 3xx Redirection 54 |
---|
5566 | 4xx Client Error 58 |
---|
5567 | 5xx Server Error 62 |
---|
5568 | |
---|
5569 | T |
---|
5570 | TRACE method 32 |
---|
5571 | |
---|
5572 | U |
---|
5573 | User-Agent header field 46 |
---|
5574 | |
---|
5575 | V |
---|
5576 | Vary header field 70 |
---|
5577 | |
---|
5578 | X |
---|
5579 | x-compress (content coding) 11 |
---|
5580 | x-gzip (content coding) 11 |
---|
5581 | |
---|
5582 | Authors' Addresses |
---|
5583 | |
---|
5584 | Roy T. Fielding (editor) |
---|
5585 | Adobe Systems Incorporated |
---|
5586 | 345 Park Ave |
---|
5587 | San Jose, CA 95110 |
---|
5588 | USA |
---|
5589 | |
---|
5590 | EMail: fielding@gbiv.com |
---|
5591 | URI: http://roy.gbiv.com/ |
---|
5592 | |
---|
5593 | |
---|
5594 | |
---|
5595 | |
---|
5596 | |
---|
5597 | |
---|
5598 | |
---|
5599 | Fielding & Reschke Expires November 7, 2014 [Page 100] |
---|
5600 | |
---|
5601 | Internet-Draft HTTP/1.1 Semantics and Content May 2014 |
---|
5602 | |
---|
5603 | |
---|
5604 | Julian F. Reschke (editor) |
---|
5605 | greenbytes GmbH |
---|
5606 | Hafenweg 16 |
---|
5607 | Muenster, NW 48155 |
---|
5608 | Germany |
---|
5609 | |
---|
5610 | EMail: julian.reschke@greenbytes.de |
---|
5611 | URI: http://greenbytes.de/tech/webdav/ |
---|
5612 | |
---|
5613 | |
---|
5614 | |
---|
5615 | |
---|
5616 | |
---|
5617 | |
---|
5618 | |
---|
5619 | |
---|
5620 | |
---|
5621 | |
---|
5622 | |
---|
5623 | |
---|
5624 | |
---|
5625 | |
---|
5626 | |
---|
5627 | |
---|
5628 | |
---|
5629 | |
---|
5630 | |
---|
5631 | |
---|
5632 | |
---|
5633 | |
---|
5634 | |
---|
5635 | |
---|
5636 | |
---|
5637 | |
---|
5638 | |
---|
5639 | |
---|
5640 | |
---|
5641 | |
---|
5642 | |
---|
5643 | |
---|
5644 | |
---|
5645 | |
---|
5646 | |
---|
5647 | |
---|
5648 | |
---|
5649 | |
---|
5650 | |
---|
5651 | |
---|
5652 | |
---|
5653 | |
---|
5654 | |
---|
5655 | Fielding & Reschke Expires November 7, 2014 [Page 101] |
---|
5656 | |
---|