XMLHttpRequest

Living Standard — Last Updated 19 March 2014

This Version:
http://xhr.spec.whatwg.org/
Participate:
Send feedback to public-webapps@w3.org (archives) or file a bug (open bugs)
IRC: #whatwg on Freenode
Version History:
https://github.com/whatwg/xhr/commits
Editor:
Anne van Kesteren (Mozilla) <annevk@annevk.nl>

Abstract

XMLHttpRequest defines an API that provides scripted client functionality for transferring data between a client and a server.

Table of Contents

  1. 1 Introduction
    1. 1.1 Specification history
  2. 2 Conformance
    1. 2.1 Extensibility
  3. 3 Terminology
  4. 4 Interface XMLHttpRequest
    1. 4.1 Constructors
    2. 4.2 Garbage collection
    3. 4.3 Event handlers
    4. 4.4 States
    5. 4.5 Request
      1. 4.5.1 The open() method
      2. 4.5.2 The setRequestHeader() method
      3. 4.5.3 The timeout attribute
      4. 4.5.4 The withCredentials attribute
      5. 4.5.5 The upload attribute
      6. 4.5.6 The send() method
      7. 4.5.7 The abort() method
    6. 4.6 Response
      1. 4.6.1 The responseURL attribute
      2. 4.6.2 The status attribute
      3. 4.6.3 The statusText attribute
      4. 4.6.4 The getResponseHeader() method
      5. 4.6.5 The getAllResponseHeaders() method
      6. 4.6.6 Response entity body
      7. 4.6.7 The overrideMimeType() method
      8. 4.6.8 The responseType attribute
      9. 4.6.9 The response attribute
      10. 4.6.10 The responseText attribute
      11. 4.6.11 The responseXML attribute
    7. 4.7 Events summary
  5. 5 Interface FormData
  6. 6 Interface ProgressEvent
    1. 6.1 Firing events using the ProgressEvent interface for Fetch
    2. 6.2 Firing events using the ProgressEvent interface for other contexts
    3. 6.3 Suggested names for events using the ProgressEvent interface
    4. 6.4 Security Considerations
    5. 6.5 Example
  7. References
  8. Acknowledgments

1 Introduction

This section is non-normative.

The XMLHttpRequest object is an API for fetching resources.

The name XMLHttpRequest is historical and has no baring on its functionality.

Some simple code to do something with data from an XML document fetched over the network:

function processData(data) {
  // taking care of data
}

function handler() {
  if(this.readyState == this.DONE) {
    if(this.status == 200 &&
       this.responseXML != null &&
       this.responseXML.getElementById('test').textContent) {
      // success!
      processData(this.responseXML.getElementById('test').textContent);
      return;
    }
    // something went wrong
    processData(null);
  }
}

var client = new XMLHttpRequest();
client.onreadystatechange = handler;
client.open("GET", "unicorn.xml");
client.send();

If you just want to log a message to the server:

function log(message) {
  var client = new XMLHttpRequest();
  client.open("POST", "/log");
  client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8");
  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 == this.DONE)
      returnStatus(this.status);
  }
  client.open("HEAD", address);
  client.send();
}

1.1 Specification history

The XMLHttpRequest object was initially defined as part of the WHATWG's HTML effort. (Long after Microsoft shipped an implementation.) It moved to the W3C in 2006. Extensions (e.g. progress events and cross-origin requests) to XMLHttpRequest were developed in a separate draft (XMLHttpRequest Level 2) until end of 2011, at which point the two drafts were merged and XMLHttpRequest became a single entity again from a standards perspective. End of 2012 it moved back to the WHATWG.

Historical discussion can be found in the following mailing list archives:

2 Conformance

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this specification are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]

2.1 Extensibility

User agents, Working Groups, and other interested parties are strongly encouraged to discuss new features with the WHATWG community.

3 Terminology

This specification uses terminology, cross-linked throughout, from DOM, DOM Parsing and Serialization, Encoding, Fetch, File API, HTML, HTTP, Typed Array, URL, Web IDL, and XML. [DOM] [DOMPS] [ENCODING] [FETCH] [FILEAPI] [HTML] [HTTP] [TYPEDARRAY] [URL] [WEBIDL] [XML] [XMLNS]

It uses the typographic conventions from HTML. [HTML]

The term user credentials for the purposes of this specification means cookies, HTTP authentication, and client-side SSL certificates. Specifically it does not refer to proxy authentication or the Origin header. [COOKIES]

4 Interface XMLHttpRequest

[NoInterfaceObject]
interface XMLHttpRequestEventTarget : EventTarget {
  // event handlers
  attribute EventHandler onloadstart;
  attribute EventHandler onprogress;
  attribute EventHandler onabort;
  attribute EventHandler onerror;
  attribute EventHandler onload;
  attribute EventHandler ontimeout;
  attribute EventHandler onloadend;
};

[Exposed=Window,Worker]
interface XMLHttpRequestUpload : XMLHttpRequestEventTarget {
};

