The XMLHttpRequest Object

This specification defines the XMLHttpRequest object, an API that provides additional HTTP client functionality for transferring data between a client and a server.

Status of this Document

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 second Working Draft of the XMLHttpRequest Object. This document is produced by the Web API 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.

Implementors should be aware that this specification is not stable. Implementors who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation stage should join the aforementioned mailing list and take part in the discussions.

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. This document is informative only. 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.

1. Introduction

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.

1.1. History

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.

What else do we want to say? Suggestions?

1.2. Examples of Usage

This section is non-normative.

Various examples are listed throughout the specification.

Need to write this or get some text...

1.3. Security Considerations

This section is non-normative.

Implementations that run code originating from untrusted sources will probably want to place additional constraints on some of the features defined in this specification. This is not required and an implementation is free to ignore this section.

The restrictions are there to stop untrusted users of the API from using the implementation to retrieve sensitive data. Specifically, an implementation in a web browser will often want to restrict pages from a website A to retrieve data from website B. The reason for this is that website B could reside inside a corporate firewall. If data could be retrieved from website B then website A could use the browser effectively circumvent the firewall.

Another possible security attack exists if website B requires authentication, like for example a web bank. If website A were allowed to access data from website B and the user had recently visited the bank and at that time logged in, the page from website A would have access to private information like statements. If correctly crafted, a page from website A could even initiate transactions transferring money out of the browser-users bank account.

To stop these attacks the implementation should only allow a page loaded from website A to access other pages on the same website. Two websites are considered separate if they use separate DNS names, even if these names refer to the same IP. This is because the two websites could be hosted at a hosting service that place several websites on a single server and then use the requested hostname to choose which website to serve. Additionally, separate TCP port numbers or separate protocols (like http vs. https) are considered as separate websites.

The implemtation must be careful to always restrict access to the same website, not just during the initial HTTP request. For example if that request results in a redirect the implemenation should check that the redirect points to the same website and otherwise deny access.

Another feature that an implementation could limit is the setRequestHeader method. If the implementation allows the Host header to be set and two websites are hosted on the same server one website might be able to access sensitive information from the other website.

...

Has to address restrictions on methods as well, etc.

1.4. Terminology

Perhaps use this text inline rather than here?

The term entity body is used in this specification as defined by RFC 2616 ([RFC2616], section 7.2.1).

The term reset either means that respective member MUST be set to its initial value or each member of the object, depending on how it's used.

The cached base URI MUST be window.document.baseURI once an XMLHttpRequest object is initialized. Specifically, the window that the XMLHttpRequest constructor comes from, not the calling window [Window].

1.5. Conformance

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:

conforming implementation: A UA that implements all interfaces described in this specification and follows all MUST-, REQUIRED- and SHALL-level of critera in this specification.
conforming document: A document that follows all MUST-, REQUIRED- and SHALL-level of critera in this specification that apply to document authors.
conforming authoring tool: One that produces conforming documents.

Not sure if all apply.

1.6. Extensibility

Extensions to the XMLHttpRequest interface are reserved for future work by the Web APIs WG. WGs besides the Web APIs WG may extend the interface, but MUST coordinate that with the Web APIs WG. UAs MAY extend the interface, but MUST prefix the new members using a string specific to the vendor following the VendorMember scheme. (Normally members follow the member scheme.) Company Foo could introduce a FooFollowRedirect(boolean) method for example.

Authors MAY use extension mechanisms specific to the host language, like .prototype in ECMAScript.

This should be in DOM Level 3 Core I suppose.

1.7. Not in this Specification

This specification does not include the following features that may or may not be implemented by UAs:

load event and onload attribute;
error event and onerror attribute;
progress event and onprogress attribute;
abort event and onabort attribute;
Timers have been suggested, perhaps an ontimeout attribute;
Property to disable following redirects;
responseXML for text/html documents;
Cross-site XMLHttpRequest.

2. The `XMLHttpRequest` Object

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 [DOM3EV].

In ECMAScript [ECMA262], an instance of XMLHttpRequest can be created using the XMLHttpRequest() constructor:

Example: XMLHttpRequest Constructor

var client = new XMLHttpRequest();

What about non-ECMAScript implementations?

A more complete description of what can be done with XMLHttpRequest can be found in the IDL below and its associated details. The IDL is non-normative and does not intend to conform to [OMGIDL]. Only the language bindings are normative.

The XMLHttpRequest Interface

interface XMLHttpRequest {

