XMLHttpRequest
ObjectCopyright © 2006 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification defines the XMLHttpRequest
object, an API that provides
additional HTTP client
functionality for transferring data between a client and a server.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This is the third Working Draft of The XMLHttpRequest
Object. This document is
produced by the Web APIs WG,
part of the Rich Web Clients
Activity in the W3C Interaction Domain.
Web content and browser developers are encouraged to review this draft. Please send comments to public-webapi@w3.org, the W3C's public email list for issues related to Web APIs. Archives of the list are available.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This section is non-normative.
The XMLHttpRequest
object is
an interface exposed by a scripting engine that allows scripts to perform
HTTP client functionality, such as submitting form data or loading data
from a server.
The name of the object is XMLHttpRequest
for compatibility with
the web as it doesn't make much sense otherwise. It supports the transport
of other data formats in addition to XML, some implementations support other protocols besides
HTTP (that functionality is not covered in this specification though) and
the API supports sending data as well.
This section is non-normative.
The XMLHttpRequest
object
has been implemented for many years as ActiveX control in the Windows
Internet Explorer browser and has later been adopted by other popular web
browsers. Unfortunately the current implementations are not completely
interoperable. Based on those early implementations this specification
defines how a common subset of XMLHttpRequest
should work and this
will probably result in changes in said implementations leading to more
interoperable and useful implementations of the XMLHttpRequest
object.
Future versions of this specification (as opposed to future drafts of this version) may add new features, after careful examination from browser developers and Web content developers.
This section is non-normative.
Various [ECMAScript] examples are listed throughout the specification. In addition, you can find some below.
Some simple code to do something with data from an XML document fetched over the network:
function test(data) { // taking care of data } function handler() { if(this.readyState == 4 && this.status == 200) { // so far so good if(this.responseXML != null && this.responseXML.getElementById('test').firstChild.data) // success! test(this.responseXML.getElementById('test').firstChild.data); else test(null); } else if (this.readyState == 4 && this.status != 200) { // fetched the wrong page or network error... test(null); } } var client = new XMLHttpRequest(); client.onreadystatechange = handler; client.open("GET", "test.xml"); client.send();
If you just want to ping the server with a message you could do something like:
function ping(message) { var client = new XMLHttpRequest(); client.open("POST", "/ping"); client.send(message); }
Or if you want to check the status of a document on the server:
function fetchStatus(address) { var client = new XMLHttpRequest(); client.onreadystatechange = function() { // in case of network errors this might not give reliable results if(this.readyState == 4) returnStatus(this.status); } client.open("HEAD", address); client.send(); }
Everying in this specification is normative except for diagrams, examples, notes and sections marked non-normative.
The key words must, must not, required, shall, shall not, should, should not, recommended, may and optional in this document are to be interpreted as described in RFC 2119 [RFC2119].
This specification defines the following classes of products:
This section is non-normative.
Extensions of the APIs defined in this specification are strongly discouraged. User agents, Working Groups and other interested parties should discuss extensions on a relevant public forum, such as public-webapi@w3.org.
This section is non normative.
This specification does not include the following features that may or may not be implemented by user agents:
load
event and onload
attribute;
error
event and onerror
attribute;
progress
event and onprogress
attribute;
abort
event and onabort
attribute;
ontimeout
attribute;
responseXML
for
text/html
documents;
XMLHttpRequest
.
XMLHttpRequest
ObjectWhat if the user cancels a request by leaving the page? How does that work for multiple windows and what's the effect on the object? Need to test.
The XMLHttpRequest
interface
may be used to allow scripts to programmatically connect to their
originating server via HTTP.
Objects implementing the XMLHttpRequest
interface must also implement the EventTarget
interface
[DOM3Events].
In [ECMAScript], an instance
of XMLHttpRequest
can be
created using the XMLHttpRequest()
constructor:
var client = new XMLHttpRequest();
XMLHttpRequest
IDLThis section is non-normative.
A more complete description of what can be done with XMLHttpRequest
can be found in the
IDL below and its
associated details. It's non-normative and does not conform to [OMGIDL].
Only the language bindings are normative.
interface XMLHttpRequest { attribute EventListener onreadystatechange; readonly attribute unsigned short readyState; void open(in DOMString method, in DOMString url); void open(in DOMString method, in DOMString url, in boolean async); void open(in DOMString method, in DOMString url, in boolean async, in DOMString user); void open(in DOMString method, in DOMString url, in boolean async, in DOMString user, in DOMString password); void setRequestHeader(in DOMString header, in DOMString value); void send(); void send(in DOMString data); void send(in Document data); void abort(); DOMString getAllResponseHeaders(); DOMString getResponseHeader(in DOMString header); readonly attribute DOMString responseText; readonly attribute Document responseXML; readonly attribute unsigned short status; readonly attribute DOMString statusText; };
XMLHttpRequest
Objectonreadystatechange
of type EventListener
An attribute that takes an EventListener
as value that
must be invoked when readystatechange
is dispatched
on the object implementing the XMLHttpRequest
interface. Its initial
value must be null
.
readyState
of type
unsigned short
, readonly
The state of the object. The attribute must be one of the following values:
open()
method has been
successfully called.
open(method,
url, async, user,
password)
, method
What about multiple open()
invocations? Like behind each other
or one after invoking send()
, etc.
Calling this method must initialize the object by
remembering the method, url, async
(defaulting to true
if omitted), user
(defaulting to null
if omitted), and password
(defaulting to null
if omitted) arguments, setting the
readyState
attribute to 1
(Open), resetting the responseText
, responseXML
, status
, and statusText
attributes to their initial
values, and resetting the list of request headers.
Same-origin security restrictions should apply.
If the method argument doesn't match the method production defined in section 5.1.1 of
[RFC2616] a SYNTAX_ERR
must be raised by the user agent. If the user agent
doesn't support the given method for security reasons a
SECURITY_ERR
should be raised.
User agents must at least support the following list of methods (see [RFC2616], [RFC2518], [RFC3253], [RFC3648] and [RFC3744]):
GET
POST
HEAD
PUT
DELETE
PROPFIND
PROPPATCH
MKCOL
COPY
MOVE
LOCK
UNLOCK
VERSION-CONTROL
REPORT
CHECKOUT
CHECKIN
UNCHECKOUT
MKWORKSPACE
UPDATE
LABEL
MERGE
BASELINE-CONTROL
MKACTIVITY
ORDERPATCH
ACL
User agents should support any method argument that matches the method production.
When method case-insensitively matches GET
,
POST
, HEAD
, PUT
or
DELETE
the user agent must use the
uppercase equivalent instead.
If the url parameter doesn't match the syntax defined in
section 3.2.2 of [RFC2616] a
SYNTAX_ERR
must be raised. When a non
same-origin url argument is given user agents should throw a SECURITY_ERR
exception.
A future version or extension of this specification will define a way of doing cross-site requests.
User agents should not support the "user:password"
format in the userinfo
production defined in section 3.2.1
of [RFC3986] and must throw a SYNTAX_ERR
when doing so (not
supporting it). When they do support it, or in case of people using the
format "user", user agents must use them if the
user and password arguments are omitted. If the
arguments are not omitted, they take precedence, even if they are
null
.
If the user argument doesn't match the
username-value
production defined in section 3.2.2 of
[RFC2617] user agents must throw a SYNTAX_ERR
exception.
Need to look at the password argument.
If open()
is invoked when
readyState
is 4 (Loaded) all
members of the object must be set to their initial
values.
setRequestHeader(header,
value)
, method
This should probably say that it can only be invoked
between the invocation of open()
and the invocation of send()
given
that readyState
doesn't
accurately reflects that period.
The nominated request header (header) field value must be set to value, with the following exceptions:
readyState
attribute has a value other than 1 (Open), an
INVALID_STATE_ERR
exception must be
raised;
field-name
production as defined by
section 4.2 of [RFC2616] a
SYNTAX_ERR
must be raised;
field-value
production as defined
by section 4.2 of [RFC2616] a
SYNTAX_ERR
must be raised;
Accept-Charset
,
Accept-Encoding
, Content-Length
,
Expect
, Date
, Host
,
Keep-Alive
, Referer
, TE
,
Trailer
, Transfer-Encoding
or
Upgrade
case-insensitively.
Implementations must replace any existing value if
the nominated request header field value is one of:
Authorization
, Content-Base
,
Content-Location
, Content-MD5
,
Content-Range
, Content-Type
,
Content-Version
, Delta-Base
,
Depth
, Destination
, ETag
,
Expect
, From
, If-Modified-Since
,
If-Range
, If-Unmodified-Since
,
Max-Forwards
, MIME-Version
,
Overwrite
, Proxy-Authorization
,
SOAPAction
or Timeout
.
Otherwise, if the nominated request header field already has a value,
the new value must be combined with the existing
value (section 4.2, [RFC2616]). See
also the send()
method regarding
user agent header handling for caching, authentication, proxies, and
cookies.
// The following script: var client = new XMLHttpRequest(); client.open('GET', 'demo.cgi'); client.setRequestHeader('X-Test', 'one'); client.setRequestHeader('X-Test', 'two'); client.send(); // ...would result in the following header being sent: ... X-Test: one, two ...
The list of request headers must be reset when the
open()
method is invoked.
send(data)
, method
What about multiple send()
invocations? Note that invoking
send()
doesn't change readyState
directly which makes this
tricky.
If the readyState
attribute
has a value other than 1 (Open), an INVALID_STATE_ERR
exception must be raised. Otherwise, a request to
url using method method is sent. url,
if relative, must be resolved using
window.document.baseURI
of the window
whose
constructor is used. If the async flag is set to false, then
the method must not return until the request has
completed. Otherwise, it must return immediately.
(See: open()
.)
If data is passed to the send()
method it must be
used for the entity body following these rules (the term entity body is defined by section 7.2.1 of
[RFC2616]):
DOMString
, it must be encoded as UTF-8 for transmission.
Document
, it must be serialized using the encoding given by
data.xmlEncoding
, if specified and supported,
or UTF-8 otherwise [DOM3Core].
DOMString
or a
Document
the host language its stringification mechanisms
must be used on the argument that was passed and
the result must be treated as if data is
a DOMString
.
Invoking send()
without the
data argument must give the same result
as if it was invoked with null
as argument.
Authors should specify the
Content-Type
header via setRequestHeader
before invoking
send()
with an argument. If the
argument to send()
is a
Document
and no Content-Type
header has been
set user agents must set it to
application/xml
for XML documents and to the most
appropriate media type for other documents (using intrinsic knowledge
about the document).
If the response is an HTTP redirect (status code 301
,
302
, 303
or 307
), then it must be transparently followed (unless it violates
security, infinite loop precautions or the scheme isn't supported). Note
that HTTP ([RFC2616]) places
requirements on user agents regarding the preservation of the request
method during redirects, and also requires users to be notified of
certain kinds of automatic redirections.
Once the request has been successfully acknowledged readyState
must be
set to 2 (Sent). Immediately before receiving the message body (if any),
the readyState
attribute must be set to to 3 (Receiving). When the request has
completed loading, the readyState
attribute must be set to 4 (Loaded). In case of a
HEAD
request readyState
must be
set to 4 (Loaded) immediately after having gone to 3 (Receiving).
If something goes wrong (infinite loop, network errors) the readyState
attribute must be set to 4 (Loaded) and all other members of the
object must be set to their initial value.
In future versions of this specification user agents will
be required to dispatch an error
event if the above occurs.
If the user agent allows the specification of a proxy it should modify the request appropriately; i.e., connect to the proxy host instead of the
origin server, modify the Request-Line
and send
Proxy-Authorization
headers as specified.
If the user agent supports HTTP Authentication ([RFC2617]) it should
consider requests originating from this object to be part of the
protection space that includes the accessed URIs and send
Authorization
headers and handle 401
Unauthorised
requests appropriately. if authentication fails,
user agents should prompt the users for credentials.
If the user agent supports HTTP State Mangement
([RFC2109], [RFC2965]) it should
persist, discard and send cookies (as received in the
Set-Cookie
and Set-Cookie2
response headers,
and sent in the Cookie
header) as applicable.
If the user agent implements a HTTP cache ([RFC2616]) it should
respect Cache-Control
request headers set by the author
(e.g., Cache-Control:
no-cache
bypasses the cache). It must not
send Cache-Control
or Pragma
request headers
automatically unless the user explicitly requests such behaviour (e.g.,
by (force-)reloading the page). 304 Not Modified
responses
that are a result of a user agent generated conditional request must be presented as 200 OK
responses with
the appropriate content. Such user agents must allow
authors to override automatic cache validation by setting request
headers (e.g., If-None-Match
,
If-Modified-Since
), in which case 304 Not
Modified
responses must be passed through.
If the user agent implements server-driven content-negotiation
([RFC2616]) it should set Accept-Language
,
Accept-Encoding
and Accept-Charset
headers as
appropriate; it must not automatically set the
Accept
header. Responses to such requests must have content-codings automatically removed.
If the user agent supports Expect/Continue for request bodies
([RFC2616]) it should insert Expect
headers and handle
100 Continue
responses appropriately.
abort()
, method
When invoked, this method must cancel any network activity for which the object is responsible and set all the members of the object to their initial values.
getAllResponseHeaders()
,
method
If the readyState
attribute
has a value other than 3 (Receiving) or 4 (Loaded), user agents must raise an INVALID_STATE_ERR
exception.
Otherwise, it must return all the HTTP headers, as a
single string, with each header line separated by a CR (U+000D) LF
(U+000A) pair. The status line must not be included.
// The following script: var client = new XMLHttpRequest(); client.open("GET", "test.txt", true); client.send(); client.onreadystatechange = function() { if(this.readyState == 3) { print(this.getAllResponseHeaders()); } } // ...should output something similar to the following text: Date: Sun, 24 Oct 2004 04:58:38 GMT Server: Apache/1.3.31 (Unix) Keep-Alive: timeout=15, max=99 Connection: Keep-Alive Transfer-Encoding: chunked Content-Type: text/plain; charset=utf-8
getResponseHeader(header)
,
method
If the header argument doesn't match the field-name
production a
SYNTAX_ERR
must be raised. Otherwise
this method works as described below.
If the readyState
attribute
has a value other than 3 (Receiving) or 4 (Loaded), the user agent must raise an INVALID_STATE_ERR
exception.
Otherwise, it must represent the value of the given
HTTP header (header) in the data received so far for the last
request sent, as a single string. If more than one header of the given
name was received, then the values must be
concatenated, separated from each other by an U+002C COMMA followed by
an U+0020 SPACE. If no headers of that name were received, then it must return null
. Header names must be compared case-insensitively to the method its
argument (header).
// The following script: var client = new XMLHttpRequest(); client.open("GET", "test.txt", true); client.send(); client.onreadystatechange = function() { if(this.readyState == 3) { print(client.getResponseHeader("Content-Type")); } } // ...should output something similar to the following text: Content-Type: text/plain; charset=utf-8
responseText
of type
DOMString
, readonly
If the readyState
attribute
has a value other than 3 (Receiving) or 4 (Loaded), the user agent must raise an INVALID_STATE_ERR
exception.
Otherwise, it must be the fragment of the entity body received so far (when
readyState
is 3 (Receiving))
or the complete entity body
(when readyState
is 4
(Loaded)), interpreted as a stream of characters.
If the response includes a Content-Type
understood by the
user agent the characters are encoded following the relevant media type
specification, with the exception that the rule in the final paragraph
of section 3.7.1 of [RFC2616], and
the rules in section 4.1.2 of [RFC2046] must be
treated as if they specified the default character encoding as being
UTF-8. Invalid bytes must be converted to U+FFFD
REPLACEMENT CHARACTER. If the user agent can't derive a character stream
in accord with the media type specification, reponseText
must be null
.
Its initial value must be the null
.
responseXML
of type
Document
, readonly
If the readyState
attribute
has a value other than 4 (Loaded), user agents must
raise an INVALID_STATE_ERR
exception. Otherwise, if the
Content-Type
header contains a media type (ignoring any
parameters) that is either text/xml
,
application/xml
, or ends in +xml
, it must be an object that implements the
Document
interface representing the parsed document. If
Content-Type
did not contain such a media type, or if the
document could not be parsed (due to an XML well-formedness error or
unsupported character encoding, for instance), it must be null
.
Its initial value must be null
.
status
of type unsigned
short
, readonly
If the status
attribute is not
available an INVALID_STATE_ERR
exception must be raised. It must be available
when readyState
is 3
(Receiving) or 4 (Loaded). When available, it must
represent the HTTP status code (typically 200
for a
successful connection).
Its initial value must be 0
.
statusText
of type
DOMString
, readonly
If the statusText
attribute
is not available an INVALID_STATE_ERR
exception must be raised. It must be available
when readyState
is 3
(Receiving) or 4 (Loaded). When available, it must
represent the HTTP status text sent by the server (appears after the
status code).
Its initial value must be the empty string.
HTTP requests sent from multiple different XMLHttpRequest
objects in succession
should be pipelined into shared HTTP connections.
XMLHttpRequest
ObjectThese sections describe the various events that can be dispatched on the
object implementing the XMLHttpRequest
interface. For this
version of the specification only one event is defined.
readystatechange
readystatechange
event must be dispatched when readyState
changes value. It must not bubble, must not be
cancelable and must implement the Event
interface [DOM3Events]. The event has
no namespace (Event.namespaceURI
is null
).
This section is non-normative
The editor would like to thank to the following people who have contributed to this specification (ordered on first name):
Special thanks to the Microsoft employees who first implemented the
XMLHttpRequest
interface,
which was first widely deployed by the Windows Internet Explorer browser.
Special thanks also to the WHATWG for drafting a first version of this specification in their Web Applications 1.0 document.
Thanks also to all those who have helped to improve this specification by sending suggestions and corrections. (Please, keep bugging us with your issues!)