enum XMLHttpRequestResponseType {
  "",
  "arraybuffer",
  "blob",
  "document",
  "json",
  "text"
};

[Constructor,
 Exposed=Window,Worker]
interface XMLHttpRequest : XMLHttpRequestEventTarget {
  // event handler
  attribute EventHandler onreadystatechange;

  // states
  const unsigned short UNSENT = 0;
  const unsigned short OPENED = 1;
  const unsigned short HEADERS_RECEIVED = 2;
  const unsigned short LOADING = 3;
  const unsigned short DONE = 4;
  readonly attribute unsigned short readyState;

  // request
  void open(ByteString method, [EnsureUTF16] DOMString url);
  void open(ByteString method, [EnsureUTF16] DOMString url, boolean async, optional [EnsureUTF16] DOMString? username = null, optional [EnsureUTF16] DOMString? password = null);
  void setRequestHeader(ByteString name, ByteString value);
           attribute unsigned long timeout;
           attribute boolean withCredentials;
  readonly attribute XMLHttpRequestUpload upload;
  void send(optional (ArrayBufferView or Blob or Document or [EnsureUTF16] DOMString or FormData or URLSearchParams)? data = null);
  void abort();

  // response
  readonly attribute DOMString responseURL;
  readonly attribute unsigned short status;
  readonly attribute ByteString statusText;
  ByteString? getResponseHeader(ByteString name);
  ByteString getAllResponseHeaders();
  void overrideMimeType(DOMString mime);
           attribute XMLHttpRequestResponseType responseType;
  readonly attribute any response;
  readonly attribute DOMString responseText;
  [Exposed=Window] readonly attribute Document? responseXML;
};

Each XMLHttpRequest object has a unique, associated XMLHttpRequestUpload object.

4.1 Constructors

The XMLHttpRequest object has an associated settings object.

client = new XMLHttpRequest()
Returns a new XMLHttpRequest object.

The XMLHttpRequest() constructor must run these steps:

  1. Let xhr be a new XMLHttpRequest object.

  2. Set xhr's settings object to the relevant settings object for the global object of xhr's interface object.

  3. Return xhr.

4.2 Garbage collection

An XMLHttpRequest object must not be garbage collected if its state is OPENED and the send() flag is set, its state is HEADERS_RECEIVED, or its state is LOADING, and one of the following is true:

If an XMLHttpRequest object is garbage collected while its connection is still open, the user agent must terminate the request.

4.3 Event handlers

The following are the event handlers (and their corresponding event handler event types) that must be supported on objects implementing an interface that inherits from XMLHttpRequestEventTarget as attributes:

event handler event handler event type
onloadstart loadstart
onprogress progress
onabort abort
onerror error
onload load
ontimeout timeout
onloadend loadend

The following is the event handler (and its corresponding event handler event type) that must be supported as attribute solely by the XMLHttpRequest object:

event handler event handler event type
onreadystatechange readystatechange

4.4 States

client . readyState

Returns the current state.

The XMLHttpRequest object can be in several states. The readyState attribute must return the current state, which must be one of the following values:

UNSENT (numeric value 0)

The object has been constructed.

OPENED (numeric value 1)

The open() method has been successfully invoked. During this state request headers can be set using setRequestHeader() and the request can be made using the send() method.

HEADERS_RECEIVED (numeric value 2)

All redirects (if any) have been followed and all HTTP headers of the final response have been received. Several response members of the object are now available.

LOADING (numeric value 3)

The response entity body is being received.

DONE (numeric value 4)

The data transfer has been completed or something went wrong during the transfer (e.g. infinite redirects).

The send() flag indicates that the send() method has been invoked. It is initially unset and is used during the OPENED state.

4.5 Request

Each XMLHttpRequest object has the following request-associated concepts: request method, request URL, author request headers, request entity body, synchronous flag, upload complete flag, and upload events flag.

The author request headers is an initially empty list of headers.

The request entity body is initially null.

The synchronous flag, upload complete flag, and upload events flag are initially unset.


To terminate the request, terminate the fetch algorithm operated by the XMLHttpRequest object with reason fatal.

4.5.1 The open() method

client . open(method, url [, async = true [, username = null [, password = null]]])

Sets the request method, request URL, and synchronous flag.

Throws a "SyntaxError" exception if either method is not a valid HTTP method or url cannot be parsed.

Throws a "SecurityError" exception if method is a case-insensitive match for `CONNECT`, `TRACE` or `TRACK`.

Throws an "InvalidAccessError" exception if async is false, the JavaScript global environment is a document environment, and either the timeout attribute is not zero, the withCredentials attribute is true, or the responseType attribute is not the empty string.

Developers must not pass false for the async argument when the JavaScript global environment is a document environment as it has detrimental effects to the end user's experience. User agents are strongly encouraged to warn about such usage in developer tools and may experiment with throwing an "InvalidAccessError" exception when it occurs so the feature can eventually be removed from the platform.

