1 |
HTTP Working Group R. Fielding, UC Irvine |
2 |
INTERNET-DRAFT H. Frystyk, MIT/LCS |
3 |
<draft-ietf-http-v11-spec-00.txt> T. Berners-Lee, MIT/LCS |
4 |
Expires May 22, 1996 November 22, 1995 |
5 |
|
6 |
|
7 |
Hypertext Transfer Protocol -- HTTP/1.1 |
8 |
|
9 |
|
10 |
Status of this Memo |
11 |
|
12 |
This document is an Internet-Draft. Internet-Drafts are working |
13 |
documents of the Internet Engineering Task Force (IETF), its areas, |
14 |
and its working groups. Note that other groups may also distribute |
15 |
working documents as Internet-Drafts. |
16 |
|
17 |
Internet-Drafts are draft documents valid for a maximum of six |
18 |
months and may be updated, replaced, or obsoleted by other |
19 |
documents at any time. It is inappropriate to use Internet-Drafts |
20 |
as reference material or to cite them other than as "work in |
21 |
progress". |
22 |
|
23 |
To learn the current status of any Internet-Draft, please check the |
24 |
"1id-abstracts.txt" listing contained in the Internet-Drafts Shadow |
25 |
Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), |
26 |
munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or |
27 |
ftp.isi.edu (US West Coast). |
28 |
|
29 |
Distribution of this document is unlimited. Please send comments to |
30 |
the HTTP working group at <http-wg@cuckoo.hpl.hp.com>. Discussions |
31 |
of the working group are archived at |
32 |
<URL:http://www.ics.uci.edu/pub/ietf/http/>. General discussions |
33 |
about HTTP and the applications which use HTTP should take place on |
34 |
the <www-talk@w3.org> mailing list. |
35 |
|
36 |
Abstract |
37 |
|
38 |
The Hypertext Transfer Protocol (HTTP) is an application-level |
39 |
protocol for distributed, collaborative, hypermedia information |
40 |
systems. It is a generic, stateless, object-oriented protocol which |
41 |
can be used for many tasks, such as name servers and distributed |
42 |
object management systems, through extension of its request methods |
43 |
(commands). A feature of HTTP is the typing and negotiation of data |
44 |
representation, allowing systems to be built independently of the |
45 |
data being transferred. |
46 |
|
47 |
HTTP has been in use by the World-Wide Web global information |
48 |
initiative since 1990. This specification defines the protocol |
49 |
referred to as "HTTP/1.1". |
50 |
|
51 |
Table of Contents |
52 |
|
53 |
1. Introduction |
54 |
1.1 Purpose |
55 |
1.2 Requirements |
56 |
1.3 Terminology |
57 |
1.4 Overall Operation |
58 |
|
59 |
2. Notational Conventions and Generic Grammar |
60 |
2.1 Augmented BNF |
61 |
2.2 Basic Rules |
62 |
|
63 |
3. Protocol Parameters |
64 |
3.1 HTTP Version |
65 |
3.2 Uniform Resource Identifiers |
66 |
3.2.1 General Syntax |
67 |
3.2.2 http URL |
68 |
3.3 Date/Time Formats |
69 |
3.3.1 Full Date |
70 |
3.3.2 Delta Seconds |
71 |
3.4 Character Sets |
72 |
3.5 Content Codings |
73 |
3.6 Transfer Codings |
74 |
3.7 Media Types |
75 |
3.7.1 Canonicalization and Text Defaults |
76 |
3.7.2 Multipart Types |
77 |
3.8 Product Tokens |
78 |
3.9 Quality Values |
79 |
3.10 Language Tags |
80 |
3.11 Logic Bags |
81 |
|
82 |
4. HTTP Message |
83 |
4.1 Message Types |
84 |
4.2 Message Headers |
85 |
4.3 General Header Fields |
86 |
|
87 |
5. Request |
88 |
5.1 Request-Line |
89 |
5.1.1 Method |
90 |
5.1.2 Request-URI |
91 |
5.2 Request Header Fields |
92 |
|
93 |
6. Response |
94 |
6.1 Status-Line |
95 |
6.1.1 Status Code and Reason Phrase |
96 |
6.2 Response Header Fields |
97 |
|
98 |
7. Entity |
99 |
7.1 Entity Header Fields |
100 |
7.2 Entity Body |
101 |
7.2.1 Type |
102 |
7.2.2 Length |
103 |
|
104 |
8. Method Definitions |
105 |
8.1 OPTIONS |
106 |
8.2 GET |
107 |
8.3 HEAD |
108 |
8.4 POST |
109 |
8.5 PUT |
110 |
8.6 PATCH |
111 |
8.7 COPY |
112 |
8.8 MOVE |
113 |
8.9 DELETE |
114 |
8.10 LINK |
115 |
8.11 UNLINK |
116 |
8.12 TRACE |
117 |
8.13 WRAPPED |
118 |
|
119 |
9. Status Code Definitions |
120 |
9.1 Informational 1xx |
121 |
9.2 Successful 2xx |
122 |
9.3 Redirection 3xx |
123 |
9.4 Client Error 4xx |
124 |
9.5 Server Error 5xx |
125 |
|
126 |
10. Header Field Definitions |
127 |
10.1 Accept |
128 |
10.2 Accept-Charset |
129 |
10.3 Accept-Encoding |
130 |
10.4 Accept-Language |
131 |
10.5 Allow |
132 |
10.6 Authorization |
133 |
10.7 Base |
134 |
10.8 Cache-Control |
135 |
10.9 Connection |
136 |
10.9.1 Persistent Connections |
137 |
10.10 Content-Encoding |
138 |
10.11 Content-Language |
139 |
10.12 Content-Length |
140 |
10.13 Content-MD5 |
141 |
10.14 Content-Range |
142 |
10.15 Content-Type |
143 |
10.16 Content-Version |
144 |
10.17 Date |
145 |
10.18 Derived-From |
146 |
10.19 Expires |
147 |
10.20 Forwarded |
148 |
10.21 From |
149 |
10.22 Host |
150 |
10.23 If-Modified-Since |
151 |
10.24 Keep-Alive |
152 |
10.25 Last-Modified |
153 |
10.26 Link |
154 |
10.27 Location |
155 |
10.28 MIME-Version |
156 |
10.29 Pragma |
157 |
10.30 Proxy-Authenticate |
158 |
10.31 Proxy-Authorization |
159 |
10.32 Public |
160 |
10.33 Range |
161 |
10.34 Referer |
162 |
10.35 Refresh |
163 |
10.36 Retry-After |
164 |
10.37 Server |
165 |
10.38 Title |
166 |
10.39 Transfer Encoding |
167 |
10.40 Unless |
168 |
10.41 Upgrade |
169 |
10.42 URI |
170 |
10.43 User-Agent |
171 |
10.44 WWW-Authenticate |
172 |
|
173 |
11. Access Authentication |
174 |
11.1 Basic Authentication Scheme |
175 |
11.2 Digest Authentication Scheme |
176 |
|
177 |
12. Content Negotiation |
178 |
12.1 Preemptive Negotiation |
179 |
|
180 |
13. Caching |
181 |
|
182 |
14. Security Considerations |
183 |
14.1 Authentication of Clients |
184 |
14.2 Safe Methods |
185 |
14.3 Abuse of Server Log Information |
186 |
14.4 Transfer of Sensitive Information |
187 |
|
188 |
15. Acknowledgments |
189 |
|
190 |
16. References |
191 |
|
192 |
17. Authors' Addresses |
193 |
|
194 |
Appendix A. Internet Media Type message/http |
195 |
Appendix B. Tolerant Applications |
196 |
Appendix C. Relationship to MIME |
197 |
C.1 Conversion to Canonical Form |
198 |
C.1.1 Representation of Line Breaks |
199 |
C.1.2 Default Character Set |
200 |
C.2 Conversion of Date Formats |
201 |
C.3 Introduction of Content-Encoding |
202 |
C.4 No Content-Transfer-Encoding |
203 |
C.5 Introduction of Transfer-Encoding |
204 |
Appendix D. Changes from HTTP/1.0 |
205 |
|
206 |
|
207 |
|
208 |
1. Introduction |
209 |
|
210 |
1.1 Purpose |
211 |
|
212 |
The Hypertext Transfer Protocol (HTTP) is an application-level |
213 |
protocol for distributed, collaborative, hypermedia information |
214 |
systems. HTTP has been in use by the World-Wide Web global |
215 |
information initiative since 1990. The first version of HTTP, |
216 |
referred to as HTTP/0.9, was a simple protocol for raw data |
217 |
transfer across the Internet. HTTP/1.0, as defined by RFC xxxx [6], |
218 |
improved the protocol by allowing messages to be in the format of |
219 |
MIME-like entities, containing metainformation about the data |
220 |
transferred and modifiers on the request/response semantics. |
221 |
However, HTTP/1.0 does not sufficiently take into consideration the |
222 |
effect of hierarchical proxies and caching, the desire for |
223 |
persistent connections and virtual hosts, and a number of other |
224 |
details that slipped through the cracks of existing |
225 |
implementations. In addition, the proliferation of incompletely- |
226 |
implemented applications calling themselves "HTTP/1.0" has |
227 |
necessitated a protocol version change in order for two |
228 |
communicating applications to determine each other's true |
229 |
capabilities. |
230 |
|
231 |
This specification defines the protocol referred to as "HTTP/1.1". |
232 |
This protocol is backwards-compatible with HTTP/1.0, but includes |
233 |
more stringent requirements in order to ensure reliable |
234 |
implementation of its features. |
235 |
|
236 |
Practical information systems require more functionality than |
237 |
simple retrieval, including search, front-end update, and |
238 |
annotation. HTTP allows an open-ended set of methods to be used to |
239 |
indicate the purpose of a request. It builds on the discipline of |
240 |
reference provided by the Uniform Resource Identifier (URI) [3], as |
241 |
a location (URL) [4] or name (URN) [20], for indicating the |
242 |
resource on which a method is to be applied. Messages are passed in |
243 |
a format similar to that used by Internet Mail [9] and the |
244 |
Multipurpose Internet Mail Extensions (MIME) [7]. |
245 |
|
246 |
HTTP is also used as a generic protocol for communication between |
247 |
user agents and proxies/gateways to other Internet protocols, such |
248 |
as SMTP [16], NNTP [13], FTP [18], Gopher [2], and WAIS [10], |
249 |
allowing basic hypermedia access to resources available from |
250 |
diverse applications and simplifying the implementation of user |
251 |
agents. |
252 |
|
253 |
1.2 Requirements |
254 |
|
255 |
This specification uses the same words as RFC 1123 [8] for defining |
256 |
the significance of each particular requirement. These words are: |
257 |
|
258 |
must |
259 |
|
260 |
This word or the adjective "required" means that the item is an |
261 |
absolute requirement of the specification. |
262 |
|
263 |
should |
264 |
|
265 |
This word or the adjective "recommended" means that there may |
266 |
exist valid reasons in particular circumstances to ignore this |
267 |
item, but the full implications should be understood and the |
268 |
case carefully weighed before choosing a different course. |
269 |
|
270 |
may |
271 |
|
272 |
This word or the adjective "optional" means that this item is |
273 |
truly optional. One vendor may choose to include the item |
274 |
because a particular marketplace requires it or because it |
275 |
enhances the product, for example; another vendor may omit the |
276 |
same item. |
277 |
|
278 |
An implementation is not compliant if it fails to satisfy one or |
279 |
more of the must requirements for the protocols it implements. An |
280 |
implementation that satisfies all the must and all the should |
281 |
requirements for its protocols is said to be "unconditionally |
282 |
compliant"; one that satisfies all the must requirements but not |
283 |
all the should requirements for its protocols is said to be |
284 |
"conditionally compliant". |
285 |
|
286 |
1.3 Terminology |
287 |
|
288 |
This specification uses a number of terms to refer to the roles |
289 |
played by participants in, and objects of, the HTTP communication. |
290 |
|
291 |
connection |
292 |
|
293 |
A transport layer virtual circuit established between two |
294 |
application programs for the purpose of communication. |
295 |
|
296 |
message |
297 |
|
298 |
The basic unit of HTTP communication, consisting of a structured |
299 |
sequence of octets matching the syntax defined in Section 4 and |
300 |
transmitted via the connection. |
301 |
|
302 |
request |
303 |
|
304 |
An HTTP request message (as defined in Section 5). |
305 |
|
306 |
response |
307 |
|
308 |
An HTTP response message (as defined in Section 6). |
309 |
|
310 |
resource |
311 |
|
312 |
A network data object or service which can be identified by a |
313 |
URI (Section 3.2). |
314 |
|
315 |
entity |
316 |
|
317 |
A particular representation or rendition of a data resource, or |
318 |
reply from a service resource, that may be enclosed within a |
319 |
request or response message. An entity consists of |
320 |
metainformation in the form of entity headers and content in the |
321 |
form of an entity body. |
322 |
|
323 |
client |
324 |
|
325 |
An application program that establishes connections for the |
326 |
purpose of sending requests. |
327 |
|
328 |
user agent |
329 |
|
330 |
The client which initiates a request. These are often browsers, |
331 |
editors, spiders (web-traversing robots), or other end user |
332 |
tools. |
333 |
|
334 |
server |
335 |
|
336 |
An application program that accepts connections in order to |
337 |
service requests by sending back responses. |
338 |
|
339 |
origin server |
340 |
|
341 |
The server on which a given resource resides or is to be created. |
342 |
|
343 |
proxy |
344 |
|
345 |
An intermediary program which acts as both a server and a client |
346 |
for the purpose of making requests on behalf of other clients. |
347 |
Requests are serviced internally or by passing them, with |
348 |
possible translation, on to other servers. A proxy must |
349 |
interpret and, if necessary, rewrite a request message before |
350 |
forwarding it. Proxies are often used as client-side portals |
351 |
through network firewalls and as helper applications for |
352 |
handling requests via protocols not implemented by the user |
353 |
agent. |
354 |
|
355 |
gateway |
356 |
|
357 |
A server which acts as an intermediary for some other server. |
358 |
Unlike a proxy, a gateway receives requests as if it were the |
359 |
origin server for the requested resource; the requesting client |
360 |
may not be aware that it is communicating with a gateway. |
361 |
Gateways are often used as server-side portals through network |
362 |
firewalls and as protocol translators for access to resources |
363 |
stored on non-HTTP systems. |
364 |
|
365 |
tunnel |
366 |
|
367 |
A tunnel is an intermediary program which is acting as a blind |
368 |
relay between two connections. Once active, a tunnel is not |
369 |
considered a party to the HTTP communication, though the tunnel |
370 |
may have been initiated by an HTTP request. The tunnel ceases to |
371 |
exist when both ends of the relayed connections are closed. |
372 |
Tunnels are used when a portal is necessary and the intermediary |
373 |
cannot, or should not, interpret the relayed communication. |
374 |
|
375 |
cache |
376 |
|
377 |
A program's local store of response messages and the subsystem |
378 |
that controls its message storage, retrieval, and deletion. A |
379 |
cache stores cachable responses in order to reduce the response |
380 |
time and network bandwidth consumption on future, equivalent |
381 |
requests. Any client or server may include a cache, though a |
382 |
cache cannot be used by a server while it is acting as a tunnel. |
383 |
|
384 |
Any given program may be capable of being both a client and a |
385 |
server; our use of these terms refers only to the role being |
386 |
performed by the program for a particular connection, rather than |
387 |
to the program's capabilities in general. Likewise, any server may |
388 |
act as an origin server, proxy, gateway, or tunnel, switching |
389 |
behavior based on the nature of each request. |
390 |
|
391 |
1.4 Overall Operation |
392 |
|
393 |
The HTTP protocol is based on a request/response paradigm. A client |
394 |
establishes a connection with a server and sends a request to the |
395 |
server in the form of a request method, URI, and protocol version, |
396 |
followed by a MIME-like message containing request modifiers, |
397 |
client information, and possible body content. The server responds |
398 |
with a status line, including the message's protocol version and a |
399 |
success or error code, followed by a MIME-like message containing |
400 |
server information, entity metainformation, and possible body |
401 |
content. |
402 |
|
403 |
Most HTTP communication is initiated by a user agent and consists |
404 |
of a request to be applied to a resource on some origin server. In |
405 |
the simplest case, this may be accomplished via a single connection |
406 |
(v) between the user agent (UA) and the origin server (O). |
407 |
|
408 |
request chain ------------------------> |
409 |
UA -------------------v------------------- O |
410 |
<----------------------- response chain |
411 |
|
412 |
A more complicated situation occurs when one or more intermediaries |
413 |
are present in the request/response chain. There are three common |
414 |
forms of intermediary: proxy, gateway, and tunnel. A proxy is a |
415 |
forwarding agent, receiving requests for a URI in its absolute |
416 |
form, rewriting all or parts of the message, and forwarding the |
417 |
reformatted request toward the server identified by the URI. A |
418 |
gateway is a receiving agent, acting as a layer above some other |
419 |
server(s) and, if necessary, translating the requests to the |
420 |
underlying server's protocol. A tunnel acts as a relay point |
421 |
between two connections without changing the messages; tunnels are |
422 |
used when the communication needs to pass through an intermediary |
423 |
(such as a firewall) even when the intermediary cannot understand |
424 |
the contents of the messages. |
425 |
|
426 |
request chain --------------------------------------> |
427 |
UA -----v----- A -----v----- B -----v----- C -----v----- O |
428 |
<------------------------------------- response chain |
429 |
|
430 |
The figure above shows three intermediaries (A, B, and C) between |
431 |
the user agent and origin server. A request or response message |
432 |
that travels the whole chain must pass through four separate |
433 |
connections. This distinction is important because some HTTP |
434 |
communication options may apply only to the connection with the |
435 |
nearest, non-tunnel neighbor, only to the end-points of the chain, |
436 |
or to all connections along the chain. Although the diagram is |
437 |
linear, each participant may be engaged in multiple, simultaneous |
438 |
communications. For example, B may be receiving requests from many |
439 |
clients other than A, and/or forwarding requests to servers other |
440 |
than C, at the same time that it is handling A's request. |
441 |
|
442 |
Any party to the communication which is not acting as a tunnel may |
443 |
employ an internal cache for handling requests. The effect of a |
444 |
cache is that the request/response chain is shortened if one of the |
445 |
participants along the chain has a cached response applicable to |
446 |
that request. The following illustrates the resulting chain if B |
447 |
has a cached copy of an earlier response from O (via C) for a |
448 |
request which has not been cached by UA or A. |
449 |
|
450 |
request chain ----------> |
451 |
UA -----v----- A -----v----- B - - - - - - C - - - - - - O |
452 |
<--------- response chain |
453 |
|
454 |
Not all responses are cachable, and some requests may contain |
455 |
modifiers which place special requirements on cache behavior. HTTP |
456 |
requirements for cache behavior and cachable responses are defined |
457 |
in Section 13. |
458 |
|
459 |
On the Internet, HTTP communication generally takes place over |
460 |
TCP/IP connections. The default port is TCP 80 [19], but other |
461 |
ports can be used. This does not preclude HTTP from being |
462 |
implemented on top of any other protocol on the Internet, or on |
463 |
other networks. HTTP only presumes a reliable transport; any |
464 |
protocol that provides such guarantees can be used, and the mapping |
465 |
of the HTTP/1.1 request and response structures onto the transport |
466 |
data units of the protocol in question is outside the scope of this |
467 |
specification. |
468 |
|
469 |
For most implementations, each connection is established by the |
470 |
client prior to the request and closed by the server after sending |
471 |
the response. However, this is not a feature of the protocol and is |
472 |
not required by this specification. Both clients and servers must |
473 |
be capable of handling cases where either party closes the |
474 |
connection prematurely, due to user action, automated time-out, or |
475 |
program failure. In any case, the closing of the connection by |
476 |
either or both parties always terminates the current request, |
477 |
regardless of its status. |
478 |
|
479 |
2. Notational Conventions and Generic Grammar |
480 |
|
481 |
2.1 Augmented BNF |
482 |
|
483 |
All of the mechanisms specified in this document are described in |
484 |
both prose and an augmented Backus-Naur Form (BNF) similar to that |
485 |
used by RFC 822 [9]. Implementors will need to be familiar with the |
486 |
notation in order to understand this specification. The augmented |
487 |
BNF includes the following constructs: |
488 |
|
489 |
name = definition |
490 |
|
491 |
The name of a rule is simply the name itself (without any |
492 |
enclosing "<" and ">") and is separated from its definition by |
493 |
the equal character "=". Whitespace is only significant in that |
494 |
indentation of continuation lines is used to indicate a rule |
495 |
definition that spans more than one line. Certain basic rules |
496 |
are in uppercase, such as SP, LWS, HT, CRLF, DIGIT, ALPHA, etc. |
497 |
Angle brackets are used within definitions whenever their |
498 |
presence will facilitate discerning the use of rule names. |
499 |
|
500 |
"literal" |
501 |
|
502 |
Quotation marks surround literal text. Unless stated otherwise, |
503 |
the text is case-insensitive. |
504 |
|
505 |
rule1 | rule2 |
506 |
|
507 |
Elements separated by a bar ("I") are alternatives, e.g., |
508 |
"yes | no" will accept yes or no. |
509 |
|
510 |
(rule1 rule2) |
511 |
|
512 |
Elements enclosed in parentheses are treated as a single |
513 |
element. Thus, "(elem (foo | bar) elem)" allows the token |
514 |
sequences "elem foo elem" and "elem bar elem". |
515 |
|
516 |
*rule |
517 |
|
518 |
The character "*" preceding an element indicates repetition. The |
519 |
full form is "<n>*<m>element" indicating at least <n> and at |
520 |
most <m> occurrences of element. Default values are 0 and |
521 |
infinity so that "*(element)" allows any number, including zero; |
522 |
"1*element" requires at least one; and "1*2element" allows one |
523 |
or two. |
524 |
|
525 |
[rule] |
526 |
|
527 |
Square brackets enclose optional elements; "[foo bar]" is |
528 |
equivalent to "*1(foo bar)". |
529 |
|
530 |
N rule |
531 |
|
532 |
Specific repetition: "<n>(element)" is equivalent to |
533 |
"<n>*<n>(element)"; that is, exactly <n> occurrences of |
534 |
(element). Thus 2DIGIT is a 2-digit number, and 3ALPHA is a |
535 |
string of three alphabetic characters. |
536 |
|
537 |
#rule |
538 |
|
539 |
A construct "#" is defined, similar to "*", for defining lists |
540 |
of elements. The full form is "<n>#<m>element" indicating at |
541 |
least <n> and at most <m> elements, each separated by one or |
542 |
more commas (",") and optional linear whitespace (LWS). This |
543 |
makes the usual form of lists very easy; a rule such as |
544 |
"( *LWS element *( *LWS "," *LWS element ))" can be shown as |
545 |
"1#element". Wherever this construct is used, null elements are |
546 |
allowed, but do not contribute to the count of elements present. |
547 |
That is, "(element), , (element)" is permitted, but counts as |
548 |
only two elements. Therefore, where at least one element is |
549 |
required, at least one non-null element must be present. Default |
550 |
values are 0 and infinity so that "#(element)" allows any |
551 |
number, including zero; "1#element" requires at least one; and |
552 |
"1#2element" allows one or two. |
553 |
|
554 |
; comment |
555 |
|
556 |
A semi-colon, set off some distance to the right of rule text, |
557 |
starts a comment that continues to the end of line. This is a |
558 |
simple way of including useful notes in parallel with the |
559 |
specifications. |
560 |
|
561 |
implied *LWS |
562 |
|
563 |
The grammar described by this specification is word-based. |
564 |
Except where noted otherwise, linear whitespace (LWS) can be |
565 |
included between any two adjacent words (token or |
566 |
quoted-string), and between adjacent tokens and delimiters |
567 |
(tspecials), without changing the interpretation of a field. At |
568 |
least one delimiter (tspecials) must exist between any two |
569 |
tokens, since they would otherwise be interpreted as a single |
570 |
token. However, applications should attempt to follow "common |
571 |
form" when generating HTTP constructs, since there exist some |
572 |
implementations that fail to accept anything beyond the common |
573 |
forms. |
574 |
|
575 |
2.2 Basic Rules |
576 |
|
577 |
The following rules are used throughout this specification to |
578 |
describe basic parsing constructs. The US-ASCII coded character set |
579 |
is defined by [21]. |
580 |
|
581 |
OCTET = <any 8-bit sequence of data> |
582 |
CHAR = <any US-ASCII character (octets 0 - 127)> |
583 |
UPALPHA = <any US-ASCII uppercase letter "A".."Z"> |
584 |
LOALPHA = <any US-ASCII lowercase letter "a".."z"> |
585 |
ALPHA = UPALPHA | LOALPHA |
586 |
DIGIT = <any US-ASCII digit "0".."9"> |
587 |
CTL = <any US-ASCII control character |
588 |
(octets 0 - 31) and DEL (127)> |
589 |
CR = <US-ASCII CR, carriage return (13)> |
590 |
LF = <US-ASCII LF, linefeed (10)> |
591 |
SP = <US-ASCII SP, space (32)> |
592 |
HT = <US-ASCII HT, horizontal-tab (9)> |
593 |
<"> = <US-ASCII double-quote mark (34)> |
594 |
|
595 |
HTTP/1.1 defines the octet sequence CR LF as the end-of-line marker |
596 |
for all protocol elements except the Entity-Body (see Appendix B |
597 |
for tolerant applications). The end-of-line marker within an |
598 |
Entity-Body is defined by its associated media type, as described |
599 |
in Section 3.7. |
600 |
|
601 |
CRLF = CR LF |
602 |
|
603 |
HTTP/1.1 headers can be folded onto multiple lines if the |
604 |
continuation line begins with a space or horizontal tab. All linear |
605 |
whitespace, including folding, has the same semantics as SP. |
606 |
|
607 |
LWS = [CRLF] 1*( SP | HT ) |
608 |
|
609 |
The TEXT rule is only used for descriptive field contents and |
610 |
values that are not intended to be interpreted by the message |
611 |
parser. Words of *TEXT may contain octets from character sets other |
612 |
than US-ASCII only when encoded according to the rules of |
613 |
RFC 1522 [14]. |
614 |
|
615 |
TEXT = <any OCTET except CTLs, |
616 |
but including LWS> |
617 |
|
618 |
Recipients of header field TEXT containing octets outside the |
619 |
US-ASCII character set range may assume that they represent |
620 |
ISO-8859-1 characters if there is no other encoding indicated by an |
621 |
RFC 1522 mechanism. |
622 |
|
623 |
Hexadecimal numeric characters are used in several protocol |
624 |
elements. |
625 |
|
626 |
HEX = "A" | "B" | "C" | "D" | "E" | "F" |
627 |
| "a" | "b" | "c" | "d" | "e" | "f" | DIGIT |
628 |
|
629 |
Many HTTP/1.1 header field values consist of words separated by LWS |
630 |
or special characters. These special characters must be in a quoted |
631 |
string to be used within a parameter value. |
632 |
|
633 |
word = token | quoted-string |
634 |
|
635 |
token = 1*<any CHAR except CTLs or tspecials> |
636 |
|
637 |
tspecials = "(" | ")" | "<" | ">" | "@" |
638 |
| "," | ";" | ":" | "\" | <"> |
639 |
| "/" | "[" | "]" | "?" | "=" |
640 |
| "{" | "}" | SP | HT |
641 |
|
642 |
Comments can be included in some HTTP header fields by surrounding |
643 |
the comment text with parentheses. Comments are only allowed in |
644 |
fields containing "comment" as part of their field value |
645 |
definition. In all other fields, parentheses are considered part of |
646 |
the field value. |
647 |
|
648 |
comment = "(" *( ctext | comment ) ")" |
649 |
ctext = <any TEXT excluding "(" and ")"> |
650 |
|
651 |
A string of text is parsed as a single word if it is quoted using |
652 |
double-quote marks. |
653 |
|
654 |
quoted-string = ( <"> *(qdtext) <"> ) |
655 |
|
656 |
qdtext = <any CHAR except <"> and CTLs, |
657 |
but including LWS> |
658 |
|
659 |
The backslash character ("\") may be used as a single-character |
660 |
quoting mechanism only within quoted-string and comment constructs. |
661 |
|
662 |
quoted-pair = "\" CHAR |
663 |
|
664 |
Braces are used to delimit an attribute-value bag, which may |
665 |
consist of a set, list, or recursively defined tokens and quoted |
666 |
strings. The bag semantics are defined by its context and the bag |
667 |
name, which may be a Uniform Resource Identifier (Section 3.2) in |
668 |
some fields. |
669 |
|
670 |
bag = "{" bagname 1*LWS *bagitem "}" |
671 |
bagname = token | URI |
672 |
bagitem = bag | token | quoted-string |
673 |
|
674 |
3. Protocol Parameters |
675 |
|
676 |
3.1 HTTP Version |
677 |
|
678 |
HTTP uses a "<major>.<minor>" numbering scheme to indicate versions |
679 |
of the protocol. The protocol versioning policy is intended to |
680 |
allow the sender to indicate the format of a message and its |
681 |
capacity for understanding further HTTP communication, rather than |
682 |
the features obtained via that communication. No change is made to |
683 |
the version number for the addition of message components which do |
684 |
not affect communication behavior or which only add to extensible |
685 |
field values. The <minor> number is incremented when the changes |
686 |
made to the protocol add features which do not change the general |
687 |
message parsing algorithm, but which may add to the message |
688 |
semantics and imply additional capabilities of the sender. The |
689 |
<major> number is incremented when the format of a message within |
690 |
the protocol is changed. |
691 |
|
692 |
The version of an HTTP message is indicated by an HTTP-Version |
693 |
field in the first line of the message. If the protocol version is |
694 |
not specified, the recipient must assume that the message is in the |
695 |
simple HTTP/0.9 format [6]. |
696 |
|
697 |
HTTP-Version = "HTTP" "/" 1*DIGIT "." 1*DIGIT |
698 |
|
699 |
Note that the major and minor numbers should be treated as separate |
700 |
integers and that each may be incremented higher than a single |
701 |
digit. Thus, HTTP/2.4 is a lower version than HTTP/2.13, which in |
702 |
turn is lower than HTTP/12.3. Leading zeros should be ignored by |
703 |
recipients and never generated by senders. |
704 |
|
705 |
Applications sending Full-Request or Full-Response messages, as |
706 |
defined by this specification, must include an HTTP-Version of |
707 |
"HTTP/1.1". Use of this version number indicates that the sending |
708 |
application is at least conditionally compliant with this |
709 |
specification. |
710 |
|
711 |
HTTP/1.1 servers must: |
712 |
|
713 |
o recognize the format of the Request-Line for HTTP/0.9, 1.0, and |
714 |
1.1 requests; |
715 |
|
716 |
o understand any valid request in the format of HTTP/0.9, 1.0, or |
717 |
1.1; |
718 |
|
719 |
o respond appropriately with a message in the same major version |
720 |
used by the client. |
721 |
|
722 |
HTTP/1.1 clients must: |
723 |
|
724 |
o recognize the format of the Status-Line for HTTP/1.0 and 1.1 |
725 |
responses; |
726 |
|
727 |
o understand any valid response in the format of HTTP/0.9, 1.0, |
728 |
or 1.1. |
729 |
|
730 |
Proxy and gateway applications must be careful in forwarding |
731 |
requests that are received in a format different than that of the |
732 |
application's native HTTP version. Since the protocol version |
733 |
indicates the protocol capability of the sender, a proxy/gateway |
734 |
must never send a message with a version indicator which is greater |
735 |
than its native version; if a higher version request is received, |
736 |
the proxy/gateway must either downgrade the request version, |
737 |
respond with an error, or switch to tunnel behavior. Requests with |
738 |
a version lower than that of the application's native format may be |
739 |
upgraded before being forwarded; the proxy/gateway's response to |
740 |
that request must follow the server requirements listed above. |
741 |
|
742 |
3.2 Uniform Resource Identifiers |
743 |
|
744 |
URIs have been known by many names: WWW addresses, Universal |
745 |
Document Identifiers, Universal Resource Identifiers [3], and |
746 |
finally the combination of Uniform Resource Locators (URL) [4] and |
747 |
Names (URN) [20]. As far as HTTP is concerned, Uniform Resource |
748 |
Identifiers are simply formatted strings which identify--via name, |
749 |
location, or any other characteristic--a network resource. |
750 |
|
751 |
3.2.1 General Syntax |
752 |
|
753 |
URIs in HTTP can be represented in absolute form or relative to |
754 |
some known base URI [11], depending upon the context of their use. |
755 |
The two forms are differentiated by the fact that absolute URIs |
756 |
always begin with a scheme name followed by a colon. |
757 |
|
758 |
URI = ( absoluteURI | relativeURI ) [ "#" fragment ] |
759 |
|
760 |
absoluteURI = scheme ":" *( uchar | reserved ) |
761 |
|
762 |
relativeURI = net_path | abs_path | rel_path |
763 |
|
764 |
net_path = "//" net_loc [ abs_path ] |
765 |
abs_path = "/" rel_path |
766 |
rel_path = [ path ] [ ";" params ] [ "?" query ] |
767 |
|
768 |
path = fsegment *( "/" segment ) |
769 |
fsegment = 1*pchar |
770 |
segment = *pchar |
771 |
|
772 |
params = param *( ";" param ) |
773 |
param = *( pchar | "/" ) |
774 |
|
775 |
scheme = 1*( ALPHA | DIGIT | "+" | "-" | "." ) |
776 |
net_loc = *( pchar | ";" | "?" ) |
777 |
query = *( uchar | reserved ) |
778 |
fragment = *( uchar | reserved ) |
779 |
|
780 |
pchar = uchar | ":" | "@" | "&" | "=" |
781 |
uchar = unreserved | escape |
782 |
unreserved = ALPHA | DIGIT | safe | extra | national |
783 |
|
784 |
escape = "%" HEX HEX |
785 |
reserved = ";" | "/" | "?" | ":" | "@" | "&" | "=" |
786 |
extra = "!" | "*" | "'" | "(" | ")" | "," |
787 |
safe = "$" | "-" | "_" | "." | "+" |
788 |
unsafe = CTL | SP | <"> | "#" | "%" | "<" | ">" |
789 |
national = <any OCTET excluding ALPHA, DIGIT, |
790 |
reserved, extra, safe, and unsafe> |
791 |
|
792 |
For definitive information on URL syntax and semantics, see RFC |
793 |
1738 [4] and RFC 1808 [11]. The BNF above includes national |
794 |
characters not allowed in valid URLs as specified by RFC 1738, |
795 |
since HTTP servers are not restricted in the set of unreserved |
796 |
characters allowed to represent the rel_path part of addresses, and |
797 |
HTTP proxies may receive requests for URIs not defined by RFC 1738. |
798 |
|
799 |
3.2.2 http URL |
800 |
|
801 |
The "http" scheme is used to locate network resources via the HTTP |
802 |
protocol. This section defines the scheme-specific syntax and |
803 |
semantics for http URLs. |
804 |
|
805 |
http_URL = "http:" "//" host [ ":" port ] [ abs_path ] |
806 |
|
807 |
host = <A legal Internet host domain name |
808 |
or IP address (in dotted-decimal form), |
809 |
as defined by Section 2.1 of RFC 1123> |
810 |
|
811 |
port = *DIGIT |
812 |
|
813 |
If the port is empty or not given, port 80 is assumed. The |
814 |
semantics are that the identified resource is located at the server |
815 |
listening for TCP connections on that port of that host, and the |
816 |
Request-URI for the resource is abs_path. If the abs_path is not |
817 |
present in the URL, it must be given as "/" when used as a |
818 |
Request-URI for a resource (Section 5.1.2). |
819 |
|
820 |
Note: Although the HTTP protocol is independent of the |
821 |
transport layer protocol, the http URL only identifies |
822 |
resources by their TCP location, and thus non-TCP resources |
823 |
must be identified by some other URI scheme. |
824 |
|
825 |
The canonical form for "http" URLs is obtained by converting any |
826 |
UPALPHA characters in host to their LOALPHA equivalent (hostnames |
827 |
are case-insensitive), eliding the [ ":" port ] if the port is 80, |
828 |
and replacing an empty abs_path with "/". |
829 |
|
830 |
3.3 Date/Time Formats |
831 |
|
832 |
3.3.1 Full Date |
833 |
|
834 |
HTTP applications have historically allowed three different formats |
835 |
for the representation of date/time stamps: |
836 |
|
837 |
Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123 |
838 |
Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036 |
839 |
Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format |
840 |
|
841 |
The first format is preferred as an Internet standard and |
842 |
represents a fixed-length subset of that defined by RFC 1123 [8] |
843 |
(an update to RFC 822 [9]). The second format is in common use, but |
844 |
is based on the obsolete RFC 850 [12] date format and lacks a |
845 |
four-digit year. HTTP/1.1 clients and servers that parse the date |
846 |
value must accept all three formats, though they must only generate |
847 |
the RFC 1123 format for representing date/time stamps in HTTP |
848 |
message fields. |
849 |
|
850 |
Note: Recipients of date values are encouraged to be robust |
851 |
in accepting date values that may have been generated by |
852 |
non-HTTP applications, as is sometimes the case when |
853 |
retrieving or posting messages via proxies/gateways to SMTP |
854 |
or NNTP. |
855 |
|
856 |
All HTTP date/time stamps must be represented in Universal Time |
857 |
(UT), also known as Greenwich Mean Time (GMT), without exception. |
858 |
This is indicated in the first two formats by the inclusion of |
859 |
"GMT" as the three-letter abbreviation for time zone, and should be |
860 |
assumed when reading the asctime format. |
861 |
|
862 |
HTTP-date = rfc1123-date | rfc850-date | asctime-date |
863 |
|
864 |
rfc1123-date = wkday "," SP date1 SP time SP "GMT" |
865 |
rfc850-date = weekday "," SP date2 SP time SP "GMT" |
866 |
asctime-date = wkday SP date3 SP time SP 4DIGIT |
867 |
|
868 |
date1 = 2DIGIT SP month SP 4DIGIT |
869 |
; day month year (e.g., 02 Jun 1982) |
870 |
date2 = 2DIGIT "-" month "-" 2DIGIT |
871 |
; day-month-year (e.g., 02-Jun-82) |
872 |
date3 = month SP ( 2DIGIT | ( SP 1DIGIT )) |
873 |
; month day (e.g., Jun 2) |
874 |
|
875 |
time = 2DIGIT ":" 2DIGIT ":" 2DIGIT |
876 |
; 00:00:00 - 23:59:59 |
877 |
|
878 |
wkday = "Mon" | "Tue" | "Wed" |
879 |
| "Thu" | "Fri" | "Sat" | "Sun" |
880 |
|
881 |
weekday = "Monday" | "Tuesday" | "Wednesday" |
882 |
| "Thursday" | "Friday" | "Saturday" | "Sunday" |
883 |
|
884 |
month = "Jan" | "Feb" | "Mar" | "Apr" |
885 |
| "May" | "Jun" | "Jul" | "Aug" |
886 |
| "Sep" | "Oct" | "Nov" | "Dec" |
887 |
|
888 |
Note: HTTP requirements for the date/time stamp format apply |
889 |
only to their usage within the protocol stream. Clients and |
890 |
servers are not required to use these formats for user |
891 |
presentation, request logging, etc. |
892 |
|
893 |
3.3.2 Delta Seconds |
894 |
|
895 |
Some HTTP header fields allow a time value to be specified as an |
896 |
integer number of seconds, represented in decimal, after the time |
897 |
that the message was received. This format should only be used to |
898 |
represent short time periods or periods that cannot start until |
899 |
receipt of the message. |
900 |
|
901 |
delta-seconds = 1*DIGIT |
902 |
|
903 |
3.4 Character Sets |
904 |
|
905 |
HTTP uses the same definition of the term "character set" as that |
906 |
described for MIME: |
907 |
|
908 |
The term "character set" is used in this document to |
909 |
refer to a method used with one or more tables to convert |
910 |
a sequence of octets into a sequence of characters. Note |
911 |
that unconditional conversion in the other direction is |
912 |
not required, in that not all characters may be available |
913 |
in a given character set and a character set may provide |
914 |
more than one sequence of octets to represent a |
915 |
particular character. This definition is intended to |
916 |
allow various kinds of character encodings, from simple |
917 |
single-table mappings such as US-ASCII to complex table |
918 |
switching methods such as those that use ISO 2022's |
919 |
techniques. However, the definition associated with a |
920 |
MIME character set name must fully specify the mapping to |
921 |
be performed from octets to characters. In particular, |
922 |
use of external profiling information to determine the |
923 |
exact mapping is not permitted. |
924 |
|
925 |
HTTP character sets are identified by case-insensitive tokens. The |
926 |
complete set of tokens are defined by the IANA Character Set |
927 |
registry [19]. However, because that registry does not define a |
928 |
single, consistent token for each character set, we define here the |
929 |
preferred names for those character sets most likely to be used |
930 |
with HTTP entities. These character sets include those registered |
931 |
by RFC 1521 [7] -- the US-ASCII [21] and ISO-8859 [22] character |
932 |
sets -- and other names specifically recommended for use within MIME |
933 |
charset parameters. |
934 |
|
935 |
charset = "US-ASCII" |
936 |
| "ISO-8859-1" | "ISO-8859-2" | "ISO-8859-3" |
937 |
| "ISO-8859-4" | "ISO-8859-5" | "ISO-8859-6" |
938 |
| "ISO-8859-7" | "ISO-8859-8" | "ISO-8859-9" |
939 |
| "ISO-2022-JP" | "ISO-2022-JP-2" | "ISO-2022-KR" |
940 |
| "UNICODE-1-1" | "UNICODE-1-1-UTF-7" | "UNICODE-1-1-UTF-8" |
941 |
| token |
942 |
|
943 |
Although HTTP allows an arbitrary token to be used as a charset |
944 |
value, any token that has a predefined value within the IANA |
945 |
Character Set registry [19] must represent the character set |
946 |
defined by that registry. Applications should limit their use of |
947 |
character sets to those defined by the IANA registry. |
948 |
|
949 |
Note: This use of the term "character set" is more commonly |
950 |
referred to as a "character encoding." However, since HTTP |
951 |
and MIME share the same registry, it is important that the |
952 |
terminology also be shared. |
953 |
|
954 |
3.5 Content Codings |
955 |
|
956 |
Content coding values are used to indicate an encoding |
957 |
transformation that has been or can be applied to a resource. |
958 |
Content codings are primarily used to allow a document to be |
959 |
compressed or encrypted without losing the identity of its |
960 |
underlying media type. Typically, the resource is stored in this |
961 |
encoding and only decoded before rendering or analogous usage. |
962 |
|
963 |
content-coding = "gzip" | "compress" | token |
964 |
|
965 |
Note: For historical reasons, HTTP applications should |
966 |
consider "x-gzip" and "x-compress" to be equivalent to "gzip" |
967 |
and "compress", respectively. |
968 |
|
969 |
All content-coding values are case-insensitive. HTTP/1.1 uses |
970 |
content-coding values in the Accept-Encoding (Section 10.3) and |
971 |
Content-Encoding (Section 10.10) header fields. Although the value |
972 |
describes the content-coding, what is more important is that it |
973 |
indicates what decoding mechanism will be required to remove the |
974 |
encoding. Note that a single program may be capable of decoding |
975 |
multiple content-coding formats. Two values are defined by this |
976 |
specification: |
977 |
|
978 |
gzip |
979 |
An encoding format produced by the file compression program |
980 |
"gzip" (GNU zip) developed by Jean-loup Gailly. This format is |
981 |
typically a Lempel-Ziv coding (LZ77) with a 32 bit CRC. Gzip is |
982 |
available from the GNU project at |
983 |
<URL:ftp://prep.ai.mit.edu/pub/gnu/>. |
984 |
|
985 |
compress |
986 |
The encoding format produced by the file compression program |
987 |
"compress". This format is an adaptive Lempel-Ziv-Welch coding |
988 |
(LZW). |
989 |
|
990 |
Note: Use of program names for the identification of |
991 |
encoding formats is not desirable and should be discouraged |
992 |
for future encodings. Their use here is representative of |
993 |
historical practice, not good design. |
994 |
|
995 |
3.6 Transfer Codings |
996 |
|
997 |
Transfer coding values are used to indicate an encoding |
998 |
transformation that has been, can be, or may need to be applied to |
999 |
an Entity-Body in order to ensure safe transport through the |
1000 |
network. This differs from a content coding in that the transfer |
1001 |
coding is a property of the message, not of the original resource. |
1002 |
|
1003 |
transfer-coding = "chunked" | token |
1004 |
|
1005 |
All transfer-coding values are case-insensitive. HTTP/1.1 uses |
1006 |
transfer coding values in the Transfer-Encoding header field |
1007 |
(Section 10.39). |
1008 |
|
1009 |
Transfer codings are analogous to the Content-Transfer-Encoding |
1010 |
values of MIME [7], which were designed to enable safe transport of |
1011 |
binary data over a 7-bit transport service. However, "safe |
1012 |
transport" has a different focus for an 8bit-clean transfer |
1013 |
protocol. In HTTP, the only unsafe characteristic of message bodies |
1014 |
is the difficulty in determining the exact body length |
1015 |
(Section 7.2.2), or the desire to encrypt data over a shared |
1016 |
transport. |
1017 |
|
1018 |
All HTTP/1.1 applications must be able to receive and decode the |
1019 |
"chunked" transfer coding. The chunked encoding modifies the body |
1020 |
of a message in order to transfer it as a series of chunks, each |
1021 |
with its own size indicator, followed by an optional footer |
1022 |
containing entity-header fields. This allows dynamically-produced |
1023 |
content to be transferred along with the information necessary for |
1024 |
the recipient to verify that it has received the full message. |
1025 |
|
1026 |
Chunked-Body = *chunk |
1027 |
"0" CRLF |
1028 |
footer |
1029 |
CRLF |
1030 |
|
1031 |
chunk = chunk-size CRLF |
1032 |
chunk-data CRLF |
1033 |
|
1034 |
chunk-size = hex-no-zero *HEX |
1035 |
chunk-data = chunk-size(OCTET) |
1036 |
|
1037 |
footer = *<Entity-Header, excluding Content-Length |
1038 |
and Transfer-Encoding> |
1039 |
|
1040 |
hex-no-zero = <HEX excluding "0"> |
1041 |
|
1042 |
Note that the chunks are ended by a zero-sized chunk, followed by |
1043 |
the footer and terminated by an empty line. An example process for |
1044 |
decoding a Chunked-Body is presented in Appendix C.5. |
1045 |
|
1046 |
3.7 Media Types |
1047 |
|
1048 |
HTTP uses Internet Media Types [17] in the Content-Type |
1049 |
(Section 10.15) and Accept (Section 10.1) header fields in order to |
1050 |
provide open and extensible data typing and type negotiation. For |
1051 |
mail applications, where there is no type negotiation between |
1052 |
sender and recipient, it is reasonable to put strict limits on the |
1053 |
set of allowed media types. With HTTP, where the sender and |
1054 |
recipient can communicate directly, applications are allowed more |
1055 |
freedom in the use of non-registered types. The following grammar |
1056 |
for media types is a superset of that for MIME because it does not |
1057 |
restrict itself to the official IANA and x-token types. |
1058 |
|
1059 |
media-type = type "/" subtype *( ";" parameter ) |
1060 |
type = token |
1061 |
subtype = token |
1062 |
|
1063 |
Parameters may follow the type/subtype in the form of |
1064 |
attribute/value pairs. |
1065 |
|
1066 |
parameter = attribute "=" value |
1067 |
attribute = token |
1068 |
value = token | quoted-string |
1069 |
|
1070 |
The type, subtype, and parameter attribute names are |
1071 |
case-insensitive. Parameter values may or may not be |
1072 |
case-sensitive, depending on the semantics of the parameter name. |
1073 |
LWS should not be generated between the type and subtype, nor |
1074 |
between an attribute and its value. |
1075 |
|
1076 |
If a given media-type value has been registered by the IANA, any |
1077 |
use of that value must be indicative of the registered data format. |
1078 |
Although HTTP allows the use of non-registered media types, such |
1079 |
usage must not conflict with the IANA registry. Data providers are |
1080 |
strongly encouraged to register their media types with IANA via the |
1081 |
procedures outlined in RFC 1590 [17]. |
1082 |
|
1083 |
All media-type's registered by IANA must be preferred over |
1084 |
extension tokens. However, HTTP does not limit applications to the |
1085 |
use of officially registered media types, nor does it encourage the |
1086 |
use of an "x-" prefix for unofficial types outside of explicitly |
1087 |
short experimental use between consenting applications. |
1088 |
|
1089 |
3.7.1 Canonicalization and Text Defaults |
1090 |
|
1091 |
Media types are registered in a canonical form. In general, entity |
1092 |
bodies transferred via HTTP must be represented in the appropriate |
1093 |
canonical form prior to transmission. If the body has been encoded |
1094 |
via a Content-Encoding and/or Transfer-Encoding, the data must be |
1095 |
in canonical form prior to that encoding. However, HTTP modifies |
1096 |
the canonical form requirements for media of primary type "text" |
1097 |
and for "application" types consisting of text-like records. |
1098 |
|
1099 |
HTTP redefines the canonical form of text media to allow multiple |
1100 |
octet sequences to indicate a text line break. In addition to the |
1101 |
preferred form of CRLF, HTTP applications must accept a bare CR or |
1102 |
LF alone as representing a single line break in text media. |
1103 |
Furthermore, if the text media is represented in a character set |
1104 |
which does not use octets 13 and 10 for CR and LF respectively, as |
1105 |
is the case for some multi-byte character sets, HTTP allows the use |
1106 |
of whatever octet sequence(s) is defined by that character set to |
1107 |
represent the equivalent of CRLF, bare CR, and bare LF. It is |
1108 |
assumed that any recipient capable of using such a character set |
1109 |
will know the appropriate octet sequence for representing line |
1110 |
breaks within that character set. |
1111 |
|
1112 |
Note: This interpretation of line breaks applies only to the |
1113 |
contents of an Entity-Body and only after any |
1114 |
Transfer-Encoding and/or Content-Encoding has been removed. |
1115 |
All other HTTP constructs use CRLF exclusively to indicate a |
1116 |
line break. Content and transfer codings define their own |
1117 |
line break requirements. |
1118 |
|
1119 |
A recipient of an HTTP text entity should translate the received |
1120 |
entity line breaks to the local line break conventions before |
1121 |
saving the entity external to the application and its cache; |
1122 |
whether this translation takes place immediately upon receipt of |
1123 |
the entity, or only when prompted by the user, is entirely up to |
1124 |
the individual application. |
1125 |
|
1126 |
HTTP also redefines the default character set for text media in an |
1127 |
entity body. If a textual media type defines a charset parameter |
1128 |
with a registered default value of "US-ASCII", HTTP changes the |
1129 |
default to be "ISO-8859-1". Since the ISO-8859-1 [22] character set |
1130 |
is a superset of US-ASCII [21], this does not affect the |
1131 |
interpretation of entity bodies which only contain octets within |
1132 |
the US-ASCII character set (0 - 127). The presence of a charset |
1133 |
parameter value in a Content-Type header field overrides the |
1134 |
default. |
1135 |
|
1136 |
It is recommended that the character set of an entity body be |
1137 |
labelled as the lowest common denominator of the character codes |
1138 |
used within a document, with the exception that no label is |
1139 |
preferred over the labels US-ASCII or ISO-8859-1. |
1140 |
|
1141 |
3.7.2 Multipart Types |
1142 |
|
1143 |
MIME provides for a number of "multipart" types -- encapsulations of |
1144 |
one or more entities within a single message's Entity-Body. All |
1145 |
multipart types share a common syntax, as defined in Section 7.2.1 |
1146 |
of RFC 1521 [7], and must include a boundary parameter as part of |
1147 |
the media type value. The message body is itself a protocol element |
1148 |
and must therefore use only CRLF to represent line breaks between |
1149 |
body-parts. Unlike in MIME, the epilogue of any multipart message |
1150 |
must be empty; HTTP applications must not transmit the epilogue |
1151 |
even if the original resource contains an epilogue. |
1152 |
|
1153 |
In HTTP, multipart body-parts may contain header fields which are |
1154 |
significant to the meaning of that part. A URI entity-header field |
1155 |
(Section 10.42) should be included in the body-part for each |
1156 |
enclosed entity that can be identified by a URI. |
1157 |
|
1158 |
In general, an HTTP user agent should follow the same or similar |
1159 |
behavior as a MIME user agent would upon receipt of a multipart |
1160 |
type. The following subtypes have been defined: |
1161 |
|
1162 |
multipart/mixed |
1163 |
|
1164 |
The mixed subtype is used when there are no additional semantics |
1165 |
implied beyond the fact that one or more entities are |
1166 |
encaspsulated. HTTP servers should not use this type to send |
1167 |
groups of entities if it is possible for those entities to be |
1168 |
individually retrieved and cached. |
1169 |
|
1170 |
multipart/alternative |
1171 |
|
1172 |
The alternative subtype implies that each of the parts is an |
1173 |
alternative format for the same information; the user agent |
1174 |
should present only the part most preferred by the user. HTTP |
1175 |
servers should use some form of content negotiation (Section 12) |
1176 |
instead of this type. |
1177 |
|
1178 |
multipart/digest |
1179 |
|
1180 |
The digest subtype implies that each of the parts is a message |
1181 |
(normally of type "message/rfc822") and thus the whole entity is |
1182 |
a collected sequence of message traffic. This type does not have |
1183 |
any special significance for HTTP. |
1184 |
|
1185 |
multipart/form-data |
1186 |
|
1187 |
The form-data subtype is defined by RFC 1867 [15] for use in |
1188 |
submitting the data that comes about from filling-in a form. |
1189 |
|
1190 |
multipart/parallel |
1191 |
|
1192 |
The parallel subtype implies that the parts should be presented |
1193 |
simultaneously by the user agent. This media type would be |
1194 |
appropriate for situations where simultaneous presentation is an |
1195 |
important aspect of the information, such as for audio-annotated |
1196 |
slides. |
1197 |
|
1198 |
Note: This document does not define what is meant by |
1199 |
"simultaneous presentation". That is, HTTP does not provide |
1200 |
any means of synchronization between the parts in messages |
1201 |
of type "multipart/parallel". |
1202 |
|
1203 |
Other multipart subtypes may be registered by IANA [19] according |
1204 |
to the procedures defined in RFC 1590 [17]. If an application |
1205 |
receives an unrecognized multipart subtype, the application must |
1206 |
treat it as being equivalent to "multipart/mixed". |
1207 |
|
1208 |
3.8 Product Tokens |
1209 |
|
1210 |
Product tokens are used to allow communicating applications to |
1211 |
identify themselves via a simple product token, with an optional |
1212 |
slash and version designator. Most fields using product tokens also |
1213 |
allow subproducts which form a significant part of the application |
1214 |
to be listed, separated by whitespace. By convention, the products |
1215 |
are listed in order of their significance for identifying the |
1216 |
application. |
1217 |
|
1218 |
product = token ["/" product-version] |
1219 |
product-version = token |
1220 |
|
1221 |
Examples: |
1222 |
|
1223 |
User-Agent: CERN-LineMode/2.15 libwww/2.17b3 |
1224 |
|
1225 |
Server: Apache/0.8.4 |
1226 |
|
1227 |
Product tokens should be short and to the point -- use of them for |
1228 |
advertizing or other non-essential information is explicitly |
1229 |
forbidden. Although any token character may appear in a |
1230 |
product-version, this token should only be used for a version |
1231 |
identifier (i.e., successive versions of the same product should |
1232 |
only differ in the product-version portion of the product value). |
1233 |
|
1234 |
3.9 Quality Values |
1235 |
|
1236 |
HTTP content negotiation (Section 12) uses short "floating point" |
1237 |
numbers to indicate the relative importance ("weight") of various |
1238 |
negotiable parameters. The weights are normalized to a real number |
1239 |
in the range 0 through 1, where 0 is the minimum and 1 the maximum |
1240 |
value. In order to discourage misuse of this feature, HTTP/1.1 |
1241 |
applications must not generate more than three digits after the |
1242 |
decimal point. User configuration of these values should also be |
1243 |
limited in this fashion. |
1244 |
|
1245 |
qvalue = ( "0" [ "." 0*3DIGIT ] ) |
1246 |
| ( "." 0*3DIGIT ) |
1247 |
| ( "1" [ "." 0*3("0") ] ) |
1248 |
|
1249 |
"Quality values" is a slight misnomer, since these values actually |
1250 |
measure relative degradation in perceived quality. Thus, a value of |
1251 |
"0.8" represents a 20% degradation from the optimum rather than a |
1252 |
statement of 80% quality. |
1253 |
|
1254 |
3.10 Language Tags |
1255 |
|
1256 |
A language tag identifies a natural language spoken, written, or |
1257 |
otherwise conveyed by human beings for communication of information |
1258 |
to other human beings. Computer languages are explicitly excluded. |
1259 |
HTTP uses language tags within the Accept-Language, |
1260 |
Content-Language, and URI-header fields. |
1261 |
|
1262 |
The syntax and registry of HTTP language tags is the same as that |
1263 |
defined by RFC 1766 [1]. In summary, a language tag is composed of |
1264 |
1 or more parts: A primary language tag and a possibly empty series |
1265 |
of subtags: |
1266 |
|
1267 |
language-tag = primary-tag *( "-" subtag ) |
1268 |
|
1269 |
primary-tag = 1*8ALPHA |
1270 |
subtag = 1*8ALPHA |
1271 |
|
1272 |
Whitespace is not allowed within the tag and all tags are |
1273 |
case-insensitive. The namespace of language tags is administered by |
1274 |
the IANA. Example tags include: |
1275 |
|
1276 |
en, en-US, en-cockney, i-cherokee, x-pig-latin |
1277 |
|
1278 |
where any two-letter primary-tag is an ISO 639 language |
1279 |
abbreviation and any two-letter initial subtag is an ISO 3166 |
1280 |
country code. |
1281 |
|
1282 |
In the context of the Accept-Language header (Section 10.4), a |
1283 |
language tag is not to be interpreted as a single token, as per RFC |
1284 |
1766, but as a hierarchy. A server should consider that it has a |
1285 |
match when a language tag received in an Accept-Language header |
1286 |
matches the initial portion of the language tag of a document. An |
1287 |
exact match should be preferred. This interpretation allows a |
1288 |
browser to send, for example: |
1289 |
|
1290 |
Accept-Language: en-US, en; ql=0.95 |
1291 |
|
1292 |
when the intent is to access, in order of preference, documents in |
1293 |
US-English ("en-US"), 'plain' or 'international' English ("en"), |
1294 |
and any other variant of English (initial "en-"). |
1295 |
|
1296 |
Note: Using the language tag as a hierarchy does not imply |
1297 |
that all languages with a common prefix will be understood |
1298 |
by those fluent in one or more of those languages; it simply |
1299 |
allows the user to request this commonality when it is true |
1300 |
for that user. |
1301 |
|
1302 |
3.11 Logic Bags |
1303 |
|
1304 |
A logic bag is a binary logic expression tree represented in prefix |
1305 |
notation using the generic bag syntax. Logic bags are used by HTTP |
1306 |
in the Unless (Section 10.40) header field as expressions to be |
1307 |
tested against the requested resource's header field |
1308 |
metainformation. |
1309 |
|
1310 |
logic-bag = "{" expression "}" |
1311 |
|
1312 |
expression = ( log-op 1*logic-bag ) |
1313 |
| ( rel-op 1*field-tuple ) |
1314 |
| ( "def" 1*field-name ) |
1315 |
|
1316 |
log-op = "and" | "or" | "xor" | "not" |
1317 |
rel-op = "eq" | "ne" | "lt" | "le" | "ge" | "gt" | "in" |
1318 |
|
1319 |
field-tuple = "{" field-name ( bag | token | quoted-string ) "}" |
1320 |
|
1321 |
The recursive structure of a logic bag allows a complex expression |
1322 |
tree to be formed by joining together subexpressions with logical |
1323 |
operators. Expressions with relational operators are used to |
1324 |
compare the requested resource's corresponding metainformation |
1325 |
(header field values) to those inside the expression field-tuples. |
1326 |
For example, |
1327 |
|
1328 |
{or {ne {Content-MD5 "Q2hlY2sgSW50ZWdyaXR5IQ=="}} |
1329 |
{ne {Content-Length 10036}} |
1330 |
{ne {Content-Version "12.4.8"}} |
1331 |
{gt {Last-Modified "Mon, 04 Dec 1995 01:23:45 GMT"}}} |
1332 |
|
1333 |
The expression is evaluated recursively by depth-first traversal |
1334 |
and bottom-up evaluation of the subexpressions until a true or |
1335 |
false value can be determined. Multiple operands to an operator |
1336 |
imply a conjunctive ("and") expression; e.g., |
1337 |
|
1338 |
{eq {A "a"} {B "b"} {C "c"}} |
1339 |
|
1340 |
is equivalent to |
1341 |
|
1342 |
{and {eq {A "a"}} {eq {B "b"}} {eq {C "c"}}} |
1343 |
|
1344 |
Each expression is evaluated as defined by the operator: |
1345 |
|
1346 |
and True if all of the operands evaluate true. |
1347 |
|
1348 |
or True if any of the operands evaluate true. |
1349 |
|
1350 |
xor True if one and only one operand evaluates true. |
1351 |
|
1352 |
not True if all of the operands evaluate false. |
1353 |
|
1354 |
eq True if all field-tuple values exactly match the resource's |
1355 |
corresponding field values. |
1356 |
|
1357 |
ne True if all field-tuple values do not match the resource's |
1358 |
corresponding field values. |
1359 |
|
1360 |
lt True if, for each field-tuple, the resource's corresponding |
1361 |
field value is less than the one given in the expression. |
1362 |
|
1363 |
le True if, for each field-tuple, the resource's corresponding |
1364 |
field value is less than or equal to the one given in the |
1365 |
expression. |
1366 |
|
1367 |
ge True if, for each field-tuple, the resource's corresponding |
1368 |
field value is greater than or equal to the one given in the |
1369 |
expression. |
1370 |
|
1371 |
gt True if, for each field-tuple, the resource's corresponding |
1372 |
field value is greater than the one given in the expression. |
1373 |
|
1374 |
in True if, for each field-tuple, the resource's corresponding |
1375 |
field value contains the component value given in the |
1376 |
expression. |
1377 |
|
1378 |
def True if, for each field-name operand, the resource defines a |
1379 |
value for that field. |
1380 |
|
1381 |
A field-tuple consists of a field-name (assumed to be an HTTP |
1382 |
header field name, though not constrained to those defined by this |
1383 |
specification) and the field-value component which is to be |
1384 |
compared against the resource's field value. The actual method of |
1385 |
comparison (e.g., byte equivalence, substring matching, numeric |
1386 |
order, substructure containment, etc.) is defined by the logical |
1387 |
definition of the operator and the type of field-value allowed for |
1388 |
that field-name. Server implementors must use an appropriate |
1389 |
comparison function for each type of field-value given in this |
1390 |
specification. The default functions for unrecognized fields are |
1391 |
numeric comparison (for values consisting of 1*DIGIT) and lexical |
1392 |
comparison (for all others). |
1393 |
|
1394 |
Except for "ne", any comparison to a field not defined by the |
1395 |
resource evaluates to false. |
1396 |
|
1397 |
4. HTTP Message |
1398 |
|
1399 |
4.1 Message Types |
1400 |
|
1401 |
HTTP messages consist of requests from client to server and |
1402 |
responses from server to client. |
1403 |
|
1404 |
HTTP-message = Simple-Request ; HTTP/0.9 messages |
1405 |
| Simple-Response |
1406 |
| Full-Request ; HTTP/1.1 messages |
1407 |
| Full-Response |
1408 |
|
1409 |
Full-Request and Full-Response use the generic message format of |
1410 |
RFC 822 [9] for transferring entities. Both messages may include |
1411 |
optional header fields (also known as "headers") and an entity |
1412 |
body. The entity body is separated from the headers by a null line |
1413 |
(i.e., a line with nothing preceding the CRLF). |
1414 |
|
1415 |
Full-Request = Request-Line ; Section 5.1 |
1416 |
*( General-Header ; Section 4.3 |
1417 |
| Request-Header ; Section 5.2 |
1418 |
| Entity-Header ) ; Section 7.1 |
1419 |
CRLF |
1420 |
[ Entity-Body ] ; Section 7.2 |
1421 |
|
1422 |
Full-Response = Status-Line ; Section 6.1 |
1423 |
*( General-Header ; Section 4.3 |
1424 |
| Response-Header ; Section 6.2 |
1425 |
| Entity-Header ) ; Section 7.1 |
1426 |
CRLF |
1427 |
[ Entity-Body ] ; Section 7.2 |
1428 |
|
1429 |
Simple-Request and Simple-Response do not allow the use of any |
1430 |
header information and are limited to a single request method (GET). |
1431 |
|
1432 |
Simple-Request = "GET" SP Request-URI CRLF |
1433 |
|
1434 |
Simple-Response = [ Entity-Body ] |
1435 |
|
1436 |
Use of the Simple-Request format is discouraged because it prevents |
1437 |
the client from using content negotiation and the server from |
1438 |
identifying the media type of the returned entity. |
1439 |
|
1440 |
4.2 Message Headers |
1441 |
|
1442 |
HTTP header fields, which include General-Header (Section 4.3), |
1443 |
Request-Header (Section 5.2), Response-Header (Section 6.2), and |
1444 |
Entity-Header (Section 7.1) fields, follow the same generic format |
1445 |
as that given in Section 3.1 of RFC 822 [9]. Each header field |
1446 |
consists of a name followed by a colon (":") and the field value. |
1447 |
Field names are case-insensitive. The field value may be preceded |
1448 |
by any amount of LWS, though a single SP is preferred. Header |
1449 |
fields can be extended over multiple lines by preceding each extra |
1450 |
line with at least one SP or HT. |
1451 |
|
1452 |
HTTP-header = field-name ":" [ field-value ] CRLF |
1453 |
|
1454 |
field-name = token |
1455 |
field-value = *( field-content | LWS ) |
1456 |
|
1457 |
field-content = <the OCTETs making up the field-value |
1458 |
and consisting of either *TEXT or combinations |
1459 |
of token, tspecials, and quoted-string> |
1460 |
|
1461 |
The order in which header fields are received is not significant. |
1462 |
However, it is "good practice" to send General-Header fields first, |
1463 |
followed by Request-Header or Response-Header fields prior to the |
1464 |
Entity-Header fields. |
1465 |
|
1466 |
Multiple HTTP-header fields with the same field-name may be present |
1467 |
in a message if and only if the entire field-value for that header |
1468 |
field is defined as a comma-separated list [i.e., #(values)]. It |
1469 |
must be possible to combine the multiple header fields into one |
1470 |
"field-name: field-value" pair, without changing the semantics of |
1471 |
the message, by appending each subsequent field-value to the first, |
1472 |
each separated by a comma. |
1473 |
|
1474 |
4.3 General Header Fields |
1475 |
|
1476 |
There are a few header fields which have general applicability for |
1477 |
both request and response messages, but which do not apply to the |
1478 |
entity being transferred. These headers apply only to the message |
1479 |
being transmitted. |
1480 |
|
1481 |
General-Header = Cache-Control ; Section 10.8 |
1482 |
| Connection ; Section 10.9 |
1483 |
| Date ; Section 10.17 |
1484 |
| Forwarded ; Section 10.20 |
1485 |
| Keep-Alive ; Section 10.24 |
1486 |
| MIME-Version ; Section 10.28 |
1487 |
| Pragma ; Section 10.29 |
1488 |
| Upgrade ; Section 10.41 |
1489 |
|
1490 |
General header field names can be extended reliably only in |
1491 |
combination with a change in the protocol version. However, new or |
1492 |
experimental header fields may be given the semantics of general |
1493 |
header fields if all parties in the communication recognize them to |
1494 |
be general header fields. Unrecognized header fields are treated as |
1495 |
Entity-Header fields. |
1496 |
|
1497 |
5. Request |
1498 |
|
1499 |
A request message from a client to a server includes, within the |
1500 |
first line of that message, the method to be applied to the |
1501 |
resource, the identifier of the resource, and the protocol version |
1502 |
in use. For backwards compatibility with the more limited HTTP/0.9 |
1503 |
protocol, there are two valid formats for an HTTP request: |
1504 |
|
1505 |
Request = Simple-Request | Full-Request |
1506 |
|
1507 |
Simple-Request = "GET" SP Request-URI CRLF |
1508 |
|
1509 |
Full-Request = Request-Line ; Section 5.1 |
1510 |
*( General-Header ; Section 4.3 |
1511 |
| Request-Header ; Section 5.2 |
1512 |
| Entity-Header ) ; Section 7.1 |
1513 |
CRLF |
1514 |
[ Entity-Body ] ; Section 7.2 |
1515 |
|
1516 |
If an HTTP/1.1 server receives a Simple-Request, it must respond |
1517 |
with an HTTP/0.9 Simple-Response. An HTTP/1.1 client must never |
1518 |
generate a Simple-Request. |
1519 |
|
1520 |
5.1 Request-Line |
1521 |
|
1522 |
The Request-Line begins with a method token, followed by the |
1523 |
Request-URI and the protocol version, and ending with CRLF. The |
1524 |
elements are separated by SP characters. No CR or LF are allowed |
1525 |
except in the final CRLF sequence. |
1526 |
|
1527 |
Request-Line = Method SP Request-URI SP HTTP-Version CRLF |
1528 |
|
1529 |
Note that the difference between a Simple-Request and the |
1530 |
Request-Line of a Full-Request is the presence of the HTTP-Version |
1531 |
field and the availability of methods other than GET. |
1532 |
|
1533 |
5.1.1 Method |
1534 |
|
1535 |
The Method token indicates the method to be performed on the |
1536 |
resource identified by the Request-URI. The method is |
1537 |
case-sensitive. |
1538 |
|
1539 |
Method = "OPTIONS" ; Section 8.1 |
1540 |
| "GET" ; Section 8.2 |
1541 |
| "HEAD" ; Section 8.3 |
1542 |
| "POST" ; Section 8.4 |
1543 |
| "PUT" ; Section 8.5 |
1544 |
| "PATCH" ; Section 8.6 |
1545 |
| "COPY" ; Section 8.7 |
1546 |
| "MOVE" ; Section 8.8 |
1547 |
| "DELETE" ; Section 8.9 |
1548 |
| "LINK" ; Section 8.10 |
1549 |
| "UNLINK" ; Section 8.11 |
1550 |
| "TRACE" ; Section 8.12 |
1551 |
| "WRAPPED" ; Section 8.13 |
1552 |
| extension-method |
1553 |
|
1554 |
extension-method = token |
1555 |
|
1556 |
The list of methods acceptable by a specific resource can be |
1557 |
specified in an Allow header field (Section 10.5). However, the |
1558 |
client is always notified through the return code of the response |
1559 |
whether a method is currently allowed on a specific resource, as |
1560 |
this can change dynamically. Servers should return the status code |
1561 |
405 (method not allowed) if the method is known by the server but |
1562 |
not allowed for the requested resource, and 501 (not implemented) |
1563 |
if the method is unrecognized or not implemented by the server. The |
1564 |
list of methods known by a server can be listed in a Public |
1565 |
response header field (Section 10.32). |
1566 |
|
1567 |
The methods GET and HEAD must be supported by all general-purpose |
1568 |
servers. Servers which provide Last-Modified dates for resources |
1569 |
must also support the conditional GET method. All other methods are |
1570 |
optional; however, if the above methods are implemented, they must |
1571 |
be implemented with the same semantics as those specified in |
1572 |
Section 8. |
1573 |
|
1574 |
5.1.2 Request-URI |
1575 |
|
1576 |
The Request-URI is a Uniform Resource Identifier (Section 3.2) and |
1577 |
identifies the resource upon which to apply the request. |
1578 |
|
1579 |
Request-URI = "*" | absoluteURI | abs_path |
1580 |
|
1581 |
The three options for Request-URI are dependent on the nature of |
1582 |
the request. The asterisk "*" means that the request does not apply |
1583 |
to a particular resource, but to the server itself, and is only |
1584 |
allowed when the Method used does not necessarily apply to a |
1585 |
resource. One example would be |
1586 |
|
1587 |
OPTIONS * HTTP/1.1 |
1588 |
|
1589 |
The absoluteURI form is only allowed when the request is being made |
1590 |
to a proxy. The proxy is requested to forward the request and |
1591 |
return the response. If the request is GET or HEAD and a prior |
1592 |
response is cached, the proxy may use the cached message if it |
1593 |
passes any restrictions in the Cache-Control and Expires header |
1594 |
fields. Note that the proxy may forward the request on to another |
1595 |
proxy or directly to the server specified by the absoluteURI. In |
1596 |
order to avoid request loops, a proxy must be able to recognize all |
1597 |
of its server names, including any aliases, local variations, and |
1598 |
the numeric IP address. An example Request-Line would be: |
1599 |
|
1600 |
GET http://www.w3.org/pub/WWW/TheProject.html HTTP/1.1 |
1601 |
|
1602 |
The most common form of Request-URI is that used to identify a |
1603 |
resource on an origin server or gateway. In this case, only the |
1604 |
absolute path of the URI is transmitted (see Section 3.2.1, |
1605 |
abs_path). For example, a client wishing to retrieve the resource |
1606 |
above directly from the origin server would create a TCP connection |
1607 |
to port 80 of the host "www.w3.org" and send the line: |
1608 |
|
1609 |
GET /pub/WWW/TheProject.html HTTP/1.1 |
1610 |
|
1611 |
followed by the remainder of the Full-Request. Note that the |
1612 |
absolute path cannot be empty; if none is present in the original |
1613 |
URI, it must be given as "/" (the server root). |
1614 |
|
1615 |
If a proxy receives a request without any path in the Request-URI |
1616 |
and the method used is capable of supporting the asterisk form of |
1617 |
request, then the last proxy on the request chain must forward the |
1618 |
request with "*" as the final Request-URI. For example, the request |
1619 |
|
1620 |
OPTIONS http://www.ics.uci.edu:8001 HTTP/1.1 |
1621 |
|
1622 |
would be forwarded by the proxy as |
1623 |
|
1624 |
OPTIONS * HTTP/1.1 |
1625 |
|
1626 |
after connecting to port 8001 of host "www.ics.uci.edu". |
1627 |
|
1628 |
The Request-URI is transmitted as an encoded string, where some |
1629 |
characters may be escaped using the "% hex hex" encoding defined by |
1630 |
RFC 1738 [4]. The origin server must decode the Request-URI in |
1631 |
order to properly interpret the request. |
1632 |
|
1633 |
5.2 Request Header Fields |
1634 |
|
1635 |
The request header fields allow the client to pass additional |
1636 |
information about the request, and about the client itself, to the |
1637 |
server. These fields act as request modifiers, with semantics |
1638 |
equivalent to the parameters on a programming language method |
1639 |
(procedure) invocation. |
1640 |
|
1641 |
Request-Header = Accept ; Section 10.1 |
1642 |
| Accept-Charset ; Section 10.2 |
1643 |
| Accept-Encoding ; Section 10.3 |
1644 |
| Accept-Language ; Section 10.4 |
1645 |
| Authorization ; Section 10.6 |
1646 |
| From ; Section 10.21 |
1647 |
| Host ; Section 10.22 |
1648 |
| If-Modified-Since ; Section 10.23 |
1649 |
| Proxy-Authorization ; Section 10.31 |
1650 |
| Range ; Section 10.33 |
1651 |
| Referer ; Section 10.34 |
1652 |
| Unless ; Section 10.40 |
1653 |
| User-Agent ; Section 10.43 |
1654 |
|
1655 |
Request-Header field names can be extended reliably only in |
1656 |
combination with a change in the protocol version. However, new or |
1657 |
experimental header fields may be given the semantics of request |
1658 |
header fields if all parties in the communication recognize them to |
1659 |
be request header fields. Unrecognized header fields are treated as |
1660 |
Entity-Header fields. |
1661 |
|
1662 |
6. Response |
1663 |
|
1664 |
After receiving and interpreting a request message, a server |
1665 |
responds in the form of an HTTP response message. |
1666 |
|
1667 |
Response = Simple-Response | Full-Response |
1668 |
|
1669 |
Simple-Response = [ Entity-Body ] |
1670 |
|
1671 |
Full-Response = Status-Line ; Section 6.1 |
1672 |
*( General-Header ; Section 4.3 |
1673 |
| Response-Header ; Section 6.2 |
1674 |
| Entity-Header ) ; Section 7.1 |
1675 |
CRLF |
1676 |
[ Entity-Body ] ; Section 7.2 |
1677 |
|
1678 |
A Simple-Response should only be sent in response to an HTTP/0.9 |
1679 |
Simple-Request or if the server only supports the more limited |
1680 |
HTTP/0.9 protocol. If a client sends an HTTP/1.1 Full-Request and |
1681 |
receives a response that does not begin with a Status-Line, it |
1682 |
should assume that the response is a Simple-Response and parse it |
1683 |
accordingly. Note that the Simple-Response consists only of the |
1684 |
entity body and is terminated by the server closing the connection. |
1685 |
|
1686 |
6.1 Status-Line |
1687 |
|
1688 |
The first line of a Full-Response message is the Status-Line, |
1689 |
consisting of the protocol version followed by a numeric status |
1690 |
code and its associated textual phrase, with each element separated |
1691 |
by SP characters. No CR or LF is allowed except in the final CRLF |
1692 |
sequence. |
1693 |
|
1694 |
Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF |
1695 |
|
1696 |
Since a status line always begins with the protocol version and |
1697 |
status code |
1698 |
|
1699 |
"HTTP/" 1*DIGIT "." 1*DIGIT SP 3DIGIT SP |
1700 |
|
1701 |
(e.g., "HTTP/1.1 200 "), the presence of that expression is |
1702 |
sufficient to differentiate a Full-Response from a Simple-Response. |
1703 |
Although the Simple-Response format may allow such an expression to |
1704 |
occur at the beginning of an entity body, and thus cause a |
1705 |
misinterpretation of the message if it was given in response to a |
1706 |
Full-Request, most HTTP/0.9 servers are limited to responses of |
1707 |
type "text/html" and therefore would never generate such a response. |
1708 |
|
1709 |
6.1.1 Status Code and Reason Phrase |
1710 |
|
1711 |
The Status-Code element is a 3-digit integer result code of the |
1712 |
attempt to understand and satisfy the request. The Reason-Phrase is |
1713 |
intended to give a short textual description of the Status-Code. |
1714 |
The Status-Code is intended for use by automata and the |
1715 |
Reason-Phrase is intended for the human user. The client is not |
1716 |
required to examine or display the Reason-Phrase. |
1717 |
|
1718 |
The first digit of the Status-Code defines the class of response. |
1719 |
The last two digits do not have any categorization role. There are |
1720 |
5 values for the first digit: |
1721 |
|
1722 |
o 1xx: Informational - Request received, continuing process |
1723 |
|
1724 |
o 2xx: Success - The action was successfully received, |
1725 |
understood, and accepted |
1726 |
|
1727 |
o 3xx: Redirection - Further action must be taken in order to |
1728 |
complete the request |
1729 |
|
1730 |
o 4xx: Client Error - The request contains bad syntax or cannot |
1731 |
be fulfilled |
1732 |
|
1733 |
o 5xx: Server Error - The server failed to fulfill an apparently |
1734 |
valid request |
1735 |
|
1736 |
The individual values of the numeric status codes defined for |
1737 |
HTTP/1.1, and an example set of corresponding Reason-Phrase's, are |
1738 |
presented below. The reason phrases listed here are only |
1739 |
recommended -- they may be replaced by local equivalents without |
1740 |
affecting the protocol. These codes are fully defined in Section 9. |
1741 |
|
1742 |
Status-Code = "100" ; Continue |
1743 |
| "101" ; Switching Protocols |
1744 |
| "200" ; OK |
1745 |
| "201" ; Created |
1746 |
| "202" ; Accepted |
1747 |
| "203" ; Non-Authoritative Information |
1748 |
| "204" ; No Content |
1749 |
| "205" ; Reset Content |
1750 |
| "206" ; Partial Content |
1751 |
| "300" ; Multiple Choices |
1752 |
| "301" ; Moved Permanently |
1753 |
| "302" ; Moved Temporarily |
1754 |
| "303" ; See Other |
1755 |
| "304" ; Not Modified |
1756 |
| "305" ; Use Proxy |
1757 |
| "400" ; Bad Request |
1758 |
| "401" ; Unauthorized |
1759 |
| "402" ; Payment Required |
1760 |
| "403" ; Forbidden |
1761 |
| "404" ; Not Found |
1762 |
| "405" ; Method Not Allowed |
1763 |
| "406" ; None Acceptable |
1764 |
| "407" ; Proxy Authentication Required |
1765 |
| "408" ; Request Timeout |
1766 |
| "409" ; Conflict |
1767 |
| "410" ; Gone |
1768 |
| "411" ; Length Required |
1769 |
| "412" ; Unless True |
1770 |
| "500" ; Internal Server Error |
1771 |
| "501" ; Not Implemented |
1772 |
| "502" ; Bad Gateway |
1773 |
| "503" ; Service Unavailable |
1774 |
| "504" ; Gateway Timeout |
1775 |
| extension-code |
1776 |
|
1777 |
extension-code = 3DIGIT |
1778 |
|
1779 |
Reason-Phrase = *<TEXT, excluding CR, LF> |
1780 |
|
1781 |
HTTP status codes are extensible. HTTP applications are not |
1782 |
required to understand the meaning of all registered status codes, |
1783 |
though such understanding is obviously desirable. However, |
1784 |
applications must understand the class of any status code, as |
1785 |
indicated by the first digit, and treat any unrecognized response |
1786 |
as being equivalent to the x00 status code of that class, with the |
1787 |
exception that an unrecognized response must not be cached. For |
1788 |
example, if an unrecognized status code of 431 is received by the |
1789 |
client, it can safely assume that there was something wrong with |
1790 |
its request and treat the response as if it had received a 400 |
1791 |
status code. In such cases, user agents should present to the user |
1792 |
the entity returned with the response, since that entity is likely |
1793 |
to include human-readable information which will explain the |
1794 |
unusual status. |
1795 |
|
1796 |
6.2 Response Header Fields |
1797 |
|
1798 |
The response header fields allow the server to pass additional |
1799 |
information about the response which cannot be placed in the |
1800 |
Status-Line. These header fields are not intended to give |
1801 |
information about an Entity-Body returned in the response, but |
1802 |
about access to the resource or the server itself. |
1803 |
|
1804 |
Response-Header= Location ; Section 10.27 |
1805 |
| Proxy-Authenticate ; Section 10.30 |
1806 |
| Public ; Section 10.32 |
1807 |
| Retry-After ; Section 10.36 |
1808 |
| Server ; Section 10.37 |
1809 |
| WWW-Authenticate ; Section 10.44 |
1810 |
|
1811 |
Response-Header field names can be extended reliably only in |
1812 |
combination with a change in the protocol version. However, new or |
1813 |
experimental header fields may be given the semantics of response |
1814 |
header fields if all parties in the communication recognize them to |
1815 |
be response header fields. Unrecognized header fields are treated |
1816 |
as Entity-Header fields. |
1817 |
|
1818 |
7. Entity |
1819 |
|
1820 |
Full-Request and Full-Response messages may transfer an entity |
1821 |
within some requests and responses. An entity consists of |
1822 |
Entity-Header fields and (usually) an Entity-Body. In this section, |
1823 |
both sender and recipient refer to either the client or the server, |
1824 |
depending on who sends and who receives the entity. |
1825 |
|
1826 |
7.1 Entity Header Fields |
1827 |
|
1828 |
Entity-Header fields define optional metainformation about the |
1829 |
Entity-Body or, if no body is present, about the resource |
1830 |
identified by the request. |
1831 |
|
1832 |
Entity-Header = Allow ; Section 10.5 |
1833 |
| Content-Encoding ; Section 10.10 |
1834 |
| Content-Language ; Section 10.11 |
1835 |
| Content-Length ; Section 10.12 |
1836 |
| Content-MD5 ; Section 10.13 |
1837 |
| Content-Range ; Section 10.14 |
1838 |
| Content-Type ; Section 10.15 |
1839 |
| Content-Version ; Section 10.16 |
1840 |
| Derived-From ; Section 10.18 |
1841 |
| Expires ; Section 10.19 |
1842 |
| Last-Modified ; Section 10.25 |
1843 |
| Link ; Section 10.26 |
1844 |
| Title ; Section 10.38 |
1845 |
| Transfer-Encoding ; Section 10.39 |
1846 |
| URI-header ; Section 10.42 |
1847 |
| extension-header |
1848 |
|
1849 |
extension-header=HTTP-header |
1850 |
|
1851 |
The extension-header mechanism allows additional Entity-Header |
1852 |
fields to be defined without changing the protocol, but these |
1853 |
fields cannot be assumed to be recognizable by the recipient. |
1854 |
Unrecognized header fields should be ignored by the recipient and |
1855 |
forwarded by proxies. |
1856 |
|
1857 |
7.2 Entity Body |
1858 |
|
1859 |
The entity body (if any) sent with an HTTP request or response is |
1860 |
in a format and encoding defined by the Entity-Header fields. |
1861 |
|
1862 |
Entity-Body = *OCTET |
1863 |
|
1864 |
An entity body is included with a request message only when the |
1865 |
request method calls for one. The presence of an entity body in a |
1866 |
request is signaled by the inclusion of a Content-Length and/or |
1867 |
Content-Type header field in the request message headers. |
1868 |
|
1869 |
For response messages, whether or not an entity body is included |
1870 |
with a message is dependent on both the request method and the |
1871 |
response code. All responses to the HEAD request method must not |
1872 |
include a body, even though the presence of entity header fields |
1873 |
may lead one to believe they do. All 1xx (informational), 204 (no |
1874 |
content), and 304 (not modified) responses must not include a body. |
1875 |
All other responses must include an entity body or a Content-Length |
1876 |
header field defined with a value of zero (0). |
1877 |
|
1878 |
7.2.1 Type |
1879 |
|
1880 |
When an entity body is included with a message, the data type of |
1881 |
that body is determined via the header fields Content-Type, |
1882 |
Content-Encoding, and Transfer-Encoding. These define a |
1883 |
three-layer, ordered encoding model: |
1884 |
|
1885 |
entity-body := |
1886 |
Transfer-Encoding( Content-Encoding( Content-Type( data ) ) ) |
1887 |
|
1888 |
The default for both encodings is none (i.e., the identity |
1889 |
function). Content-Type specifies the media type of the underlying |
1890 |
data. Content-Encoding may be used to indicate any additional |
1891 |
content codings applied to the type, usually for the purpose of |
1892 |
data compression, that are a property of the resource requested. |
1893 |
Transfer-Encoding may be used to indicate any additional transfer |
1894 |
codings applied by an application to ensure safe and proper |
1895 |
transfer of the message. Note that Transfer-Encoding is a property |
1896 |
of the message, not of the resource. |
1897 |
|
1898 |
Any HTTP/1.1 message containing an entity body should include a |
1899 |
Content-Type header field defining the media type of that body. If |
1900 |
and only if the media type is not given by a Content-Type header, |
1901 |
as is the case for Simple-Response messages, the recipient may |
1902 |
attempt to guess the media type via inspection of its content |
1903 |
and/or the name extension(s) of the URL used to identify the |
1904 |
resource. If the media type remains unknown, the recipient should |
1905 |
treat it as type "application/octet-stream". |
1906 |
|
1907 |
7.2.2 Length |
1908 |
|
1909 |
When an entity body is included with a message, the length of that |
1910 |
body may be determined in one of several ways. If a Content-Length |
1911 |
header field is present, its value in bytes represents the length |
1912 |
of the entity body. Otherwise, the body length is determined by the |
1913 |
Transfer-Encoding (if the "chunked" transfer coding has been |
1914 |
applied), by the Content-Type (for multipart types with an explicit |
1915 |
end-of-body delimiter), or by the server closing the connection. |
1916 |
|
1917 |
Note: Any response message which must not include an entity |
1918 |
body (such as the 1xx, 204, and 304 responses and any |
1919 |
response to a HEAD request) is always terminated by the |
1920 |
first empty line after the header fields, regardless of the |
1921 |
entity header fields present in the message. |
1922 |
|
1923 |
Closing the connection cannot be used to indicate the end of a |
1924 |
request body, since it leaves no possibility for the server to send |
1925 |
back a response. For compatibility with HTTP/1.0 applications, |
1926 |
HTTP/1.1 requests containing an entity body must include a valid |
1927 |
Content-Length header field unless the server is known to be |
1928 |
HTTP/1.1 compliant. HTTP/1.1 servers must accept the "chunked" |
1929 |
transfer coding (Section 3.6) and multipart media types |
1930 |
(Section 3.7.2), thus allowing either mechanism to be used for a |
1931 |
request when Content-Length is unknown. |
1932 |
|
1933 |
If a request contains an entity body and Content-Length is not |
1934 |
specified, the server should respond with 400 (bad request) if it |
1935 |
cannot determine the length of the request message's content, or |
1936 |
with 411 (length required) if it wishes to insist on receiving a |
1937 |
valid Content-Length. |
1938 |
|
1939 |
Messages must not include both a Content-Length header field and |
1940 |
the "chunked" transfer coding. If both are received, the |
1941 |
Content-Length must be ignored. |
1942 |
|
1943 |
When a Content-Length is given in a message where an entity body is |
1944 |
allowed, its field value must exactly match the number of OCTETs in |
1945 |
the entity body. HTTP/1.1 user agents must notify the user when an |
1946 |
invalid length is received and detected. |
1947 |
|
1948 |
8. Method Definitions |
1949 |
|
1950 |
The set of common methods for HTTP/1.1 is defined below. Although |
1951 |
this set can be expanded, additional methods cannot be assumed to |
1952 |
share the same semantics for separately extended clients and |
1953 |
servers. |
1954 |
|
1955 |
The semantics of all methods may be affected by the presence of an |
1956 |
Unless request header field, as described in Section 10.40. |
1957 |
|
1958 |
8.1 OPTIONS |
1959 |
|
1960 |
The OPTIONS method represents a request for information about the |
1961 |
communication options available on the request/response chain |
1962 |
identified by the Request-URI. This method allows the client to |
1963 |
determine the options and/or requirements associated with a |
1964 |
resource, or the capabilities of a server, without implying a |
1965 |
resource action or initiating a resource retrieval. |
1966 |
|
1967 |
Unless the server's response is an error, the response must not |
1968 |
include entity information other than what can be considered as |
1969 |
communication options (e.g., Allow is appropriate, but Content-Type |
1970 |
is not) and must include a Content-Length with a value of zero (0). |
1971 |
Responses to this method are not cachable. |
1972 |
|
1973 |
If the Request-URI is an asterisk ("*"), the OPTIONS request is |
1974 |
intended to apply to the server as a whole. A 200 response should |
1975 |
include any header fields which indicate optional features |
1976 |
implemented by the server (e.g., Public), including any extensions |
1977 |
not defined by this specification, in addition to any applicable |
1978 |
general or response header fields. As described in Section 5.1.2, |
1979 |
an "OPTIONS *" request can be applied through a proxy by specifying |
1980 |
the destination server in the Request-URI without any path |
1981 |
information. |
1982 |
|
1983 |
If the Request-URI is not an asterisk, the OPTIONS request applies |
1984 |
only to the options that are available when communicating with that |
1985 |
resource. A 200 response should include any header fields which |
1986 |
indicate optional features implemented by the server and applicable |
1987 |
to that resource (e.g., Allow), including any extensions not |
1988 |
defined by this specification, in addition to any applicable |
1989 |
general or response header fields. If the OPTIONS request passes |
1990 |
through a proxy, the proxy must edit the response to exclude those |
1991 |
options known to be unavailable through that proxy. |
1992 |
|
1993 |
8.2 GET |
1994 |
|
1995 |
The GET method means retrieve whatever information (in the form of |
1996 |
an entity) is identified by the Request-URI. If the Request-URI |
1997 |
refers to a data-producing process, it is the produced data which |
1998 |
shall be returned as the entity in the response and not the source |
1999 |
text of the process, unless that text happens to be the output of |
2000 |
the process. |
2001 |
|
2002 |
The semantics of the GET method change to a "conditional GET" if |
2003 |
the request message includes an If-Modified-Since header field. A |
2004 |
conditional GET method requests that the identified resource be |
2005 |
transferred only if it has been modified since the date given by |
2006 |
the If-Modified-Since header, as described in Section 10.23. The |
2007 |
conditional GET method is intended to reduce unnecessary network |
2008 |
usage by allowing cached entities to be refreshed without requiring |
2009 |
multiple requests or transferring data already held by the client. |
2010 |
|
2011 |
The semantics of the GET method change to a "partial GET" if the |
2012 |
request message includes a Range header field. A partial GET |
2013 |
requests that only part of the identified resource be transferred, |
2014 |
as described in Section 10.33. The partial GET method is intended |
2015 |
to reduce unnecessary network usage by allowing partially-retrieved |
2016 |
entities to be completed without transferring data already held by |
2017 |
the client. |
2018 |
|
2019 |
The response to a GET request may be cachable if and only if it |
2020 |
meets the requirements for HTTP caching described in Section 13. |
2021 |
|
2022 |
8.3 HEAD |
2023 |
|
2024 |
The HEAD method is identical to GET except that the server must not |
2025 |
return any Entity-Body in the response. The metainformation |
2026 |
contained in the HTTP headers in response to a HEAD request should |
2027 |
be identical to the information sent in response to a GET request. |
2028 |
This method can be used for obtaining metainformation about the |
2029 |
resource identified by the Request-URI without transferring the |
2030 |
Entity-Body itself. This method is often used for testing hypertext |
2031 |
links for validity, accessibility, and recent modification. |
2032 |
|
2033 |
The response to a HEAD request may be cachable in the sense that |
2034 |
the information contained in the response may be used to update a |
2035 |
previously cached entity from that resource. If the new field |
2036 |
values indicate that the cached entity differs from the current |
2037 |
resource (as would be indicated by a change in Content-Length, |
2038 |
Content-MD5, or Content-Version), then the cache must discard the |
2039 |
cached entity. |
2040 |
|
2041 |
There is no "conditional HEAD" or "partial HEAD" request analogous |
2042 |
to those associated with the GET method. If an If-Modified-Since |
2043 |
and/or Range header field is included with a HEAD request, they |
2044 |
should be ignored. |
2045 |
|
2046 |
8.4 POST |
2047 |
|
2048 |
The POST method is used to request that the destination server |
2049 |
accept the entity enclosed in the request as a new subordinate of |
2050 |
the resource identified by the Request-URI in the Request-Line. |
2051 |
POST is designed to allow a uniform method to cover the following |
2052 |
functions: |
2053 |
|
2054 |
o Annotation of existing resources; |
2055 |
|
2056 |
o Posting a message to a bulletin board, newsgroup, mailing list, |
2057 |
or similar group of articles; |
2058 |
|
2059 |
o Providing a block of data, such as the result of submitting a |
2060 |
form [5], to a data-handling process; |
2061 |
|
2062 |
o Extending a database through an append operation. |
2063 |
|
2064 |
The actual function performed by the POST method is determined by |
2065 |
the server and is usually dependent on the Request-URI. The posted |
2066 |
entity is subordinate to that URI in the same way that a file is |
2067 |
subordinate to a directory containing it, a news article is |
2068 |
subordinate to a newsgroup to which it is posted, or a record is |
2069 |
subordinate to a database. |
2070 |
|
2071 |
HTTP/1.1 allows for a two-phase process to occur in accepting and |
2072 |
processing a POST request. If the media type of the posted entity |
2073 |
is not "application/x-www-form-urlencoded" [5], an HTTP/1.1 client |
2074 |
must pause between sending the message header fields (including the |
2075 |
empty line signifying the end of the headers) and sending the |
2076 |
message body; the duration of the pause is five (5) seconds or |
2077 |
until a response is received from the server, whichever is shorter. |
2078 |
If no response is received during the pause period, or if the |
2079 |
initial response is 100 (continue), the client may continue sending |
2080 |
the POST request. If the response indicates an error, the client |
2081 |
must discontinue the request and close the connection with the |
2082 |
server after reading the response. |
2083 |
|
2084 |
Upon receipt of a POST request, the server must examine the header |
2085 |
fields and determine whether or not the client should continue its |
2086 |
request. If any of the header fields indicate the request is |
2087 |
insufficient or unacceptable to the server (i.e., will result in a |
2088 |
4xx or 5xx response), or if the server can determine the response |
2089 |
without reading the entity body (e.g., a 301 or 302 response due to |
2090 |
an old Request-URI), the server must send that response immediately |
2091 |
upon its determination. If, on the other hand, the request appears |
2092 |
(at least initially) to be acceptable and the client has indicated |
2093 |
HTTP/1.1 compliance, the server must transmit an interim 100 |
2094 |
response message after receiving the empty line terminating the |
2095 |
request headers and continue processing the request. After |
2096 |
processing has finished, a final response message must be sent to |
2097 |
indicate the actual result of the request. A 100 response should |
2098 |
not be sent in response to an HTTP/1.0 request except under |
2099 |
experimental conditions, since an HTTP/1.0 client may mistake the |
2100 |
100 response for the final response. |
2101 |
|
2102 |
For compatibility with HTTP/1.0 applications, all POST requests |
2103 |
must include a valid Content-Length header field unless the server |
2104 |
is known to be HTTP/1.1 compliant. When sending a POST request to |
2105 |
an HTTP/1.1 server, a client must use at least one of: a valid |
2106 |
Content-Length, a multipart Content-Type, or the "chunked" |
2107 |
Transfer-Encoding. The server should respond with a 400 (bad |
2108 |
request) message if it cannot determine the length of the request |
2109 |
message's content, or with 411 (length required) if it wishes to |
2110 |
insist on receiving a valid Content-Length. |
2111 |
|
2112 |
The client can suggest one or more URIs for the new resource by |
2113 |
including a URI header field in the request. However, the server |
2114 |
should treat those URIs as advisory and may store the entity under |
2115 |
a different URI, additional URIs, or without any URI. |
2116 |
|
2117 |
The client may apply relationships between the new resource and |
2118 |
other existing resources by including Link header fields, as |
2119 |
described in Section 10.26. The server may use the Link information |
2120 |
to perform other operations as a result of the new resource being |
2121 |
added. For example, lists and indexes might be updated. However, no |
2122 |
mandatory operation is imposed on the origin server. The origin |
2123 |
server may also generate its own or additional links to other |
2124 |
resources. |
2125 |
|
2126 |
A successful POST does not require that the entity be created as a |
2127 |
resource on the origin server or made accessible for future |
2128 |
reference. That is, the action performed by the POST method might |
2129 |
not result in a resource that can be identified by a URI. In this |
2130 |
case, either 200 (ok) or 204 (no content) is the appropriate |
2131 |
response status, depending on whether or not the response includes |
2132 |
an entity that describes the result. |
2133 |
|
2134 |
If a resource has been created on the origin server, the response |
2135 |
should be 201 (created) and contain an entity (preferably of type |
2136 |
"text/html") which describes the status of the request and refers |
2137 |
to the new resource. |
2138 |
|
2139 |
Responses to this method are not cachable. However, the 303 (see |
2140 |
other) response can be used to direct the user agent to retrieve a |
2141 |
cachable resource. |
2142 |
|
2143 |
8.5 PUT |
2144 |
|
2145 |
The PUT method requests that the enclosed entity be stored under |
2146 |
the supplied Request-URI. If the Request-URI refers to an already |
2147 |
existing resource, the enclosed entity should be considered as a |
2148 |
modified version of the one residing on the origin server. If the |
2149 |
Request-URI does not point to an existing resource, and that URI is |
2150 |
capable of being defined as a new resource by the requesting user |
2151 |
agent, the origin server can create the resource with that URI. If |
2152 |
a new resource is created, the origin server must inform the user |
2153 |
agent via the 201 (created) response. If an existing resource is |
2154 |
modified, either the 200 (ok) or 204 (no content) response codes |
2155 |
should be sent to indicate successful completion of the request. If |
2156 |
the resource could not be created or modified with the Request-URI, |
2157 |
an appropriate error response should be given that reflects the |
2158 |
nature of the problem. |
2159 |
|
2160 |
If the request passes through a cache and the Request-URI |
2161 |
identifies a currently cached entity, that entity must be removed |
2162 |
from the cache. Responses to this method are not cachable. |
2163 |
|
2164 |
The fundamental difference between the POST and PUT requests is |
2165 |
reflected in the different meaning of the Request-URI. The URI in a |
2166 |
POST request identifies the resource that will handle the enclosed |
2167 |
entity as an appendage. That resource may be a data-accepting |
2168 |
process, a gateway to some other protocol, or a separate entity |
2169 |
that accepts annotations. In contrast, the URI in a PUT request |
2170 |
identifies the entity enclosed with the request -- the user agent |
2171 |
knows what URI is intended and the server must not attempt to apply |
2172 |
the request to some other resource. If the server desires that the |
2173 |
request be applied to a different URI, it must send a 301 (moved |
2174 |
permanently) response; the user agent may then make its own |
2175 |
decision regarding whether or not to redirect the request. |
2176 |
|
2177 |
A single resource may be identified by many different URIs. For |
2178 |
example, an article may have a URI for identifying "the current |
2179 |
version" which is separate from the URI identifying each particular |
2180 |
version. In this case, a PUT request on a general URI may result in |
2181 |
several other URIs being defined by the origin server. The user |
2182 |
agent should be informed of these URIs via one or more URI header |
2183 |
fields in the response. |
2184 |
|
2185 |
HTTP/1.1 allows for a two-phase process to occur in accepting and |
2186 |
processing a PUT request. An HTTP/1.1 client must pause between |
2187 |
sending the message header fields (including the empty line |
2188 |
signifying the end of the headers) and sending the message body; |
2189 |
the duration of the pause is five (5) seconds or until a response |
2190 |
is received from the server, whichever is shorter. If no response |
2191 |
is received during the pause period, or if the initial response is |
2192 |
100 (continue), the client may continue sending the PUT request. If |
2193 |
the response indicates an error, the client must discontinue the |
2194 |
request and close the connection with the server after reading the |
2195 |
response. |
2196 |
|
2197 |
Upon receipt of a PUT request, the server must examine the header |
2198 |
fields and determine whether or not the client should continue its |
2199 |
request. If any of the header fields indicate the request is |
2200 |
insufficient or unacceptable to the server (i.e., will result in a |
2201 |
4xx or 5xx response), or if the server can determine the response |
2202 |
without reading the entity body (e.g., a 301 or 302 response due to |
2203 |
an old Request-URI), the server must send that response immediately |
2204 |
upon its determination. If, on the other hand, the request appears |
2205 |
(at least initially) to be acceptable and the client has indicated |
2206 |
HTTP/1.1 compliance, the server must transmit an interim 100 |
2207 |
response message after receiving the empty line terminating the |
2208 |
request headers and continue processing the request. After |
2209 |
processing has finished, a final response message must be sent to |
2210 |
indicate the actual result of the request. A 100 response should |
2211 |
not be sent in response to an HTTP/1.0 request except under |
2212 |
experimental conditions, since an HTTP/1.0 client may mistake the |
2213 |
100 response for the final response. |
2214 |
|
2215 |
For compatibility with HTTP/1.0 applications, all PUT requests must |
2216 |
include a valid Content-Length header field unless the server is |
2217 |
known to be HTTP/1.1 compliant. When sending a PUT request to an |
2218 |
HTTP/1.1 server, a client must use at least one of: a valid |
2219 |
Content-Length, a multipart Content-Type, or the "chunked" |
2220 |
Transfer-Encoding. The server should respond with a 400 (bad |
2221 |
request) message if it cannot determine the length of the request |
2222 |
message's content, or with 411 (length required) if it wishes to |
2223 |
insist on receiving a valid Content-Length. |
2224 |
|
2225 |
The client can create or modify relationships between the enclosed |
2226 |
entity and other existing resources by including Link header |
2227 |
fields, as described in Section 10.26. As with POST, the server may |
2228 |
use the Link information to perform other operations as a result of |
2229 |
the request. However, no mandatory operation is imposed on the |
2230 |
origin server. The origin server may generate its own or additional |
2231 |
links to other resources. |
2232 |
|
2233 |
The actual method for determining how the resource is placed, and |
2234 |
what happens to its predecessor, is defined entirely by the origin |
2235 |
server. If version control is implemented by the origin server, |
2236 |
then Link relationships should be defined by the server to help |
2237 |
identify and control revisions to a resource. If the entity being |
2238 |
PUT was derived from an existing resource which included a |
2239 |
Content-Version header field, the new entity must include a |
2240 |
Derived-From header field corresponding to the value of the |
2241 |
original Content-Version header field. Multiple Derived-From values |
2242 |
may be included if the entity was derived from multiple resources |
2243 |
with Content-Version information. Applications are encouraged to |
2244 |
use these fields for constructing versioning relationships and |
2245 |
resolving version conflicts. |
2246 |
|
2247 |
8.6 PATCH |
2248 |
|
2249 |
The PATCH method is similar to PUT except that the entity contains |
2250 |
a list of differences between the original version of the resource |
2251 |
identified by the Request-URI and the desired content of the |
2252 |
resource after the PATCH action has been applied. The list of |
2253 |
differences is in a format defined by the media type of the entity |
2254 |
(e.g., "application/diff") and must include sufficient information |
2255 |
to allow the server to recreate the changes necessary to convert |
2256 |
the original version of the resource to the desired version. |
2257 |
|
2258 |
If the request passes through a cache and the Request-URI |
2259 |
identifies a currently cached entity, that entity must be removed |
2260 |
from the cache. Responses to this method are not cachable. |
2261 |
|
2262 |
HTTP/1.1 allows for a two-phase process to occur in accepting and |
2263 |
processing a PATCH request. An HTTP/1.1 client must pause between |
2264 |
sending the message header fields (including the empty line |
2265 |
signifying the end of the headers) and sending the message body; |
2266 |
the duration of the pause is five (5) seconds or until a response |
2267 |
is received from the server, whichever is shorter. If no response |
2268 |
is received during the pause period, or if the initial response is |
2269 |
100 (continue), the client may continue sending the PATCH request. |
2270 |
If the response indicates an error, the client must discontinue the |
2271 |
request and close the connection with the server after reading the |
2272 |
response. |
2273 |
|
2274 |
Upon receipt of a PATCH request, the server must examine the header |
2275 |
fields and determine whether or not the client should continue its |
2276 |
request. If any of the header fields indicate the request is |
2277 |
insufficient or unacceptable to the server (i.e., will result in a |
2278 |
4xx or 5xx response), or if the server can determine the response |
2279 |
without reading the entity body (e.g., a 301 or 302 response due to |
2280 |
an old Request-URI), the server must send that response immediately |
2281 |
upon its determination. If, on the other hand, the request appears |
2282 |
(at least initially) to be acceptable and the client has indicated |
2283 |
HTTP/1.1 compliance, the server must transmit an interim 100 |
2284 |
response message after receiving the empty line terminating the |
2285 |
request headers and continue processing the request. After |
2286 |
processing has finished, a final response message must be sent to |
2287 |
indicate the actual result of the request. A 100 response should |
2288 |
not be sent in response to an HTTP/1.0 request except under |
2289 |
experimental conditions, since an HTTP/1.0 client may mistake the |
2290 |
100 response for the final response. |
2291 |
|
2292 |
For compatibility with HTTP/1.0 applications, all PATCH requests |
2293 |
must include a valid Content-Length header field unless the server |
2294 |
is known to be HTTP/1.1 compliant. When sending a PATCH request to |
2295 |
an HTTP/1.1 server, a client must use at least one of: a valid |
2296 |
Content-Length, a multipart Content-Type, or the "chunked" |
2297 |
Transfer-Encoding. The server should respond with a 400 (bad |
2298 |
request) message if it cannot determine the length of the request |
2299 |
message's content, or with 411 (length required) if it wishes to |
2300 |
insist on receiving a valid Content-Length. |
2301 |
|
2302 |
The client can create or modify relationships between the new |
2303 |
resource and other existing resources by including Link header |
2304 |
fields, as described in Section 10.26. As with POST, the server may |
2305 |
use the Link information to perform other operations as a result of |
2306 |
the request. However, no mandatory operation is imposed on the |
2307 |
origin server. The origin server may generate its own or additional |
2308 |
links to other resources. |
2309 |
|
2310 |
The actual method for determining how the patched resource is |
2311 |
placed, and what happens to its predecessor, is defined entirely by |
2312 |
the origin server. If version control is implemented by the origin |
2313 |
server, then Link relationships should be defined by the server to |
2314 |
help identify and control revisions to a resource. If the original |
2315 |
version of the resource being patched included a Content-Version |
2316 |
header field, the request entity must include a Derived-From header |
2317 |
field corresponding to the value of the original Content-Version |
2318 |
header field. Applications are encouraged to use these fields for |
2319 |
constructing versioning relationships and resolving version |
2320 |
conflicts. |
2321 |
|
2322 |
8.7 COPY |
2323 |
|
2324 |
The COPY method requests that the resource identified by the |
2325 |
Request-URI be copied to the location(s) given in the URI header |
2326 |
field of the request. Responses to this method are not cachable. |
2327 |
|
2328 |
8.8 MOVE |
2329 |
|
2330 |
The MOVE method requests that the resource identified by the |
2331 |
Request-URI be moved to the location(s) given in the URI header |
2332 |
field of the request. This method is equivalent to a COPY |
2333 |
immediately followed by a DELETE, but enables both to occur within |
2334 |
a single transaction. |
2335 |
|
2336 |
If the request passes through a cache and the Request-URI |
2337 |
identifies a currently cached entity, that entity must be removed |
2338 |
from the cache. Responses to this method are not cachable. |
2339 |
|
2340 |
8.9 DELETE |
2341 |
|
2342 |
The DELETE method requests that the origin server delete the |
2343 |
resource identified by the Request-URI. This method may be |
2344 |
overridden by human intervention (or other means) on the origin |
2345 |
server. The client cannot be guaranteed that the operation has been |
2346 |
carried out, even if the status code returned from the origin |
2347 |
server indicates that the action has been completed successfully. |
2348 |
However, the server should not indicate success unless, at the time |
2349 |
the response is given, it intends to delete the resource or move it |
2350 |
to an inaccessible location. |
2351 |
|
2352 |
A successful response should be 200 (ok) if the response includes |
2353 |
an entity describing the status, 202 (accepted) if the action has |
2354 |
not yet been enacted, or 204 (no content) if the response is OK but |
2355 |
does not include an entity. |
2356 |
|
2357 |
If the request passes through a cache and the Request-URI |
2358 |
identifies a currently cached entity, that entity must be removed |
2359 |
from the cache. Responses to this method are not cachable. |
2360 |
|
2361 |
8.10 LINK |
2362 |
|
2363 |
The LINK method establishes one or more Link relationships between |
2364 |
the existing resource identified by the Request-URI and other |
2365 |
existing resources. The difference between LINK and other methods |
2366 |
allowing links to be established between resources is that the LINK |
2367 |
method does not allow any Entity-Body to be sent in the request and |
2368 |
does not directly result in the creation of new resources. |
2369 |
|
2370 |
If the request passes through a cache and the Request-URI |
2371 |
identifies a currently cached entity, that entity must be removed |
2372 |
from the cache. Responses to this method are not cachable. |
2373 |
|
2374 |
8.11 UNLINK |
2375 |
|
2376 |
The UNLINK method removes one or more Link relationships from the |
2377 |
existing resource identified by the Request-URI. These |
2378 |
relationships may have been established using the LINK method or by |
2379 |
any other method supporting the Link header. The removal of a link |
2380 |
to a resource does not imply that the resource ceases to exist or |
2381 |
becomes inaccessible for future references. |
2382 |
|
2383 |
If the request passes through a cache and the Request-URI |
2384 |
identifies a currently cached entity, that entity must be removed |
2385 |
from the cache. Responses to this method are not cachable. |
2386 |
|
2387 |
8.12 TRACE |
2388 |
|
2389 |
The TRACE method requests that the server identified by the |
2390 |
Request-URI reflect whatever is received back to the client as the |
2391 |
entity body of the response. In this way, the client can see what |
2392 |
is being received at the other end of the request chain, and may |
2393 |
use this data for testing or diagnostic information. |
2394 |
|
2395 |
If successful, the response should contain the entire, unedited |
2396 |
request message in the entity body, with a Content-Type of |
2397 |
"message/http", "application/http", or "text/plain". Responses to |
2398 |
this method are not cachable. |
2399 |
|
2400 |
8.13 WRAPPED |
2401 |
|
2402 |
The WRAPPED method allows a client to send one or more encapsulated |
2403 |
requests to the server identified by the Request-URI. This method |
2404 |
is intended to allow the request(s) to be wrapped together, |
2405 |
possibly encrypted in order to improve the security and/or privacy |
2406 |
of the request, and delivered for unwrapping by the destination |
2407 |
server. Upon receipt of the WRAPPED request, the destination server |
2408 |
must unwrap the message and feed it to the appropriate protocol |
2409 |
handler as if it were an incoming request stream. |
2410 |
|
2411 |
Responses to this method are not cachable. Applications should not |
2412 |
use this method for making requests that would normally be public |
2413 |
and cachable. |
2414 |
|
2415 |
The request entity must include at least one encapsulated message, |
2416 |
with the media type identifying the protocol of that message. For |
2417 |
example, if the wrapped request is another HTTP request message, |
2418 |
then the media type must be either "message/http" (for a single |
2419 |
message) or "application/http" (for a request stream containing one |
2420 |
or more requests), with any codings identied by the |
2421 |
Content-Encoding and Transfer-Encoding header fields. |
2422 |
|
2423 |
HTTP/1.1 allows for a two-phase process to occur in accepting and |
2424 |
processing a WRAPPED request. An HTTP/1.1 client must pause between |
2425 |
sending the message header fields (including the empty line |
2426 |
signifying the end of the headers) and sending the message body; |
2427 |
the duration of the pause is five (5) seconds or until a response |
2428 |
is received from the server, whichever is shorter. If no response |
2429 |
is received during the pause period, or if the initial response is |
2430 |
100 (continue), the client may continue sending the WRAPPED |
2431 |
request. If the response indicates an error, the client must |
2432 |
discontinue the request and close the connection with the server |
2433 |
after reading the response. |
2434 |
|
2435 |
Upon receipt of a WRAPPED request, the server must examine the |
2436 |
header fields and determine whether or not the client should |
2437 |
continue its request. If any of the header fields indicate the |
2438 |
request is insufficient or unacceptable to the server (i.e., will |
2439 |
result in a 4xx or 5xx response), or if the server can determine |
2440 |
the response without reading the entity body (e.g., a 301 or 302 |
2441 |
response due to an old Request-URI), the server must send that |
2442 |
response immediately upon its determination. If, on the other hand, |
2443 |
the request appears (at least initially) to be acceptable and the |
2444 |
client has indicated HTTP/1.1 compliance, the server must transmit |
2445 |
an interim 100 response message after receiving the empty line |
2446 |
terminating the request headers and continue processing the |
2447 |
request. After processing has finished, a final response message |
2448 |
must be sent to indicate the actual result of the request. A 100 |
2449 |
response should not be sent in response to an HTTP/1.0 request |
2450 |
except under experimental conditions, since an HTTP/1.0 client may |
2451 |
mistake the 100 response for the final response. |
2452 |
|
2453 |
For compatibility with HTTP/1.0 applications, all WRAPPED requests |
2454 |
must include a valid Content-Length header field unless the server |
2455 |
is known to be HTTP/1.1 compliant. When sending a WRAPPED request |
2456 |
to an HTTP/1.1 server, a client must use at least one of: a valid |
2457 |
Content-Length, a multipart Content-Type, or the "chunked" |
2458 |
Transfer-Encoding. The server should respond with a 400 (bad |
2459 |
request) message if it cannot determine the length of the request |
2460 |
message's content, or with 411 (length required) if it wishes to |
2461 |
insist on receiving a valid Content-Length. |
2462 |
|
2463 |
9. Status Code Definitions |
2464 |
|
2465 |
Each Status-Code is described below, including a description of |
2466 |
which method(s) it can follow and any metainformation required in |
2467 |
the response. |
2468 |
|
2469 |
9.1 Informational 1xx |
2470 |
|
2471 |
This class of status code indicates a provisional response, |
2472 |
consisting only of the Status-Line and optional headers, and is |
2473 |
terminated by an empty line. Since HTTP/1.0 did not define any 1xx |
2474 |
status codes, servers should not send a 1xx response to an HTTP/1.0 |
2475 |
client except under experimental conditions. |
2476 |
|
2477 |
100 Continue |
2478 |
|
2479 |
The client may continue with its request. This interim response is |
2480 |
used to inform the client that the initial part of the request has |
2481 |
been received and has not yet been rejected by the server. The |
2482 |
client should continue by sending the remainder of the request or, |
2483 |
if the request has already been completed, ignore this response. |
2484 |
The server must send a final response after the request has been |
2485 |
completed. |
2486 |
|
2487 |
101 Switching Protocols |
2488 |
|
2489 |
The server understands and is willing to comply with the client's |
2490 |
request, via the Upgrade message header field (Section 10.41), for |
2491 |
a change in the application protocol being used on this connection. |
2492 |
The server will switch protocols to those defined by the response's |
2493 |
Upgrade header field immediately after the empty line which |
2494 |
terminates the 101 response. |
2495 |
|
2496 |
The protocol should only be switched when it is advantageous to do |
2497 |
so. For example, switching to a newer version of HTTP is |
2498 |
advantageous over older versions, and switching to a real-time, |
2499 |
synchronous protocol may be advantageous when delivering resources |
2500 |
that use such features. |
2501 |
|
2502 |
9.2 Successful 2xx |
2503 |
|
2504 |
This class of status code indicates that the client's request was |
2505 |
successfully received, understood, and accepted. |
2506 |
|
2507 |
200 OK |
2508 |
|
2509 |
The request has succeeded. The information returned with the |
2510 |
response is dependent on the method used in the request, as follows: |
2511 |
|
2512 |
GET an entity corresponding to the requested resource is sent |
2513 |
in the response; |
2514 |
|
2515 |
HEAD the response must only contain the header information and |
2516 |
no Entity-Body; |
2517 |
|
2518 |
POST an entity describing or containing the result of the action; |
2519 |
|
2520 |
TRACE an entity containing the request message as received by the |
2521 |
end server; |
2522 |
|
2523 |
otherwise, an entity describing the result of the action; |
2524 |
|
2525 |
If the entity corresponds to a resource, the response may include a |
2526 |
Location header field giving the actual location of that specific |
2527 |
resource for later reference. |
2528 |
|
2529 |
201 Created |
2530 |
|
2531 |
The request has been fulfilled and resulted in a new resource being |
2532 |
created. The newly created resource can be referenced by the URI(s) |
2533 |
returned in the URI-header field and/or the entity of the response, |
2534 |
with the most specific URL for the resource given by a Location |
2535 |
header field. The origin server should create the resource before |
2536 |
using this Status-Code. If the action cannot be carried out |
2537 |
immediately, the server must include in the response body a |
2538 |
description of when the resource will be available; otherwise, the |
2539 |
server should respond with 202 (accepted). |
2540 |
|
2541 |
202 Accepted |
2542 |
|
2543 |
The request has been accepted for processing, but the processing |
2544 |
has not been completed. The request may or may not eventually be |
2545 |
acted upon, as it may be disallowed when processing actually takes |
2546 |
place. There is no facility for re-sending a status code from an |
2547 |
asynchronous operation such as this. |
2548 |
|
2549 |
The 202 response is intentionally non-committal. Its purpose is to |
2550 |
allow a server to accept a request for some other process (perhaps |
2551 |
a batch-oriented process that is only run once per day) without |
2552 |
requiring that the user agent's connection to the server persist |
2553 |
until the process is completed. The entity returned with this |
2554 |
response should include an indication of the request's current |
2555 |
status and either a pointer to a status monitor or some estimate of |
2556 |
when the user can expect the request to be fulfilled. |
2557 |
|
2558 |
203 Non-Authoritative Information |
2559 |
|
2560 |
The returned metainformation in the Entity-Header is not the |
2561 |
definitive set as available from the origin server, but is gathered |
2562 |
from a local or a third-party copy. The set presented may be a |
2563 |
subset or superset of the original version. For example, including |
2564 |
local annotation information about the resource may result in a |
2565 |
superset of the metainformation known by the origin server. Use of |
2566 |
this response code is not required and is only appropriate when the |
2567 |
response would otherwise be 200 (ok). |
2568 |
|
2569 |
204 No Content |
2570 |
|
2571 |
The server has fulfilled the request but there is no new |
2572 |
information to send back. If the client is a user agent, it should |
2573 |
not change its document view from that which caused the request to |
2574 |
be generated. This response is primarily intended to allow input |
2575 |
for actions to take place without causing a change to the user |
2576 |
agent's active document view. The response may include new |
2577 |
metainformation in the form of entity headers, which should apply |
2578 |
to the document currently in the user agent's active view. |
2579 |
|
2580 |
The 204 response must not include an entity body, and thus is |
2581 |
always ternminated by the first empty line after the header fields. |
2582 |
|
2583 |
205 Reset Content |
2584 |
|
2585 |
The server has fulfilled the request and the user agent should |
2586 |
reset the document view which caused the request to be generated. |
2587 |
This response is primarily intended to allow input for actions to |
2588 |
take place via user input, followed by a clearing of the form in |
2589 |
which the input is given so that the user can easily initiate |
2590 |
another input action. The response must include a Content-Length |
2591 |
with a value of zero (0) and no entity body. |
2592 |
|
2593 |
206 Partial Content |
2594 |
|
2595 |
The server has fulfilled the partial GET request for the resource. |
2596 |
The request must have included a Range header field (Section 10.33) |
2597 |
indicating the desired range. The response must include a |
2598 |
Content-Range header field (Section 10.14) indicating the range |
2599 |
included with this response. All entity header fields in the |
2600 |
response must describe the actual entity transmitted rather than |
2601 |
what would have been transmitted in a full response. In particular, |
2602 |
the Content-Length header field in the response must match the |
2603 |
actual number of OCTETs transmitted in the entity body. It is |
2604 |
assumed that the client already has the complete entity's header |
2605 |
field data. |
2606 |
|
2607 |
9.3 Redirection 3xx |
2608 |
|
2609 |
This class of status code indicates that further action needs to be |
2610 |
taken by the user agent in order to fulfill the request. The action |
2611 |
required may be carried out by the user agent without interaction |
2612 |
with the user if and only if the method used in the second request |
2613 |
is GET or HEAD. A user agent should never automatically redirect a |
2614 |
request more than 5 times, since such redirections usually indicate |
2615 |
an infinite loop. |
2616 |
|
2617 |
300 Multiple Choices |
2618 |
|
2619 |
The requested resource is available at one or more locations and a |
2620 |
preferred location could not be determined via preemptive content |
2621 |
negotiation (Section 12). Unless it was a HEAD request, the |
2622 |
response should include an entity containing a list of resource |
2623 |
characteristics and locations from which the user or user agent can |
2624 |
choose the one most appropriate. The entity format is specified by |
2625 |
the media type given in the Content-Type header field. Depending |
2626 |
upon the format and the capabilities of the user agent, selection |
2627 |
of the most appropriate choice may be performed automatically. If |
2628 |
the server has a preferred choice, it should include the URL in a |
2629 |
Location field; user agents not capable of complex selection may |
2630 |
use this field value for automatic redirection. This response is |
2631 |
cachable unless indicated otherwise. |
2632 |
|
2633 |
301 Moved Permanently |
2634 |
|
2635 |
The requested resource has been assigned a new permanent URI and |
2636 |
any future references to this resource should be done using one of |
2637 |
the returned URIs. Clients with link editing capabilities should |
2638 |
automatically relink references to the Request-URI to one or more |
2639 |
of the new references returned by the server, where possible. This |
2640 |
response is cachable unless indicated otherwise. |
2641 |
|
2642 |
If the new URI is a single location, its URL must be given by the |
2643 |
Location field in the response. If more than one URI exists for the |
2644 |
resource, the primary URL should be given in the Location field and |
2645 |
the other URIs given in one or more URI-header fields. Unless it |
2646 |
was a HEAD request, the Entity-Body of the response should contain |
2647 |
a short hypertext note with a hyperlink to the new URI(s). |
2648 |
|
2649 |
If the 301 status code is received in response to a request other |
2650 |
than GET or HEAD, the user agent must not automatically redirect |
2651 |
the request unless it can be confirmed by the user, since this |
2652 |
might change the conditions under which the request was issued. |
2653 |
|
2654 |
302 Moved Temporarily |
2655 |
|
2656 |
The requested resource resides temporarily under a different URI. |
2657 |
Since the redirection may be altered on occasion, the client should |
2658 |
continue to use the Request-URI for future requests. This response |
2659 |
is only cachable if indicated by a Cache-Control or Expires header |
2660 |
field. |
2661 |
|
2662 |
If the new URI is a single location, its URL must be given by the |
2663 |
Location field in the response. If more than one URI exists for the |
2664 |
resource, the primary URL should be given in the Location field and |
2665 |
the other URIs given in one or more URI-header fields. Unless it |
2666 |
was a HEAD request, the Entity-Body of the response should contain |
2667 |
a short hypertext note with a hyperlink to the new URI(s). |
2668 |
|
2669 |
If the 302 status code is received in response to a request other |
2670 |
than GET or HEAD, the user agent must not automatically redirect |
2671 |
the request unless it can be confirmed by the user, since this |
2672 |
might change the conditions under which the request was issued. |
2673 |
|
2674 |
303 See Other |
2675 |
|
2676 |
The response to the request can be found under a different URI and |
2677 |
should be retrieved using a GET method on that resource. This |
2678 |
method exists primarily to allow the output of a POST-activated |
2679 |
script to redirect the user agent to a selected resource. The new |
2680 |
resource is not a replacement reference for the original |
2681 |
Request-URI. The 303 response is not cachable, but the response to |
2682 |
the second request may be cachable. |
2683 |
|
2684 |
If the new URI is a single location, its URL must be given by the |
2685 |
Location field in the response. If more than one URI exists for the |
2686 |
resource, the primary URL should be given in the Location field and |
2687 |
the other URIs given in one or more URI-header fields. Unless it |
2688 |
was a HEAD request, the Entity-Body of the response should contain |
2689 |
a short hypertext note with a hyperlink to the new URI(s). |
2690 |
|
2691 |
304 Not Modified |
2692 |
|
2693 |
If the client has performed a conditional GET request and access is |
2694 |
allowed, but the document has not been modified since the date and |
2695 |
time specified in the If-Modified-Since field, the server must |
2696 |
respond with this status code and not send an Entity-Body to the |
2697 |
client. Header fields contained in the response should only include |
2698 |
information which is relevant to cache managers or which may have |
2699 |
changed independently of the entity's Last-Modified date. Examples |
2700 |
of relevant header fields include: Date, Server, Content-Length, |
2701 |
Content-MD5, Content-Version, Cache-Control and Expires. |
2702 |
|
2703 |
A cache should update its cached entity to reflect any new field |
2704 |
values given in the 304 response. If the new field values indicate |
2705 |
that the cached entity differs from the current resource (as would |
2706 |
be indicated by a change in Content-Length, Content-MD5, or |
2707 |
Content-Version), then the cache must disregard the 304 response |
2708 |
and repeat the request without an If-Modified-Since field. |
2709 |
|
2710 |
The 304 response must not include an entity body, and thus is |
2711 |
always ternminated by the first empty line after the header fields. |
2712 |
|
2713 |
305 Use Proxy |
2714 |
|
2715 |
The requested resource must be accessed through the proxy given by |
2716 |
the Location field in the response. In other words, this is a proxy |
2717 |
redirect. |
2718 |
|
2719 |
9.4 Client Error 4xx |
2720 |
|
2721 |
The 4xx class of status code is intended for cases in which the |
2722 |
client seems to have erred. If the client has not completed the |
2723 |
request when a 4xx code is received, it should immediately cease |
2724 |
sending data to the server. Except when responding to a HEAD |
2725 |
request, the server should include an entity containing an |
2726 |
explanation of the error situation, and whether it is a temporary |
2727 |
or permanent condition. These status codes are applicable to any |
2728 |
request method. |
2729 |
|
2730 |
Note: If the client is sending data, server implementations |
2731 |
on TCP should be careful to ensure that the client |
2732 |
acknowledges receipt of the packet(s) containing the |
2733 |
response prior to closing the input connection. If the |
2734 |
client continues sending data to the server after the close, |
2735 |
the server's controller will send a reset packet to the |
2736 |
client, which may erase the client's unacknowledged input |
2737 |
buffers before they can be read and interpreted by the HTTP |
2738 |
application. |
2739 |
|
2740 |
400 Bad Request |
2741 |
|
2742 |
The request could not be understood by the server due to malformed |
2743 |
syntax. The client should not repeat the request without |
2744 |
modifications. |
2745 |
|
2746 |
401 Unauthorized |
2747 |
|
2748 |
The request requires user authentication. The response must include |
2749 |
a WWW-Authenticate header field (Section 10.44) containing a |
2750 |
challenge applicable to the requested resource. The client may |
2751 |
repeat the request with a suitable Authorization header field |
2752 |
(Section 10.6). If the request already included Authorization |
2753 |
credentials, then the 401 response indicates that authorization has |
2754 |
been refused for those credentials. If the 401 response contains |
2755 |
the same challenge as the prior response, and the user agent has |
2756 |
already attempted authentication at least once, then the user |
2757 |
should be presented the entity that was given in the response, |
2758 |
since that entity may include relevant diagnostic information. HTTP |
2759 |
access authentication is explained in Section 11. |
2760 |
|
2761 |
402 Payment Required |
2762 |
|
2763 |
This code is reserved for future use. |
2764 |
|
2765 |
403 Forbidden |
2766 |
|
2767 |
The server understood the request, but is refusing to fulfill it. |
2768 |
Authorization will not help and the request should not be repeated. |
2769 |
If the request method was not HEAD and the server wishes to make |
2770 |
public why the request has not been fulfilled, it should describe |
2771 |
the reason for the refusal in the entity body. This status code is |
2772 |
commonly used when the server does not wish to reveal exactly why |
2773 |
the request has been refused, or when no other response is |
2774 |
applicable. |
2775 |
|
2776 |
404 Not Found |
2777 |
|
2778 |
The server has not found anything matching the Request-URI. No |
2779 |
indication is given of whether the condition is temporary or |
2780 |
permanent. If the server does not wish to make this information |
2781 |
available to the client, the status code 403 (forbidden) can be |
2782 |
used instead. The 410 (gone) status code should be used if the |
2783 |
server knows, through some internally configurable mechanism, that |
2784 |
an old resource is permanently unavailable and has no forwarding |
2785 |
address. |
2786 |
|
2787 |
405 Method Not Allowed |
2788 |
|
2789 |
The method specified in the Request-Line is not allowed for the |
2790 |
resource identified by the Request-URI. The response must include |
2791 |
an Allow header containing a list of valid methods for the |
2792 |
requested resource. |
2793 |
|
2794 |
406 None Acceptable |
2795 |
|
2796 |
The server has found a resource matching the Request-URI, but not |
2797 |
one that satisfies the conditions identified by the Accept and |
2798 |
Accept-Encoding request headers. Unless it was a HEAD request, the |
2799 |
response should include an entity containing a list of resource |
2800 |
characteristics and locations from which the user or user agent can |
2801 |
choose the one most appropriate. The entity format is specified by |
2802 |
the media type given in the Content-Type header field. Depending |
2803 |
upon the format and the capabilities of the user agent, selection |
2804 |
of the most appropriate choice may be performed automatically. |
2805 |
|
2806 |
407 Proxy Authentication Required |
2807 |
|
2808 |
This code is similar to 401 (unauthorized), but indicates that the |
2809 |
client must first authenticate itself with the proxy. The proxy |
2810 |
must return a Proxy-Authenticate header field (Section 10.30) |
2811 |
containing a challenge applicable to the proxy for the requested |
2812 |
resource. The client may repeat the request with a suitable |
2813 |
Proxy-Authorization header field (Section 10.31). HTTP access |
2814 |
authentication is explained in Section 11. |
2815 |
|
2816 |
408 Request Timeout |
2817 |
|
2818 |
The client did not produce a request within the time that the |
2819 |
server was prepared to wait. The client may repeat the request |
2820 |
without modifications at any later time. |
2821 |
|
2822 |
409 Conflict |
2823 |
|
2824 |
The request could not be completed due to a conflict with the |
2825 |
current state of the resource. This code is only allowed in |
2826 |
situations where it is expected that the user may be able to |
2827 |
resolve the conflict and resubmit the request. The response body |
2828 |
should include enough information for the user to recognize the |
2829 |
source of the conflict. Ideally, the response entity would include |
2830 |
enough information for the user or user-agent to fix the problem; |
2831 |
however, that may not be possible and is not required. |
2832 |
|
2833 |
Conflicts are most likely to occur in response to a PUT or PATCH |
2834 |
request. If versioning is being used and the entity being PUT or |
2835 |
PATCHed includes changes to a resource which conflict with those |
2836 |
made by an earlier (third-party) request, the server may use the |
2837 |
409 response to indicate that it can't complete the request. In |
2838 |
this case, the response entity should contain a list of the |
2839 |
differences between the two versions in a format defined by the |
2840 |
response Content-Type. |
2841 |
|
2842 |
410 Gone |
2843 |
|
2844 |
The requested resource is no longer available at the server and no |
2845 |
forwarding address is known. This condition should be considered |
2846 |
permanent. Clients with link editing capabilities should delete |
2847 |
references to the Request-URI after user approval. If the server |
2848 |
does not know, or has no facility to determine, whether or not the |
2849 |
condition is permanent, the status code 404 (not found) should be |
2850 |
used instead. This response is cachable unless indicated otherwise. |
2851 |
|
2852 |
The 410 response is primarily intended to assist the task of web |
2853 |
maintenance by notifying the recipient that the resource is |
2854 |
intentionally unavailable and that the server owners desire that |
2855 |
remote links to that resource be removed. Such an event is common |
2856 |
for limited-time, promotional services and for resources belonging |
2857 |
to individuals no longer working at the server's site. It is not |
2858 |
necessary to mark all permanently unavailable resources as "gone" |
2859 |
or to keep the mark for any length of time -- that is left to the |
2860 |
discretion of the server owner. |
2861 |
|
2862 |
411 Length Required |
2863 |
|
2864 |
The server refuses to accept the request without a defined |
2865 |
Content-Length. The client may repeat the request if it adds a |
2866 |
valid Content-Length header field containing the length of the |
2867 |
entity body in the request message. |
2868 |
|
2869 |
412 Unless True |
2870 |
|
2871 |
The condition given in the Unless request-header field |
2872 |
(Section 10.40) evaluated to true when it was tested on the server |
2873 |
and the request did not include a Range header field (which would |
2874 |
indicate a partial GET) or an If-Modified-Since header field (which |
2875 |
would indicate a conditional GET). This response code allows the |
2876 |
client to place arbitrary preconditions on the current resource |
2877 |
metainformation (header field data) and thus prevent the requested |
2878 |
method from being applied to a resource other than the one intended. |
2879 |
|
2880 |
9.5 Server Error 5xx |
2881 |
|
2882 |
Response status codes beginning with the digit "5" indicate cases |
2883 |
in which the server is aware that it has erred or is incapable of |
2884 |
performing the request. If the client has not completed the request |
2885 |
when a 5xx code is received, it should immediately cease sending |
2886 |
data to the server. Except when responding to a HEAD request, the |
2887 |
server should include an entity containing an explanation of the |
2888 |
error situation, and whether it is a temporary or permanent |
2889 |
condition. These response codes are applicable to any request |
2890 |
method and there are no required header fields. |
2891 |
|
2892 |
500 Internal Server Error |
2893 |
|
2894 |
The server encountered an unexpected condition which prevented it |
2895 |
from fulfilling the request. |
2896 |
|
2897 |
501 Not Implemented |
2898 |
|
2899 |
The server does not support the functionality required to fulfill |
2900 |
the request. This is the appropriate response when the server does |
2901 |
not recognize the request method and is not capable of supporting |
2902 |
it for any resource. |
2903 |
|
2904 |
502 Bad Gateway |
2905 |
|
2906 |
The server, while acting as a gateway or proxy, received an invalid |
2907 |
response from the upstream server it accessed in attempting to |
2908 |
fulfill the request. |
2909 |
|
2910 |
503 Service Unavailable |
2911 |
|
2912 |
The server is currently unable to handle the request due to a |
2913 |
temporary overloading or maintenance of the server. The implication |
2914 |
is that this is a temporary condition which will be alleviated |
2915 |
after some delay. If known, the length of the delay may be |
2916 |
indicated in a Retry-After header. If no Retry-After is given, the |
2917 |
client should handle the response as it would for a 500 response. |
2918 |
|
2919 |
Note: The existence of the 503 status code does not imply |
2920 |
that a server must use it when becoming overloaded. Some |
2921 |
servers may wish to simply refuse the connection. |
2922 |
|
2923 |
504 Gateway Timeout |
2924 |
|
2925 |
The server, while acting as a gateway or proxy, did not receive a |
2926 |
timely response from the upstream server it accessed in attempting |
2927 |
to complete the request. |
2928 |
|
2929 |
10. Header Field Definitions |
2930 |
|
2931 |
This section defines the syntax and semantics of all standard |
2932 |
HTTP/1.1 header fields. For Entity-Header fields, both sender and |
2933 |
recipient refer to either the client or the server, depending on |
2934 |
who sends and who receives the entity. |
2935 |
|
2936 |
10.1 Accept |
2937 |
|
2938 |
The Accept response-header field can be used to indicate a list of |
2939 |
media ranges which are acceptable as a response to the request. The |
2940 |
asterisk "*" character is used to group media types into ranges, |
2941 |
with "*/*" indicating all media types and "type/*" indicating all |
2942 |
subtypes of that type. The set of ranges given by the client should |
2943 |
represent what types are acceptable given the context of the |
2944 |
request. The Accept field should only be used when the request is |
2945 |
specifically limited to a set of desired types, as in the case of a |
2946 |
request for an in-line image, or to indicate qualitative |
2947 |
preferences for specific media types. |
2948 |
|
2949 |
The field may be folded onto several lines and more than one |
2950 |
occurrence of the field is allowed, with the semantics being the |
2951 |
same as if all the entries had been in one field value. |
2952 |
|
2953 |
Accept = "Accept" ":" #( |
2954 |
media-range |
2955 |
[ ";" "q" "=" qvalue ] |
2956 |
[ ";" "mxb" "=" 1*DIGIT ] ) |
2957 |
|
2958 |
media-range = ( "*/*" |
2959 |
| ( type "/" "*" ) |
2960 |
| ( type "/" subtype ) |
2961 |
) *( ";" parameter ) |
2962 |
|
2963 |
The parameter q is used to indicate the quality factor, which |
2964 |
represents the user's preference for that range of media types. The |
2965 |
parameter mxb gives the maximum acceptable size of the Entity-Body, |
2966 |
in decimal number of octets, for that range of media types. |
2967 |
Section 12 describes the content negotiation algorithm which makes |
2968 |
use of these values. The default values are: q=1 and mxb=undefined |
2969 |
(i.e., infinity). |
2970 |
|
2971 |
The example |
2972 |
|
2973 |
Accept: audio/*; q=0.2, audio/basic |
2974 |
|
2975 |
should be interpreted as "I prefer audio/basic, but send me any |
2976 |
audio type if it is the best available after an 80% mark-down in |
2977 |
quality." |
2978 |
|
2979 |
If no Accept header is present, then it is assumed that the client |
2980 |
accepts all media types with quality factor 1. This is equivalent |
2981 |
to the client sending the following accept header field: |
2982 |
|
2983 |
Accept: */*; q=1 |
2984 |
|
2985 |
or |
2986 |
|
2987 |
Accept: */* |
2988 |
|
2989 |
If a single Accept header is provided and it contains no field |
2990 |
value, then the server must interpret it as a request to not |
2991 |
perform any preemptive content negotiation (Section 12) and instead |
2992 |
return a 406 (none acceptable) response if there are variants |
2993 |
available for the Request-URI. |
2994 |
|
2995 |
A more elaborate example is |
2996 |
|
2997 |
Accept: text/plain; q=0.5, text/html, |
2998 |
text/x-dvi; q=0.8; mxb=100000, text/x-c |
2999 |
|
3000 |
Verbally, this would be interpreted as "text/html and text/x-c are |
3001 |
the preferred media types, but if they do not exist, then send the |
3002 |
text/x-dvi entity if it is less than 100000 bytes, otherwise send |
3003 |
the text/plain entity." |
3004 |
|
3005 |
Media ranges can be overridden by more specific media ranges or |
3006 |
specific media types. If more than one media range applies to a |
3007 |
given type, the most specific reference has precedence. For example, |
3008 |
|
3009 |
Accept: text/*, text/html, text/html;version=2.0, */* |
3010 |
|
3011 |
have the following precedence: |
3012 |
|
3013 |
1) text/html;version=2.0 |
3014 |
2) text/html |
3015 |
3) text/* |
3016 |
4) */* |
3017 |
|
3018 |
The quality value associated with a given type is determined by |
3019 |
finding the media range with the highest precedence which matches |
3020 |
that type. For example, |
3021 |
|
3022 |
Accept: text/*;q=0.3, text/html;q=0.7, text/html;version=2.0, |
3023 |
*/*;q=0.5 |
3024 |
|
3025 |
would cause the following values to be associated: |
3026 |
|
3027 |
text/html;version=2.0 = 1 |
3028 |
text/html = 0.7 |
3029 |
text/plain = 0.3 |
3030 |
image/jpeg = 0.5 |
3031 |
text/html;level=3 = 0.7 |
3032 |
|
3033 |
It must be emphasized that the Accept field should only be used |
3034 |
when it is necessary to restrict the response media types to a |
3035 |
subset of those possible or when the user has been permitted to |
3036 |
specify qualitative values for ranges of media types. If no quality |
3037 |
factors have been set by the user, and the context of the request |
3038 |
is such that the user agent is capable of saving the entity to a |
3039 |
file if the received media type is unknown, then the only |
3040 |
appropriate value for Accept is "*/*", or an empty value if the |
3041 |
user desires reactive negotiation. |
3042 |
|
3043 |
Note: A user agent may be provided with a default set of |
3044 |
quality values for certain media ranges. However, unless the |
3045 |
user agent is a closed system which cannot interact with |
3046 |
other rendering agents, this default set should be |
3047 |
configurable by the user. |
3048 |
|
3049 |
10.2 Accept-Charset |
3050 |
|
3051 |
The Accept-Charset request-header field can be used to indicate |
3052 |
what character sets are acceptable for the response. This field |
3053 |
allows clients capable of understanding more comprehensive or |
3054 |
special-purpose character sets to signal that capability to a |
3055 |
server which is capable of representing documents in those |
3056 |
character sets. The US-ASCII character set can be assumed to be |
3057 |
acceptable to all user agents. |
3058 |
|
3059 |
Accept-Charset = "Accept-Charset" ":" 1#charset |
3060 |
|
3061 |
Character set values are described in Section 3.4. An example is |
3062 |
|
3063 |
Accept-Charset: iso-8859-1, unicode-1-1 |
3064 |
|
3065 |
If no Accept-Charset field is given, the default is that any |
3066 |
character set is acceptable. If the Accept-Charset field is given |
3067 |
and the requested resource is not available in one of the listed |
3068 |
character sets, then the server should respond with the 406 (none |
3069 |
acceptable) status code. |
3070 |
|
3071 |
10.3 Accept-Encoding |
3072 |
|
3073 |
The Accept-Encoding request-header field is similar to Accept, but |
3074 |
restricts the content-coding values (Section 3.5) which are |
3075 |
acceptable in the response. |
3076 |
|
3077 |
Accept-Encoding = "Accept-Encoding" ":" |
3078 |
#( content-coding ) |
3079 |
|
3080 |
An example of its use is |
3081 |
|
3082 |
Accept-Encoding: compress, gzip |
3083 |
|
3084 |
If no Accept-Encoding field is present in a request, the server may |
3085 |
assume that the client will accept any content coding. If an |
3086 |
Accept-Encoding field is present, but contains an empty field |
3087 |
value, then the user agent is refusing to accept any content coding. |
3088 |
|
3089 |
10.4 Accept-Language |
3090 |
|
3091 |
The Accept-Language request-header field is similar to Accept, but |
3092 |
restricts the set of natural languages that are preferred as a |
3093 |
response to the request. |
3094 |
|
3095 |
Accept-Language = "Accept-Language" ":" |
3096 |
1#( language-tag [ ";" "q" "=" qvalue ] ) |
3097 |
|
3098 |
The language-tag is described in Section 3.10. Each language may be |
3099 |
given an associated quality value which represents an estimate of |
3100 |
the user's comprehension of that language. The quality value |
3101 |
defaults to "q=1" (100% comprehension) for listed languages. This |
3102 |
value may be used in the server's content negotiation algorithm |
3103 |
(Section 12). For example, |
3104 |
|
3105 |
Accept-Language: da, en-gb;q=0.8, de;q=0.55 |
3106 |
|
3107 |
would mean: "I prefer Danish, but will accept British English (with |
3108 |
80% comprehension) or German (with a 55% comprehension)." |
3109 |
|
3110 |
If the server cannot fulfill the request with one or more of the |
3111 |
languages given, or if the languages only represent a subset of a |
3112 |
multi-linguistic Entity-Body, it is acceptable to serve the request |
3113 |
in an unspecified language. This is equivalent to assigning a |
3114 |
quality value of "q=0.001" to any unlisted language. |
3115 |
|
3116 |
If no Accept-Language header is present in the request, the server |
3117 |
should assume that all languages are equally acceptable. |
3118 |
|
3119 |
Note: As intelligibility is highly dependent on the |
3120 |
individual user, it is recommended that client applications |
3121 |
make the choice of linguistic preference available to the |
3122 |
user. If the choice is not made available, then the |
3123 |
Accept-Language header field must not be given in the |
3124 |
request. |
3125 |
|
3126 |
10.5 Allow |
3127 |
|
3128 |
The Allow entity-header field lists the set of methods supported by |
3129 |
the resource identified by the Request-URI. The purpose of this |
3130 |
field is strictly to inform the recipient of valid methods |
3131 |
associated with the resource. An Allow header field must be present |
3132 |
in a 405 (method not allowed) response. The Allow header field is |
3133 |
not permitted in a request using the POST method, and thus should |
3134 |
be ignored if it is received as part of a POST entity. |
3135 |
|
3136 |
Allow = "Allow" ":" 1#method |
3137 |
|
3138 |
Example of use: |
3139 |
|
3140 |
Allow: GET, HEAD, PUT |
3141 |
|
3142 |
This field cannot prevent a client from trying other methods. |
3143 |
However, the indications given by the Allow header field value |
3144 |
should be followed. The actual set of allowed methods is defined by |
3145 |
the origin server at the time of each request. |
3146 |
|
3147 |
The Allow header field may be provided with a PUT request to |
3148 |
recommend the methods to be supported by the new or modified |
3149 |
resource. The server is not required to support these methods and |
3150 |
should include an Allow header in the response giving the actual |
3151 |
supported methods. |
3152 |
|
3153 |
A proxy must not modify the Allow header field even if it does not |
3154 |
understand all the methods specified, since the user agent may have |
3155 |
other means of communicating with the origin server. |
3156 |
|
3157 |
The Allow header field does not indicate what methods are |
3158 |
implemented at the server level. Servers may use the Public |
3159 |
response header field (Section 10.32) to describe what methods are |
3160 |
implemented on the server as a whole. |
3161 |
|
3162 |
10.6 Authorization |
3163 |
|
3164 |
A user agent that wishes to authenticate itself with a |
3165 |
server--usually, but not necessarily, after receiving a 401 |
3166 |
response--may do so by including an Authorization request-header |
3167 |
field with the request. The Authorization field value consists of |
3168 |
credentials containing the authentication information of the user |
3169 |
agent for the realm of the resource being requested. |
3170 |
|
3171 |
Authorization = "Authorization" ":" credentials |
3172 |
|
3173 |
HTTP access authentication is described in Section 11. If a request |
3174 |
is authenticated and a realm specified, the same credentials should |
3175 |
be valid for all other requests within this realm. |
3176 |
|
3177 |
Responses to requests containing an Authorization field are not |
3178 |
cachable. |
3179 |
|
3180 |
10.7 Base |
3181 |
|
3182 |
The Base entity-header field may be used to specify the base URI |
3183 |
for resolving relative URLs, as described in RFC 1808 [11]. |
3184 |
|
3185 |
10.8 Cache-Control |
3186 |
|
3187 |
The Cache-Control general-header field is used to specify |
3188 |
directives that must be obeyed by all caching mechanisms along the |
3189 |
request/response chain. The directives specify behavior intended to |
3190 |
prevent caches from adversely interfering with the request or |
3191 |
response. Cache directives are unidirectional in that the presence |
3192 |
of a directive in a request does not imply that the same directive |
3193 |
should be given in the response. |
3194 |
|
3195 |
Cache-Control = "Cache-Control" ":" 1#cache-directive |
3196 |
|
3197 |
cache-directive = "cachable" |
3198 |
| "max-age" "=" delta-seconds |
3199 |
| "private" [ "=" <"> 1#field-name <"> ] |
3200 |
| "no-cache" [ "=" <"> 1#field-name <"> ] |
3201 |
|
3202 |
The Cache-Control header field may be used to modify the optional |
3203 |
behavior of caching mechanisms, and the default cachability of a |
3204 |
response message; it cannot be used to modify the required behavior |
3205 |
of caching mechanisms. HTTP requirements for caching and cachable |
3206 |
messages are described in Section 13. |
3207 |
|
3208 |
The "cachable" directive indicates that the entire response message |
3209 |
is cachable unless required otherwise by HTTP restrictions on the |
3210 |
request method and response code. In other words, this directive |
3211 |
indicates that the server believes the response to be cachable. |
3212 |
This directive applies only to responses and must not be used with |
3213 |
any other cache directive. |
3214 |
|
3215 |
When the "max-age" directive is present in a request message, an |
3216 |
application must forward the request toward the origin server if it |
3217 |
has no cached copy, or refresh its cached copy if it is older than |
3218 |
the age value given (in seconds) prior to returning a response. A |
3219 |
cached copy's age is determined by the cached message's Date header |
3220 |
field, or the equivalent as stored by the cache manager. |
3221 |
|
3222 |
In most cases, a cached copy can be refreshed by forwarding a |
3223 |
conditional GET request toward the origin server with the stored |
3224 |
message's Last-Modified value in the If-Modified-Since field. The |
3225 |
Unless header field may be used to add further restrictions to the |
3226 |
modification test on the server. If a 304 (not modified) response |
3227 |
is received, the cache should replace the cached message's Date |
3228 |
with that of the 304 response and send this refreshed message as |
3229 |
the response. Any other response should be forwarded directly to |
3230 |
the requestor and, depending on the response code and the |
3231 |
discretion of the cache manager, may replace the message in the |
3232 |
cache. |
3233 |
|
3234 |
When the "max-age" directive is present in a cached response |
3235 |
message, an application must refresh the message if it is older |
3236 |
than the age value given (in seconds) at the time of a new request |
3237 |
for that resource. The behavior should be equivalent to what would |
3238 |
occur if the request had included the max-age directive. If both |
3239 |
the new request and the cached message have max-age specified, then |
3240 |
the lesser of the two values must be used. A max-age value of zero |
3241 |
(0) forces a cache to perform a refresh (If-Modified-Since) on |
3242 |
every request. The max-age directive on a response implies that the |
3243 |
server believes it to be cachable. |
3244 |
|
3245 |
The "private" directive indicates that parts of the response |
3246 |
message are intended for a single user and must not be cached |
3247 |
except within a private (non-shared) cache controlled by the user |
3248 |
agent. If no list of field names is given, then the entire message |
3249 |
is private; otherwise, only the information within the header |
3250 |
fields identified by the list of names is private and the remainder |
3251 |
of the message is believed to be cachable by any application. This |
3252 |
allows an origin server to state that the specified parts of the |
3253 |
message are intended for only one user and are not a valid response |
3254 |
for requests by other agents. The "private" directive is only |
3255 |
applicable to responses and must not be generated by clients. |
3256 |
|
3257 |
Note: This usage of the word "private" implies only that the |
3258 |
message must not be cached publically; it does not ensure |
3259 |
the privacy of the message content. |
3260 |
|
3261 |
The "no-cache" directive on a request message requires any cache to |
3262 |
forward the request toward the origin server even if it has a |
3263 |
cached copy of what is being requested. This allows a client to |
3264 |
insist upon receiving an authoritative response to its request. It |
3265 |
also allows a client to refresh a cached copy which is known to be |
3266 |
corrupted or stale. This is equivalent to the "no-cache" |
3267 |
pragma-directive in Section 10.29. The list of field names is not |
3268 |
used with requests and must not be generated by clients. The |
3269 |
no-cache directive overrides any max-age directive. |
3270 |
|
3271 |
The "no-cache" directive on a response message indicates that parts |
3272 |
of the message must never be cached. If no list of field names is |
3273 |
given, then the entire message must not be cached; otherwise, only |
3274 |
the information within the header fields identified by the list of |
3275 |
names must not be cached and the remainder of the message is |
3276 |
believed to be cachable. This allows an origin server to state that |
3277 |
the specified parts of the message are intended for only one |
3278 |
recipient and must not be stored unless the user explicitly |
3279 |
requests it through a separate action. |
3280 |
|
3281 |
The max-age, private, and no-cache directives may be used in |
3282 |
combination to define the cachability of each part of the message. |
3283 |
In all cases, no-cache takes precedence over private, which in turn |
3284 |
takes precedence over max-age. |
3285 |
|
3286 |
Cache directives must be passed through by a proxy or gateway |
3287 |
application, regardless of their significance to that application, |
3288 |
since the directives may be applicable to all recipients along the |
3289 |
request/response chain. It is not possible to specify a |
3290 |
cache-directive for a specific cache. |
3291 |
|
3292 |
10.9 Connection |
3293 |
|
3294 |
The Connection general-header field is used to indicate a list of |
3295 |
keywords and header field names containing information which is |
3296 |
only applicable to the current connection between the sender and |
3297 |
the nearest non-tunnel recipient on the request/response chain. |
3298 |
This information must not be forwarded or cached. Unlike the |
3299 |
default behavior, the recipient cannot safely ignore the semantics |
3300 |
of the listed field-names if they are not understood, since |
3301 |
forwarding them may imply that understanding. |
3302 |
|
3303 |
Connection = "Connection" ":" 1#field-name |
3304 |
|
3305 |
Proxies and gateways must discard the named header fields, and the |
3306 |
Connection header itself, before forwarding the message. Proxies |
3307 |
and gateways may add their own Connection information to forwarded |
3308 |
messages if such options are desired for the forwarding connection. |
3309 |
These restrictions do not apply to a tunnel, since the tunnel is |
3310 |
acting as a relay between two connections and does not affect the |
3311 |
connection options. |
3312 |
|
3313 |
Whether or not the listed field-name(s) occur as header fields in |
3314 |
the message is optional. If no corresponding header field is |
3315 |
present, then the field name is treated as a keyword. Keywords are |
3316 |
useful for indicating a desired option without assigning parameters |
3317 |
to that option. This allows for a minimal syntax to provide |
3318 |
connection-based options without pre-restricting the syntax or |
3319 |
number of those options. HTTP/1.1 only defines the "keep-alive" |
3320 |
keyword. |
3321 |
|
3322 |
The semantics of Connection are defined by HTTP/1.1 in order to |
3323 |
provide a safe transition to connection-based features. Connection |
3324 |
header fields received in an HTTP/1.0 message, as would be the case |
3325 |
if an older proxy mistakenly forwards the field, cannot be trusted |
3326 |
and must be discarded except under experimental conditions. |
3327 |
|
3328 |
10.9.1 Persistent Connections |
3329 |
|
3330 |
The "keep-alive" keyword in a Connection header field allows the |
3331 |
sender to indicate its desire for a persistent connection (i.e., a |
3332 |
connection that lasts beyond the current request/response |
3333 |
transaction). Persistent connections allow the client to perform |
3334 |
multiple requests without the overhead of connection tear-down and |
3335 |
set-up between each request. |
3336 |
|
3337 |
As an example, a client would send |
3338 |
|
3339 |
Connection: Keep-Alive |
3340 |
|
3341 |
to indicate that it desires to keep the connection open for |
3342 |
multiple requests. The server may then respond with a message |
3343 |
containing |
3344 |
|
3345 |
Connection: Keep-Alive |
3346 |
|
3347 |
to indicate that the connection will be kept open for the next |
3348 |
request. The Connection header field with a keep-alive keyword must |
3349 |
be sent on all requests and responses that wish to continue the |
3350 |
persistence. The client sends requests as normal and the server |
3351 |
responds as normal, except that all messages containing an entity |
3352 |
body must have a length that can be determined without closing the |
3353 |
connection (i.e., each message containg an entity body must have a |
3354 |
valid Content-Length, be a multipart media type, or be encoded |
3355 |
using the "chunked" transfer coding, as described in Section 7.2.2). |
3356 |
|
3357 |
The Keep-Alive header field (Section 10.24) may be used to include |
3358 |
diagnostic information and other optional parameters. For example, |
3359 |
the server may responds with |
3360 |
|
3361 |
Connection: Keep-Alive |
3362 |
Keep-Alive: timeout=10, max=5 |
3363 |
|
3364 |
to indicate that the server has selected (perhaps dynamically) a |
3365 |
maximum of 5 requests, but will timeout if the next request is not |
3366 |
received within 10 seconds. Note, however, that this additional |
3367 |
information is optional and the Keep-Alive header field does not |
3368 |
need to be present. If it is present, the semantics of the |
3369 |
Connection header field prevents it from being accidentally |
3370 |
forwarded to downstream connections. |
3371 |
|
3372 |
The persistent connection ends when either side closes the |
3373 |
connection or after the receipt of a response which lacks the |
3374 |
"keep-alive" keyword. The server may close the connection |
3375 |
immediately after responding to a request without a "keep-alive" |
3376 |
keyword. A client can tell if the connection will be closed by |
3377 |
looking for a "keep-alive" in the response. |
3378 |
|
3379 |
10.10 Content-Encoding |
3380 |
|
3381 |
The Content-Encoding entity-header field is used as a modifier to |
3382 |
the media-type. When present, its value indicates what additional |
3383 |
content codings have been applied to the resource, and thus what |
3384 |
decoding mechanisms must be applied in order to obtain the |
3385 |
media-type referenced by the Content-Type header field. |
3386 |
Content-Encoding is primarily used to allow a document to be |
3387 |
compressed without losing the identity of its underlying media type. |
3388 |
|
3389 |
Content-Encoding = "Content-Encoding" ":" 1#content-coding |
3390 |
|
3391 |
Content codings are defined in Section 3.5. An example of its use is |
3392 |
|
3393 |
Content-Encoding: gzip |
3394 |
|
3395 |
The Content-Encoding is a characteristic of the resource identified |
3396 |
by the Request-URI. Typically, the resource is stored with this |
3397 |
encoding and is only decoded before rendering or analogous usage. |
3398 |
|
3399 |
If multiple encodings have been applied to a resource, the content |
3400 |
codings must be listed in the order in which they were applied. |
3401 |
Additional information about the encoding parameters may be |
3402 |
provided by other Entity-Header fields not defined by this |
3403 |
specification. |
3404 |
|
3405 |
10.11 Content-Language |
3406 |
|
3407 |
The Content-Language entity-header field describes the natural |
3408 |
language(s) of the intended audience for the enclosed entity. Note |
3409 |
that this may not be equivalent to all the languages used within |
3410 |
the entity. |
3411 |
|
3412 |
Content-Language = "Content-Language" ":" 1#language-tag |
3413 |
|
3414 |
Language tags are defined in Section 3.10. The primary purpose of |
3415 |
Content-Language is to allow a selective consumer to identify and |
3416 |
differentiate resources according to the consumer's own preferred |
3417 |
language. Thus, if the body content is intended only for a |
3418 |
Danish-literate audience, the appropriate field is |
3419 |
|
3420 |
Content-Language: dk |
3421 |
|
3422 |
If no Content-Language is specified, the default is that the |
3423 |
content is intended for all language audiences. This may mean that |
3424 |
the sender does not consider it to be specific to any natural |
3425 |
language, or that the sender does not know for which language it is |
3426 |
intended. |
3427 |
|
3428 |
Multiple languages may be listed for content that is intended for |
3429 |
multiple audiences. For example, a rendition of the "Treaty of |
3430 |
Waitangi," presented simultaneously in the original Maori and |
3431 |
English versions, would call for |
3432 |
|
3433 |
Content-Language: mi, en |
3434 |
|
3435 |
However, just because multiple languages are present within an |
3436 |
entity does not mean that it is intended for multiple linguistic |
3437 |
audiences. An example would be a beginner's language primer, such |
3438 |
as "A First Lesson in Latin," which is clearly intended to be used |
3439 |
by an English-literate audience. In this case, the Content-Language |
3440 |
should only include "en". |
3441 |
|
3442 |
Content-Language may be applied to any media type -- it should not |
3443 |
be limited to textual documents. |
3444 |
|
3445 |
10.12 Content-Length |
3446 |
|
3447 |
The Content-Length entity-header field indicates the size of the |
3448 |
Entity-Body, in decimal number of octets, sent to the recipient or, |
3449 |
in the case of the HEAD method, the size of the Entity-Body that |
3450 |
would have been sent had the request been a GET. |
3451 |
|
3452 |
Content-Length = "Content-Length" ":" 1*DIGIT |
3453 |
|
3454 |
An example is |
3455 |
|
3456 |
Content-Length: 3495 |
3457 |
|
3458 |
Applications should use this field to indicate the size of the |
3459 |
Entity-Body to be transferred, regardless of the media type of the |
3460 |
entity. A valid Content-Length field value is required on all |
3461 |
HTTP/1.1 request messages containing an entity body. |
3462 |
|
3463 |
Any Content-Length greater than or equal to zero is a valid value. |
3464 |
Section 7.2.2 describes how to determine the length of an |
3465 |
Entity-Body if a Content-Length is not given. |
3466 |
|
3467 |
Note: The meaning of this field is significantly different |
3468 |
from the corresponding definition in MIME, where it is an |
3469 |
optional field used within the "message/external-body" |
3470 |
content-type. In HTTP, it should be used whenever the |
3471 |
entity's length can be determined prior to being transferred. |
3472 |
|
3473 |
10.13 Content-MD5 |
3474 |
|
3475 |
TBS |
3476 |
|
3477 |
10.14 Content-Range |
3478 |
|
3479 |
TBS |
3480 |
|
3481 |
10.15 Content-Type |
3482 |
|
3483 |
The Content-Type entity-header field indicates the media type of |
3484 |
the Entity-Body sent to the recipient or, in the case of the HEAD |
3485 |
method, the media type that would have been sent had the request |
3486 |
been a GET. |
3487 |
|
3488 |
Content-Type = "Content-Type" ":" media-type |
3489 |
|
3490 |
Media types are defined in Section 3.7. An example of the field is |
3491 |
|
3492 |
Content-Type: text/html; charset=ISO-8859-4 |
3493 |
|
3494 |
Further discussion of methods for identifying the media type of an |
3495 |
entity is provided in Section 7.2.1. |
3496 |
|
3497 |
10.16 Content-Version |
3498 |
|
3499 |
The Content-Version entity-header field defines the version tag |
3500 |
associated with a rendition of an evolving entity. Together with |
3501 |
the Derived-From field described in Section 10.18, it allows a |
3502 |
group of people to work simultaneously on the creation of a work as |
3503 |
an iterative process. The field should be used to allow evolution |
3504 |
of a particular work along a single path. It should not be used to |
3505 |
indicate derived works or renditions in different representations. |
3506 |
It may also me used as an opaque value for comparing a cached |
3507 |
entity's version with that of the current resource. |
3508 |
|
3509 |
Content-Version= "Content-Version" ":" quoted-string |
3510 |
|
3511 |
Examples of the Content-Version field include: |
3512 |
|
3513 |
Content-Version: "2.1.2" |
3514 |
|
3515 |
Content-Version: "Fred 19950116-12:26:48" |
3516 |
|
3517 |
Content-Version: "2.5a4-omega7" |
3518 |
|
3519 |
The value of the Content-Version field should be considered opaque |
3520 |
to all parties but the origin server. A user agent may suggest a |
3521 |
value for the version of an entity transferred via a PUT request; |
3522 |
however, only the origin server can reliably assign that value. |
3523 |
|
3524 |
10.17 Date |
3525 |
|
3526 |
The Date general-header field represents the date and time at which |
3527 |
the message was originated, having the same semantics as orig-date |
3528 |
in RFC 822. The field value is an HTTP-date, as described in |
3529 |
Section 3.3. |
3530 |
|
3531 |
Date = "Date" ":" HTTP-date |
3532 |
|
3533 |
An example is |
3534 |
|
3535 |
Date: Tue, 15 Nov 1994 08:12:31 GMT |
3536 |
|
3537 |
If a message is received via direct connection with the user agent |
3538 |
(in the case of requests) or the origin server (in the case of |
3539 |
responses), then the date can be assumed to be the current date at |
3540 |
the receiving end. However, since the date--as it is believed by the |
3541 |
origin--is important for evaluating cached responses, origin servers |
3542 |
should always include a Date header. Clients should only send a |
3543 |
Date header field in messages that include an entity body, as in |
3544 |
the case of the PUT and POST requests, and even then it is |
3545 |
optional. A received message which does not have a Date header |
3546 |
field should be assigned one by the recipient if the message will |
3547 |
be cached by that recipient or gatewayed via a protocol which |
3548 |
requires a Date. |
3549 |
|
3550 |
In theory, the date should represent the moment just before the |
3551 |
entity is generated. In practice, the date can be generated at any |
3552 |
time during the message origination without affecting its semantic |
3553 |
value. |
3554 |
|
3555 |
Note: An earlier version of this document incorrectly |
3556 |
specified that this field should contain the creation date |
3557 |
of the enclosed Entity-Body. This has been changed to |
3558 |
reflect actual (and proper) usage. |
3559 |
|
3560 |
10.18 Derived-From |
3561 |
|
3562 |
The Derived-From entity-header field can be used to indicate the |
3563 |
version tag of the resource from which the enclosed entity was |
3564 |
derived before modifications were made by the sender. This field is |
3565 |
used to help manage the process of merging successive changes to a |
3566 |
resource, particularly when such changes are being made in parallel |
3567 |
and from multiple sources. |
3568 |
|
3569 |
Derived-From = "Derived-From" ":" quoted-string |
3570 |
|
3571 |
An example use of the field is: |
3572 |
|
3573 |
Derived-From: "2.1.1" |
3574 |
|
3575 |
The Derived-From field is required for PUT and PATCH requests if |
3576 |
the entity being sent was previously retrieved from the same URI |
3577 |
and a Content-Version header was included with the entity when it |
3578 |
was last retrieved. |
3579 |
|
3580 |
10.19 Expires |
3581 |
|
3582 |
The Expires entity-header field gives the date/time after which the |
3583 |
entity should be considered stale. This allows information |
3584 |
providers to suggest the volatility of the resource, or a date |
3585 |
after which the information may no longer be valid. Applications |
3586 |
must not cache this entity beyond the date given. The presence of |
3587 |
an Expires field does not imply that the original resource will |
3588 |
change or cease to exist at, before, or after that time. However, |
3589 |
information providers that know or even suspect that a resource |
3590 |
will change by a certain date should include an Expires header with |
3591 |
that date. The format is an absolute date and time as defined by |
3592 |
HTTP-date in Section 3.3. |
3593 |
|
3594 |
Expires = "Expires" ":" HTTP-date |
3595 |
|
3596 |
An example of its use is |
3597 |
|
3598 |
Expires: Thu, 01 Dec 1994 16:00:00 GMT |
3599 |
|
3600 |
If the date given is equal to or earlier than the value of the Date |
3601 |
header, the recipient must not cache the enclosed entity. If a |
3602 |
resource is dynamic by nature, as is the case with many |
3603 |
data-producing processes, entities from that resource should be |
3604 |
given an appropriate Expires value which reflects that dynamism. |
3605 |
|
3606 |
The Expires field cannot be used to force a user agent to refresh |
3607 |
its display or reload a resource; its semantics apply only to |
3608 |
caching mechanisms, and such mechanisms need only check a |
3609 |
resource's expiration status when a new request for that resource |
3610 |
is initiated. |
3611 |
|
3612 |
User agents often have history mechanisms, such as "Back" buttons |
3613 |
and history lists, which can be used to redisplay an entity |
3614 |
retrieved earlier in a session. By default, the Expires field does |
3615 |
not apply to history mechanisms. If the entity is still in storage, |
3616 |
a history mechanism should display it even if the entity has |
3617 |
expired, unless the user has specifically configured the agent to |
3618 |
refresh expired history documents. |
3619 |
|
3620 |
Note: Applications are encouraged to be tolerant of bad or |
3621 |
misinformed implementations of the Expires header. A value |
3622 |
of zero (0) or an invalid date format should be considered |
3623 |
equivalent to an "expires immediately." Although these |
3624 |
values are not legitimate for HTTP/1.1, a robust |
3625 |
implementation is always desirable. |
3626 |
|
3627 |
10.20 Forwarded |
3628 |
|
3629 |
The Forwarded general-header field is to be used by gateways and |
3630 |
proxies to indicate the intermediate steps between the user agent |
3631 |
and the server on requests, and between the origin server and the |
3632 |
client on responses. It is analogous to the "Received" field of RFC |
3633 |
822 [9] and is intended to be used for tracing transport problems |
3634 |
and avoiding request loops. |
3635 |
|
3636 |
Forwarded = "Forwarded" ":" #( "by" URI [ "(" product ")" ] |
3637 |
[ "for" FQDN ] ) |
3638 |
|
3639 |
FQDN = <Fully-Qualified Domain Name> |
3640 |
|
3641 |
For example, a message could be sent from a client on |
3642 |
ptsun00.cern.ch to a server at www.ics.uci.edu port 80, via an |
3643 |
intermediate HTTP proxy at info.cern.ch port 8000. The request |
3644 |
received by the server at www.ics.uci.edu would then have the |
3645 |
following Forwarded header field: |
3646 |
|
3647 |
Forwarded: by http://info.cern.ch:8000/ for ptsun00.cern.ch |
3648 |
|
3649 |
Multiple Forwarded header fields are allowed and should represent |
3650 |
each proxy/gateway that has forwarded the message. It is strongly |
3651 |
recommended that proxies/gateways used as a portal through a |
3652 |
network firewall do not, by default, send out information about the |
3653 |
internal hosts within the firewall region. This information should |
3654 |
only be propagated if explicitly enabled. If not enabled, the for |
3655 |
token and FQDN should not be included in the field value, and any |
3656 |
Forwarded headers already present in the message (those added |
3657 |
behind the firewall) should be removed. |
3658 |
|
3659 |
10.21 From |
3660 |
|
3661 |
The From request-header field, if given, should contain an Internet |
3662 |
e-mail address for the human user who controls the requesting user |
3663 |
agent. The address should be machine-usable, as defined by mailbox |
3664 |
in RFC 822 [9] (as updated by RFC 1123 [8]): |
3665 |
|
3666 |
From = "From" ":" mailbox |
3667 |
|
3668 |
An example is: |
3669 |
|
3670 |
From: webmaster@w3.org |
3671 |
|
3672 |
This header field may be used for logging purposes and as a means |
3673 |
for identifying the source of invalid or unwanted requests. It |
3674 |
should not be used as an insecure form of access protection. The |
3675 |
interpretation of this field is that the request is being performed |
3676 |
on behalf of the person given, who accepts responsibility for the |
3677 |
method performed. In particular, robot agents should include this |
3678 |
header so that the person responsible for running the robot can be |
3679 |
contacted if problems occur on the receiving end. |
3680 |
|
3681 |
The Internet e-mail address in this field may be separate from the |
3682 |
Internet host which issued the request. For example, when a request |
3683 |
is passed through a proxy the original issuer's address should be |
3684 |
used. |
3685 |
|
3686 |
Note: The client should not send the From header field |
3687 |
without the user's approval, as it may conflict with the |
3688 |
user's privacy interests or their site's security policy. It |
3689 |
is strongly recommended that the user be able to disable, |
3690 |
enable, and modify the value of this field at any time prior |
3691 |
to a request. |
3692 |
|
3693 |
10.22 Host |
3694 |
|
3695 |
The Host request-header field allows the client to specify, for the |
3696 |
server's benefit, the Internet host given by the original Uniform |
3697 |
Resource Identifier (Section 3.2) of the resource being requested, |
3698 |
as it was obtained from the user or the referring resource. This |
3699 |
allows a server to differentiate between internally-ambiguous URLs |
3700 |
(such as the root "/" URL of a server harboring multiple virtual |
3701 |
hostnames). This field is required on all HTTP/1.1 requests which |
3702 |
do not already include the host in the Request-URI. |
3703 |
|
3704 |
Host = "Host" ":" host ; Section 3.2.2 |
3705 |
|
3706 |
Example: |
3707 |
|
3708 |
Host: www.w3.org |
3709 |
|
3710 |
The contents of the Host header field should exactly match the host |
3711 |
information used to contact the origin server or gateway in |
3712 |
question. It must not include the trailing ":port" information |
3713 |
which may also be found in the net_loc portion of a URL |
3714 |
(Section 3.2). |
3715 |
|
3716 |
10.23 If-Modified-Since |
3717 |
|
3718 |
The If-Modified-Since request-header field is used with the GET |
3719 |
method to make it conditional: if the requested resource has not |
3720 |
been modified since the time specified in this field, a copy of the |
3721 |
resource will not be returned from the server; instead, a 304 (not |
3722 |
modified) response will be returned without any Entity-Body. |
3723 |
|
3724 |
If-Modified-Since = "If-Modified-Since" ":" HTTP-date |
3725 |
|
3726 |
An example of the field is: |
3727 |
|
3728 |
If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT |
3729 |
|
3730 |
A conditional GET method requests that the identified resource be |
3731 |
transferred only if it has been modified since the date given by |
3732 |
the If-Modified-Since header. The algorithm for determining this |
3733 |
includes the following cases: |
3734 |
|
3735 |
a) If the request would normally result in anything other than |
3736 |
a 200 (ok) status, or if the passed If-Modified-Since date |
3737 |
is invalid, the response is exactly the same as for a |
3738 |
normal GET. A date which is later than the server's current |
3739 |
time is invalid. |
3740 |
|
3741 |
b) If the resource has been modified since the |
3742 |
If-Modified-Since date, the response is exactly the same as |
3743 |
for a normal GET. |
3744 |
|
3745 |
c) If the resource has not been modified since a valid |
3746 |
If-Modified-Since date, the server must return a 304 (not |
3747 |
modified) response. |
3748 |
|
3749 |
The purpose of this feature is to allow efficient updates of cached |
3750 |
information with a minimum amount of transaction overhead. |
3751 |
|
3752 |
10.24 Keep-Alive |
3753 |
|
3754 |
The Keep-Alive general-header field may be used to include |
3755 |
diagnostic information and other optional parameters associated |
3756 |
with the "keep-alive" keyword of the Connection header field |
3757 |
(Section 10.9). This Keep-Alive field must only be used when the |
3758 |
"keep-alive" keyword is present (Section 10.9.1). |
3759 |
|
3760 |
Keep-Alive = "Keep-Alive" ":" 1#kaparam |
3761 |
|
3762 |
kaparam = ( "timeout" "=" delta-seconds ) |
3763 |
| ( "max" "=" 1*DIGIT ) |
3764 |
| ( attribute [ "=" value ] ) |
3765 |
|
3766 |
The Keep-Alive header field and the additional information it |
3767 |
provides are optional and do not need to be present to indicate a |
3768 |
persistent connection has been established. The semantics of the |
3769 |
Connection header field prevent the Keep-Alive field from being |
3770 |
accidentally forwarded to downstream connections. |
3771 |
|
3772 |
HTTP/1.1 defines semantics for the optional "timeout" and "max" |
3773 |
parameters on responses; other parameters may be added and the |
3774 |
field may also be used on request messages. The "timeout" parameter |
3775 |
allows the server to indicate, for diagnostic purposes only, the |
3776 |
amount of time in seconds it is currently allowing between when the |
3777 |
response was generated and when the next request is received from |
3778 |
the client (i.e., the request timeout limit). Similarly, the "max" |
3779 |
parameter allows the server to indicate the maximum additional |
3780 |
requests that it will allow on the current persistent connection. |
3781 |
|
3782 |
For example, the server may respond to a request for a persistent |
3783 |
connection with |
3784 |
|
3785 |
Connection: Keep-Alive |
3786 |
Keep-Alive: timeout=10, max=5 |
3787 |
|
3788 |
to indicate that the server has selected (perhaps dynamically) a |
3789 |
maximum of 5 requests, but will timeout the connection if the next |
3790 |
request is not received within 10 seconds. Although these |
3791 |
parameters have no affect on the operational requirements of the |
3792 |
connection, they are sometimes useful for testing functionality and |
3793 |
monitoring server behavior. |
3794 |
|
3795 |
10.25 Last-Modified |
3796 |
|
3797 |
The Last-Modified entity-header field indicates the date and time |
3798 |
at which the sender believes the resource was last modified. The |
3799 |
exact semantics of this field are defined in terms of how the |
3800 |
recipient should interpret it: if the recipient has a copy of this |
3801 |
resource which is older than the date given by the Last-Modified |
3802 |
field, that copy should be considered stale. |
3803 |
|
3804 |
Last-Modified = "Last-Modified" ":" HTTP-date |
3805 |
|
3806 |
An example of its use is |
3807 |
|
3808 |
Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT |
3809 |
|
3810 |
The exact meaning of this header field depends on the |
3811 |
implementation of the sender and the nature of the original |
3812 |
resource. For files, it may be just the file system last-modified |
3813 |
time. For entities with dynamically included parts, it may be the |
3814 |
most recent of the set of last-modify times for its component |
3815 |
parts. For database gateways, it may be the last-update timestamp |
3816 |
of the record. For virtual objects, it may be the last time the |
3817 |
internal state changed. |
3818 |
|
3819 |
An origin server must not send a Last-Modified date which is later |
3820 |
than the server's time of message origination. In such cases, where |
3821 |
the resource's last modification would indicate some time in the |
3822 |
future, the server must replace that date with the message |
3823 |
origination date. |
3824 |
|
3825 |
10.26 Link |
3826 |
|
3827 |
The Link entity-header field provides a means for describing a |
3828 |
relationship between the entity and some other resource. An entity |
3829 |
may include multiple Link values. Links at the metainformation |
3830 |
level typically indicate relationships like hierarchical structure |
3831 |
and navigation paths. The Link field is semantically equivalent to |
3832 |
the <LINK> element in HTML [5]. |
3833 |
|
3834 |
Link = "Link" ":" #("<" URI ">" |
3835 |
[ ";" "rel" "=" relationship ] |
3836 |
[ ";" "rev" "=" relationship ] |
3837 |
[ ";" "title" "=" quoted-string ] ) |
3838 |
|
3839 |
relationship = sgml-name |
3840 |
| ( <"> sgml-name *( SP sgml-name) <"> ) |
3841 |
|
3842 |
sgml-name = ALPHA *( ALPHA | DIGIT | "." | "-" ) |
3843 |
|
3844 |
Relationship values are case-insensitive and may be extended within |
3845 |
the constraints of the sgml-name syntax. The title parameter may be |
3846 |
used to label the destination of a link such that it can be used as |
3847 |
identification within a human-readable menu. |
3848 |
|
3849 |
Examples of usage include: |
3850 |
|
3851 |
Link: <http://www.cern.ch/TheBook/chapter2>; rel="Previous" |
3852 |
|
3853 |
Link: <mailto:timbl@w3.org>; rev="Made"; title="Tim Berners-Lee" |
3854 |
|
3855 |
The first example indicates that chapter2 is previous to the |
3856 |
entity in a logical navigation path. The second indicates that the |
3857 |
person responsible for making the resource available is identified |
3858 |
by the given e-mail address. |
3859 |
|
3860 |
10.27 Location |
3861 |
|
3862 |
The Location response-header field defines the exact location of |
3863 |
the resource that was identified by the Request-URI. For 2xx |
3864 |
responses, if the Request-URI corresponds to a negotiable set of |
3865 |
variants and the response includes one of those variants, then the |
3866 |
response must also include a Location header field containing the |
3867 |
exact location of the chosen variant. For 3xx responses, the |
3868 |
location should indicate the server's preferred URL for automatic |
3869 |
redirection to the resource. The field value consists of a single |
3870 |
absolute URL. |
3871 |
|
3872 |
Location = "Location" ":" absoluteURI |
3873 |
|
3874 |
An example is |
3875 |
|
3876 |
Location: http://www.w3.org/pub/WWW/People.html |
3877 |
|
3878 |
If no base URL is provided by or within the entity, the value of |
3879 |
the Location field should be used as the base for resolving |
3880 |
relative URLs [11]. |
3881 |
|
3882 |
10.28 MIME-Version |
3883 |
|
3884 |
HTTP is not a MIME-compliant protocol (see Appendix C). However, |
3885 |
HTTP/1.1 messages may include a single MIME-Version general-header |
3886 |
field to indicate what version of the MIME protocol was used to |
3887 |
construct the message. Use of the MIME-Version header field |
3888 |
indicates that the message is in full compliance with the MIME |
3889 |
protocol (as defined in [7]). Proxies/gateways are responsible for |
3890 |
ensuring full compliance (where possible) when exporting HTTP |
3891 |
messages to strict MIME environments. |
3892 |
|
3893 |
MIME-Version = "MIME-Version" ":" 1*DIGIT "." 1*DIGIT |
3894 |
|
3895 |
MIME version "1.0" is the default for use in HTTP/1.1. However, |
3896 |
HTTP/1.1 message parsing and semantics are defined by this document |
3897 |
and not the MIME specification. |
3898 |
|
3899 |
10.29 Pragma |
3900 |
|
3901 |
The Pragma general-header field is used to include |
3902 |
implementation-specific directives that may apply to any recipient |
3903 |
along the request/response chain. All pragma directives specify |
3904 |
optional behavior from the viewpoint of the protocol; however, some |
3905 |
systems may require that behavior be consistent with the directives. |
3906 |
|
3907 |
Pragma = "Pragma" ":" 1#pragma-directive |
3908 |
|
3909 |
pragma-directive = "no-cache" | extension-pragma |
3910 |
extension-pragma = token [ "=" word ] |
3911 |
|
3912 |
When the "no-cache" directive is present in a request message, an |
3913 |
application should forward the request toward the origin server |
3914 |
even if it has a cached copy of what is being requested. This |
3915 |
pragma directive has the same semantics as the "no-cache" |
3916 |
cache-directive (see Section 10.8) and is defined here for |
3917 |
backwards compatibility with HTTP/1.0. Clients should include both |
3918 |
header fields when a "no-cache" request is sent to a server not |
3919 |
known to be HTTP/1.1 compliant. |
3920 |
|
3921 |
Pragma directives must be passed through by a proxy or gateway |
3922 |
application, regardless of their significance to that application, |
3923 |
since the directives may be applicable to all recipients along the |
3924 |
request/response chain. It is not possible to specify a pragma for |
3925 |
a specific recipient; however, any pragma directive not relevant to |
3926 |
a recipient should be ignored by that recipient. |
3927 |
|
3928 |
10.30 Proxy-Authenticate |
3929 |
|
3930 |
The Proxy-Authenticate response-header field must be included as |
3931 |
part of a 407 (proxy authentication required) response. The field |
3932 |
value consists of a challenge that indicates the authentication |
3933 |
scheme and parameters applicable to the proxy for this Request-URI. |
3934 |
|
3935 |
Proxy-Authentication = "Proxy-Authentication" ":" challenge |
3936 |
|
3937 |
The HTTP access authentication process is described in Section 11. |
3938 |
Unlike WWW-Authenticate, the Proxy-Authenticate header field |
3939 |
applies only to the current connection and must not be passed on to |
3940 |
downstream clients. |
3941 |
|
3942 |
10.31 Proxy-Authorization |
3943 |
|
3944 |
The Proxy-Authorization request-header field allows the client to |
3945 |
identify itself (or its user) to a proxy which requires |
3946 |
authentication. The Proxy-Authorization field value consists of |
3947 |
credentials containing the authentication information of the user |
3948 |
agent for the proxy and/or realm of the resource being requested. |
3949 |
|
3950 |
Proxy-Authorization = "Proxy-Authorization" ":" credentials |
3951 |
|
3952 |
The HTTP access authentication process is described in Section 11. |
3953 |
Unlike Authorization, the Proxy-Authorization applies only to the |
3954 |
current connection and must not be passed on to upstream servers. |
3955 |
If a request is authenticated and a realm specified, the same |
3956 |
credentials should be valid for all other requests within this |
3957 |
realm. |
3958 |
|
3959 |
10.32 Public |
3960 |
|
3961 |
The Public response-header field lists the set of non-standard |
3962 |
methods supported by the server. The purpose of this field is |
3963 |
strictly to inform the recipient of the capabilities of the server |
3964 |
regarding unusual methods. The methods listed may or may not be |
3965 |
applicable to the Request-URI; the Allow header field |
3966 |
(Section 10.5) should be used to indicate methods allowed for a |
3967 |
particular URI. This does not prevent a client from trying other |
3968 |
methods. The field value should not include the methods predefined |
3969 |
for HTTP/1.1 in Section 5.1.1. |
3970 |
|
3971 |
Public = "Public" ":" 1#method |
3972 |
|
3973 |
Example of use: |
3974 |
|
3975 |
Public: OPTIONS, MGET, MHEAD |
3976 |
|
3977 |
This header field applies only to the server directly connected to |
3978 |
the client (i.e., the nearest neighbor in a chain of connections). |
3979 |
If the response passes through a proxy, the proxy must either |
3980 |
remove the Public header field or replace it with one applicable to |
3981 |
its own capabilities. |
3982 |
|
3983 |
10.33 Range |
3984 |
|
3985 |
TBS |
3986 |
|
3987 |
10.34 Referer |
3988 |
|
3989 |
The Referer request-header field allows the client to specify, for |
3990 |
the server's benefit, the address (URI) of the resource from which |
3991 |
the Request-URI was obtained. This allows a server to generate |
3992 |
lists of back-links to resources for interest, logging, optimized |
3993 |
caching, etc. It also allows obsolete or mistyped links to be |
3994 |
traced for maintenance. The Referer field must not be sent if the |
3995 |
Request-URI was obtained from a source that does not have its own |
3996 |
URI, such as input from the user keyboard. |
3997 |
|
3998 |
Referer = "Referer" ":" ( absoluteURI | relativeURI ) |
3999 |
|
4000 |
Example: |
4001 |
|
4002 |
Referer: http://www.w3.org/hypertext/DataSources/Overview.html |
4003 |
|
4004 |
If a partial URI is given, it should be interpreted relative to the |
4005 |
Request-URI. The URI must not include a fragment. |
4006 |
|
4007 |
Note: Because the source of a link may be private |
4008 |
information or may reveal an otherwise private information |
4009 |
source, it is strongly recommended that the user be able to |
4010 |
select whether or not the Referer field is sent. For |
4011 |
example, a browser client could have a toggle switch for |
4012 |
browsing openly/anonymously, which would respectively |
4013 |
enable/disable the sending of Referer and From information. |
4014 |
|
4015 |
10.35 Refresh |
4016 |
|
4017 |
TBS |
4018 |
|
4019 |
10.36 Retry-After |
4020 |
|
4021 |
The Retry-After response-header field can be used with a 503 |
4022 |
(service unavailable) response to indicate how long the service is |
4023 |
expected to be unavailable to the requesting client. The value of |
4024 |
this field can be either an HTTP-date or an integer number of |
4025 |
seconds (in decimal) after the time of the response. |
4026 |
|
4027 |
Retry-After = "Retry-After" ":" ( HTTP-date | delta-seconds ) |
4028 |
|
4029 |
Two examples of its use are |
4030 |
|
4031 |
Retry-After: Wed, 14 Dec 1994 18:22:54 GMT |
4032 |
Retry-After: 120 |
4033 |
|
4034 |
In the latter example, the delay is 2 minutes. |
4035 |
|
4036 |
10.37 Server |
4037 |
|
4038 |
The Server response-header field contains information about the |
4039 |
software used by the origin server to handle the request. The field |
4040 |
can contain multiple product tokens (Section 3.8) and comments |
4041 |
identifying the server and any significant subproducts. By |
4042 |
convention, the product tokens are listed in order of their |
4043 |
significance for identifying the application. |
4044 |
|
4045 |
Server = "Server" ":" 1*( product | comment ) |
4046 |
|
4047 |
Example: |
4048 |
|
4049 |
Server: CERN/3.0 libwww/2.17 |
4050 |
|
4051 |
If the response is being forwarded through a proxy, the proxy |
4052 |
application must not add its data to the product list. Instead, it |
4053 |
should include a Forwarded field (as described in Section 10.20). |
4054 |
|
4055 |
Note: Revealing the specific software version of the server |
4056 |
may allow the server machine to become more vulnerable to |
4057 |
attacks against software that is known to contain security |
4058 |
holes. Server implementors are encouraged to make this field |
4059 |
a configurable option. |
4060 |
|
4061 |
10.38 Title |
4062 |
|
4063 |
The Title entity-header field indicates the title of the entity |
4064 |
|
4065 |
Title = "Title" ":" *TEXT |
4066 |
|
4067 |
An example of the field is |
4068 |
|
4069 |
Title: Hypertext Transfer Protocol -- HTTP/1.1 |
4070 |
|
4071 |
This field is isomorphic with the <TITLE> element in HTML [5]. |
4072 |
|
4073 |
10.39 Transfer Encoding |
4074 |
|
4075 |
The Transfer-Encoding general-header field indicates what (if any) |
4076 |
type of transformation has been applied to the message body in |
4077 |
order to safely transfer it between the sender and the recipient. |
4078 |
This differs from the Content-Encoding in that the transfer coding |
4079 |
is a property of the message, not of the original resource. |
4080 |
|
4081 |
Transfer-Encoding = "Transfer-Encoding" ":" 1#transfer-coding |
4082 |
|
4083 |
Transfer codings are defined in Section 3.6. An example is: |
4084 |
|
4085 |
Transfer-Encoding: chunked |
4086 |
|
4087 |
Many older HTTP/1.0 applications do not understand the |
4088 |
Transfer-Encoding header. |
4089 |
|
4090 |
10.40 Unless |
4091 |
|
4092 |
The Unless request-header field performs a similar function as |
4093 |
If-Modified-Since, but the comparison is based on any Entity-Header |
4094 |
field value of the resource and is not restricted to the GET method. |
4095 |
|
4096 |
Unless = "Unless" ":" 1#logic-bag |
4097 |
|
4098 |
For example, |
4099 |
|
4100 |
Unless: {or {ne {Content-MD5 "Q2hlY2sgSW50ZWdyaXR5IQ=="}} |
4101 |
{ne {Content-Length 10036}} |
4102 |
{ne {Content-Version "12.4.8"}} |
4103 |
{gt {Last-Modified "Mon, 04 Dec 1995 01:23:45 GMT"}}} |
4104 |
|
4105 |
Multiple Unless headers, or multiple bags separated by commas, can |
4106 |
be combined by OR'ing them together: |
4107 |
|
4108 |
Unless: {eq {A "a"}} |
4109 |
Unless: {eq {B "b"}} |
4110 |
|
4111 |
is equivalent to |
4112 |
|
4113 |
Unless: {eq {A "a"}},{eq {B "b"}} |
4114 |
|
4115 |
which in turn is equivalent to |
4116 |
|
4117 |
Unless: {or {eq {A "a"}} {eq {B "b"}}} |
4118 |
|
4119 |
When a request containing an Unless header field is received, the |
4120 |
server must evaluate the expression defined by the listed |
4121 |
logic-bags (Section 3.11). If the expression evaluates to false, |
4122 |
then no change is made to the semantics of the request. If it |
4123 |
evaluates true and the request is not a conditional GET |
4124 |
(If-Modified-Since, Section 10.23) or a partial GET (Range, |
4125 |
Section 10.33), then the server must abort the request and respond |
4126 |
with the 412 (unless true) status code. If the request is a |
4127 |
conditional GET, then the server must disregard the |
4128 |
If-Modified-Since value and respond as it would for a normal GET. |
4129 |
Similarly, if the request is a partial GET, then the server must |
4130 |
disregard the Range value and respond as it would for a normal GET. |
4131 |
|
4132 |
10.41 Upgrade |
4133 |
|
4134 |
The Upgrade general-header allows the client to specify what |
4135 |
additional communication protocols it supports and would like to |
4136 |
use if the server finds it appropriate to switch protocols. The |
4137 |
server must use the Upgrade header field within a 101 (switching |
4138 |
protocols) response to indicate which protocol(s) are being |
4139 |
switched. |
4140 |
|
4141 |
Upgrade = "Upgrade" ":" 1#product |
4142 |
|
4143 |
For example, |
4144 |
|
4145 |
Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11 |
4146 |
|
4147 |
The purpose of the Upgrade header is to allow easier migration |
4148 |
across protocols in order to better match the application needs |
4149 |
with protocol capabilities. |
4150 |
|
4151 |
10.42 URI |
4152 |
|
4153 |
The URI entity-header field is used to inform the recipient of |
4154 |
other Uniform Resource Identifiers (Section 3.2) by which the |
4155 |
resource can be identified, and of all negotiable variants |
4156 |
corresponding to the Request-URI. |
4157 |
|
4158 |
URI-header = "URI" ":" 1#( uri-mirror | uri-name | uri-variant ) |
4159 |
|
4160 |
uri-mirror = "{" "mirror" <"> URI <"> "}" |
4161 |
uri-name = "{" "name" <"> URI <"> "}" |
4162 |
uri-variant = "{" "variant" <"> URI <"> qvalue |
4163 |
[ "{" "type" <"> media-type <"> "}" ] |
4164 |
[ "{" "language" <"> 1#language-tag <"> "}" ] |
4165 |
[ "{" "encoding" <"> 1#content-coding <"> "}" ] |
4166 |
[ "{" "length" 1*DIGIT "}" ] |
4167 |
[ "{" "user-agent" "}" ] |
4168 |
"}" |
4169 |
|
4170 |
Any URI specified in this field can be absolute or relative to the |
4171 |
Request-URI. The "mirror" form of URI refers to a location which is |
4172 |
a mirror copy of the Request-URI. The "name" form refers to a |
4173 |
location-independent name corresponding to the Request-URI. The |
4174 |
"variant" form refers to one of the set of negotiable variants that |
4175 |
may be retrieved via a request on the Request-URI. |
4176 |
|
4177 |
If the Request-URI maps to a set of variants, then the dimensions |
4178 |
of that variance must be given in any response containing one of |
4179 |
those variants. If the Location header field is present in a 2xx |
4180 |
response, its value identifies which one of the variants is |
4181 |
included with the response. An example is: |
4182 |
|
4183 |
Location: http://www.w3.org/pub/WWW/TheProject.en.html |
4184 |
|
4185 |
URI: {variant "TheProject.fr.html" 1.0 |
4186 |
{type "text/html"} {language "fr"}}, |
4187 |
{variant "TheProject.en.html" 1.0 |
4188 |
{type "text/html"} {language "en"}}, |
4189 |
{variant "TheProject.fr.txt" 0.7 |
4190 |
{type "text/plain"} {language "fr"}}, |
4191 |
{variant "TheProject.en.txt" 0.8 |
4192 |
{type "text/plain"} {language "en"}} |
4193 |
|
4194 |
which indicates that the negotiable Request-URI covers a group of |
4195 |
four individual resources that vary in media type and natural |
4196 |
language. The type, language, encoding, and length attributes refer |
4197 |
to their Content-* counterparts for each resource. The user-agent |
4198 |
attribute indicates that the associated URI is negotiable based on |
4199 |
the User-Agent header field. |
4200 |
|
4201 |
User agents may use this information to notify the user of |
4202 |
additional formats and to guide the process of reactive content |
4203 |
negotiation (Section 12). |
4204 |
|
4205 |
10.43 User-Agent |
4206 |
|
4207 |
The User-Agent request-header field contains information about the |
4208 |
user agent originating the request. This is for statistical |
4209 |
purposes, the tracing of protocol violations, and automated |
4210 |
recognition of user agents for the sake of tailoring responses to |
4211 |
avoid particular user agent limitations. Although it is not |
4212 |
required, user agents should include this field with requests. The |
4213 |
field can contain multiple product tokens (Section 3.8) and |
4214 |
comments identifying the agent and any subproducts which form a |
4215 |
significant part of the user agent. By convention, the product |
4216 |
tokens are listed in order of their significance for identifying |
4217 |
the application. |
4218 |
|
4219 |
User-Agent = "User-Agent" ":" 1*( product | comment ) |
4220 |
|
4221 |
Example: |
4222 |
|
4223 |
User-Agent: CERN-LineMode/2.15 libwww/2.17b3 |
4224 |
|
4225 |
10.44 WWW-Authenticate |
4226 |
|
4227 |
The WWW-Authenticate response-header field must be included in 401 |
4228 |
(unauthorized) response messages. The field value consists of at |
4229 |
least one challenge that indicates the authentication scheme(s) and |
4230 |
parameters applicable to the Request-URI. |
4231 |
|
4232 |
WWW-Authenticate = "WWW-Authenticate" ":" 1#challenge |
4233 |
|
4234 |
The HTTP access authentication process is described in Section 11. |
4235 |
User agents must take special care in parsing the WWW-Authenticate |
4236 |
field value if it contains more than one challenge, or if more than |
4237 |
one WWW-Authenticate header field is provided, since the contents |
4238 |
of a challenge may itself contain a comma-separated list of |
4239 |
authentication parameters. |
4240 |
|
4241 |
11. Access Authentication |
4242 |
|
4243 |
HTTP provides a simple challenge-response authentication mechanism |
4244 |
which may be used by a server to challenge a client request and by |
4245 |
a client to provide authentication information. It uses an |
4246 |
extensible, case-insensitive token to identify the authentication |
4247 |
scheme, followed by a comma-separated list of attribute-value pairs |
4248 |
which carry the parameters necessary for achieving authentication |
4249 |
via that scheme. |
4250 |
|
4251 |
auth-scheme = token |
4252 |
|
4253 |
auth-param = token "=" quoted-string |
4254 |
|
4255 |
The 401 (unauthorized) response message is used by an origin server |
4256 |
to challenge the authorization of a user agent. This response must |
4257 |
include a WWW-Authenticate header field containing at least one |
4258 |
challenge applicable to the requested resource. |
4259 |
|
4260 |
challenge = auth-scheme 1*SP realm *( "," auth-param ) |
4261 |
|
4262 |
realm = "realm" "=" realm-value |
4263 |
realm-value = quoted-string |
4264 |
|
4265 |
The realm attribute (case-insensitive) is required for all |
4266 |
authentication schemes which issue a challenge. The realm value |
4267 |
(case-sensitive), in combination with the canonical root URL of the |
4268 |
server being accessed, defines the protection space. These realms |
4269 |
allow the protected resources on a server to be partitioned into a |
4270 |
set of protection spaces, each with its own authentication scheme |
4271 |
and/or authorization database. The realm value is a string, |
4272 |
generally assigned by the origin server, which may have additional |
4273 |
semantics specific to the authentication scheme. |
4274 |
|
4275 |
A user agent that wishes to authenticate itself with a |
4276 |
server--usually, but not necessarily, after receiving a 401 or 411 |
4277 |
response--may do so by including an Authorization header field with |
4278 |
the request. The Authorization field value consists of credentials |
4279 |
containing the authentication information of the user agent for the |
4280 |
realm of the resource being requested. |
4281 |
|
4282 |
credentials = basic-credentials |
4283 |
| auth-scheme *("," auth-param ) |
4284 |
|
4285 |
The domain over which credentials can be automatically applied by a |
4286 |
user agent is determined by the protection space. If a prior |
4287 |
request has been authorized, the same credentials may be reused for |
4288 |
all other requests within that protection space for a period of |
4289 |
time determined by the authentication scheme, parameters, and/or |
4290 |
user preference. Unless otherwise defined by the authentication |
4291 |
scheme, a single protection space cannot extend outside the scope |
4292 |
of its server. |
4293 |
|
4294 |
If the server does not wish to accept the credentials sent with a |
4295 |
request, it should return a 401 (unauthorized) response. The |
4296 |
response must include a WWW-Authenticate header field containing |
4297 |
the (possibly new) challenge applicable to the requested resource |
4298 |
and an entity explaining the refusal. |
4299 |
|
4300 |
The HTTP protocol does not restrict applications to this simple |
4301 |
challenge-response mechanism for access authentication. Additional |
4302 |
mechanisms may be used, such as encryption at the transport level |
4303 |
or via message encapsulation, and with additional header fields |
4304 |
specifying authentication information. However, these additional |
4305 |
mechanisms are not defined by this specification. |
4306 |
|
4307 |
Proxies must be completely transparent regarding user agent |
4308 |
authentication. That is, they must forward the WWW-Authenticate and |
4309 |
Authorization headers untouched, and must not cache the response to |
4310 |
a request containing Authorization. |
4311 |
|
4312 |
HTTP/1.1 allows a client pass authentication information to and |
4313 |
from a proxy via the Proxy-Authenticate and Proxy-Authorization |
4314 |
headers. |
4315 |
|
4316 |
11.1 Basic Authentication Scheme |
4317 |
|
4318 |
The "basic" authentication scheme is based on the model that the |
4319 |
user agent must authenticate itself with a user-ID and a password |
4320 |
for each realm. The realm value should be considered an opaque |
4321 |
string which can only be compared for equality with other realms on |
4322 |
that server. The server will service the request only if it can |
4323 |
validate the user-ID and password for the protection space of the |
4324 |
Request-URI. There are no optional authentication parameters. |
4325 |
|
4326 |
Upon receipt of an unauthorized request for a URI within the |
4327 |
protection space, the server should respond with a challenge like |
4328 |
the following: |
4329 |
|
4330 |
WWW-Authenticate: Basic realm="WallyWorld" |
4331 |
|
4332 |
where "WallyWorld" is the string assigned by the server to identify |
4333 |
the protection space of the Request-URI. |
4334 |
|
4335 |
To receive authorization, the client sends the user-ID and |
4336 |
password, separated by a single colon (":") character, within a |
4337 |
base64 [7] encoded string in the credentials. |
4338 |
|
4339 |
basic-credentials = " Basic" SP basic-cookie |
4340 |
|
4341 |
basic-cookie = <base64 [7] encoding of userid-password, |
4342 |
except not limited to 76 char/line> |
4343 |
|
4344 |
userid-password = [ token ] ":" *TEXT |
4345 |
|
4346 |
If the user agent wishes to send the user-ID "Aladdin" and password |
4347 |
"open sesame", it would use the following header field: |
4348 |
|
4349 |
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== |
4350 |
|
4351 |
The basic authentication scheme is a non-secure method of filtering |
4352 |
unauthorized access to resources on an HTTP server. It is based on |
4353 |
the assumption that the connection between the client and the |
4354 |
server can be regarded as a trusted carrier. As this is not |
4355 |
generally true on an open network, the basic authentication scheme |
4356 |
should be used accordingly. In spite of this, clients should |
4357 |
implement the scheme in order to communicate with servers that use |
4358 |
it. |
4359 |
|
4360 |
11.2 Digest Authentication Scheme |
4361 |
|
4362 |
The "digest" authentication scheme is [currently described in an |
4363 |
expired Internet-Draft, and this description will have to be |
4364 |
improved to reference a new draft or include the old one]. |
4365 |
|
4366 |
12. Content Negotiation |
4367 |
|
4368 |
Content negotiation is an optional feature of the HTTP protocol. It |
4369 |
is designed to allow for selection of a preferred content |
4370 |
representation based upon the attributes of the negotiable variants |
4371 |
corresponding to the requested resource. HTTP/1.1 provides for two |
4372 |
types of negotiation: preemptive and reactive. |
4373 |
|
4374 |
Servers that make use of content negotiated resources must include |
4375 |
URI response headers which accurately describe the available |
4376 |
variants, and include the relevant parameters necessary for the |
4377 |
client (user agent or proxy) to evaluate those variants. |
4378 |
|
4379 |
12.1 Preemptive Negotiation |
4380 |
|
4381 |
Preemptive negotiation attempts to "negotiate" the variant |
4382 |
parameters by including the user agent preferences within each |
4383 |
request. In this way, the preferred representation of the resource |
4384 |
may be negotiated and obtained within a single request-response |
4385 |
round-trip, and without intervention from the user. However, this |
4386 |
also means that the user agent preferences are all the time, even |
4387 |
though relatively few resources are ever negotiable. Preemptive |
4388 |
negotiation may not always be desirable for the user and is |
4389 |
sometimes unnecessary for the content provider. Implementors should |
4390 |
provide mechanisms whereby the amount of preemptive content |
4391 |
negotiation, and the parameters of that negotiation, are |
4392 |
configurable by the user and server maintainer. |
4393 |
|
4394 |
The first step in the negotiation algorithm is for the server to |
4395 |
determine whether or not there are any content variants for the |
4396 |
requested resource. Content variants may be in the form of multiple |
4397 |
preexisting entities or a set of dynamic conversion filters. These |
4398 |
variants make up the set of entities which may be sent in response |
4399 |
to a request for the given Request-URI. In most cases, there will |
4400 |
only be one available form of the resource, and thus a single |
4401 |
"variant". |
4402 |
|
4403 |
For each variant form of the resource, the server identifies a set |
4404 |
of quality values (Section 3.9) which act as weights for measuring |
4405 |
the desirability of that resource as a response to the current |
4406 |
request. The calculated weights are all real numbers in the range 0 |
4407 |
through 1, where 0 is the minimum and 1 the maximum value. The |
4408 |
maximum acceptable bytes for each media range and the size of the |
4409 |
resource variant are also factors in the equation. |
4410 |
|
4411 |
The following parameters are included in the calculation: |
4412 |
|
4413 |
qs Source quality is measured by the content provider as |
4414 |
representing the amount of degradation from the original |
4415 |
source. For example, a picture originally in JPEG form |
4416 |
would have a lower qs when translated to the XBM format, |
4417 |
and much lower qs when translated to an ASCII-art |
4418 |
representation. Note, however, that this is a function of |
4419 |
the source -- an original piece of ASCII-art may degrade in |
4420 |
quality if it is captured in JPEG form. The qs value should |
4421 |
be assigned to each variant by the content provider; if no |
4422 |
qs value has been assigned, the default is generally |
4423 |
"qs=1". A server may define its own default qs value based |
4424 |
on the resource characteristics, but only if individual |
4425 |
resources can override those defaults. |
4426 |
|
4427 |
qe Encoding quality is measured by comparing the variant's |
4428 |
applied content-codings (Section 3.5) to those listed in |
4429 |
the request message's Accept-Encoding field. If the variant |
4430 |
has no assigned Content-Encoding, or if no Accept-Encoding |
4431 |
field is present, the value assigned is "qe=1". If all of |
4432 |
the variant's content encodings are listed in the |
4433 |
Accept-Encoding field, then the value assigned is "qe=1". |
4434 |
If any of the variant's content encodings are not listed in |
4435 |
the provided Accept-Encoding field, then the value assigned |
4436 |
is "qe=0". |
4437 |
|
4438 |
qc Charset quality is measured by comparing the variant |
4439 |
media-type's charset parameter value (if any) to those |
4440 |
character sets (Section 3.4) listed in the request |
4441 |
message's Accept-Charset field. If the variant's media-type |
4442 |
has no charset parameter, or the variant's charset is |
4443 |
US-ASCII, or if no Accept-Charset field is present, then |
4444 |
the value assigned is "qc=1". If the variant's charset is |
4445 |
listed in the Accept-Charset field, then the value assigned |
4446 |
is "qc=1". Otherwise, if the variant's charset is not |
4447 |
listed in the provided Accept-Encoding field, then the |
4448 |
value assigned is "qc=0". |
4449 |
|
4450 |
ql Language quality is measured by comparing the variant's |
4451 |
assigned language tag(s) (Section 3.10) to those listed in |
4452 |
the request message's Accept-Language field. If no variant |
4453 |
has an assigned Content-Language, or if no Accept-Language |
4454 |
field is present, the value assigned is "ql=1". If at least |
4455 |
one variant has an assigned content language, but the one |
4456 |
currently under consideration does not, then it should be |
4457 |
assigned the value "ql=0.5". If any of the variant's |
4458 |
content languages are listed in the Accept-Language field, |
4459 |
then the value assigned is the maximum of the "q" parameter |
4460 |
values for those language tags (Section 10.4); if there was |
4461 |
no exact match and at least one of the Accept-Language |
4462 |
field values is a complete subtag prefix of the content |
4463 |
language tag(s), then the "q" parameter value of the |
4464 |
largest matching prefix is used. If none of the variant's |
4465 |
content language tags or tag prefixes are listed in the |
4466 |
provided Accept-Language field, then the value assigned is |
4467 |
"ql=0.001". |
4468 |
|
4469 |
q Media type quality is measured by comparing the variant's |
4470 |
assigned media type (Section 3.7) to those listed in the |
4471 |
request message's Accept field. If no Accept field is |
4472 |
given, then the value assigned is "q=1". If at least one |
4473 |
listed media range (Section 10.1) matches the variant's |
4474 |
media type, then the "q" parameter value assigned to the |
4475 |
most specific of those matched is used (e.g., |
4476 |
"text/html;version=3.0" is more specific than "text/html", |
4477 |
which is more specific than "text/*", which in turn is more |
4478 |
specific than "*/*"). If no media range in the provided |
4479 |
Accept field matches the variant's media type, then the |
4480 |
value assigned is "q=0". |
4481 |
|
4482 |
mxb The maximum number of bytes in an Entity-Body that the |
4483 |
client will accept is also obtained from the matching of |
4484 |
the variant's assigned media type to those listed in the |
4485 |
request message's Accept field. If no Accept field is |
4486 |
given, or if no media range in the provided Accept field |
4487 |
matches the variant's media type, then the value assigned |
4488 |
is "mxb=undefined" (i.e., infinity). Otherwise, the value |
4489 |
used is that given to the "mxb" parameter in the media |
4490 |
range chosen above for the q value. |
4491 |
|
4492 |
bs The actual number of bytes in the Entity-Body for the |
4493 |
variant when it is included in a response message. This |
4494 |
should equal the value of Content-Length. |
4495 |
|
4496 |
The mapping function is defined as: |
4497 |
|
4498 |
Q(qs,qe,qc,ql, { if mxb=undefined, then (qs*qe*qc*ql*q) } |
4499 |
q,mxb,bs) = { if mxb >= bs, then (qs*qe*qc*ql*q) } |
4500 |
{ if mxb < bs, then 0 } |
4501 |
|
4502 |
The variants with a maximal value for the Q function represent the |
4503 |
preferred representation(s) of the entity; those with a Q values |
4504 |
less than the maximal value are therefore excluded from further |
4505 |
consideration. If multiple representations exist that only vary by |
4506 |
Content-Encoding, then the smallest representation (lowest bs) is |
4507 |
preferred. |
4508 |
|
4509 |
If no variants remain with a value of Q greater than zero (0), the |
4510 |
server should respond with a 406 (none acceptable) response |
4511 |
message. If multiple variants remain with an equally high Q value, |
4512 |
the server may either choose one from those available and respond |
4513 |
with 200 (ok) or respond with 300 (multiple choices) and include an |
4514 |
entity describing the choices. In the latter case, the entity |
4515 |
should either be of type "text/html', such that the user can choose |
4516 |
from among the choices by following an exact link, or of some type |
4517 |
that would allow the user agent to perform the selection |
4518 |
automatically. |
4519 |
|
4520 |
The 300 (multiple choices) response can be given even if the server |
4521 |
does not perform any winnowing of the representation choices via |
4522 |
the content negotiation algorithm described above. Furthermore, it |
4523 |
may include choices that were not considered as part of the |
4524 |
negotiation algorithm and resources that may be located at other |
4525 |
servers. |
4526 |
|
4527 |
The algorithm presented above assumes that the user agent has |
4528 |
correctly implemented the protocol and is accurately communicating |
4529 |
its intentions in the form of Accept-related header fields. The |
4530 |
server may alter its response if it knows that the particular |
4531 |
version of user agent software making the request has incorrectly |
4532 |
or inadequately implemented these fields. |
4533 |
|
4534 |
13. Caching |
4535 |
|
4536 |
[This will be a summary of what is already defined in the Methods, |
4537 |
Status Codes, Cache-Control, Unless, and If-Modified-Since |
4538 |
sections.] |
4539 |
|
4540 |
14. Security Considerations |
4541 |
|
4542 |
This section is meant to inform application developers, information |
4543 |
providers, and users of the security limitations in HTTP/1.1 as |
4544 |
described by this document. The discussion does not include |
4545 |
definitive solutions to the problems revealed, though it does make |
4546 |
some suggestions for reducing security risks. |
4547 |
|
4548 |
14.1 Authentication of Clients |
4549 |
|
4550 |
As mentioned in Section 11.1, the Basic authentication scheme is |
4551 |
not a secure method of user authentication, nor does it prevent the |
4552 |
Entity-Body from being transmitted in clear text across the |
4553 |
physical network used as the carrier. HTTP does not prevent |
4554 |
additional authentication schemes and encryption mechanisms from |
4555 |
being employed to increase security. |
4556 |
|
4557 |
14.2 Safe Methods |
4558 |
|
4559 |
The writers of client software should be aware that the software |
4560 |
represents the user in their interactions over the Internet, and |
4561 |
should be careful to allow the user to be aware of any actions they |
4562 |
may take which may have an unexpected significance to themselves or |
4563 |
others. |
4564 |
|
4565 |
In particular, the convention has been established that the GET and |
4566 |
HEAD methods should never have the significance of taking an action |
4567 |
other than retrieval. These methods should be considered "safe." |
4568 |
This allows user agents to represent other methods, such as POST, |
4569 |
PUT and DELETE, in a special way, so that the user is made aware of |
4570 |
the fact that a possibly unsafe action is being requested. |
4571 |
|
4572 |
Naturally, it is not possible to ensure that the server does not |
4573 |
generate side-effects as a result of performing a GET request; in |
4574 |
fact, some dynamic resources consider that a feature. The important |
4575 |
distinction here is that the user did not request the side-effects, |
4576 |
so therefore cannot be held accountable for them. |
4577 |
|
4578 |
14.3 Abuse of Server Log Information |
4579 |
|
4580 |
A server is in the position to save personal data about a user's |
4581 |
requests which may identify their reading patterns or subjects of |
4582 |
interest. This information is clearly confidential in nature and |
4583 |
its handling may be constrained by law in certain countries. People |
4584 |
using the HTTP protocol to provide data are responsible for |
4585 |
ensuring that such material is not distributed without the |
4586 |
permission of any individuals that are identifiable by the |
4587 |
published results. |
4588 |
|
4589 |
14.4 Transfer of Sensitive Information |
4590 |
|
4591 |
Like any generic data transfer protocol, HTTP cannot regulate the |
4592 |
content of the data that is transferred, nor is there any a priori |
4593 |
method of determining the sensitivity of any particular piece of |
4594 |
information within the context of any given request. Therefore, |
4595 |
applications should supply as much control over this information as |
4596 |
possible to the provider of that information. Four header fields |
4597 |
are worth special mention in this context: Server, Forwarded, |
4598 |
Referer and From. |
4599 |
|
4600 |
Revealing the specific software version of the server may allow the |
4601 |
server machine to become more vulnerable to attacks against |
4602 |
software that is known to contain security holes. Implementors |
4603 |
should make the Server header field a configurable option. |
4604 |
|
4605 |
Proxies which serve as a portal through a network firewall should |
4606 |
take special precautions regarding the transfer of header |
4607 |
information that identifies the hosts behind the firewall. In |
4608 |
particular, they should remove, or replace with sanitized versions, |
4609 |
any Forwarded fields generated behind the firewall. |
4610 |
|
4611 |
The Referer field allows reading patterns to be studied and reverse |
4612 |
links drawn. Although it can be very useful, its power can be |
4613 |
abused if user details are not separated from the information |
4614 |
contained in the Referer. Even when the personal information has |
4615 |
been removed, the Referer field may indicate a private document's |
4616 |
URI whose publication would be inappropriate. |
4617 |
|
4618 |
The information sent in the From field might conflict with the |
4619 |
user's privacy interests or their site's security policy, and hence |
4620 |
it should not be transmitted without the user being able to |
4621 |
disable, enable, and modify the contents of the field. The user |
4622 |
must be able to set the contents of this field within a user |
4623 |
preference or application defaults configuration. |
4624 |
|
4625 |
We suggest, though do not require, that a convenient toggle |
4626 |
interface be provided for the user to enable or disable the sending |
4627 |
of From and Referer information. |
4628 |
|
4629 |
15. Acknowledgments |
4630 |
|
4631 |
This specification makes heavy use of the augmented BNF and generic |
4632 |
constructs defined by David H. Crocker for RFC 822 [9]. Similarly, |
4633 |
it reuses many of the definitions provided by Nathaniel Borenstein |
4634 |
and Ned Freed for MIME [7]. We hope that their inclusion in this |
4635 |
specification will help reduce past confusion over the relationship |
4636 |
between HTTP and Internet mail message formats. |
4637 |
|
4638 |
The HTTP protocol has evolved considerably over the past four |
4639 |
years. It has benefited from a large and active developer |
4640 |
community--the many people who have participated on the www-talk |
4641 |
mailing list--and it is that community which has been most |
4642 |
responsible for the success of HTTP and of the World-Wide Web in |
4643 |
general. Marc Andreessen, Robert Cailliau, Daniel W. Connolly, Bob |
4644 |
Denny, John Franks, Jean-Francois Groff, Phillip M. Hallam-Baker, |
4645 |
H&kon W. Lie, Ari Luotonen, Rob McCool, Lou Montulli, Dave Raggett, |
4646 |
Tony Sanders, and Marc VanHeyningen deserve special recognition for |
4647 |
their efforts in defining early aspects of the protocol. |
4648 |
|
4649 |
This document has benefited greatly from the comments of all those |
4650 |
participating in the HTTP-WG. In addition to those already |
4651 |
mentioned, the following individuals have contributed to this |
4652 |
specification: |
4653 |
|
4654 |
Gary Adams Harald Tveit Alvestrand |
4655 |
Keith Ball Brian Behlendorf |
4656 |
Paul Burchard Maurizio Codogno |
4657 |
Mike Cowlishaw Roman Czyborra |
4658 |
Michael A. Dolan Jim Gettys |
4659 |
Marc Hedlund Koen Holtman |
4660 |
Alex Hopmann Bob Jernigan |
4661 |
Shel Kaphan Rohit Khare |
4662 |
Martijn Koster Alexei Kosut |
4663 |
Dave Kristol Daniel LaLiberte |
4664 |
Paul Leach Albert Lunde |
4665 |
John C. Mallery Jean-Philippe Martin-Flatin |
4666 |
Larry Masinter Mitra |
4667 |
Jeffrey Mogul Gavin Nicol |
4668 |
Bill Perry Jeffrey Perry |
4669 |
Owen Rees Luigi Rizzo |
4670 |
David Robinson Marc Salomon |
4671 |
Rich Salz Jim Seidman |
4672 |
Chuck Shotton Eric W. Sink |
4673 |
Simon E. Spero Richard N. Taylor |
4674 |
Robert S. Thau Franccedillaois Yergeau |
4675 |
Mary Ellen Zurko |
4676 |
|
4677 |
16. References |
4678 |
|
4679 |
[1] H. Alvestrand. "Tags for the identification of languages." RFC |
4680 |
1766, UNINETT, March 1995. |
4681 |
|
4682 |
[2] F. Anklesaria, M. McCahill, P. Lindner, D. Johnson, D. Torrey, |
4683 |
B. Alberti. "The Internet Gopher Protocol: A distributed |
4684 |
document search and retrieval protocol." RFC 1436, University |
4685 |
of Minnesota, March 1993. |
4686 |
|
4687 |
[3] T. Berners-Lee. "Universal Resource Identifiers in WWW: A |
4688 |
Unifying Syntax for the Expression of Names and Addresses of |
4689 |
Objects on the Network as used in the World-Wide Web." |
4690 |
RFC 1630, CERN, June 1994. |
4691 |
|
4692 |
[4] T. Berners-Lee, L. Masinter, M. McCahill. "Uniform Resource |
4693 |
Locators (URL)." RFC 1738, CERN, Xerox PARC, University of |
4694 |
Minnesota, December 1994. |
4695 |
|
4696 |
[5] T. Berners-Lee, D. Connolly. "HyperText Markup Language |
4697 |
Specification - 2.0." RFC 1866, MIT/LCS, November 1995. |
4698 |
|
4699 |
[6] T. Berners-Lee, R. Fielding, H. Frystyk. "Hypertext Transfer |
4700 |
Protocol - HTTP/1.0." Work in Progress |
4701 |
(draft-ietf-http-v10-spec-04.txt), MIT/LCS, UC Irvine, |
4702 |
September 1995. |
4703 |
|
4704 |
[7] N. Borenstein, N. Freed. "MIME (Multipurpose Internet Mail |
4705 |
Extensions) Part One: Mechanisms for Specifying and Describing |
4706 |
the Format of Internet Message Bodies." RFC 1521, Bellcore, |
4707 |
Innosoft, September 1993. |
4708 |
|
4709 |
[8] R. Braden. "Requirements for Internet hosts - application and |
4710 |
support." STD 3, RFC 1123, IETF, October 1989. |
4711 |
|
4712 |
[9] D. H. Crocker. "Standard for the Format of ARPA Internet Text |
4713 |
Messages." STD 11, RFC 822, UDEL, August 1982. |
4714 |
|
4715 |
[10] F. Davis, B. Kahle, H. Morris, J. Salem, T. Shen, R. Wang, |
4716 |
J. Sui, M. Grinbaum. "WAIS Interface Protocol Prototype |
4717 |
Functional Specification." (v1.5), Thinking Machines |
4718 |
Corporation, April 1990. |
4719 |
|
4720 |
[11] R. Fielding. "Relative Uniform Resource Locators." RFC 1808, UC |
4721 |
Irvine, June 1995. |
4722 |
|
4723 |
[12] M. Horton, R. Adams. "Standard for interchange of USENET |
4724 |
messages." RFC 1036 (Obsoletes RFC 850), AT&T Bell |
4725 |
Laboratories, Center for Seismic Studies, December 1987. |
4726 |
|
4727 |
[13] B. Kantor, P. Lapsley. "Network News Transfer Protocol: A |
4728 |
Proposed Standard for the Stream-Based Transmission of News." |
4729 |
RFC 977, UC San Diego, UC Berkeley, February 1986. |
4730 |
|
4731 |
[14] K. Moore. "MIME (Multipurpose Internet Mail Extensions) Part |
4732 |
Two: Message Header Extensions for Non-ASCII Text." RFC 1522, |
4733 |
University of Tennessee, September 1993. |
4734 |
|
4735 |
[15] E. Nebel, L. Masinter. "Form-based File Upload in HTML." |
4736 |
RFC 1867, Xerox Corporation, November 1995. |
4737 |
|
4738 |
[16] J. Postel. "Simple Mail Transfer Protocol." STD 10, RFC 821, |
4739 |
USC/ISI, August 1982. |
4740 |
|
4741 |
[17] J. Postel. "Media Type Registration Procedure." RFC 1590, |
4742 |
USC/ISI, March 1994. |
4743 |
|
4744 |
[18] J. Postel, J. K. Reynolds. "File Transfer Protocol (FTP)." STD |
4745 |
9, RFC 959, USC/ISI, October 1985. |
4746 |
|
4747 |
[19] J. Reynolds, J. Postel. "Assigned Numbers." STD 2, RFC 1700, |
4748 |
USC/ISI, October 1994. |
4749 |
|
4750 |
[20] K. Sollins, L. Masinter. "Functional Requirements for Uniform |
4751 |
Resource Names." RFC 1737, MIT/LCS, Xerox Corporation, December |
4752 |
1994. |
4753 |
|
4754 |
[21] US-ASCII. Coded Character Set - 7-Bit American Standard Code |
4755 |
for Information Interchange. Standard ANSI X3.4-1986, ANSI, |
4756 |
1986. |
4757 |
|
4758 |
[22] ISO-8859. International Standard -- Information Processing -- |
4759 |
8-bit Single-Byte Coded Graphic Character Sets -- |
4760 |
Part 1: Latin alphabet No. 1, ISO 8859-1:1987. |
4761 |
Part 2: Latin alphabet No. 2, ISO 8859-2, 1987. |
4762 |
Part 3: Latin alphabet No. 3, ISO 8859-3, 1988. |
4763 |
Part 4: Latin alphabet No. 4, ISO 8859-4, 1988. |
4764 |
Part 5: Latin/Cyrillic alphabet, ISO 8859-5, 1988. |
4765 |
Part 6: Latin/Arabic alphabet, ISO 8859-6, 1987. |
4766 |
Part 7: Latin/Greek alphabet, ISO 8859-7, 1987. |
4767 |
Part 8: Latin/Hebrew alphabet, ISO 8859-8, 1988. |
4768 |
Part 9: Latin alphabet No. 5, ISO 8859-9, 1990. |
4769 |
|
4770 |
17. Authors' Addresses |
4771 |
|
4772 |
Roy T. Fielding |
4773 |
Department of Information and Computer Science |
4774 |
University of California |
4775 |
Irvine, CA 92717-3425, U.S.A. |
4776 |
Fax: +1 (714) 824-4056 |
4777 |
Email: fielding@ics.uci.edu |
4778 |
|
4779 |
Henrik Frystyk Nielsen |
4780 |
W3 Consortium |
4781 |
MIT Laboratory for Computer Science |
4782 |
545 Technology Square |
4783 |
Cambridge, MA 02139, U.S.A. |
4784 |
Fax: +1 (617) 258 8682 |
4785 |
Email: frystyk@w3.org |
4786 |
|
4787 |
Tim Berners-Lee |
4788 |
Director, W3 Consortium |
4789 |
MIT Laboratory for Computer Science |
4790 |
545 Technology Square |
4791 |
Cambridge, MA 02139, U.S.A. |
4792 |
Fax: +1 (617) 258 8682 |
4793 |
Email: timbl@w3.org |
4794 |
|
4795 |
Appendices |
4796 |
|
4797 |
These appendices are provided for informational reasons only -- they |
4798 |
do not form a part of the HTTP/1.1 specification. |
4799 |
|
4800 |
A. Internet Media Type message/http |
4801 |
|
4802 |
In addition to defining the HTTP/1.1 protocol, this document serves |
4803 |
as the specification for the Internet media type "message/http". |
4804 |
The following is to be registered with IANA [17]. |
4805 |
|
4806 |
Media Type name: message |
4807 |
|
4808 |
Media subtype name: http |
4809 |
|
4810 |
Required parameters: none |
4811 |
|
4812 |
Optional parameters: version, msgtype |
4813 |
|
4814 |
version: The HTTP-Version number of the enclosed message |
4815 |
(e.g., "1.1"). If not present, the version can be |
4816 |
determined from the first line of the body. |
4817 |
|
4818 |
msgtype: The message type -- "request" or "response". If |
4819 |
not present, the type can be determined from the |
4820 |
first line of the body. |
4821 |
|
4822 |
Encoding considerations: only "7bit", "8bit", or "binary" are |
4823 |
permitted |
4824 |
|
4825 |
Security considerations: none |
4826 |
|
4827 |
B. Tolerant Applications |
4828 |
|
4829 |
Although this document specifies the requirements for the |
4830 |
generation of HTTP/1.1 messages, not all applications will be |
4831 |
correct in their implementation. We therefore recommend that |
4832 |
operational applications be tolerant of deviations whenever those |
4833 |
deviations can be interpreted unambiguously. |
4834 |
|
4835 |
Clients should be tolerant in parsing the Status-Line and servers |
4836 |
tolerant when parsing the Request-Line. In particular, they should |
4837 |
accept any amount of SP or HT characters between fields, even |
4838 |
though only a single SP is required. |
4839 |
|
4840 |
The line terminator for HTTP-header fields is the sequence CRLF. |
4841 |
However, we recommend that applications, when parsing such headers, |
4842 |
recognize a single LF as a line terminator and ignore the leading |
4843 |
CR. |
4844 |
|
4845 |
C. Relationship to MIME |
4846 |
|
4847 |
HTTP/1.1 reuses many of the constructs defined for Internet Mail |
4848 |
(RFC 822 [9]) and the Multipurpose Internet Mail Extensions |
4849 |
(MIME [7]) to allow entities to be transmitted in an open variety |
4850 |
of representations and with extensible mechanisms. However, HTTP is |
4851 |
not a MIME-compliant application. HTTP's performance requirements |
4852 |
differ substantially from those of Internet mail. Since it is not |
4853 |
limited by the restrictions of existing mail protocols and SMTP |
4854 |
gateways, HTTP does not obey some of the constraints imposed by |
4855 |
RFC 822 and MIME for mail transport. |
4856 |
|
4857 |
This appendix describes specific areas where HTTP differs from |
4858 |
MIME. Proxies/gateways to MIME-compliant protocols must be aware of |
4859 |
these differences and provide the appropriate conversions where |
4860 |
necessary. |
4861 |
|
4862 |
C.1 Conversion to Canonical Form |
4863 |
|
4864 |
MIME requires that an entity be converted to canonical form prior |
4865 |
to being transferred, as described in Appendix G of RFC 1521 [7]. |
4866 |
Although HTTP does require media types to be transferred in |
4867 |
canonical form, it changes the definition of "canonical form" for |
4868 |
text-based media types as described in Section 3.7.1. |
4869 |
|
4870 |
C.1.1 Representation of Line Breaks |
4871 |
|
4872 |
MIME requires that the canonical form of any text type represent |
4873 |
line breaks as CRLF and forbids the use of CR or LF outside of line |
4874 |
break sequences. Since HTTP allows CRLF, bare CR, and bare LF (or |
4875 |
the octet sequence(s) to which they would be translated for the |
4876 |
given character set) to indicate a line break within text content, |
4877 |
recipients of an HTTP message cannot rely upon receiving |
4878 |
MIME-canonical line breaks in text. |
4879 |
|
4880 |
Where it is possible, a proxy/gateway from HTTP to a MIME-compliant |
4881 |
protocol should translate all line breaks within text/* media types |
4882 |
to the MIME canonical form of CRLF. However, this may be |
4883 |
complicated by the presence of a Content-Encoding and by the fact |
4884 |
that HTTP allows the use of some character sets which do not use |
4885 |
octets 13 and 10 to represent CR and LF, as is the case for some |
4886 |
multi-byte character sets. If canonicalization is performed, the |
4887 |
Content-Length header field value must be updated to reflect the |
4888 |
new body length. |
4889 |
|
4890 |
C.1.2 Default Character Set |
4891 |
|
4892 |
MIME requires that all subtypes of the top-level Content-Type |
4893 |
"text" have a default character set of US-ASCII [21]. In contrast, |
4894 |
HTTP defines the default character set for "text" to be |
4895 |
ISO-8859-1 [22] (a superset of US-ASCII). Therefore, if a text/* |
4896 |
media type given in the Content-Type header field does not already |
4897 |
include an explicit charset parameter, the parameter |
4898 |
|
4899 |
;charset="iso-8859-1" |
4900 |
|
4901 |
should be added by the proxy/gateway if the entity contains any |
4902 |
octets greater than 127. |
4903 |
|
4904 |
C.2 Conversion of Date Formats |
4905 |
|
4906 |
HTTP/1.1 uses a restricted subset of date formats to simplify the |
4907 |
process of date comparison. Proxies/gateways from other protocols |
4908 |
should ensure that any Date header field present in a message |
4909 |
conforms to one of the HTTP/1.1 formats and rewrite the date if |
4910 |
necessary. |
4911 |
|
4912 |
C.3 Introduction of Content-Encoding |
4913 |
|
4914 |
MIME does not include any concept equivalent to HTTP's |
4915 |
Content-Encoding header field. Since this acts as a modifier on the |
4916 |
media type, proxies/gateways to MIME-compliant protocols must |
4917 |
either change the value of the Content-Type header field or decode |
4918 |
the Entity-Body before forwarding the message. |
4919 |
|
4920 |
Note: Some experimental applications of Content-Type for |
4921 |
Internet mail have used a media-type parameter of |
4922 |
";conversions=<content-coding>" to perform an equivalent |
4923 |
function as Content-Encoding. However, this parameter is not |
4924 |
part of the MIME specification at the time of this writing. |
4925 |
|
4926 |
C.4 No Content-Transfer-Encoding |
4927 |
|
4928 |
HTTP does not use the Content-Transfer-Encoding (CTE) field of |
4929 |
MIME. Proxies/gateways from MIME-compliant protocols must remove |
4930 |
any non-identity CTE ("quoted-printable" or "base64") encoding |
4931 |
prior to delivering the response message to an HTTP client. |
4932 |
Proxies/gateways to MIME-compliant protocols are responsible for |
4933 |
ensuring that the message is in the correct format and encoding for |
4934 |
safe transport on that protocol, where "safe transport" is defined |
4935 |
by the limitations of the protocol being used. At a minimum, the |
4936 |
CTE field of |
4937 |
|
4938 |
Content-Transfer-Encoding: binary |
4939 |
|
4940 |
should be added by the proxy/gateway if it is unwilling to apply a |
4941 |
content transfer encoding. |
4942 |
|
4943 |
An HTTP client may include a Content-Transfer-Encoding as an |
4944 |
extension Entity-Header in a POST request when it knows the |
4945 |
destination of that request is a proxy/gateway to a MIME-compliant |
4946 |
protocol. |
4947 |
|
4948 |
C.5 Introduction of Transfer-Encoding |
4949 |
|
4950 |
HTTP/1.1 introduces the Transfer-Encoding header field |
4951 |
(Section 10.39). Proxies/gateways must remove any transfer coding |
4952 |
prior to forwarding a message via a MIME-compliant protocol. The |
4953 |
process for decoding the "chunked" transfer coding (Section 3.6) |
4954 |
can be represented in pseudo-code as: |
4955 |
|
4956 |
length := 0 |
4957 |
read chunk-size and CRLF |
4958 |
while (chunk-size > 0) { |
4959 |
read chunk-data and CRLF |
4960 |
append chunk-data to Entity-Body |
4961 |
length := length + chunk-size |
4962 |
read chunk-size and CRLF |
4963 |
} |
4964 |
read entity-header |
4965 |
while (entity-header not empty) { |
4966 |
append entity-header to existing header fields |
4967 |
read entity-header |
4968 |
} |
4969 |
Content-Length := length |
4970 |
Remove "chunked" from Transfer-Encoding |
4971 |
|
4972 |
D. Changes from HTTP/1.0 |
4973 |
|
4974 |
This section will summarize the differences between versions 1.0 |
4975 |
and 1.1 of the Hypertext Transfer Protocol. |
4976 |
|