source: draft-ietf-httpbis/01/draft-ietf-httpbis-p2-semantics-01.txt @ 2104

Last change on this file since 2104 was 166, checked in by fielding@…, 13 years ago

generated draft 01
  • Property svn:eol-style set to native
File size: 98.5 KB
Line 
1
2
3
4Network Working Group                                   R. Fielding, Ed.
5Internet-Draft                                              Day Software
6Obsoletes: 2616 (if approved)                                  J. Gettys
7Intended status: Standards Track                    One Laptop per Child
8Expires: July 15, 2008                                          J. Mogul
9                                                                      HP
10                                                              H. Frystyk
11                                                               Microsoft
12                                                             L. Masinter
13                                                           Adobe Systems
14                                                                P. Leach
15                                                               Microsoft
16                                                          T. Berners-Lee
17                                                                 W3C/MIT
18                                                           Y. Lafon, Ed.
19                                                                     W3C
20                                                         J. Reschke, Ed.
21                                                              greenbytes
22                                                        January 12, 2008
23
24
25                  HTTP/1.1, part 2: Message Semantics
26                   draft-ietf-httpbis-p2-semantics-01
27
28Status of this Memo
29
30   By submitting this Internet-Draft, each author represents that any
31   applicable patent or other IPR claims of which he or she is aware
32   have been or will be disclosed, and any of which he or she becomes
33   aware will be disclosed, in accordance with Section 6 of BCP 79.
34
35   Internet-Drafts are working documents of the Internet Engineering
36   Task Force (IETF), its areas, and its working groups.  Note that
37   other groups may also distribute working documents as Internet-
38   Drafts.
39
40   Internet-Drafts are draft documents valid for a maximum of six months
41   and may be updated, replaced, or obsoleted by other documents at any
42   time.  It is inappropriate to use Internet-Drafts as reference
43   material or to cite them other than as "work in progress."
44
45   The list of current Internet-Drafts can be accessed at
46   http://www.ietf.org/ietf/1id-abstracts.txt.
47
48   The list of Internet-Draft Shadow Directories can be accessed at
49   http://www.ietf.org/shadow.html.
50
51   This Internet-Draft will expire on July 15, 2008.
52
53
54
55Fielding, et al.          Expires July 15, 2008                 [Page 1]
56
57Internet-Draft              HTTP/1.1, Part 2                January 2008
58
59
60Copyright Notice
61
62   Copyright (C) The IETF Trust (2008).
63
64Abstract
65
66   The Hypertext Transfer Protocol (HTTP) is an application-level
67   protocol for distributed, collaborative, hypermedia information
68   systems.  HTTP has been in use by the World Wide Web global
69   information initiative since 1990.  This document is Part 2 of the
70   seven-part specification that defines the protocol referred to as
71   "HTTP/1.1" and, taken together, obsoletes RFC 2616.  Part 2 defines
72   the semantics of HTTP messages as expressed by request methods,
73   request-header fields, response status codes, and response-header
74   fields.
75
76Editorial Note (To be removed by RFC Editor)
77
78   Discussion of this draft should take place on the HTTPBIS working
79   group mailing list (ietf-http-wg@w3.org).  The current issues list is
80   at <http://www.tools.ietf.org/wg/httpbis/trac/report/11> and related
81   documents (including fancy diffs) can be found at
82   <http://www.tools.ietf.org/wg/httpbis/>.
83
84   This draft incorporates those issue resolutions that were either
85   collected in the original RFC2616 errata list
86   (<http://purl.org/NET/http-errata>), or which were agreed upon on the
87   mailing list between October 2006 and November 2007 (as published in
88   "draft-lafon-rfc2616bis-03").
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111Fielding, et al.          Expires July 15, 2008                 [Page 2]
112
113Internet-Draft              HTTP/1.1, Part 2                January 2008
114
115
116Table of Contents
117
118   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  6
119     1.1.  Requirements . . . . . . . . . . . . . . . . . . . . . . .  6
120   2.  Product Tokens . . . . . . . . . . . . . . . . . . . . . . . .  6
121   3.  Method . . . . . . . . . . . . . . . . . . . . . . . . . . . .  7
122   4.  Request Header Fields  . . . . . . . . . . . . . . . . . . . .  7
123   5.  Status Code and Reason Phrase  . . . . . . . . . . . . . . . .  8
124   6.  Response Header Fields . . . . . . . . . . . . . . . . . . . . 10
125   7.  Entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
126   8.  Method Definitions . . . . . . . . . . . . . . . . . . . . . . 11
127     8.1.  Safe and Idempotent Methods  . . . . . . . . . . . . . . . 11
128       8.1.1.  Safe Methods . . . . . . . . . . . . . . . . . . . . . 11
129       8.1.2.  Idempotent Methods . . . . . . . . . . . . . . . . . . 11
130     8.2.  OPTIONS  . . . . . . . . . . . . . . . . . . . . . . . . . 12
131     8.3.  GET  . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
132     8.4.  HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
133     8.5.  POST . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
134     8.6.  PUT  . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
135     8.7.  DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . 16
136     8.8.  TRACE  . . . . . . . . . . . . . . . . . . . . . . . . . . 16
137     8.9.  CONNECT  . . . . . . . . . . . . . . . . . . . . . . . . . 17
138   9.  Status Code Definitions  . . . . . . . . . . . . . . . . . . . 17
139     9.1.  Informational 1xx  . . . . . . . . . . . . . . . . . . . . 17
140       9.1.1.  100 Continue . . . . . . . . . . . . . . . . . . . . . 17
141       9.1.2.  101 Switching Protocols  . . . . . . . . . . . . . . . 18
142     9.2.  Successful 2xx . . . . . . . . . . . . . . . . . . . . . . 18
143       9.2.1.  200 OK . . . . . . . . . . . . . . . . . . . . . . . . 18
144       9.2.2.  201 Created  . . . . . . . . . . . . . . . . . . . . . 18
145       9.2.3.  202 Accepted . . . . . . . . . . . . . . . . . . . . . 19
146       9.2.4.  203 Non-Authoritative Information  . . . . . . . . . . 19
147       9.2.5.  204 No Content . . . . . . . . . . . . . . . . . . . . 19
148       9.2.6.  205 Reset Content  . . . . . . . . . . . . . . . . . . 20
149       9.2.7.  206 Partial Content  . . . . . . . . . . . . . . . . . 20
150     9.3.  Redirection 3xx  . . . . . . . . . . . . . . . . . . . . . 20
151       9.3.1.  300 Multiple Choices . . . . . . . . . . . . . . . . . 20
152       9.3.2.  301 Moved Permanently  . . . . . . . . . . . . . . . . 21
153       9.3.3.  302 Found  . . . . . . . . . . . . . . . . . . . . . . 21
154       9.3.4.  303 See Other  . . . . . . . . . . . . . . . . . . . . 22
155       9.3.5.  304 Not Modified . . . . . . . . . . . . . . . . . . . 22
156       9.3.6.  305 Use Proxy  . . . . . . . . . . . . . . . . . . . . 22
157       9.3.7.  306 (Unused) . . . . . . . . . . . . . . . . . . . . . 23
158       9.3.8.  307 Temporary Redirect . . . . . . . . . . . . . . . . 23
159     9.4.  Client Error 4xx . . . . . . . . . . . . . . . . . . . . . 23
160       9.4.1.  400 Bad Request  . . . . . . . . . . . . . . . . . . . 24
161       9.4.2.  401 Unauthorized . . . . . . . . . . . . . . . . . . . 24
162       9.4.3.  402 Payment Required . . . . . . . . . . . . . . . . . 24
163       9.4.4.  403 Forbidden  . . . . . . . . . . . . . . . . . . . . 24
164
165
166
167Fielding, et al.          Expires July 15, 2008                 [Page 3]
168
169Internet-Draft              HTTP/1.1, Part 2                January 2008
170
171
172       9.4.5.  404 Not Found  . . . . . . . . . . . . . . . . . . . . 24
173       9.4.6.  405 Method Not Allowed . . . . . . . . . . . . . . . . 24
174       9.4.7.  406 Not Acceptable . . . . . . . . . . . . . . . . . . 24
175       9.4.8.  407 Proxy Authentication Required  . . . . . . . . . . 25
176       9.4.9.  408 Request Timeout  . . . . . . . . . . . . . . . . . 25
177       9.4.10. 409 Conflict . . . . . . . . . . . . . . . . . . . . . 25
178       9.4.11. 410 Gone . . . . . . . . . . . . . . . . . . . . . . . 26
179       9.4.12. 411 Length Required  . . . . . . . . . . . . . . . . . 26
180       9.4.13. 412 Precondition Failed  . . . . . . . . . . . . . . . 26
181       9.4.14. 413 Request Entity Too Large . . . . . . . . . . . . . 26
182       9.4.15. 414 Request-URI Too Long . . . . . . . . . . . . . . . 27
183       9.4.16. 415 Unsupported Media Type . . . . . . . . . . . . . . 27
184       9.4.17. 416 Requested Range Not Satisfiable  . . . . . . . . . 27
185       9.4.18. 417 Expectation Failed . . . . . . . . . . . . . . . . 27
186     9.5.  Server Error 5xx . . . . . . . . . . . . . . . . . . . . . 27
187       9.5.1.  500 Internal Server Error  . . . . . . . . . . . . . . 27
188       9.5.2.  501 Not Implemented  . . . . . . . . . . . . . . . . . 28
189       9.5.3.  502 Bad Gateway  . . . . . . . . . . . . . . . . . . . 28
190       9.5.4.  503 Service Unavailable  . . . . . . . . . . . . . . . 28
191       9.5.5.  504 Gateway Timeout  . . . . . . . . . . . . . . . . . 28
192       9.5.6.  505 HTTP Version Not Supported . . . . . . . . . . . . 28
193   10. Header Field Definitions . . . . . . . . . . . . . . . . . . . 29
194     10.1. Allow  . . . . . . . . . . . . . . . . . . . . . . . . . . 29
195     10.2. Expect . . . . . . . . . . . . . . . . . . . . . . . . . . 29
196     10.3. From . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
197     10.4. Location . . . . . . . . . . . . . . . . . . . . . . . . . 31
198     10.5. Max-Forwards . . . . . . . . . . . . . . . . . . . . . . . 32
199     10.6. Referer  . . . . . . . . . . . . . . . . . . . . . . . . . 32
200     10.7. Retry-After  . . . . . . . . . . . . . . . . . . . . . . . 33
201     10.8. Server . . . . . . . . . . . . . . . . . . . . . . . . . . 33
202     10.9. User-Agent . . . . . . . . . . . . . . . . . . . . . . . . 34
203   11. IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 34
204   12. Security Considerations  . . . . . . . . . . . . . . . . . . . 34
205     12.1. Transfer of Sensitive Information  . . . . . . . . . . . . 34
206     12.2. Encoding Sensitive Information in URI's  . . . . . . . . . 35
207     12.3. Location Headers and Spoofing  . . . . . . . . . . . . . . 36
208   13. Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 36
209   14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 36
210     14.1. Normative References . . . . . . . . . . . . . . . . . . . 36
211     14.2. Informative References . . . . . . . . . . . . . . . . . . 37
212   Appendix A.  Compatibility with Previous Versions  . . . . . . . . 37
213     A.1.  Changes from RFC 2068  . . . . . . . . . . . . . . . . . . 37
214     A.2.  Changes from RFC 2616  . . . . . . . . . . . . . . . . . . 38
215   Appendix B.  Change Log (to be removed by RFC Editor before
216                publication)  . . . . . . . . . . . . . . . . . . . . 39
217     B.1.  Since RFC2616  . . . . . . . . . . . . . . . . . . . . . . 39
218     B.2.  Since draft-ietf-httpbis-p2-semantics-00 . . . . . . . . . 39
219   Index  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
220
221
222
223Fielding, et al.          Expires July 15, 2008                 [Page 4]
224
225Internet-Draft              HTTP/1.1, Part 2                January 2008
226
227
228   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 43
229   Intellectual Property and Copyright Statements . . . . . . . . . . 47
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279Fielding, et al.          Expires July 15, 2008                 [Page 5]
280
281Internet-Draft              HTTP/1.1, Part 2                January 2008
282
283
2841.  Introduction
285
286   This document defines HTTP/1.1 request and response semantics.  Each
287   HTTP message, as defined in [Part1], is in the form of either a
288   request or a response.  An HTTP server listens on a connection for
289   HTTP requests and responds to each request, in the order received on
290   that connection, with one or more HTTP response messages.  This
291   document defines the commonly agreed upon semantics of the HTTP
292   uniform interface, the intentions defined by each request method, and
293   the various response messages that might be expected as a result of
294   applying that method for the requested resource.
295
296   This document is currently disorganized in order to minimize the
297   changes between drafts and enable reviewers to see the smaller errata
298   changes.  The next draft will reorganize the sections to better
299   reflect the content.  In particular, the sections will be ordered
300   according to the typical processing of an HTTP request message (after
301   message parsing): resource mapping, general header fields, methods,
302   request modifiers, response status, and resource metadata.  The
303   current mess reflects how widely dispersed these topics and
304   associated requirements had become in [RFC2616].
305
3061.1.  Requirements
307
308   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
309   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
310   document are to be interpreted as described in [RFC2119].
311
312   An implementation is not compliant if it fails to satisfy one or more
313   of the MUST or REQUIRED level requirements for the protocols it
314   implements.  An implementation that satisfies all the MUST or
315   REQUIRED level and all the SHOULD level requirements for its
316   protocols is said to be "unconditionally compliant"; one that
317   satisfies all the MUST level requirements but not all the SHOULD
318   level requirements for its protocols is said to be "conditionally
319   compliant."
320
321
3222.  Product Tokens
323
324   Product tokens are used to allow communicating applications to
325   identify themselves by software name and version.  Most fields using
326   product tokens also allow sub-products which form a significant part
327   of the application to be listed, separated by white space.  By
328   convention, the products are listed in order of their significance
329   for identifying the application.
330
331     product         = token ["/" product-version]
332
333
334
335Fielding, et al.          Expires July 15, 2008                 [Page 6]
336
337Internet-Draft              HTTP/1.1, Part 2                January 2008
338
339
340     product-version = token
341
342   Examples:
343
344       User-Agent: CERN-LineMode/2.15 libwww/2.17b3
345       Server: Apache/0.8.4
346
347   Product tokens SHOULD be short and to the point.  They MUST NOT be
348   used for advertising or other non-essential information.  Although
349   any token character MAY appear in a product-version, this token
350   SHOULD only be used for a version identifier (i.e., successive
351   versions of the same product SHOULD only differ in the product-
352   version portion of the product value).
353
354
3553.  Method
356
357   The Method token indicates the method to be performed on the resource
358   identified by the Request-URI.  The method is case-sensitive.
359
360     Method         = "OPTIONS"                ; Section 8.2
361                    | "GET"                    ; Section 8.3
362                    | "HEAD"                   ; Section 8.4
363                    | "POST"                   ; Section 8.5
364                    | "PUT"                    ; Section 8.6
365                    | "DELETE"                 ; Section 8.7
366                    | "TRACE"                  ; Section 8.8
367                    | "CONNECT"                ; Section 8.9
368                    | extension-method
369     extension-method = token
370
371   The list of methods allowed by a resource can be specified in an
372   Allow header field (Section 10.1).  The return code of the response
373   always notifies the client whether a method is currently allowed on a
374   resource, since the set of allowed methods can change dynamically.
375   An origin server SHOULD return the status code 405 (Method Not
376   Allowed) if the method is known by the origin server but not allowed
377   for the requested resource, and 501 (Not Implemented) if the method
378   is unrecognized or not implemented by the origin server.  The methods
379   GET and HEAD MUST be supported by all general-purpose servers.  All
380   other methods are OPTIONAL; however, if the above methods are
381   implemented, they MUST be implemented with the same semantics as
382   those specified in Section 8.
383
384
3854.  Request Header Fields
386
387   The request-header fields allow the client to pass additional
388
389
390
391Fielding, et al.          Expires July 15, 2008                 [Page 7]
392
393Internet-Draft              HTTP/1.1, Part 2                January 2008
394
395
396   information about the request, and about the client itself, to the
397   server.  These fields act as request modifiers, with semantics
398   equivalent to the parameters on a programming language method
399   invocation.
400
401     request-header = Accept                   ; [Part3], Section 5.1
402                    | Accept-Charset           ; [Part3], Section 5.2
403                    | Accept-Encoding          ; [Part3], Section 5.3
404                    | Accept-Language          ; [Part3], Section 5.4
405                    | Authorization            ; [Part7], Section 3.1
406                    | Expect                   ; Section 10.2
407                    | From                     ; Section 10.3
408                    | Host                     ; [Part1], Section 8.4
409                    | If-Match                 ; [Part4], Section 6.2
410                    | If-Modified-Since        ; [Part4], Section 6.3
411                    | If-None-Match            ; [Part4], Section 6.4
412                    | If-Range                 ; [Part5], Section 5.3
413                    | If-Unmodified-Since      ; [Part4], Section 6.5
414                    | Max-Forwards             ; Section 10.5
415                    | Proxy-Authorization      ; [Part7], Section 3.3
416                    | Range                    ; [Part5], Section 5.4
417                    | Referer                  ; Section 10.6
418                    | TE                       ; [Part1], Section 8.8
419                    | User-Agent               ; Section 10.9
420
421   Request-header field names can be extended reliably only in
422   combination with a change in the protocol version.  However, new or
423   experimental header fields MAY be given the semantics of request-
424   header fields if all parties in the communication recognize them to
425   be request-header fields.  Unrecognized header fields are treated as
426   entity-header fields.
427
428
4295.  Status Code and Reason Phrase
430
431   The Status-Code element is a 3-digit integer result code of the
432   attempt to understand and satisfy the request.  The status codes
433   listed below are defined in Section 9.  The Reason-Phrase is intended
434   to give a short textual description of the Status-Code.  The Status-
435   Code is intended for use by automata and the Reason-Phrase is
436   intended for the human user.  The client is not required to examine
437   or display the Reason-Phrase.
438
439   The individual values of the numeric status codes defined for
440   HTTP/1.1, and an example set of corresponding Reason-Phrase's, are
441   presented below.  The reason phrases listed here are only
442   recommendations -- they MAY be replaced by local equivalents without
443   affecting the protocol.
444
445
446
447Fielding, et al.          Expires July 15, 2008                 [Page 8]
448
449Internet-Draft              HTTP/1.1, Part 2                January 2008
450
451
452     Status-Code    =
453            "100"  ; Section 9.1.1: Continue
454          | "101"  ; Section 9.1.2: Switching Protocols
455          | "200"  ; Section 9.2.1: OK
456          | "201"  ; Section 9.2.2: Created
457          | "202"  ; Section 9.2.3: Accepted
458          | "203"  ; Section 9.2.4: Non-Authoritative Information
459          | "204"  ; Section 9.2.5: No Content
460          | "205"  ; Section 9.2.6: Reset Content
461          | "206"  ; Section 9.2.7: Partial Content
462          | "300"  ; Section 9.3.1: Multiple Choices
463          | "301"  ; Section 9.3.2: Moved Permanently
464          | "302"  ; Section 9.3.3: Found
465          | "303"  ; Section 9.3.4: See Other
466          | "304"  ; Section 9.3.5: Not Modified
467          | "305"  ; Section 9.3.6: Use Proxy
468          | "307"  ; Section 9.3.8: Temporary Redirect
469          | "400"  ; Section 9.4.1: Bad Request
470          | "401"  ; Section 9.4.2: Unauthorized
471          | "402"  ; Section 9.4.3: Payment Required
472          | "403"  ; Section 9.4.4: Forbidden
473          | "404"  ; Section 9.4.5: Not Found
474          | "405"  ; Section 9.4.6: Method Not Allowed
475          | "406"  ; Section 9.4.7: Not Acceptable
476          | "407"  ; Section 9.4.8: Proxy Authentication Required
477          | "408"  ; Section 9.4.9: Request Time-out
478          | "409"  ; Section 9.4.10: Conflict
479          | "410"  ; Section 9.4.11: Gone
480          | "411"  ; Section 9.4.12: Length Required
481          | "412"  ; Section 9.4.13: Precondition Failed
482          | "413"  ; Section 9.4.14: Request Entity Too Large
483          | "414"  ; Section 9.4.15: Request-URI Too Large
484          | "415"  ; Section 9.4.16: Unsupported Media Type
485          | "416"  ; Section 9.4.17: Requested range not satisfiable
486          | "417"  ; Section 9.4.18: Expectation Failed
487          | "500"  ; Section 9.5.1: Internal Server Error
488          | "501"  ; Section 9.5.2: Not Implemented
489          | "502"  ; Section 9.5.3: Bad Gateway
490          | "503"  ; Section 9.5.4: Service Unavailable
491          | "504"  ; Section 9.5.5: Gateway Time-out
492          | "505"  ; Section 9.5.6: HTTP Version not supported
493          | extension-code
494
495     extension-code = 3DIGIT
496     Reason-Phrase  = *<TEXT, excluding CR, LF>
497
498   HTTP status codes are extensible.  HTTP applications are not required
499   to understand the meaning of all registered status codes, though such
500
501
502
503Fielding, et al.          Expires July 15, 2008                 [Page 9]
504
505Internet-Draft              HTTP/1.1, Part 2                January 2008
506
507
508   understanding is obviously desirable.  However, applications MUST
509   understand the class of any status code, as indicated by the first
510   digit, and treat any unrecognized response as being equivalent to the
511   x00 status code of that class, with the exception that an
512   unrecognized response MUST NOT be cached.  For example, if an
513   unrecognized status code of 431 is received by the client, it can
514   safely assume that there was something wrong with its request and
515   treat the response as if it had received a 400 status code.  In such
516   cases, user agents SHOULD present to the user the entity returned
517   with the response, since that entity is likely to include human-
518   readable information which will explain the unusual status.
519
520
5216.  Response Header Fields
522
523   The response-header fields allow the server to pass additional
524   information about the response which cannot be placed in the Status-
525   Line.  These header fields give information about the server and
526   about further access to the resource identified by the Request-URI.
527
528     response-header = Accept-Ranges           ; [Part5], Section 5.1
529                     | Age                     ; [Part6], Section 15.1
530                     | ETag                    ; [Part4], Section 6.1
531                     | Location                ; Section 10.4
532                     | Proxy-Authenticate      ; [Part7], Section 3.2
533                     | Retry-After             ; Section 10.7
534                     | Server                  ; Section 10.8
535                     | Vary                    ; [Part6], Section 15.5
536                     | WWW-Authenticate        ; [Part7], Section 3.4
537
538   Response-header field names can be extended reliably only in
539   combination with a change in the protocol version.  However, new or
540   experimental header fields MAY be given the semantics of response-
541   header fields if all parties in the communication recognize them to
542   be response-header fields.  Unrecognized header fields are treated as
543   entity-header fields.
544
545
5467.  Entity
547
548   Request and Response messages MAY transfer an entity if not otherwise
549   restricted by the request method or response status code.  An entity
550   consists of entity-header fields and an entity-body, although some
551   responses will only include the entity-headers.  HTTP entity-body and
552   entity-header fields are defined in [Part3].
553
554   An entity-body is only present in a message when a message-body is
555   present, as described in Section 4.3 of [Part1].  The entity-body is
556
557
558
559Fielding, et al.          Expires July 15, 2008                [Page 10]
560
561Internet-Draft              HTTP/1.1, Part 2                January 2008
562
563
564   obtained from the message-body by decoding any Transfer-Encoding that
565   might have been applied to ensure safe and proper transfer of the
566   message.
567
568
5698.  Method Definitions
570
571   The set of common methods for HTTP/1.1 is defined below.  Although
572   this set can be expanded, additional methods cannot be assumed to
573   share the same semantics for separately extended clients and servers.
574   The Host request-header field (Section 8.4 of [Part1]) MUST accompany
575   all HTTP/1.1 requests.
576
5778.1.  Safe and Idempotent Methods
578
5798.1.1.  Safe Methods
580
581   Implementors should be aware that the software represents the user in
582   their interactions over the Internet, and should be careful to allow
583   the user to be aware of any actions they might take which may have an
584   unexpected significance to themselves or others.
585
586   In particular, the convention has been established that the GET and
587   HEAD methods SHOULD NOT have the significance of taking an action
588   other than retrieval.  These methods ought to be considered "safe".
589   This allows user agents to represent other methods, such as POST, PUT
590   and DELETE, in a special way, so that the user is made aware of the
591   fact that a possibly unsafe action is being requested.
592
593   Naturally, it is not possible to ensure that the server does not
594   generate side-effects as a result of performing a GET request; in
595   fact, some dynamic resources consider that a feature.  The important
596   distinction here is that the user did not request the side-effects,
597   so therefore cannot be held accountable for them.
598
5998.1.2.  Idempotent Methods
600
601   Methods can also have the property of "idempotence" in that (aside
602   from error or expiration issues) the side-effects of N > 0 identical
603   requests is the same as for a single request.  The methods GET, HEAD,
604   PUT and DELETE share this property.  Also, the methods OPTIONS and
605   TRACE SHOULD NOT have side effects, and so are inherently idempotent.
606
607   However, it is possible that a sequence of several requests is non-
608   idempotent, even if all of the methods executed in that sequence are
609   idempotent.  (A sequence is idempotent if a single execution of the
610   entire sequence always yields a result that is not changed by a
611   reexecution of all, or part, of that sequence.)  For example, a
612
613
614
615Fielding, et al.          Expires July 15, 2008                [Page 11]
616
617Internet-Draft              HTTP/1.1, Part 2                January 2008
618
619
620   sequence is non-idempotent if its result depends on a value that is
621   later modified in the same sequence.
622
623   A sequence that never has side effects is idempotent, by definition
624   (provided that no concurrent operations are being executed on the
625   same set of resources).
626
6278.2.  OPTIONS
628
629   The OPTIONS method represents a request for information about the
630   communication options available on the request/response chain
631   identified by the Request-URI.  This method allows the client to
632   determine the options and/or requirements associated with a resource,
633   or the capabilities of a server, without implying a resource action
634   or initiating a resource retrieval.
635
636   Responses to this method are not cacheable.
637
638   If the OPTIONS request includes an entity-body (as indicated by the
639   presence of Content-Length or Transfer-Encoding), then the media type
640   MUST be indicated by a Content-Type field.  Although this
641   specification does not define any use for such a body, future
642   extensions to HTTP might use the OPTIONS body to make more detailed
643   queries on the server.  A server that does not support such an
644   extension MAY discard the request body.
645
646   If the Request-URI is an asterisk ("*"), the OPTIONS request is
647   intended to apply to the server in general rather than to a specific
648   resource.  Since a server's communication options typically depend on
649   the resource, the "*" request is only useful as a "ping" or "no-op"
650   type of method; it does nothing beyond allowing the client to test
651   the capabilities of the server.  For example, this can be used to
652   test a proxy for HTTP/1.1 compliance (or lack thereof).
653
654   If the Request-URI is not an asterisk, the OPTIONS request applies
655   only to the options that are available when communicating with that
656   resource.
657
658   A 200 response SHOULD include any header fields that indicate
659   optional features implemented by the server and applicable to that
660   resource (e.g., Allow), possibly including extensions not defined by
661   this specification.  The response body, if any, SHOULD also include
662   information about the communication options.  The format for such a
663   body is not defined by this specification, but might be defined by
664   future extensions to HTTP.  Content negotiation MAY be used to select
665   the appropriate response format.  If no response body is included,
666   the response MUST include a Content-Length field with a field-value
667   of "0".
668
669
670
671Fielding, et al.          Expires July 15, 2008                [Page 12]
672
673Internet-Draft              HTTP/1.1, Part 2                January 2008
674
675
676   The Max-Forwards request-header field MAY be used to target a
677   specific proxy in the request chain.  When a proxy receives an
678   OPTIONS request on an absoluteURI for which request forwarding is
679   permitted, the proxy MUST check for a Max-Forwards field.  If the
680   Max-Forwards field-value is zero ("0"), the proxy MUST NOT forward
681   the message; instead, the proxy SHOULD respond with its own
682   communication options.  If the Max-Forwards field-value is an integer
683   greater than zero, the proxy MUST decrement the field-value when it
684   forwards the request.  If no Max-Forwards field is present in the
685   request, then the forwarded request MUST NOT include a Max-Forwards
686   field.
687
6888.3.  GET
689
690   The GET method means retrieve whatever information (in the form of an
691   entity) is identified by the Request-URI.  If the Request-URI refers
692   to a data-producing process, it is the produced data which shall be
693   returned as the entity in the response and not the source text of the
694   process, unless that text happens to be the output of the process.
695
696   The semantics of the GET method change to a "conditional GET" if the
697   request message includes an If-Modified-Since, If-Unmodified-Since,
698   If-Match, If-None-Match, or If-Range header field.  A conditional GET
699   method requests that the entity be transferred only under the
700   circumstances described by the conditional header field(s).  The
701   conditional GET method is intended to reduce unnecessary network
702   usage by allowing cached entities to be refreshed without requiring
703   multiple requests or transferring data already held by the client.
704
705   The semantics of the GET method change to a "partial GET" if the
706   request message includes a Range header field.  A partial GET
707   requests that only part of the entity be transferred, as described in
708   Section 5.4 of [Part5].  The partial GET method is intended to reduce
709   unnecessary network usage by allowing partially-retrieved entities to
710   be completed without transferring data already held by the client.
711
712   The response to a GET request is cacheable if and only if it meets
713   the requirements for HTTP caching described in [Part6].
714
715   See Section 12.2 for security considerations when used for forms.
716
7178.4.  HEAD
718
719   The HEAD method is identical to GET except that the server MUST NOT
720   return a message-body in the response.  The metainformation contained
721   in the HTTP headers in response to a HEAD request SHOULD be identical
722   to the information sent in response to a GET request.  This method
723   can be used for obtaining metainformation about the entity implied by
724
725
726
727Fielding, et al.          Expires July 15, 2008                [Page 13]
728
729Internet-Draft              HTTP/1.1, Part 2                January 2008
730
731
732   the request without transferring the entity-body itself.  This method
733   is often used for testing hypertext links for validity,
734   accessibility, and recent modification.
735
736   The response to a HEAD request MAY be cacheable in the sense that the
737   information contained in the response MAY be used to update a
738   previously cached entity from that resource.  If the new field values
739   indicate that the cached entity differs from the current entity (as
740   would be indicated by a change in Content-Length, Content-MD5, ETag
741   or Last-Modified), then the cache MUST treat the cache entry as
742   stale.
743
7448.5.  POST
745
746   The POST method is used to request that the origin server accept the
747   entity enclosed in the request as data to be processed by the
748   resource identified by the Request-URI in the Request-Line.  POST is
749   designed to allow a uniform method to cover the following functions:
750
751   o  Annotation of existing resources;
752
753   o  Posting a message to a bulletin board, newsgroup, mailing list, or
754      similar group of articles;
755
756   o  Providing a block of data, such as the result of submitting a
757      form, to a data-handling process;
758
759   o  Extending a database through an append operation.
760
761   The actual function performed by the POST method is determined by the
762   server and is usually dependent on the Request-URI.
763
764   The action performed by the POST method might not result in a
765   resource that can be identified by a URI.  In this case, either 200
766   (OK) or 204 (No Content) is the appropriate response status,
767   depending on whether or not the response includes an entity that
768   describes the result.
769
770   If a resource has been created on the origin server, the response
771   SHOULD be 201 (Created) and contain an entity which describes the
772   status of the request and refers to the new resource, and a Location
773   header (see Section 10.4).
774
775   Responses to this method are not cacheable, unless the response
776   includes appropriate Cache-Control or Expires header fields.
777   However, the 303 (See Other) response can be used to direct the user
778   agent to retrieve a cacheable resource.
779
780
781
782
783Fielding, et al.          Expires July 15, 2008                [Page 14]
784
785Internet-Draft              HTTP/1.1, Part 2                January 2008
786
787
7888.6.  PUT
789
790   The PUT method requests that the enclosed entity be stored under the
791   supplied Request-URI.  If the Request-URI refers to an already
792   existing resource, the enclosed entity SHOULD be considered as a
793   modified version of the one residing on the origin server.  If the
794   Request-URI does not point to an existing resource, and that URI is
795   capable of being defined as a new resource by the requesting user
796   agent, the origin server can create the resource with that URI.  If a
797   new resource is created, the origin server MUST inform the user agent
798   via the 201 (Created) response.  If an existing resource is modified,
799   either the 200 (OK) or 204 (No Content) response codes SHOULD be sent
800   to indicate successful completion of the request.  If the resource
801   could not be created or modified with the Request-URI, an appropriate
802   error response SHOULD be given that reflects the nature of the
803   problem.  The recipient of the entity MUST NOT ignore any Content-*
804   (e.g.  Content-Range) headers that it does not understand or
805   implement and MUST return a 501 (Not Implemented) response in such
806   cases.
807
808   If the request passes through a cache and the Request-URI identifies
809   one or more currently cached entities, those entries SHOULD be
810   treated as stale.  Responses to this method are not cacheable.
811
812   The fundamental difference between the POST and PUT requests is
813   reflected in the different meaning of the Request-URI.  The URI in a
814   POST request identifies the resource that will handle the enclosed
815   entity.  That resource might be a data-accepting process, a gateway
816   to some other protocol, or a separate entity that accepts
817   annotations.  In contrast, the URI in a PUT request identifies the
818   entity enclosed with the request -- the user agent knows what URI is
819   intended and the server MUST NOT attempt to apply the request to some
820   other resource.  If the server desires that the request be applied to
821   a different URI, it MUST send a 301 (Moved Permanently) response; the
822   user agent MAY then make its own decision regarding whether or not to
823   redirect the request.
824
825   A single resource MAY be identified by many different URIs.  For
826   example, an article might have a URI for identifying "the current
827   version" which is separate from the URI identifying each particular
828   version.  In this case, a PUT request on a general URI might result
829   in several other URIs being defined by the origin server.
830
831   HTTP/1.1 does not define how a PUT method affects the state of an
832   origin server.
833
834   Unless otherwise specified for a particular entity-header, the
835   entity-headers in the PUT request SHOULD be applied to the resource
836
837
838
839Fielding, et al.          Expires July 15, 2008                [Page 15]
840
841Internet-Draft              HTTP/1.1, Part 2                January 2008
842
843
844   created or modified by the PUT.
845
8468.7.  DELETE
847
848   The DELETE method requests that the origin server delete the resource
849   identified by the Request-URI.  This method MAY be overridden by
850   human intervention (or other means) on the origin server.  The client
851   cannot be guaranteed that the operation has been carried out, even if
852   the status code returned from the origin server indicates that the
853   action has been completed successfully.  However, the server SHOULD
854   NOT indicate success unless, at the time the response is given, it
855   intends to delete the resource or move it to an inaccessible
856   location.
857
858   A successful response SHOULD be 200 (OK) if the response includes an
859   entity describing the status, 202 (Accepted) if the action has not
860   yet been enacted, or 204 (No Content) if the action has been enacted
861   but the response does not include an entity.
862
863   If the request passes through a cache and the Request-URI identifies
864   one or more currently cached entities, those entries SHOULD be
865   treated as stale.  Responses to this method are not cacheable.
866
8678.8.  TRACE
868
869   The TRACE method is used to invoke a remote, application-layer loop-
870   back of the request message.  The final recipient of the request
871   SHOULD reflect the message received back to the client as the entity-
872   body of a 200 (OK) response.  The final recipient is either the
873   origin server or the first proxy or gateway to receive a Max-Forwards
874   value of zero (0) in the request (see Section 10.5).  A TRACE request
875   MUST NOT include an entity.
876
877   TRACE allows the client to see what is being received at the other
878   end of the request chain and use that data for testing or diagnostic
879   information.  The value of the Via header field (Section 8.9 of
880   [Part1]) is of particular interest, since it acts as a trace of the
881   request chain.  Use of the Max-Forwards header field allows the
882   client to limit the length of the request chain, which is useful for
883   testing a chain of proxies forwarding messages in an infinite loop.
884
885   If the request is valid, the response SHOULD contain the entire
886   request message in the entity-body, with a Content-Type of "message/
887   http".  Responses to this method MUST NOT be cached.
888
889
890
891
892
893
894
895Fielding, et al.          Expires July 15, 2008                [Page 16]
896
897Internet-Draft              HTTP/1.1, Part 2                January 2008
898
899
9008.9.  CONNECT
901
902   This specification reserves the method name CONNECT for use with a
903   proxy that can dynamically switch to being a tunnel (e.g.  SSL
904   tunneling [Luo1998]).
905
906
9079.  Status Code Definitions
908
909   Each Status-Code is described below, including a description of which
910   method(s) it can follow and any metainformation required in the
911   response.
912
9139.1.  Informational 1xx
914
915   This class of status code indicates a provisional response,
916   consisting only of the Status-Line and optional headers, and is
917   terminated by an empty line.  There are no required headers for this
918   class of status code.  Since HTTP/1.0 did not define any 1xx status
919   codes, servers MUST NOT send a 1xx response to an HTTP/1.0 client
920   except under experimental conditions.
921
922   A client MUST be prepared to accept one or more 1xx status responses
923   prior to a regular response, even if the client does not expect a 100
924   (Continue) status message.  Unexpected 1xx status responses MAY be
925   ignored by a user agent.
926
927   Proxies MUST forward 1xx responses, unless the connection between the
928   proxy and its client has been closed, or unless the proxy itself
929   requested the generation of the 1xx response.  (For example, if a
930   proxy adds a "Expect: 100-continue" field when it forwards a request,
931   then it need not forward the corresponding 100 (Continue)
932   response(s).)
933
9349.1.1.  100 Continue
935
936   The client SHOULD continue with its request.  This interim response
937   is used to inform the client that the initial part of the request has
938   been received and has not yet been rejected by the server.  The
939   client SHOULD continue by sending the remainder of the request or, if
940   the request has already been completed, ignore this response.  The
941   server MUST send a final response after the request has been
942   completed.  See Section 7.2.3 of [Part1] for detailed discussion of
943   the use and handling of this status code.
944
945
946
947
948
949
950
951Fielding, et al.          Expires July 15, 2008                [Page 17]
952
953Internet-Draft              HTTP/1.1, Part 2                January 2008
954
955
9569.1.2.  101 Switching Protocols
957
958   The server understands and is willing to comply with the client's
959   request, via the Upgrade message header field (Section 5.4 of
960   [Part5]), for a change in the application protocol being used on this
961   connection.  The server will switch protocols to those defined by the
962   response's Upgrade header field immediately after the empty line
963   which terminates the 101 response.
964
965   The protocol SHOULD be switched only when it is advantageous to do
966   so.  For example, switching to a newer version of HTTP is
967   advantageous over older versions, and switching to a real-time,
968   synchronous protocol might be advantageous when delivering resources
969   that use such features.
970
9719.2.  Successful 2xx
972
973   This class of status code indicates that the client's request was
974   successfully received, understood, and accepted.
975
9769.2.1.  200 OK
977
978   The request has succeeded.  The information returned with the
979   response is dependent on the method used in the request, for example:
980
981   GET  an entity corresponding to the requested resource is sent in the
982      response;
983
984   HEAD  the entity-header fields corresponding to the requested
985      resource are sent in the response without any message-body;
986
987   POST  an entity describing or containing the result of the action;
988
989   TRACE  an entity containing the request message as received by the
990      end server.
991
9929.2.2.  201 Created
993
994   The request has been fulfilled and resulted in a new resource being
995   created.  The newly created resource can be referenced by the URI(s)
996   returned in the entity of the response, with the most specific URI
997   for the resource given by a Location header field.  The response
998   SHOULD include an entity containing a list of resource
999   characteristics and location(s) from which the user or user agent can
1000   choose the one most appropriate.  The entity format is specified by
1001   the media type given in the Content-Type header field.  The origin
1002   server MUST create the resource before returning the 201 status code.
1003   If the action cannot be carried out immediately, the server SHOULD
1004
1005
1006
1007Fielding, et al.          Expires July 15, 2008                [Page 18]
1008
1009Internet-Draft              HTTP/1.1, Part 2                January 2008
1010
1011
1012   respond with 202 (Accepted) response instead.
1013
1014   A 201 response MAY contain an ETag response header field indicating
1015   the current value of the entity tag for the requested variant just
1016   created, see Section 6.1 of [Part4].
1017
10189.2.3.  202 Accepted
1019
1020   The request has been accepted for processing, but the processing has
1021   not been completed.  The request might or might not eventually be
1022   acted upon, as it might be disallowed when processing actually takes
1023   place.  There is no facility for re-sending a status code from an
1024   asynchronous operation such as this.
1025
1026   The 202 response is intentionally non-committal.  Its purpose is to
1027   allow a server to accept a request for some other process (perhaps a
1028   batch-oriented process that is only run once per day) without
1029   requiring that the user agent's connection to the server persist
1030   until the process is completed.  The entity returned with this
1031   response SHOULD include an indication of the request's current status
1032   and either a pointer to a status monitor or some estimate of when the
1033   user can expect the request to be fulfilled.
1034
10359.2.4.  203 Non-Authoritative Information
1036
1037   The returned metainformation in the entity-header is not the
1038   definitive set as available from the origin server, but is gathered
1039   from a local or a third-party copy.  The set presented MAY be a
1040   subset or superset of the original version.  For example, including
1041   local annotation information about the resource might result in a
1042   superset of the metainformation known by the origin server.  Use of
1043   this response code is not required and is only appropriate when the
1044   response would otherwise be 200 (OK).
1045
10469.2.5.  204 No Content
1047
1048   The server has fulfilled the request but does not need to return an
1049   entity-body, and might want to return updated metainformation.  The
1050   response MAY include new or updated metainformation in the form of
1051   entity-headers, which if present SHOULD be associated with the
1052   requested variant.
1053
1054   If the client is a user agent, it SHOULD NOT change its document view
1055   from that which caused the request to be sent.  This response is
1056   primarily intended to allow input for actions to take place without
1057   causing a change to the user agent's active document view, although
1058   any new or updated metainformation SHOULD be applied to the document
1059   currently in the user agent's active view.
1060
1061
1062
1063Fielding, et al.          Expires July 15, 2008                [Page 19]
1064
1065Internet-Draft              HTTP/1.1, Part 2                January 2008
1066
1067
1068   The 204 response MUST NOT include a message-body, and thus is always
1069   terminated by the first empty line after the header fields.
1070
10719.2.6.  205 Reset Content
1072
1073   The server has fulfilled the request and the user agent SHOULD reset
1074   the document view which caused the request to be sent.  This response
1075   is primarily intended to allow input for actions to take place via
1076   user input, followed by a clearing of the form in which the input is
1077   given so that the user can easily initiate another input action.  The
1078   response MUST NOT include an entity.
1079
10809.2.7.  206 Partial Content
1081
1082   The server has fulfilled the partial GET request for the resource and
1083   the enclosed entity is a partial representation as defined in
1084   [Part5].
1085
10869.3.  Redirection 3xx
1087
1088   This class of status code indicates that further action needs to be
1089   taken by the user agent in order to fulfill the request.  The action
1090   required MAY be carried out by the user agent without interaction
1091   with the user if and only if the method used in the second request is
1092   GET or HEAD.  A client SHOULD detect infinite redirection loops,
1093   since such loops generate network traffic for each redirection.
1094
1095      Note: previous versions of this specification recommended a
1096      maximum of five redirections.  Content developers should be aware
1097      that there might be clients that implement such a fixed
1098      limitation.
1099
11009.3.1.  300 Multiple Choices
1101
1102   The requested resource corresponds to any one of a set of
1103   representations, each with its own specific location, and agent-
1104   driven negotiation information (Section 4 of [Part3]) is being
1105   provided so that the user (or user agent) can select a preferred
1106   representation and redirect its request to that location.
1107
1108   Unless it was a HEAD request, the response SHOULD include an entity
1109   containing a list of resource characteristics and location(s) from
1110   which the user or user agent can choose the one most appropriate.
1111   The entity format is specified by the media type given in the
1112   Content-Type header field.  Depending upon the format and the
1113   capabilities of the user agent, selection of the most appropriate
1114   choice MAY be performed automatically.  However, this specification
1115   does not define any standard for such automatic selection.
1116
1117
1118
1119Fielding, et al.          Expires July 15, 2008                [Page 20]
1120
1121Internet-Draft              HTTP/1.1, Part 2                January 2008
1122
1123
1124   If the server has a preferred choice of representation, it SHOULD
1125   include the specific URI for that representation in the Location
1126   field; user agents MAY use the Location field value for automatic
1127   redirection.  This response is cacheable unless indicated otherwise.
1128
11299.3.2.  301 Moved Permanently
1130
1131   The requested resource has been assigned a new permanent URI and any
1132   future references to this resource SHOULD use one of the returned
1133   URIs.  Clients with link editing capabilities ought to automatically
1134   re-link references to the Request-URI to one or more of the new
1135   references returned by the server, where possible.  This response is
1136   cacheable unless indicated otherwise.
1137
1138   The new permanent URI SHOULD be given by the Location field in the
1139   response.  Unless the request method was HEAD, the entity of the
1140   response SHOULD contain a short hypertext note with a hyperlink to
1141   the new URI(s).
1142
1143   If the 301 status code is received in response to a request method
1144   that is known to be "safe", as defined in Section 8.1.1, then the
1145   request MAY be automatically redirected by the user agent without
1146   confirmation.  Otherwise, the user agent MUST NOT automatically
1147   redirect the request unless it can be confirmed by the user, since
1148   this might change the conditions under which the request was issued.
1149
1150      Note: When automatically redirecting a POST request after
1151      receiving a 301 status code, some existing HTTP/1.0 user agents
1152      will erroneously change it into a GET request.
1153
11549.3.3.  302 Found
1155
1156   The requested resource resides temporarily under a different URI.
1157   Since the redirection might be altered on occasion, the client SHOULD
1158   continue to use the Request-URI for future requests.  This response
1159   is only cacheable if indicated by a Cache-Control or Expires header
1160   field.
1161
1162   The temporary URI SHOULD be given by the Location field in the
1163   response.  Unless the request method was HEAD, the entity of the
1164   response SHOULD contain a short hypertext note with a hyperlink to
1165   the new URI(s).
1166
1167   If the 302 status code is received in response to a request method
1168   that is known to be "safe", as defined in Section 8.1.1, then the
1169   request MAY be automatically redirected by the user agent without
1170   confirmation.  Otherwise, the user agent MUST NOT automatically
1171   redirect the request unless it can be confirmed by the user, since
1172
1173
1174
1175Fielding, et al.          Expires July 15, 2008                [Page 21]
1176
1177Internet-Draft              HTTP/1.1, Part 2                January 2008
1178
1179
1180   this might change the conditions under which the request was issued.
1181
1182      Note: [RFC1945] and [RFC2068] specify that the client is not
1183      allowed to change the method on the redirected request.  However,
1184      most existing user agent implementations treat 302 as if it were a
1185      303 response, performing a GET on the Location field-value
1186      regardless of the original request method.  The status codes 303
1187      and 307 have been added for servers that wish to make
1188      unambiguously clear which kind of reaction is expected of the
1189      client.
1190
11919.3.4.  303 See Other
1192
1193   The response to the request can be found under a different URI and
1194   SHOULD be retrieved using a GET method on that resource.  This method
1195   exists primarily to allow the output of a POST-activated script to
1196   redirect the user agent to a selected resource.  The new URI is not a
1197   substitute reference for the originally requested resource.  The 303
1198   response MUST NOT be cached, but the response to the second
1199   (redirected) request might be cacheable.
1200
1201   The different URI SHOULD be given by the Location field in the
1202   response.  Unless the request method was HEAD, the entity of the
1203   response SHOULD contain a short hypertext note with a hyperlink to
1204   the new URI(s).
1205
1206      Note: Many pre-HTTP/1.1 user agents do not understand the 303
1207      status.  When interoperability with such clients is a concern, the
1208      302 status code may be used instead, since most user agents react
1209      to a 302 response as described here for 303.
1210
12119.3.5.  304 Not Modified
1212
1213   The response to the request has not been modified since the
1214   conditions indicated by the client's conditional GET request, as
1215   defined in [Part4].
1216
12179.3.6.  305 Use Proxy
1218
1219   The requested resource MUST be accessed through the proxy given by
1220   the Location field.  The Location field gives the URI of the proxy.
1221   The recipient is expected to repeat this single request via the
1222   proxy. 305 responses MUST only be generated by origin servers.
1223
1224      Note: [RFC2068] was not clear that 305 was intended to redirect a
1225      single request, and to be generated by origin servers only.  Not
1226      observing these limitations has significant security consequences.
1227
1228
1229
1230
1231Fielding, et al.          Expires July 15, 2008                [Page 22]
1232
1233Internet-Draft              HTTP/1.1, Part 2                January 2008
1234
1235
12369.3.7.  306 (Unused)
1237
1238   The 306 status code was used in a previous version of the
1239   specification, is no longer used, and the code is reserved.
1240
12419.3.8.  307 Temporary Redirect
1242
1243   The requested resource resides temporarily under a different URI.
1244   Since the redirection MAY be altered on occasion, the client SHOULD
1245   continue to use the Request-URI for future requests.  This response
1246   is only cacheable if indicated by a Cache-Control or Expires header
1247   field.
1248
1249   The temporary URI SHOULD be given by the Location field in the
1250   response.  Unless the request method was HEAD, the entity of the
1251   response SHOULD contain a short hypertext note with a hyperlink to
1252   the new URI(s) , since many pre-HTTP/1.1 user agents do not
1253   understand the 307 status.  Therefore, the note SHOULD contain the
1254   information necessary for a user to repeat the original request on
1255   the new URI.
1256
1257   If the 307 status code is received in response to a request method
1258   that is known to be "safe", as defined in Section 8.1.1, then the
1259   request MAY be automatically redirected by the user agent without
1260   confirmation.  Otherwise, the user agent MUST NOT automatically
1261   redirect the request unless it can be confirmed by the user, since
1262   this might change the conditions under which the request was issued.
1263
12649.4.  Client Error 4xx
1265
1266   The 4xx class of status code is intended for cases in which the
1267   client seems to have erred.  Except when responding to a HEAD
1268   request, the server SHOULD include an entity containing an
1269   explanation of the error situation, and whether it is a temporary or
1270   permanent condition.  These status codes are applicable to any
1271   request method.  User agents SHOULD display any included entity to
1272   the user.
1273
1274   If the client is sending data, a server implementation using TCP
1275   SHOULD be careful to ensure that the client acknowledges receipt of
1276   the packet(s) containing the response, before the server closes the
1277   input connection.  If the client continues sending data to the server
1278   after the close, the server's TCP stack will send a reset packet to
1279   the client, which may erase the client's unacknowledged input buffers
1280   before they can be read and interpreted by the HTTP application.
1281
1282
1283
1284
1285
1286
1287Fielding, et al.          Expires July 15, 2008                [Page 23]
1288
1289Internet-Draft              HTTP/1.1, Part 2                January 2008
1290
1291
12929.4.1.  400 Bad Request
1293
1294   The request could not be understood by the server due to malformed
1295   syntax.  The client SHOULD NOT repeat the request without
1296   modifications.
1297
12989.4.2.  401 Unauthorized
1299
1300   The request requires user authentication (see [Part7]).
1301
13029.4.3.  402 Payment Required
1303
1304   This code is reserved for future use.
1305
13069.4.4.  403 Forbidden
1307
1308   The server understood the request, but is refusing to fulfill it.
1309   Authorization will not help and the request SHOULD NOT be repeated.
1310   If the request method was not HEAD and the server wishes to make
1311   public why the request has not been fulfilled, it SHOULD describe the
1312   reason for the refusal in the entity.  If the server does not wish to
1313   make this information available to the client, the status code 404
1314   (Not Found) can be used instead.
1315
13169.4.5.  404 Not Found
1317
1318   The server has not found anything matching the Request-URI.  No
1319   indication is given of whether the condition is temporary or
1320   permanent.  The 410 (Gone) status code SHOULD be used if the server
1321   knows, through some internally configurable mechanism, that an old
1322   resource is permanently unavailable and has no forwarding address.
1323   This status code is commonly used when the server does not wish to
1324   reveal exactly why the request has been refused, or when no other
1325   response is applicable.
1326
13279.4.6.  405 Method Not Allowed
1328
1329   The method specified in the Request-Line is not allowed for the
1330   resource identified by the Request-URI.  The response MUST include an
1331   Allow header containing a list of valid methods for the requested
1332   resource.
1333
13349.4.7.  406 Not Acceptable
1335
1336   The resource identified by the request is only capable of generating
1337   response entities which have content characteristics not acceptable
1338   according to the accept headers sent in the request.
1339
1340
1341
1342
1343Fielding, et al.          Expires July 15, 2008                [Page 24]
1344
1345Internet-Draft              HTTP/1.1, Part 2                January 2008
1346
1347
1348   Unless it was a HEAD request, the response SHOULD include an entity
1349   containing a list of available entity characteristics and location(s)
1350   from which the user or user agent can choose the one most
1351   appropriate.  The entity format is specified by the media type given
1352   in the Content-Type header field.  Depending upon the format and the
1353   capabilities of the user agent, selection of the most appropriate
1354   choice MAY be performed automatically.  However, this specification
1355   does not define any standard for such automatic selection.
1356
1357      Note: HTTP/1.1 servers are allowed to return responses which are
1358      not acceptable according to the accept headers sent in the
1359      request.  In some cases, this may even be preferable to sending a
1360      406 response.  User agents are encouraged to inspect the headers
1361      of an incoming response to determine if it is acceptable.
1362
1363   If the response could be unacceptable, a user agent SHOULD
1364   temporarily stop receipt of more data and query the user for a
1365   decision on further actions.
1366
13679.4.8.  407 Proxy Authentication Required
1368
1369   This code is similar to 401 (Unauthorized), but indicates that the
1370   client must first authenticate itself with the proxy (see [Part7]).
1371
13729.4.9.  408 Request Timeout
1373
1374   The client did not produce a request within the time that the server
1375   was prepared to wait.  The client MAY repeat the request without
1376   modifications at any later time.
1377
13789.4.10.  409 Conflict
1379
1380   The request could not be completed due to a conflict with the current
1381   state of the resource.  This code is only allowed in situations where
1382   it is expected that the user might be able to resolve the conflict
1383   and resubmit the request.  The response body SHOULD include enough
1384   information for the user to recognize the source of the conflict.
1385   Ideally, the response entity would include enough information for the
1386   user or user agent to fix the problem; however, that might not be
1387   possible and is not required.
1388
1389   Conflicts are most likely to occur in response to a PUT request.  For
1390   example, if versioning were being used and the entity being PUT
1391   included changes to a resource which conflict with those made by an
1392   earlier (third-party) request, the server might use the 409 response
1393   to indicate that it can't complete the request.  In this case, the
1394   response entity would likely contain a list of the differences
1395   between the two versions in a format defined by the response Content-
1396
1397
1398
1399Fielding, et al.          Expires July 15, 2008                [Page 25]
1400
1401Internet-Draft              HTTP/1.1, Part 2                January 2008
1402
1403
1404   Type.
1405
14069.4.11.  410 Gone
1407
1408   The requested resource is no longer available at the server and no
1409   forwarding address is known.  This condition is expected to be
1410   considered permanent.  Clients with link editing capabilities SHOULD
1411   delete references to the Request-URI after user approval.  If the
1412   server does not know, or has no facility to determine, whether or not
1413   the condition is permanent, the status code 404 (Not Found) SHOULD be
1414   used instead.  This response is cacheable unless indicated otherwise.
1415
1416   The 410 response is primarily intended to assist the task of web
1417   maintenance by notifying the recipient that the resource is
1418   intentionally unavailable and that the server owners desire that
1419   remote links to that resource be removed.  Such an event is common
1420   for limited-time, promotional services and for resources belonging to
1421   individuals no longer working at the server's site.  It is not
1422   necessary to mark all permanently unavailable resources as "gone" or
1423   to keep the mark for any length of time -- that is left to the
1424   discretion of the server owner.
1425
14269.4.12.  411 Length Required
1427
1428   The server refuses to accept the request without a defined Content-
1429   Length.  The client MAY repeat the request if it adds a valid
1430   Content-Length header field containing the length of the message-body
1431   in the request message.
1432
14339.4.13.  412 Precondition Failed
1434
1435   The precondition given in one or more of the request-header fields
1436   evaluated to false when it was tested on the server, as defined in
1437   [Part4].
1438
14399.4.14.  413 Request Entity Too Large
1440
1441   The server is refusing to process a request because the request
1442   entity is larger than the server is willing or able to process.  The
1443   server MAY close the connection to prevent the client from continuing
1444   the request.
1445
1446   If the condition is temporary, the server SHOULD include a Retry-
1447   After header field to indicate that it is temporary and after what
1448   time the client MAY try again.
1449
1450
1451
1452
1453
1454
1455Fielding, et al.          Expires July 15, 2008                [Page 26]
1456
1457Internet-Draft              HTTP/1.1, Part 2                January 2008
1458
1459
14609.4.15.  414 Request-URI Too Long
1461
1462   The server is refusing to service the request because the Request-URI
1463   is longer than the server is willing to interpret.  This rare
1464   condition is only likely to occur when a client has improperly
1465   converted a POST request to a GET request with long query
1466   information, when the client has descended into a URI "black hole" of
1467   redirection (e.g., a redirected URI prefix that points to a suffix of
1468   itself), or when the server is under attack by a client attempting to
1469   exploit security holes present in some servers using fixed-length
1470   buffers for reading or manipulating the Request-URI.
1471
14729.4.16.  415 Unsupported Media Type
1473
1474   The server is refusing to service the request because the entity of
1475   the request is in a format not supported by the requested resource
1476   for the requested method.
1477
14789.4.17.  416 Requested Range Not Satisfiable
1479
1480   The request included a Range request-header field (Section 5.4 of
1481   [Part5]) and none of the range-specifier values in this field overlap
1482   the current extent of the selected resource.
1483
14849.4.18.  417 Expectation Failed
1485
1486   The expectation given in an Expect request-header field (see
1487   Section 10.2) could not be met by this server, or, if the server is a
1488   proxy, the server has unambiguous evidence that the request could not
1489   be met by the next-hop server.
1490
14919.5.  Server Error 5xx
1492
1493   Response status codes beginning with the digit "5" indicate cases in
1494   which the server is aware that it has erred or is incapable of
1495   performing the request.  Except when responding to a HEAD request,
1496   the server SHOULD include an entity containing an explanation of the
1497   error situation, and whether it is a temporary or permanent
1498   condition.  User agents SHOULD display any included entity to the
1499   user.  These response codes are applicable to any request method.
1500
15019.5.1.  500 Internal Server Error
1502
1503   The server encountered an unexpected condition which prevented it
1504   from fulfilling the request.
1505
1506
1507
1508
1509
1510
1511Fielding, et al.          Expires July 15, 2008                [Page 27]
1512
1513Internet-Draft              HTTP/1.1, Part 2                January 2008
1514
1515
15169.5.2.  501 Not Implemented
1517
1518   The server does not support the functionality required to fulfill the
1519   request.  This is the appropriate response when the server does not
1520   recognize the request method and is not capable of supporting it for
1521   any resource.
1522
15239.5.3.  502 Bad Gateway
1524
1525   The server, while acting as a gateway or proxy, received an invalid
1526   response from the upstream server it accessed in attempting to
1527   fulfill the request.
1528
15299.5.4.  503 Service Unavailable
1530
1531   The server is currently unable to handle the request due to a
1532   temporary overloading or maintenance of the server.  The implication
1533   is that this is a temporary condition which will be alleviated after
1534   some delay.  If known, the length of the delay MAY be indicated in a
1535   Retry-After header.  If no Retry-After is given, the client SHOULD
1536   handle the response as it would for a 500 response.
1537
1538      Note: The existence of the 503 status code does not imply that a
1539      server must use it when becoming overloaded.  Some servers may
1540      wish to simply refuse the connection.
1541
15429.5.5.  504 Gateway Timeout
1543
1544   The server, while acting as a gateway or proxy, did not receive a
1545   timely response from the upstream server specified by the URI (e.g.
1546   HTTP, FTP, LDAP) or some other auxiliary server (e.g.  DNS) it needed
1547   to access in attempting to complete the request.
1548
1549      Note: Note to implementors: some deployed proxies are known to
1550      return 400 or 500 when DNS lookups time out.
1551
15529.5.6.  505 HTTP Version Not Supported
1553
1554   The server does not support, or refuses to support, the HTTP protocol
1555   version that was used in the request message.  The server is
1556   indicating that it is unable or unwilling to complete the request
1557   using the same major version as the client, as described in Section
1558   3.1 of [Part1], other than with this error message.  The response
1559   SHOULD contain an entity describing why that version is not supported
1560   and what other protocols are supported by that server.
1561
1562
1563
1564
1565
1566
1567Fielding, et al.          Expires July 15, 2008                [Page 28]
1568
1569Internet-Draft              HTTP/1.1, Part 2                January 2008
1570
1571
157210.  Header Field Definitions
1573
1574   This section defines the syntax and semantics of HTTP/1.1 header
1575   fields related to request and response semantics.
1576
1577   For entity-header fields, both sender and recipient refer to either
1578   the client or the server, depending on who sends and who receives the
1579   entity.
1580
158110.1.  Allow
1582
1583   The Allow entity-header field lists the set of methods supported by
1584   the resource identified by the Request-URI.  The purpose of this
1585   field is strictly to inform the recipient of valid methods associated
1586   with the resource.  An Allow header field MUST be present in a 405
1587   (Method Not Allowed) response.
1588
1589     Allow   = "Allow" ":" #Method
1590
1591   Example of use:
1592
1593          Allow: GET, HEAD, PUT
1594
1595   This field cannot prevent a client from trying other methods.
1596   However, the indications given by the Allow header field value SHOULD
1597   be followed.  The actual set of allowed methods is defined by the
1598   origin server at the time of each request.
1599
1600   The Allow header field MAY be provided with a PUT request to
1601   recommend the methods to be supported by the new or modified
1602   resource.  The server is not required to support these methods and
1603   SHOULD include an Allow header in the response giving the actual
1604   supported methods.
1605
1606   A proxy MUST NOT modify the Allow header field even if it does not
1607   understand all the methods specified, since the user agent might have
1608   other means of communicating with the origin server.
1609
161010.2.  Expect
1611
1612   The Expect request-header field is used to indicate that particular
1613   server behaviors are required by the client.
1614
1615     Expect       =  "Expect" ":" 1#expectation
1616
1617     expectation  =  "100-continue" | expectation-extension
1618     expectation-extension =  token [ "=" ( token | quoted-string )
1619                              *expect-params ]
1620
1621
1622
1623Fielding, et al.          Expires July 15, 2008                [Page 29]
1624
1625Internet-Draft              HTTP/1.1, Part 2                January 2008
1626
1627
1628     expect-params =  ";" token [ "=" ( token | quoted-string ) ]
1629
1630   A server that does not understand or is unable to comply with any of
1631   the expectation values in the Expect field of a request MUST respond
1632   with appropriate error status.  The server MUST respond with a 417
1633   (Expectation Failed) status if any of the expectations cannot be met
1634   or, if there are other problems with the request, some other 4xx
1635   status.
1636
1637   This header field is defined with extensible syntax to allow for
1638   future extensions.  If a server receives a request containing an
1639   Expect field that includes an expectation-extension that it does not
1640   support, it MUST respond with a 417 (Expectation Failed) status.
1641
1642   Comparison of expectation values is case-insensitive for unquoted
1643   tokens (including the 100-continue token), and is case-sensitive for
1644   quoted-string expectation-extensions.
1645
1646   The Expect mechanism is hop-by-hop: that is, an HTTP/1.1 proxy MUST
1647   return a 417 (Expectation Failed) status if it receives a request
1648   with an expectation that it cannot meet.  However, the Expect
1649   request-header itself is end-to-end; it MUST be forwarded if the
1650   request is forwarded.
1651
1652   Many older HTTP/1.0 and HTTP/1.1 applications do not understand the
1653   Expect header.
1654
1655   See Section 7.2.3 of [Part1] for the use of the 100 (Continue)
1656   status.
1657
165810.3.  From
1659
1660   The From request-header field, if given, SHOULD contain an Internet
1661   e-mail address for the human user who controls the requesting user
1662   agent.  The address SHOULD be machine-usable, as defined by "mailbox"
1663   in Section 3.4 of [RFC2822]:
1664
1665     From   = "From" ":" mailbox
1666
1667   An example is:
1668
1669       From: webmaster@example.org
1670
1671   This header field MAY be used for logging purposes and as a means for
1672   identifying the source of invalid or unwanted requests.  It SHOULD
1673   NOT be used as an insecure form of access protection.  The
1674   interpretation of this field is that the request is being performed
1675   on behalf of the person given, who accepts responsibility for the
1676
1677
1678
1679Fielding, et al.          Expires July 15, 2008                [Page 30]
1680
1681Internet-Draft              HTTP/1.1, Part 2                January 2008
1682
1683
1684   method performed.  In particular, robot agents SHOULD include this
1685   header so that the person responsible for running the robot can be
1686   contacted if problems occur on the receiving end.
1687
1688   The Internet e-mail address in this field MAY be separate from the
1689   Internet host which issued the request.  For example, when a request
1690   is passed through a proxy the original issuer's address SHOULD be
1691   used.
1692
1693   The client SHOULD NOT send the From header field without the user's
1694   approval, as it might conflict with the user's privacy interests or
1695   their site's security policy.  It is strongly recommended that the
1696   user be able to disable, enable, and modify the value of this field
1697   at any time prior to a request.
1698
169910.4.  Location
1700
1701   The Location response-header field is used to redirect the recipient
1702   to a location other than the Request-URI for completion of the
1703   request or identification of a new resource.  For 201 (Created)
1704   responses, the Location is that of the new resource which was created
1705   by the request.  For 3xx responses, the location SHOULD indicate the
1706   server's preferred URI for automatic redirection to the resource.
1707   The field value consists of a single absolute URI.
1708
1709     Location       = "Location" ":" absoluteURI [ "#" fragment ]
1710
1711   An example is:
1712
1713       Location: http://www.example.org/pub/WWW/People.html
1714
1715      Note: The Content-Location header field (Section 5.7 of [Part3])
1716      differs from Location in that the Content-Location identifies the
1717      original location of the entity enclosed in the request.  It is
1718      therefore possible for a response to contain header fields for
1719      both Location and Content-Location.
1720
1721   There are circumstances in which a fragment identifier in a Location
1722   URL would not be appropriate:
1723
1724   o  With a 201 Created response, because in this usage the Location
1725      header specifies the URL for the entire created resource.
1726
1727   o  With a 300 Multiple Choices, since the choice decision is intended
1728      to be made on resource characteristics and not fragment
1729      characteristics.
1730
1731
1732
1733
1734
1735Fielding, et al.          Expires July 15, 2008                [Page 31]
1736
1737Internet-Draft              HTTP/1.1, Part 2                January 2008
1738
1739
1740   o  With 305 Use Proxy.
1741
174210.5.  Max-Forwards
1743
1744   The Max-Forwards request-header field provides a mechanism with the
1745   TRACE (Section 8.8) and OPTIONS (Section 8.2) methods to limit the
1746   number of proxies or gateways that can forward the request to the
1747   next inbound server.  This can be useful when the client is
1748   attempting to trace a request chain which appears to be failing or
1749   looping in mid-chain.
1750
1751     Max-Forwards   = "Max-Forwards" ":" 1*DIGIT
1752
1753   The Max-Forwards value is a decimal integer indicating the remaining
1754   number of times this request message may be forwarded.
1755
1756   Each proxy or gateway recipient of a TRACE or OPTIONS request
1757   containing a Max-Forwards header field MUST check and update its
1758   value prior to forwarding the request.  If the received value is zero
1759   (0), the recipient MUST NOT forward the request; instead, it MUST
1760   respond as the final recipient.  If the received Max-Forwards value
1761   is greater than zero, then the forwarded message MUST contain an
1762   updated Max-Forwards field with a value decremented by one (1).
1763
1764   The Max-Forwards header field MAY be ignored for all other methods
1765   defined by this specification and for any extension methods for which
1766   it is not explicitly referred to as part of that method definition.
1767
176810.6.  Referer
1769
1770   The Referer[sic] request-header field allows the client to specify,
1771   for the server's benefit, the address (URI) of the resource from
1772   which the Request-URI was obtained (the "referrer", although the
1773   header field is misspelled.)  The Referer request-header allows a
1774   server to generate lists of back-links to resources for interest,
1775   logging, optimized caching, etc.  It also allows obsolete or mistyped
1776   links to be traced for maintenance.  The Referer field MUST NOT be
1777   sent if the Request-URI was obtained from a source that does not have
1778   its own URI, such as input from the user keyboard.
1779
1780     Referer        = "Referer" ":" ( absoluteURI | relativeURI )
1781
1782   Example:
1783
1784       Referer: http://www.example.org/hypertext/Overview.html
1785
1786   If the field value is a relative URI, it SHOULD be interpreted
1787   relative to the Request-URI.  The URI MUST NOT include a fragment.
1788
1789
1790
1791Fielding, et al.          Expires July 15, 2008                [Page 32]
1792
1793Internet-Draft              HTTP/1.1, Part 2                January 2008
1794
1795
1796   See Section 12.2 for security considerations.
1797
179810.7.  Retry-After
1799
1800   The Retry-After response-header field can be used with a 503 (Service
1801   Unavailable) response to indicate how long the service is expected to
1802   be unavailable to the requesting client.  This field MAY also be used
1803   with any 3xx (Redirection) response to indicate the minimum time the
1804   user-agent is asked wait before issuing the redirected request.  The
1805   value of this field can be either an HTTP-date or an integer number
1806   of seconds (in decimal) after the time of the response.
1807
1808     Retry-After  = "Retry-After" ":" ( HTTP-date | delta-seconds )
1809
1810   Two examples of its use are
1811
1812       Retry-After: Fri, 31 Dec 1999 23:59:59 GMT
1813       Retry-After: 120
1814
1815   In the latter example, the delay is 2 minutes.
1816
181710.8.  Server
1818
1819   The Server response-header field contains information about the
1820   software used by the origin server to handle the request.  The field
1821   can contain multiple product tokens (Section 2) and comments
1822   identifying the server and any significant subproducts.  The product
1823   tokens are listed in order of their significance for identifying the
1824   application.
1825
1826     Server         = "Server" ":" 1*( product | comment )
1827
1828   Example:
1829
1830       Server: CERN/3.0 libwww/2.17
1831
1832   If the response is being forwarded through a proxy, the proxy
1833   application MUST NOT modify the Server response-header.  Instead, it
1834   MUST include a Via field (as described in Section 8.9 of [Part1]).
1835
1836      Note: Revealing the specific software version of the server might
1837      allow the server machine to become more vulnerable to attacks
1838      against software that is known to contain security holes.  Server
1839      implementors are encouraged to make this field a configurable
1840      option.
1841
1842
1843
1844
1845
1846
1847Fielding, et al.          Expires July 15, 2008                [Page 33]
1848
1849Internet-Draft              HTTP/1.1, Part 2                January 2008
1850
1851
185210.9.  User-Agent
1853
1854   The User-Agent request-header field contains information about the
1855   user agent originating the request.  This is for statistical
1856   purposes, the tracing of protocol violations, and automated
1857   recognition of user agents for the sake of tailoring responses to
1858   avoid particular user agent limitations.  User agents SHOULD include
1859   this field with requests.  The field can contain multiple product
1860   tokens (Section 2) and comments identifying the agent and any
1861   subproducts which form a significant part of the user agent.  By
1862   convention, the product tokens are listed in order of their
1863   significance for identifying the application.
1864
1865     User-Agent     = "User-Agent" ":" 1*( product | comment )
1866
1867   Example:
1868
1869       User-Agent: CERN-LineMode/2.15 libwww/2.17b3
1870
1871
187211.  IANA Considerations
1873
1874   TBD.
1875
1876
187712.  Security Considerations
1878
1879   This section is meant to inform application developers, information
1880   providers, and users of the security limitations in HTTP/1.1 as
1881   described by this document.  The discussion does not include
1882   definitive solutions to the problems revealed, though it does make
1883   some suggestions for reducing security risks.
1884
188512.1.  Transfer of Sensitive Information
1886
1887   Like any generic data transfer protocol, HTTP cannot regulate the
1888   content of the data that is transferred, nor is there any a priori
1889   method of determining the sensitivity of any particular piece of
1890   information within the context of any given request.  Therefore,
1891   applications SHOULD supply as much control over this information as
1892   possible to the provider of that information.  Four header fields are
1893   worth special mention in this context: Server, Via, Referer and From.
1894
1895   Revealing the specific software version of the server might allow the
1896   server machine to become more vulnerable to attacks against software
1897   that is known to contain security holes.  Implementors SHOULD make
1898   the Server header field a configurable option.
1899
1900
1901
1902
1903Fielding, et al.          Expires July 15, 2008                [Page 34]
1904
1905Internet-Draft              HTTP/1.1, Part 2                January 2008
1906
1907
1908   Proxies which serve as a portal through a network firewall SHOULD
1909   take special precautions regarding the transfer of header information
1910   that identifies the hosts behind the firewall.  In particular, they
1911   SHOULD remove, or replace with sanitized versions, any Via fields
1912   generated behind the firewall.
1913
1914   The Referer header allows reading patterns to be studied and reverse
1915   links drawn.  Although it can be very useful, its power can be abused
1916   if user details are not separated from the information contained in
1917   the Referer.  Even when the personal information has been removed,
1918   the Referer header might indicate a private document's URI whose
1919   publication would be inappropriate.
1920
1921   The information sent in the From field might conflict with the user's
1922   privacy interests or their site's security policy, and hence it
1923   SHOULD NOT be transmitted without the user being able to disable,
1924   enable, and modify the contents of the field.  The user MUST be able
1925   to set the contents of this field within a user preference or
1926   application defaults configuration.
1927
1928   We suggest, though do not require, that a convenient toggle interface
1929   be provided for the user to enable or disable the sending of From and
1930   Referer information.
1931
1932   The User-Agent (Section 10.9) or Server (Section 10.8) header fields
1933   can sometimes be used to determine that a specific client or server
1934   have a particular security hole which might be exploited.
1935   Unfortunately, this same information is often used for other valuable
1936   purposes for which HTTP currently has no better mechanism.
1937
193812.2.  Encoding Sensitive Information in URI's
1939
1940   Because the source of a link might be private information or might
1941   reveal an otherwise private information source, it is strongly
1942   recommended that the user be able to select whether or not the
1943   Referer field is sent.  For example, a browser client could have a
1944   toggle switch for browsing openly/anonymously, which would
1945   respectively enable/disable the sending of Referer and From
1946   information.
1947
1948   Clients SHOULD NOT include a Referer header field in a (non-secure)
1949   HTTP request if the referring page was transferred with a secure
1950   protocol.
1951
1952   Authors of services which use the HTTP protocol SHOULD NOT use GET
1953   based forms for the submission of sensitive data, because this will
1954   cause this data to be encoded in the Request-URI.  Many existing
1955   servers, proxies, and user agents will log the request URI in some
1956
1957
1958
1959Fielding, et al.          Expires July 15, 2008                [Page 35]
1960
1961Internet-Draft              HTTP/1.1, Part 2                January 2008
1962
1963
1964   place where it might be visible to third parties.  Servers can use
1965   POST-based form submission instead
1966
196712.3.  Location Headers and Spoofing
1968
1969   If a single server supports multiple organizations that do not trust
1970   one another, then it MUST check the values of Location and Content-
1971   Location headers in responses that are generated under control of
1972   said organizations to make sure that they do not attempt to
1973   invalidate resources over which they have no authority.
1974
1975
197613.  Acknowledgments
1977
1978
197914.  References
1980
198114.1.  Normative References
1982
1983   [Part1]    Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H.,
1984              Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed.,
1985              and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections,
1986              and Message Parsing", draft-ietf-httpbis-p1-messaging-01
1987              (work in progress), January 2008.
1988
1989   [Part3]    Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H.,
1990              Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed.,
1991              and J. Reschke, Ed., "HTTP/1.1, part 3: Message Payload
1992              and Content Negotiation", draft-ietf-httpbis-p3-payload-01
1993              (work in progress), January 2008.
1994
1995   [Part4]    Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H.,
1996              Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed.,
1997              and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional
1998              Requests", draft-ietf-httpbis-p4-conditional-01 (work in
1999              progress), January 2008.
2000
2001   [Part5]    Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H.,
2002              Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed.,
2003              and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and
2004              Partial Responses", draft-ietf-httpbis-p5-range-01 (work
2005              in progress), January 2008.
2006
2007   [Part6]    Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H.,
2008              Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed.,
2009              and J. Reschke, Ed., "HTTP/1.1, part 6: Caching",
2010              draft-ietf-httpbis-p6-cache-01 (work in progress),
2011              January 2008.
2012
2013
2014
2015Fielding, et al.          Expires July 15, 2008                [Page 36]
2016
2017Internet-Draft              HTTP/1.1, Part 2                January 2008
2018
2019
2020   [Part7]    Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H.,
2021              Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed.,
2022              and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication",
2023              draft-ietf-httpbis-p7-auth-01 (work in progress),
2024              January 2008.
2025
2026   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
2027              Requirement Levels", BCP 14, RFC 2119, March 1997.
2028
202914.2.  Informative References
2030
2031   [Luo1998]  Luotonen, A., "Tunneling TCP based protocols through Web
2032              proxy servers", draft-luotonen-web-proxy-tunneling-01
2033              (work in progress), August 1998.
2034
2035   [RFC1945]  Berners-Lee, T., Fielding, R., and H. Nielsen, "Hypertext
2036              Transfer Protocol -- HTTP/1.0", RFC 1945, May 1996.
2037
2038   [RFC2068]  Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and T.
2039              Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1",
2040              RFC 2068, January 1997.
2041
2042   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
2043              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
2044              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
2045
2046   [RFC2822]  Resnick, P., "Internet Message Format", RFC 2822,
2047              April 2001.
2048
2049
2050Appendix A.  Compatibility with Previous Versions
2051
2052A.1.  Changes from RFC 2068
2053
2054   Clarified which error code should be used for inbound server failures
2055   (e.g.  DNS failures).  (Section 9.5.5).
2056
2057   201 (Created) had a race that required an Etag be sent when a
2058   resource is first created.  (Section 9.2.2).
2059
2060   Rewrite of message transmission requirements to make it much harder
2061   for implementors to get it wrong, as the consequences of errors here
2062   can have significant impact on the Internet, and to deal with the
2063   following problems:
2064
2065   1.  Changing "HTTP/1.1 or later" to "HTTP/1.1", in contexts where
2066       this was incorrectly placing a requirement on the behavior of an
2067       implementation of a future version of HTTP/1.x
2068
2069
2070
2071Fielding, et al.          Expires July 15, 2008                [Page 37]
2072
2073Internet-Draft              HTTP/1.1, Part 2                January 2008
2074
2075
2076   2.  Made it clear that user-agents should retry requests, not
2077       "clients" in general.
2078
2079   3.  Converted requirements for clients to ignore unexpected 100
2080       (Continue) responses, and for proxies to forward 100 responses,
2081       into a general requirement for 1xx responses.
2082
2083   4.  Modified some TCP-specific language, to make it clearer that non-
2084       TCP transports are possible for HTTP.
2085
2086   5.  Require that the origin server MUST NOT wait for the request body
2087       before it sends a required 100 (Continue) response.
2088
2089   6.  Allow, rather than require, a server to omit 100 (Continue) if it
2090       has already seen some of the request body.
2091
2092   7.  Allow servers to defend against denial-of-service attacks and
2093       broken clients.
2094
2095   This change adds the Expect header and 417 status code.
2096
2097   Clean up confusion between 403 and 404 responses.  (Section 9.4.4,
2098   9.4.5, and 9.4.11)
2099
2100   The PATCH, LINK, UNLINK methods were defined but not commonly
2101   implemented in previous versions of this specification.  See
2102   [RFC2068].
2103
2104A.2.  Changes from RFC 2616
2105
2106   Clarify definition of POST.  (Section 8.5)
2107
2108   Failed to consider that there are many other request methods that are
2109   safe to automatically redirect, and further that the user agent is
2110   able to make that determination based on the request method
2111   semantics.  (Sections 9.3.2, 9.3.3 and 9.3.8 )
2112
2113   Correct syntax of Location header to allow fragment, as referred
2114   symbol wasn't what was expected, and add some clarifications as to
2115   when it would not be appropriate.  (Section 10.4)
2116
2117   In the description of the Server header, the Via field was described
2118   as a SHOULD.  The requirement was and is stated correctly in the
2119   description of the Via header in Section 8.9 of [Part1].
2120   (Section 10.8)
2121
2122
2123
2124
2125
2126
2127Fielding, et al.          Expires July 15, 2008                [Page 38]
2128
2129Internet-Draft              HTTP/1.1, Part 2                January 2008
2130
2131
2132Appendix B.  Change Log (to be removed by RFC Editor before publication)
2133
2134B.1.  Since RFC2616
2135
2136   Extracted relevant partitions from [RFC2616].
2137
2138B.2.  Since draft-ietf-httpbis-p2-semantics-00
2139
2140   Closed issues:
2141
2142   o  <http://www3.tools.ietf.org/wg/httpbis/trac/ticket/5>: "Via is a
2143      MUST" (<http://purl.org/NET/http-errata#via-must>)
2144
2145   o  <http://www3.tools.ietf.org/wg/httpbis/trac/ticket/6>: "Fragments
2146      allowed in Location"
2147      (<http://purl.org/NET/http-errata#location-fragments>)
2148
2149   o  <http://www3.tools.ietf.org/wg/httpbis/trac/ticket/10>: "Safe
2150      Methods vs Redirection"
2151      (<http://purl.org/NET/http-errata#saferedirect>)
2152
2153   o  <http://www3.tools.ietf.org/wg/httpbis/trac/ticket/17>: "Revise
2154      description of the POST method"
2155      (<http://purl.org/NET/http-errata#post>)
2156
2157   o  <http://www3.tools.ietf.org/wg/httpbis/trac/ticket/35>: "Normative
2158      and Informative references"
2159
2160   o  <http://www3.tools.ietf.org/wg/httpbis/trac/ticket/42>: "RFC2606
2161      Compliance"
2162
2163   o  <http://www3.tools.ietf.org/wg/httpbis/trac/ticket/65>:
2164      "Informative references"
2165
2166   o  <http://www3.tools.ietf.org/wg/httpbis/trac/ticket/84>: "Redundant
2167      cross-references"
2168
2169   Other changes:
2170
2171   o  Move definitions of 304 and 412 condition codes to [Part4]
2172
2173
2174Index
2175
2176   1
2177      100 Continue (status code)  17
2178      101 Switching Protocols (status code)  18
2179
2180
2181
2182
2183Fielding, et al.          Expires July 15, 2008                [Page 39]
2184
2185Internet-Draft              HTTP/1.1, Part 2                January 2008
2186
2187
2188   2
2189      200 OK (status code)  18
2190      201 Created (status code)  18
2191      202 Accepted (status code)  19
2192      203 Non-Authoritative Information (status code)  19
2193      204 No Content (status code)  19
2194      205 Reset Content (status code)  20
2195      206 Partial Content (status code)  20
2196
2197   3
2198      300 Multiple Choices (status code)  20
2199      301 Moved Permanently (status code)  21
2200      302 Found (status code)  21
2201      303 See Other (status code)  22
2202      304 Not Modified (status code)  22
2203      305 Use Proxy (status code)  22
2204      306 (Unused) (status code)  23
2205      307 Temporary Redirect (status code)  23
2206
2207   4
2208      400 Bad Request (status code)  24
2209      401 Unauthorized (status code)  24
2210      402 Payment Required (status code)  24
2211      403 Forbidden (status code)  24
2212      404 Not Found (status code)  24
2213      405 Method Not Allowed (status code)  24
2214      406 Not Acceptable (status code)  24
2215      407 Proxy Authentication Required (status code)  25
2216      408 Request Timeout (status code)  25
2217      409 Conflict (status code)  25
2218      410 Gone (status code)  26
2219      411 Length Required (status code)  26
2220      412 Precondition Failed (status code)  26
2221      413 Request Entity Too Large (status code)  26
2222      414 Request-URI Too Long (status code)  27
2223      415 Unsupported Media Type (status code)  27
2224      416 Requested Range Not Satisfiable (status code)  27
2225      417 Expectation Failed (status code)  27
2226
2227   5
2228      500 Internal Server Error (status code)  27
2229      501 Not Implemented (status code)  28
2230      502 Bad Gateway (status code)  28
2231      503 Service Unavailable (status code)  28
2232      504 Gateway Timeout (status code)  28
2233      505 HTTP Version Not Supported (status code)  28
2234
2235   A
2236
2237
2238
2239Fielding, et al.          Expires July 15, 2008                [Page 40]
2240
2241Internet-Draft              HTTP/1.1, Part 2                January 2008
2242
2243
2244      Allow header  29
2245
2246   C
2247      CONNECT method  17
2248
2249   D
2250      DELETE method  16
2251
2252   E
2253      Expect header  29
2254
2255   F
2256      From header  30
2257
2258   G
2259      GET method  13
2260      Grammar
2261         Allow  29
2262         Expect  29
2263         expect-params  29
2264         expectation  29
2265         expectation-extension  29
2266         extension-code  9
2267         extension-method  7
2268         From  30
2269         Location  31
2270         Max-Forwards  32
2271         Method  7
2272         product  6
2273         product-version  6
2274         Reason-Phrase  9
2275         Referer  32
2276         request-header  8
2277         response-header  10
2278         Retry-After  33
2279         Server  33
2280         Status-Code  9
2281         User-Agent  34
2282
2283   H
2284      HEAD method  13
2285      Headers
2286         Allow  29
2287         Expect  29
2288         From  30
2289         Location  31
2290         Max-Forwards  32
2291         Referer  32
2292
2293
2294
2295Fielding, et al.          Expires July 15, 2008                [Page 41]
2296
2297Internet-Draft              HTTP/1.1, Part 2                January 2008
2298
2299
2300         Retry-After  33
2301         Server  33
2302         User-Agent  34
2303
2304   L
2305      LINK method  38
2306      Location header  31
2307
2308   M
2309      Max-Forwards header  32
2310      Methods
2311         CONNECT  17
2312         DELETE  16
2313         GET  13
2314         HEAD  13
2315         LINK  38
2316         OPTIONS  12
2317         PATCH  38
2318         POST  14
2319         PUT  15
2320         TRACE  16
2321         UNLINK  38
2322
2323   O
2324      OPTIONS method  12
2325
2326   P
2327      PATCH method  38
2328      POST method  14
2329      PUT method  15
2330
2331   R
2332      Referer header  32
2333      Retry-After header  33
2334
2335   S
2336      Server header  33
2337      Status Codes
2338         100 Continue  17
2339         101 Switching Protocols  18
2340         200 OK  18
2341         201 Created  18
2342         202 Accepted  19
2343         203 Non-Authoritative Information  19
2344         204 No Content  19
2345         205 Reset Content  20
2346         206 Partial Content  20
2347         300 Multiple Choices  20
2348
2349
2350
2351Fielding, et al.          Expires July 15, 2008                [Page 42]
2352
2353Internet-Draft              HTTP/1.1, Part 2                January 2008
2354
2355
2356         301 Moved Permanently  21
2357         302 Found  21
2358         303 See Other  22
2359         304 Not Modified  22
2360         305 Use Proxy  22
2361         306 (Unused)  23
2362         307 Temporary Redirect  23
2363         400 Bad Request  24
2364         401 Unauthorized  24
2365         402 Payment Required  24
2366         403 Forbidden  24
2367         404 Not Found  24
2368         405 Method Not Allowed  24
2369         406 Not Acceptable  24
2370         407 Proxy Authentication Required  25
2371         408 Request Timeout  25
2372         409 Conflict  25
2373         410 Gone  26
2374         411 Length Required  26
2375         412 Precondition Failed  26
2376         413 Request Entity Too Large  26
2377         414 Request-URI Too Long  27
2378         415 Unsupported Media Type  27
2379         416 Requested Range Not Satisfiable  27
2380         417 Expectation Failed  27
2381         500 Internal Server Error  27
2382         501 Not Implemented  28
2383         502 Bad Gateway  28
2384         503 Service Unavailable  28
2385         504 Gateway Timeout  28
2386         505 HTTP Version Not Supported  28
2387
2388   T
2389      TRACE method  16
2390
2391   U
2392      UNLINK method  38
2393      User-Agent header  34
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407Fielding, et al.          Expires July 15, 2008                [Page 43]
2408
2409Internet-Draft              HTTP/1.1, Part 2                January 2008
2410
2411
2412Authors' Addresses
2413
2414   Roy T. Fielding (editor)
2415   Day Software
2416   23 Corporate Plaza DR, Suite 280
2417   Newport Beach, CA  92660
2418   USA
2419
2420   Phone: +1-949-706-5300
2421   Fax:   +1-949-706-5305
2422   Email: fielding@gbiv.com
2423   URI:   http://roy.gbiv.com/
2424
2425
2426   Jim Gettys
2427   One Laptop per Child
2428   21 Oak Knoll Road
2429   Carlisle, MA  01741
2430   USA
2431
2432   Email: jg@laptop.org
2433   URI:   http://www.laptop.org/
2434
2435
2436   Jeffrey C. Mogul
2437   Hewlett-Packard Company
2438   HP Labs, Large Scale Systems Group
2439   1501 Page Mill Road, MS 1177
2440   Palo Alto, CA  94304
2441   USA
2442
2443   Email: JeffMogul@acm.org
2444
2445
2446   Henrik Frystyk Nielsen
2447   Microsoft Corporation
2448   1 Microsoft Way
2449   Redmond, WA  98052
2450   USA
2451
2452   Email: henrikn@microsoft.com
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463Fielding, et al.          Expires July 15, 2008                [Page 44]
2464
2465Internet-Draft              HTTP/1.1, Part 2                January 2008
2466
2467
2468   Larry Masinter
2469   Adobe Systems, Incorporated
2470   345 Park Ave
2471   San Jose, CA  95110
2472   USA
2473
2474   Email: LMM@acm.org
2475   URI:   http://larry.masinter.net/
2476
2477
2478   Paul J. Leach
2479   Microsoft Corporation
2480   1 Microsoft Way
2481   Redmond, WA  98052
2482
2483   Email: paulle@microsoft.com
2484
2485
2486   Tim Berners-Lee
2487   World Wide Web Consortium
2488   MIT Computer Science and Artificial Intelligence Laboratory
2489   The Stata Center, Building 32
2490   32 Vassar Street
2491   Cambridge, MA  02139
2492   USA
2493
2494   Email: timbl@w3.org
2495   URI:   http://www.w3.org/People/Berners-Lee/
2496
2497
2498   Yves Lafon (editor)
2499   World Wide Web Consortium
2500   W3C / ERCIM
2501   2004, rte des Lucioles
2502   Sophia-Antipolis, AM  06902
2503   France
2504
2505   Email: ylafon@w3.org
2506   URI:   http://www.raubacapeu.net/people/yves/
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519Fielding, et al.          Expires July 15, 2008                [Page 45]
2520
2521Internet-Draft              HTTP/1.1, Part 2                January 2008
2522
2523
2524   Julian F. Reschke (editor)
2525   greenbytes GmbH
2526   Hafenweg 16
2527   Muenster, NW  48155
2528   Germany
2529
2530   Phone: +49 251 2807760
2531   Fax:   +49 251 2807761
2532   Email: julian.reschke@greenbytes.de
2533   URI:   http://greenbytes.de/tech/webdav/
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575Fielding, et al.          Expires July 15, 2008                [Page 46]
2576
2577Internet-Draft              HTTP/1.1, Part 2                January 2008
2578
2579
2580Full Copyright Statement
2581
2582   Copyright (C) The IETF Trust (2008).
2583
2584   This document is subject to the rights, licenses and restrictions
2585   contained in BCP 78, and except as set forth therein, the authors
2586   retain all their rights.
2587
2588   This document and the information contained herein are provided on an
2589   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
2590   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
2591   THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
2592   OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
2593   THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
2594   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
2595
2596
2597Intellectual Property
2598
2599   The IETF takes no position regarding the validity or scope of any
2600   Intellectual Property Rights or other rights that might be claimed to
2601   pertain to the implementation or use of the technology described in
2602   this document or the extent to which any license under such rights
2603   might or might not be available; nor does it represent that it has
2604   made any independent effort to identify any such rights.  Information
2605   on the procedures with respect to rights in RFC documents can be
2606   found in BCP 78 and BCP 79.
2607
2608   Copies of IPR disclosures made to the IETF Secretariat and any
2609   assurances of licenses to be made available, or the result of an
2610   attempt made to obtain a general license or permission for the use of
2611   such proprietary rights by implementers or users of this
2612   specification can be obtained from the IETF on-line IPR repository at
2613   http://www.ietf.org/ipr.
2614
2615   The IETF invites any interested party to bring to its attention any
2616   copyrights, patents or patent applications, or other proprietary
2617   rights that may cover technology that may be required to implement
2618   this standard.  Please address the information to the IETF at
2619   ietf-ipr@ietf.org.
2620
2621
2622Acknowledgment
2623
2624   Funding for the RFC Editor function is provided by the IETF
2625   Administrative Support Activity (IASA).
2626
2627
2628
2629
2630
2631Fielding, et al.          Expires July 15, 2008                [Page 47]
2632
Note: See TracBrowser for help on using the repository browser.