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