           attribute EventListener   onreadystatechange;
  readonly attribute unsigned short  readyState;
  void               open(in DOMString method, in DOMString uri);
  void               open(in DOMString method, in DOMString uri, in boolean async);
  void               open(in DOMString method, in DOMString uri, in boolean async, in DOMString user);
  void               open(in DOMString method, in DOMString uri, in boolean async, in DOMString user, in DOMString password);
  void               setRequestHeader(in DOMString header, in DOMString value)
                                        raises(DOMException);
  void               send(in DOMString data)
                                        raises(DOMException);
  void               send(in Document data)
                                        raises(DOMException);
  void               abort();
  DOMString          getAllResponseHeaders();
  DOMString          getResponseHeader(in DOMString header);
           attribute DOMString       responseText;
           attribute Document        responseXML;
           attribute unsigned short  status;
                                        // raises(DOMException) on retrieval
           attribute DOMString       statusText;
                                        // raises(DOMException) on retrieval
};

Attributes

onreadystatechange 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:

0 Uninitialized: The initial value.
1 Open: The open() method has been successfully called.
2 Sent: The UA successfully completed the request, but no data has yet been received.
3 Receiving: Immediately before receiving the message body (if any). All HTTP headers have been received.
4 Loaded: The data transfer has been completed.

responseText of type DOMString

If the readyState attribute has a value other than 3 (Receiving) or 4 (Loaded), responseText MUST be the empty string. 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 UA 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 UA can't derive a character stream in accord with the media type specification, reponseText MUST be null.

responseXML of type Document

If the readyState attribute has a value other than 4 (Loaded), it MUST be null. 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.

status of type unsigned short

If the status attribute is not available it MUST raise an exception. 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).

Exceptions on retrieval

DOMException

INVALID_STATE_ERR MUST be raised when this attribute is accessed when readyState has an inappropriate value.

statusText of type DOMString

If the statusText attribute is not available it MUST raise an exception. 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).

Exceptions on retrieval

DOMException

INVALID_STATE_ERR MUST be raised if this attribute is accessed when readyState has an inappropriate value.

Methods

abort

When invoked, this method MUST cancel any network activity for which the object is responsible and reset the object.

No Parameters
No Return Value
No Exceptions

getAllResponseHeaders

If the readyState attribute has a value other than 3 (Receiving) or 4 (Loaded), it MUST return null. 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.

Example: Manipulating Response Headers

// The following script:
var client = new XMLHttpRequest();
client.open('GET', 'test.txt', false);
client.send();
print(client.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

No Parameters

Return Value

A single string consisting of all HTTP headers. See prose for details.

No Exceptions

getResponseHeader

If the readyState attribute has a value other than 3 (Receiving) or 4 (Loaded), it MUST return the empty string. Otherwise, it MUST represent the value of the given HTTP 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 the empty string. Header names MUST be compared case-insensitively to the method its argument (header).

Case-insensitively how?

Needs to be revised largely based on Mark's comments.

Example: Getting a Response Header

// The following script:
var client = new XMLHttpRequest();
client.open('GET', 'test.txt', false);
client.send();
print(client.getResponseHeader('Content-Type'));

// ...should output something similar to the following text:
Content-Type: text/plain; charset=utf-8

Parameters

header of type DOMString: Name of the HTTP header.

Return Value

Value of the given HTTP header.

No Exceptions

open

Calling this method MUST initialize the object by remembering the method, uri, 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 URI given to this method contains userinfo ([RFC3986], section 3.2.1) then the user name and password specified MUST be used if the user and password arguments are omitted. If the arguments are not omitted, they take precedence, even if they are null. The usage of userinfo is discouraged MAY not work in implementations.

If open() is called when readyState is 4 (Loaded) the entire object MUST be reset.

Parameters

method of type DOMString: A valid HTTP method name. The GET, POST, PUT, DELETE and HEAD values MUST be supported [RFC2616].
uri of type DOMString: A URI, which MUST be resolved to an absolute URI using the cached base URI.
async of type boolean, optional: Whether or not script execution can continue.
user of type DOMString, optional: Username.
password of type DOMString, optional: Password.

No Return Value

No Exceptions

send

If the readyState attribute has a value other than 1 (Open), an exception MUST be raised. Otherwise, the readyState attribute MUST be set to 2 (Sent) and a request to uri using method method is sent. 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 passed to the send() method it MUST be used for the entity body following these rules:

If data is a DOMString, it MUST be encoded as UTF-8 for transmission.
If the data is a Document, it MUST be serialized using the encoding given by data.xmlEncoding, if specified and supported, or UTF-8 otherwise [DOM3].
If data is not a DOMString or a Document the host language its stringification mechanisms MUST be used on the argument that was passed and the result MUST be encoded as UTF-8 for transmission.

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 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 UAs regarding the preservation of the request method during redirects, and also requires users to be notified of certain kinds of automatic redirections.

If the UA 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 UA 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, UAs should prompt the users for credentials.

If the UA 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 UA 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 UA-generated conditional request MUST be presented as 200 OK responses with the appropriate content. Such UAs 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 UA 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.

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) immediatly after having gone to 3 (Receiving).