The open(method, url, async, username, password) method must run these steps:

  1. If settings object's responsible document is not fully active, throw an "InvalidStateError" exception.

  2. Set base to settings object's API base URL.

  3. If method does not match the Method token production, throw a "SyntaxError" exception.

  4. If method is a forbidden method, throw a "SecurityError" exception.

  5. If method is a case-insensitive match for `DELETE`, `GET`, `HEAD`, `OPTIONS`, `POST`, or `PUT`, subtract 0x20 from each byte in the range 0x61 (ASCII a) to 0x7A (ASCII z).

    If it does not match any of the above, it is passed through literally, including in the final request.

  6. Let parsedURL be the result of parsing url with base.

  7. If parsedURL is failure, throw a "SyntaxError" exception.

  8. If the async argument is omitted, set async to true, and set username and password to null.

    Due to unfortunate legacy constraints, passing undefined for the async argument is treated differently from async being omitted.

  9. If parsedURL's relative flag is set, run these substeps:

    1. If the username argument is not null, set parsedURL's username to username.

    2. If the password argument is not null, set parsedURL's password to password.

  10. If async is false, the JavaScript global environment is a document environment, and either the timeout attribute value is not zero, the withCredentials attribute value is true, or the responseType attribute value is not the empty string, throw an "InvalidAccessError" exception.

  11. Terminate the request.

    After all, a request can be ongoing at this point.

  12. Set variables associated with the object as follows:

  13. If the state is not OPENED, run these substeps:

    1. Change the state to OPENED.

    2. Fire an event named readystatechange.

4.5.2 The setRequestHeader() method

client . setRequestHeader(name, value)

Appends an header to author request headers, or if name is already a header's name in author request headers, appends value to that header's value.

Throws an "InvalidStateError" exception if the state is not OPENED or if the send() flag is set.

Throws a "SyntaxError" exception if name is not a valid HTTP header field name or if value is not a valid HTTP header field value.

As indicated in the algorithm below certain headers cannot be set and are left up to the user agent. In addition there are certain other headers the user agent will take control of if they are not set by the author as indicated at the end of the send() method section.

The setRequestHeader(name, value) method must run these steps:

  1. If the state is not OPENED, throw an "InvalidStateError" exception.

  2. If the send() flag is set, throw an "InvalidStateError" exception.

  3. If name does not match the field-name production, throw a "SyntaxError" exception.

  4. If value does not match the field-value production, throw a "SyntaxError" exception.

    An empty string represents an empty header field value.

  5. Terminate these steps if name is a forbidden author header name.

  6. If name is not a name of a header in author request headers, append a header whose name is name and value is value to author request headers.

  7. Otherwise, append `,`, followed by 0x20, followed by value, to the value of the header in author request headers whose name is name.

    The XMLHttpRequest standard intentionally constraints the use of HTTP here in line with contemporary implementations.

Some simple code demonstrating what happens when setting the same header twice:

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

// …results in the following header being sent:
X-Test: one, two

4.5.3 The timeout attribute

client . timeout

Can be set to a time in milliseconds. When set to a non-zero value will cause fetching to terminate after the given time has passed. When the time has passed, the request has not yet completed, and the synchronous flag is unset, a timeout event will then be dispatched, or a "TimeoutError" exception will be thrown otherwise (for the send() method).

When set: throws an "InvalidAccessError" exception if the synchronous flag is set and the JavaScript global environment is a document environment.

The timeout attribute must return its value. Initially its value must be zero.

Setting the timeout attribute must run these steps:

  1. If the JavaScript global environment is a document environment and the synchronous flag is set, throw an "InvalidAccessError" exception.

  2. Set its value to the new value.

This implies that the timeout attribute can be set while fetching is in progress. If that occurs it will still be measured relative to the start of fetching.

4.5.4 The withCredentials attribute

client . withCredentials

True when user credentials are to be included in a cross-origin request. False when they are to be excluded in a cross-origin request and when cookies are to be ignored in its response. Initially false.

When set: throws an "InvalidStateError" exception if the state is not UNSENT or OPENED, or if the send() flag is set.

When set: throws an "InvalidAccessError" exception if either the synchronous flag is set and the JavaScript global environment is a document environment.

The withCredentials attribute must return its value. Initially its value must be false.

Setting the withCredentials attribute must run these steps:

  1. If the state is not UNSENT or OPENED, throw an "InvalidStateError" exception.

  2. If the send() flag is set, throw an "InvalidStateError" exception.

  3. If the JavaScript global environment is a document environment and the synchronous flag is set, throw an "InvalidAccessError" exception.

  4. Set the withCredentials attribute's value to the given value.

The withCredentials attribute has no effect when fetching same-origin resources.

4.5.5 The upload attribute

client . upload

Returns the associated XMLHttpRequestUpload object. It can be used to gather transmission information when data is transferred to a server.

The upload attribute must return the associated XMLHttpRequestUpload object.

As indicated earlier, each XMLHttpRequest object has an associated XMLHttpRequestUpload object.

4.5.6 The send() method

client . send([data = null])

Initiates the request. The optional argument provides the request entity body. The argument is ignored if request method is GET or HEAD.

Throws an "InvalidStateError" exception if the state is not OPENED or if the send() flag is set.

The send(data) method must run these steps:

  1. If the state is not OPENED, throw an "InvalidStateError" exception.

  2. If the send() flag is set, throw an "InvalidStateError" exception.

  3. If the request method is GET or HEAD, set data to null.

  4. If data is null, do not include a request entity body and go to the next step.

    Otherwise, let encoding be null, mime type be null, and then follow these rules, depending on data:

    ArrayBufferView

    Let the request entity body be the raw data represented by data.

    Blob

    If the object's type attribute value is not the empty string, let mime type be its value.

    See also Blob's type attribute.

    Let the request entity body be the raw data represented by data.

    document

    Let encoding be "UTF-8".

    If data is an HTML document, let mime type be "text/html", or let mime type be "application/xml" otherwise. Then append ";charset=UTF-8" to mime type.

    Let the request entity body be data, serialized, converted to Unicode, and utf-8 encoded. Re-throw any exception serializing throws.

    If data cannot be serialized, an "InvalidStateError" exception is thrown.

    a string

    Let encoding be "UTF-8".

    Let mime type be "text/plain;charset=UTF-8".

    Let the request entity body be data, utf-8 encoded.

    FormData

    Let the request entity body be the result of running the multipart/form-data encoding algorithm with data as form data set and with utf-8 as the explicit character encoding.

    Let mime type be the concatenation of "multipart/form-data;", a U+0020 SPACE character, "boundary=", and the multipart/form-data boundary string generated by the multipart/form-data encoding algorithm.

    URLSearchParams

    Let the request entity body be the result of running the application/x-www-form-urlencoded serializer with data's associated list of name-value pairs as pairs.

    Let mime type be "application/x-www-form-urlencoded;charset=UTF-8".

    If a Content-Type header is in author request headers and its value is a valid MIME type that has a charset parameter whose value is not a case-insensitive match for encoding, and encoding is not null, set all the charset parameters of that Content-Type header to encoding.

    If no Content-Type header is in author request headers and mime type is not null, append a Content-Type header with value mime type to author request headers.

  5. If the synchronous flag is set, release the storage mutex.

  6. Unset the upload complete flag and upload events flag.

  7. If there is no request entity body or if it is empty, set the upload complete flag.

  8. If the synchronous flag is unset and one or more event listeners are registered on the XMLHttpRequestUpload object, set the upload events flag.

  9. If the synchronous flag is unset, run these substeps:

    1. Set the send() flag.

    2. Fire a progress event named loadstart.

    3. If the upload complete flag is unset, fire an upload progress event named loadstart on the XMLHttpRequestUpload object.

    4. Return the send() method call, but continue running the steps in this algorithm.

  10. Let req be a new request, initialized as follows:

    method
    request method
    url
    request URL
    author headers
    author request headers
    origin
    settings object's origin
    force Origin header flag
    Set.
    referrer
    settings object's API referrer source's URL if settings object's API referrer source is a document, and settings object's API referrer source otherwise
    body
    request entity body
    synchronous flag
    Set if the synchronous flag is set.
    mode
    CORS
    force preflight flag
    Set if the upload events flag is set.
    omit credentials mode
    If the withCredentials attribute value is true, never, and CORS otherwise.
    use URL credentials flag
    Set if either request URL's username is not the empty string or request URL's password is non-null.
  11. If a header named `Accept-Language` is not in req's author headers, append one with an appropriate value.

  12. If a header named `Accept` is not in req's author headers, append one with `*/*` as value.

  13. Fetch req.

    If req's synchronous flag is set, pass the return value, synchronously, to process response end-of-file below. Otherwise, handle the tasks queued on the networking task source per below.

    If the timeout attribute value is not 0, terminate fetching after the amount of milliseconds specified by the timeout attribute value have passed with reason timeout.

    To process request body for request, fire an upload progress event named progress on the XMLHttpRequestUpload object.

    To process request end-of-file for request, run these substeps:

    1. Set the upload complete flag.

    2. Fire an upload progress event named progress on the XMLHttpRequestUpload object.

    3. Fire an upload progress event named load on the XMLHttpRequestUpload object.

    4. Fire an upload progress event named loadend on the XMLHttpRequestUpload object.

    To process response for response, run these substeps:

    1. Handle errors for response.

    2. Set response to response.

    3. If state is OPENED, run these subsubsteps:

      1. Change the state to HEADERS_RECEIVED.

      2. Fire an event named readystatechange.

    To process response body for response, run these substeps:

    1. Handle errors for response.

    2. If state is HEADERS_RECEIVED, run these subsubsteps:

      1. Change the state to LOADING.

      2. Fire an event named readystatechange.

    3. Update response entity body with response's body.

    4. Fire a progress event named progress.

    To process response end-of-file for response, run these substeps:

    1. Handle errors for response.

    2. If the synchronous flag is set, set response to response.

    3. If state is LOADING, run these subsubsteps:

      1. Update response entity body with response's body.

      2. Change the state to DONE.

      3. Unset the send() flag.

      4. Fire an event named readystatechange.

      5. Fire a progress event named progress.

      6. Fire a progress event named load.

      7. Fire a progress event named loadend.