If the UA supports Expect/Continue for request bodies [RFC2616] it SHOULD insert Expect headers and handle 100 Continue responses appropriately.

Parameters

data of varying types (see IDL): Data to send.

No Return Value

Exceptions

DOMException

INVALID_STATE_ERR MUST be raised if this method is called when readyState has an inappropriate value.

setRequestHeader

The nominated request header (header) field value MUST be set to value, with the following exceptions:

If the readyState attribute has a value other than 1 (Open), an exception MUST be raised.
Nothing MUST be done if the header or value arguments contain any U+000A LINE FEED or U+000D CARRIAGE RETURN characters, or if the header argument contains any U+0020 SPACE or U+003A COLON charecters.
Nothing MUST be done if the header argument matches Accept-Charset, Accept-Encoding, Content-Length, Expect, Date, Host, Keep-Alive, Referer, TE, Trailer, Transfer-Encoding or Upgrade case-insensitively.

Example: Setting a Request Header

// The following script:
var client = new XMLHttpRequest();
client.open('GET', 'demo.cgi');
client.setRequestHeader('X-Test', 'one');
client.setRequestHeader('X-Test', 'two');
client.send(null);

// ...would result in the following header being sent:
...
X-Test: one, two
...

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, Destinaion, 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 UA header handling for caching, authentication, proxies, and cookies.

The list of request headers must be reset when the open() method is called.

Parameters

header of type DOMString: Name of the HTTP header.
value of type DOMString: Value of the HTTP header.

No Return Value

Exceptions

DOMException

INVALID_STATE_ERR MUST be raised if readyState has an inappropriate value. (See prose above.)

HTTP requests sent from multiple different XMLHttpRequest objects in succession SHOULD be pipelined into shared HTTP connections.

3. Events

These 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: The readystatechange event MUST be dispatched when readyState changes value. It MUST NOT bubble, MUST NOT be cancelable and MUST implement the Event interface [DOM3EV]. The event has no namespace (Event.namespaceURI is null).

A. References

DOM3: Document Object Model (DOM) Level 3 Core Specification, Arnaud Le Hors (IBM), Philippe Le Hégaret (W3C), Lauren Wood (SoftQuad, Inc.), Gavin Nicol (Inso EPS), Jonathan Robie (Texcel Research and Software AG), Mike Champion (Arbortext and Software AG), and Steve Byrne (JavaSoft).
DOM3EV: Document Object Model (DOM) Level 3 Events Specification, Philippe Le Hégaret (W3C), and Tom Pixley (Netscape Communications Corporation).
RFC2119: Key words for use in RFCs to Indicate Requirement Levels, S. Bradner.
RFC2616: Hypertext Transfer Protocol -- HTTP/1.1, R. Fielding (UC Irvine), J. Gettys (Compaq/W3C), J. Mogul (Compaq), H. Frystyk (W3C/MIT), L. Masinter (Xerox), P. Leach (Microsoft), and T. Berners-Lee (W3C/MIT).

B. Acknowledgements

This section is non-normative

Asbjørn Ulsberg
Boris Zbarsky
Björn Höhrmann
Cameron McCormack
Christophe Jolif
Charles McCathieNevile
Dean Jackson
Doug Schepers
Douglas Livingstone
Gorm Haug Eriksen
Hallvord R. M. Steen
Håkon Wium Lie
Ian Davis
Ian Hickson
Ivan Herman
Jens Lindström
Jim Deegan
Jim Ley
Jonas Sicking
Julian Reschke
Karl Dubost
Maciej Stachowiak
Marc Hadley
Mark Nottingham
Pawel Glowacki
Robin Berjon

Special thanks also 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 drafing 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!)

(By the way, if you contributed to this specification in any way and you are not listed in this appendix please e-mail either editor directly.)

The XMLHttpRequest Object

W3C Working Draft 19 June 2006

Abstract

Status of this Document

Table of Contents

1. Introduction

1.1. History

1.2. Examples of Usage

1.3. Security Considerations

1.4. Terminology

1.5. Conformance

1.6. Extensibility

1.7. Not in this Specification

2. The `XMLHttpRequest` Object

Attributes

Methods

3. Events

A. References

B. Acknowledgements

The XMLHttpRequest Object

W3C Working Draft 19 June 2006

Abstract

Status of this Document

Table of Contents

1. Introduction

1.1. History

1.2. Examples of Usage

1.3. Security Considerations

1.4. Terminology

1.5. Conformance

1.6. Extensibility

1.7. Not in this Specification

2. The XMLHttpRequest Object

Attributes

Methods

3. Events

A. References

B. Acknowledgements

2. The `XMLHttpRequest` Object