To handle errors for response run these substeps:

  1. If response is a network error, run the request error steps for event error and exception "NetworkError".

  2. Otherwise, if response has a termination reason:

    end-user abort

    Run the request error steps for event abort and exception "AbortError".

    fatal

    Terminate the entire send() algorithm.

    Game over.

    timeout

    Run the request error steps for event timeout and exception "TimeoutError".

The request error steps for event event and optionally an exception exception are:

  1. Change the state to DONE.

  2. Unset the send() flag.

  3. Set response to a network error.

  4. If the synchronous flag is set, throw an exception exception.

  5. Fire an event named readystatechange.

    At this point it is clear that the synchronous flag is unset.

  6. If the upload complete flag is unset, follow these substeps:

    1. Set the upload complete flag.

    2. Fire an upload progress event named progress on the XMLHttpRequestUpload object.

    3. Fire an upload progress event named event on the XMLHttpRequestUpload object.

    4. Fire an upload progress event named loadend on the XMLHttpRequestUpload object.

  7. Fire a progress event named progress.

  8. Fire a progress event named event.

  9. Fire a progress event named loadend.

4.5.7 The abort() method

client . abort()
Cancels any network activity.

The abort() method must run these steps:

  1. Terminate the request.

  2. If the state is OPENED with the send() flag set, HEADERS_RECEIVED, or LOADING, run the request error steps for event abort.

  3. Change the state to UNSENT.

    No readystatechange event is dispatched.

4.6 Response

An XMLHttpRequest has an associated response. Unless stated otherwise it is a network error.

4.6.1 The responseURL attribute

The responseURL attribute must return the empty string if response's url is null and its serialization otherwise.

4.6.2 The status attribute

The status attribute must return the response's status.

4.6.3 The statusText attribute

The statusText attribute must return the response's status message.

4.6.4 The getResponseHeader() method

The getResponseHeader(name) method must run these steps:

  1. If response's headers has multiple headers whose name is name, return their values in list order as a single byte sequence separated from each other by a 0x2C 0x20 byte pair.

  2. If response's headers has one header whose name is name, return its value.

  3. Return null.

The Fetch Standard filters headers exposed by getResponseHeader(). [FETCH]

For the following script:

var client = new XMLHttpRequest();
client.open("GET", "unicorns-are-teh-awesome.txt", true);
client.send();
client.onreadystatechange = function() {
  if(this.readyState == 2) {
    print(client.getResponseHeader("Content-Type"));
  }
}

The print() function will get to process something like:

text/plain; charset=UTF-8

4.6.5 The getAllResponseHeaders() method

The getAllResponseHeaders() method must return all response's headers, in list order, as a single byte sequence with each header separated by a 0x0D 0x0A byte pair, and each name and value of a header separated by a 0x3A 0x20 byte pair.

The Fetch Standard filters headers exposed by getAllResponseHeaders(). [FETCH]

For the following script:

var client = new XMLHttpRequest();
client.open("GET", "narwhals-too.txt", true);
client.send();
client.onreadystatechange = function() {
  if(this.readyState == 2) {
    print(this.getAllResponseHeaders());
  }
}

The print() function will get to process something like:

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

4.6.6 Response entity body

The response MIME type is the MIME type the `Content-Type` header contains excluding any parameters and converted to ASCII lowercase, or null if the response header can not be parsed or was omitted. The override MIME type is initially null and can get a value if overrideMimeType() is invoked. Final MIME type is the override MIME type unless that is null in which case it is the response MIME type.

The response charset is the value of the charset parameter of the `Content-Type` header or null if there was no `charset` parameter or the header could not be parsed or was omitted. The override charset is initially null and can get a value if overrideMimeType() is invoked. Final charset is the override charset unless that is null in which case it is the response charset.


The response entity body is the fragment of response's body received so far (LOADING) or the complete body of the response (DONE). If response's body is null, response entity body is null.


The arraybuffer response entity body is either an ArrayBuffer representing the response entity body or null. If the arraybuffer response entity body is null, let it be the return value of the following algorithm:

  1. If the response entity body is null, return an empty ArrayBuffer object.

  2. Return an ArrayBuffer object representing the response entity body.

The blob response entity body is either a Blob representing the response entity body or null. If the blob response entity body is null, set it to the return value of the following algorithm:

  1. If the response entity body is null, return an empty Blob object.

  2. Return a Blob object representing the response entity body.

The document response entity body is either a document representing the response entity body or null. If the document response entity body is null, set it to the return value of the following algorithm:

  1. If the response entity body is null, return null.

  2. If final MIME type is not null, text/html, text/xml, application/xml, or does not end in +xml, return null.

  3. If responseType is the empty string and final MIME type is text/html, return null.

    This is restricted to responseType being "document" in order to prevent breaking legacy content.

  4. If final MIME type is text/html, run these substeps:

    1. Let charset be the final charset.

    2. If charset is null, prescan the first 1024 bytes of the response entity body and if that does not terminate unsuccessfully then let charset be the return value.

    3. If charset is null, set charset to utf-8.

    4. Let document be a document that represents the result parsing response entity body following the rules set forth in the HTML Standard for an HTML parser with scripting disabled and a known definite encoding charset. [HTML]

    5. Flag document as an HTML document.

  5. Otherwise, let document be a document that represents the result of parsing the response entity body following the rules set forth in the XML specifications. If that fails (unsupported character encoding, namespace well-formedness error, etc.), return null. [XML] [XMLNS]

    Scripts in the resulting document tree will not be executed, resources referenced will not be loaded and no associated XSLT will be applied.

  6. If charset is null, set charset to utf-8.

  7. Set document's encoding to charset.

  8. Set document's content type to final MIME type.

  9. Set document's URL to response's url.

  10. Set document's origin to settings object's origin.

  11. Return document.

The JSON response entity body is either a JavaScript value representing the response entity body. If the JSON response entity body is null, set it to the return value of the following algorithm:

  1. If the response entity body is null, return null.

  2. Let JSON text be the result of running utf-8 decode on byte stream response entity body.

  3. Return the result of invoking the initial value of the parse property of the JSON object defined in JavaScript, with JSON text as its only argument, or null if that function throws an exception. [ECMASCRIPT]

The text response entity body is either a string representing the response entity body or null. If the text response entity body is null, set it to the return value of the following algorithm:

  1. If the response entity body is null, return the empty string.

  2. Let charset be the final charset.

  3. If responseType is the empty string, charset is null, and final MIME type is either null, text/xml, application/xml or ends in +xml, use the rules set forth in the XML specifications to determine the encoding. Let charset be the determined encoding. [XML] [XMLNS]

    This is restricted to responseType being the empty string to keep the non-legacy responseType value "text" simple.

  4. If charset is null, set charset to utf-8.

  5. Return the result of running decode on byte stream response entity body using fallback encoding charset.

Authors are strongly encouraged to always encode their resources using utf-8.

4.6.7 The overrideMimeType() method

client . overrideMimeType(mime)

Sets the `Content-Type` header for response to mime.

Throws an "InvalidStateError" exception if the state is LOADING or DONE.

Throws a "SyntaxError" exception if mime is not a valid MIME type.

The overrideMimeType(mime) method must run these steps:

  1. If the state is LOADING or DONE, throw an "InvalidStateError" exception.

  2. If parsing mime analogously to the value of the `Content-Type` header fails, throw a "SyntaxError" exception.

  3. If mime is successfully parsed, set override MIME type to its MIME type, excluding any parameters, and converted to ASCII lowercase.

  4. If a `charset` parameter is successfully parsed, set override charset to its value.

4.6.8 The responseType attribute

client . responseType [ = value ]

Returns the response type.

Can be set to change the response type. Values are: the empty string (default), "arraybuffer", "blob", "document", "json", and "text".

When set: setting to "document" is ignored if the JavaScript global environment is a worker environment

When set: throws an "InvalidStateError" exception if the state is LOADING or DONE.

When set: throws an "InvalidAccessError" exception if the synchronous flag is set and the JavaScript global environment is a document environment.

The responseType attribute must return its value. Initially its value must be the empty string.

Setting the responseType attribute must run these steps:

  1. If the JavaScript global environment is a worker environment and the given value is "document", terminate these steps.

  2. If the state is LOADING or DONE, throw an "InvalidStateError" exception.

  3. If the JavaScript global environment is a document environment and the synchronous flag is set, throw an "InvalidAccessError" exception.

  4. Set the responseType attribute's value to the given value.

4.6.9 The response attribute

client . response

Returns the response entity body.

The response attribute must return the result of running these steps:

If responseType is the empty string or "text"
  1. If the state is not LOADING or DONE, return the empty string.

  2. Return the text response entity body.

Otherwise
  1. If the state is not DONE, return null.

  2. If responseType is "arraybuffer"

    Return the arraybuffer response entity body.

    If responseType is "blob"

    Return the blob response entity body.

    If responseType is "document"

    Return the document response entity body.

    If responseType is "json"

    Return the JSON response entity body.

4.6.10 The responseText attribute

client . responseText

Returns the text response entity body.

Throws an "InvalidStateError" exception if responseType is not the empty string or "text".

The responseText attribute must return the result of running these steps:

  1. If responseType is not the empty string or "text", throw an "InvalidStateError" exception.

  2. If the state is not LOADING or DONE, return the empty string.

  3. Return the text response entity body.

4.6.11 The responseXML attribute

client . responseXML

Returns the document response entity body.

Throws an "InvalidStateError" exception if responseType is not the empty string or "document".

The responseXML attribute must return the result of running these steps:

  1. If responseType is not the empty string or "document", throw an "InvalidStateError" exception.

  2. If the state is not DONE, return null.

  3. Return the document response entity body.

The responseXML attribute has XML in its name for historical reasons. It also returns HTML resources as documents.

4.7 Events summary

This section is non-normative.

The following events are dispatched on XMLHttpRequest and/or XMLHttpRequestUpload objects:

Event name Interface Dispatched when…
readystatechange Event The readyState attribute changes value, except when it changes to UNSENT.
loadstart ProgressEvent The fetch initiates.
progress ProgressEvent Transmitting data.
abort ProgressEvent When the fetch has been aborted. For instance, by invoking the abort() method.
error ProgressEvent The fetch failed.
load ProgressEvent The fetch succeeded.
timeout ProgressEvent The author specified timeout has passed before the fetch completed.
loadend ProgressEvent The fetch completed (success or failure).

5 Interface FormData

typedef (File or [EnsureUTF16] DOMString) FormDataEntryValue;

[Constructor(optional HTMLFormElement form),
 Exposed=Window,Worker]
interface FormData {
  void append([EnsureUTF16] DOMString name, Blob value, optional [EnsureUTF16] DOMString filename);
  void append([EnsureUTF16] DOMString name, [EnsureUTF16] DOMString value);
  void delete([EnsureUTF16] DOMString name);
  FormDataEntryValue? get([EnsureUTF16] DOMString name);
  sequence<FormDataEntryValue> getAll([EnsureUTF16] DOMString name);
  boolean has([EnsureUTF16] DOMString name);
  void set([EnsureUTF16] DOMString name, Blob value, optional [EnsureUTF16] DOMString filename);
  void set([EnsureUTF16] DOMString name, [EnsureUTF16] DOMString value);
};

The FormData object represents an ordered list of entries. Each entry consists of a name and a value.

For the purposes of interaction with other algorithms, an entry's type is "string" if value is a string and "file" otherwise. If an entry's type is "file", its filename is the value of entry's value's name attribute.

To create an entry for name, value, and optionally a filename, run these steps:

  1. Let entry be a new entry.

  2. Set entry's name to name.

  3. If value is a Blob, set value to a new File object, representing the same bytes, whose name attribute value is "blob".

  4. If value is a File and filename is given, set value to a new File object, representing the same bytes, whose name attribute value is filename.

  5. Set entry's value to value.

  6. Return entry.

The FormData(form) constructor must run these steps:

  1. Let fd be a new FormData object.

  2. If form is given, set fd's entries to the result of constructing the form data set for form.

  3. Return fd.

The append(name, value, filename) method must run these steps:

  1. Let entry be the result of create an entry with name, value, and filename if given.

  2. Append entry to FormData object's list of entries.

The delete(name) method must remove all entries whose name is name.

The get(name) method must return the value of the first entry whose name is name, and null otherwise.

The getAll(name) method must return the values of all entries whose name is name, in list order, and the empty sequence otherwise.

The set(name, value) method must run these steps:

  1. Let entry be the result of create an entry with name, value, and filename if given.

  2. If there are any entries whose name is name, replace the first such entry with entry and remove the others.

  3. Otherwise, append entry to FormData object's list of entries.

The has(name) method must return true if there is an entry whose name is name, and false otherwise.

6 Interface ProgressEvent

[Constructor(DOMString type, optional ProgressEventInit eventInitDict),
 Exposed=Window,Worker]
interface ProgressEvent : Event {
  readonly attribute boolean lengthComputable;
  readonly attribute unsigned long long loaded;
  readonly attribute unsigned long long total;
};

dictionary ProgressEventInit : EventInit {
  boolean lengthComputable;
  unsigned long long loaded;
  unsigned long long total;
}

Events using the ProgressEvent interface indicate some kind of progression.

The lengthComputable attribute must return the value it was initialized to. When an event is created the attribute must be initialized to false.

The loaded and total attributes must return the value they were initialized to. When an event is created the attributes must be initialized to 0.

6.1 Firing events using the ProgressEvent interface for Fetch

To fire an upload progress event named e means to fire an event named e with an event using the ProgressEvent interface that also meets these conditions:

To fire a progress event named e means to fire an event named e with an event using the ProgressEvent interface that also meets these conditions:

6.2 Firing events using the ProgressEvent interface for other contexts

This is left as an exercise for the editor of the specification that introduces such a context. The editor is encouraged to define it in a way consistent with this and other specifications that utilize events using the ProgressEvent interface.

6.3 Suggested names for events using the ProgressEvent interface

This section is non-normative.

The suggested type attribute values for use with events using the ProgressEvent interface are summarized in the table below. Specification editors are free to tune the details to their specific scenarios, though are strongly encouraged to discuss their usage with the WHATWG community to ensure input from people familiar with the subject.

type attribute value Description Times When
loadstart Progress has begun. Once. First.
progress In progress. Once or more. After loadstart has been dispatched.
error Progression failed. Zero or once (mutually exclusive). After the last progress has been dispatched.
abort Progression is terminated.
timeout Progression is terminated due to preset time expiring.
load Progression is successful.
loadend Progress has stopped. Once. After one of error, abort, timeout or load has been dispatched.

The error, abort, timeout, and load event types are mutually exclusive.

Throughout the web platform the error, abort, timeout and load event types have their bubbles and cancelable attributes initialized to false, so it is suggested that for consistency all events using the ProgressEvent interface do the same.

6.4 Security Considerations

For cross-origin requests some kind of opt-in, e.g. the CORS protocol defined in the Fetch Standard, has to be used before events using the ProgressEvent interface are dispatched as information (e.g. size) would be revealed that cannot be obtained otherwise. [FETCH]

6.5 Example

In this example XMLHttpRequest, combined with concepts defined in the sections before, and the HTML progress element are used together to display the process of fetching a resource.

<!DOCTYPE html>
<title>Waiting for Magical Unicorns</title>
<progress id=p></progress>
<script>
  var progressBar = document.getElementById("p"),
      client = new XMLHttpRequest()
  client.open("GET", "magical-unicorns")
  client.onprogress = function(pe) {
    if(pe.lengthComputable) {
      progressBar.max = pe.total
      progressBar.value = pe.loaded
    }
  }
  client.onloadend = function(pe) {
    progressBar.value = pe.loaded
  }
  client.send()
</script>

Fully working code would of course be more elaborate and deal with more scenarios, such as network errors or the end user terminating the request.

References

[COOKIES]
HTTP State Management Mechanism, Adam Barth. IETF.
[DOM]
DOM, Anne van Kesteren, Aryeh Gregor and Ms2ger. WHATWG.
[DOMPS]
DOM Parsing and Serialization, Ms2ger. WHATWG.
[ECMASCRIPT]
ECMAScript Language Specification. ECMA.
[ENCODING]
Encoding, Anne van Kesteren. WHATWG.
[FETCH]
Fetch, Anne van Kesteren. WHATWG.
[FILEAPI]
File API, Arun Ranganathan and Jonas Sicking. W3C.
[HTML]
HTML, Ian Hickson. WHATWG.
[HTTP]
Hypertext Transfer Protocol -- HTTP/1.1, Roy Fielding, James Gettys, Jeffrey Mogul et al.. IETF.
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, Scott Bradner. IETF.
[TYPEDARRAY]
Typed Array, David Herman and Kenneth Russell. Khronos.
[URL]
URL, Anne van Kesteren. WHATWG.
[WEBIDL]
Web IDL, Cameron McCormack. W3C.
[XML]
Extensible Markup Language, Tim Bray, Jean Paoli, C. M. Sperberg-McQueen et al.. W3C.
[XMLNS]
Namespaces in XML, Tim Bray, Dave Hollander, Andrew Layman et al.. W3C.

Acknowledgments

The editor would like to thank Addison Phillips, Adrian Bateman, Ahmed Kamel, Alex Hopmann, Alex Vincent, Alexey Proskuryakov, Andrea Marchesini, Asbjørn Ulsberg, Boris Zbarsky, Björn Höhrmann, Cameron McCormack, Chris Marrin, Christophe Jolif, Charles McCathieNevile, Dan Winship, David Andersson, David Flanagan, David Håsäther, David Levin, Dean Jackson, Denis Sureau, Dominik Röttsches, Doug Schepers, Douglas Livingstone, Elliott Sprehn, Elliotte Harold, Eric Lawrence, Eric Uhrhane, Erik Arvidsson, Erik Dahlström, Feras Moussa, Geoffrey Sneddon, Gideon Cohn, Glenn Adams, Gorm Haug Eriksen, Håkon Wium Lie, Hallvord R. M. Steen, Henri Sivonen, Huub Schaeks, Ian Davis, Ian Hickson, Ivan Herman, Jared Jacobs, Jarred Nicholls, Jeff Walden, Jens Lindström, Jim Deegan, Jim Ley, Joe Farro, Jonas Sicking, Julian Reschke, 송정기 (Jungkee Song), 呂康豪 (Kang-Hao Lu), Karl Dubost, Lachlan Hunt, Maciej Stachowiak, Magnus Kristiansen, Marc Hadley, Marcos Caceres, Mark Baker, Mark Birbeck, Mark Nottingham, Mark S. Miller, Martin Hassman, Mohamed Zergaoui, Ms2ger, Odin Hørthe Omdal, Olli Pettay, Pawel Glowacki, Peter Michaux, Philip Taylor, Robin Berjon, Rune F. Halvorsen, Ruud Steltenpool, Sergiu Dumitriu, Sigbjørn Finne, Simon Pieters, Stewart Brodie, Sunava Dutta, Takeshi Yoshino, Thomas Roessler, Tom Magliery, Travis Leithead, Yehuda Katz, and Zhenbin Xu for their contributions to this specification.

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 an initial version of this specification in their Web Applications 1.0 document (now renamed to HTML). [HTML]

Special thanks to the SVG WG for drafting the original ProgressEvent interface as part of the SVG Micro DOM.

Thanks also to all those who have helped to improve this specification by sending suggestions and corrections. (Please, keep bugging us with your issues!)