XMLHttpRequest

Living Standard — Last Updated 12 August 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 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
    2. 6.2 Suggested names for events using the ProgressEvent interface
    3. 6.3 Security Considerations
    4. 6.4 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 bearing 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. (Based on Microsoft's implementation many years prior.) 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.

Discussion that led to the current draft 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, URL, Web IDL, and XML. [DOM] [DOMPS] [ENCODING] [FETCH] [FILEAPI] [HTML] [HTTP] [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,
 Exposed=(Window,Worker)]
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, ScalarValueString url);
  void open(ByteString method, ScalarValueString url, boolean async, optional ScalarValueString? username = null, optional ScalarValueString? password = null);
  void setRequestHeader(ByteString name, ByteString value);
           attribute unsigned long timeout;
           attribute boolean withCredentials;
  readonly attribute XMLHttpRequestUpload upload;
  void send(optional (Document or FetchBodyInit)? body = null);
  void abort();

  // response
  readonly attribute ScalarValueString 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 ScalarValueString 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 it has one or more event listeners registered whose type is one of readystatechange, progress, abort, error, load, timeout, and loadend.

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 response have been received.

LOADING (numeric value 3)

The response's 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).

Initially the XMLHttpRequest object must be in the UNSENT state.

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 body, synchronous flag, upload complete flag, and upload events flag.

The author request headers is an initially empty header list.

The request 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 is not a method, throw a "SyntaxError" exception.

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

  5. Normalize method.

  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.

    Unfortunately legacy content prevents treating the async argument being undefined identical from it 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.

    A fetch 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)

Combines a header in author request headers.

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 header name or if value is not a header 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 is not a name or value is not a value, throw a "SyntaxError" exception.

    An empty byte sequence represents an empty header value.

  4. Terminate these steps if name is a forbidden header name.

  5. Combine name/value in author request headers.

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([body = null])

Initiates the request. The optional argument provides the request 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(body) 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 body to null.

  4. If body is null, go to the next step.

    Otherwise, let encoding be null, Content-Type be null, and then follow these rules, depending on body:

    Document

    Set encoding to `UTF-8`.

    If body is an HTML document, set Content-Type to `text/html`, and set Content-Type to `application/xml` otherwise. Then append `;charset=UTF-8` to Content-Type.

    Set request body to body, serialized, converted to Unicode, and utf-8 encoded. Re-throw any exception serializing throws.

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

    FetchBodyInit

    If body is a string, set encoding to `UTF-8`.

    Set request body and Content-Type to the result of extracting body.

    If Content-Type is non-null and author request headers contains no header named `Content-Type`, append `Content-Type`/Content-Type to author request headers.

    Otherwise, if the header named `Content-Type` in author request headers has a value that is a valid MIME type, which 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's value to encoding.

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

    method
    request method
    url
    request URL
    header list
    author request headers
    unsafe request flag
    Set.
    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 body
    client
    settings object's global object
    context
    xmlhttprequest
    authentication flag
    Set.
    synchronous flag
    Set if the synchronous flag is set.
    mode
    CORS if the upload events flag is unset, and CORS-with-forced-preflight otherwise.
    credentials mode
    If the withCredentials attribute value is true, include, and same-origin 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.
  6. If a header named `Accept-Language` is not in req's header list, append `Accept-Language`/an appropriate value to it.

  7. If a header named `Accept` is not in req's header list, append `Accept`/`*/*` to it.

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

  9. If req's body is null, set the upload complete flag.

  10. Set the send() flag.

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

    1. If one or more event listeners are registered on the XMLHttpRequestUpload object, set the upload events flag.

    2. Fire a progress event named loadstart with 0 and 0.

    3. If the upload complete flag is unset, fire a progress event named loadstart on the XMLHttpRequestUpload object with 0 and req's body's length.

    4. Fetch req. 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 a progress event named progress on the XMLHttpRequestUpload object with request's body's transmitted and request's body's length.

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

      1. Set the upload complete flag.

      2. Let transmitted be request's body's transmitted.

      3. Let length be request's body's length.

      4. Fire a progress event named progress on the XMLHttpRequestUpload object with transmitted and length.

      5. Fire a progress event named load on the XMLHttpRequestUpload object with transmitted and length.

      6. Fire a progress event named loadend on the XMLHttpRequestUpload object with transmitted and length.

      To process response for response, run these subsubsteps:

      1. Set response to response.

      2. Handle errors for response.

      3. If response is a network error, return.

      4. Change the state to HEADERS_RECEIVED.

      5. Fire an event named readystatechange.

      To process response body for response, run these subsubsteps:

      1. Handle errors for response.

      2. If response is a network error, return.

      3. If state is HEADERS_RECEIVED, change the state to LOADING and fire an event named readystatechange.

      4. Fire a progress event named progress with response's body's transmitted and response's body's length.

      To process response end-of-file for response, run handle response end-of-file for response.

  12. Otherwise, if the synchronous flag is set, run these substeps:

    1. Release the storage mutex.

    2. Let response be the result of fetching req.

    3. Run handle response end-of-file for response.

To handle response end-of-file for response, run these steps:

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

  2. Handle errors for response.

  3. If response is a network error, return.

  4. If the synchronous flag is unset, update response's body using response.

  5. Change the state to DONE.

  6. Unset the send() flag.

  7. Fire an event named readystatechange.

  8. Let transmitted be response's body's transmitted.

  9. Let length be response's body's length.

  10. Fire a progress event named progress with transmitted and length.

  11. Fire a progress event named load with transmitted and length.

  12. Fire a progress event named loadend with transmitted and length.

To handle errors for response run these steps:

  1. If the send() flag is unset, return.

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

  3. Otherwise, if response has a termination reason:

    end-user abort

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

    fatal
    1. Change the state to DONE.

    2. Unset the send() flag.

    3. Set response to a network error.

    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 a progress event named progress on the XMLHttpRequestUpload object with 0 and 0.

    3. Fire a progress event named event on the XMLHttpRequestUpload object with 0 and 0.

    4. Fire a progress event named loadend on the XMLHttpRequestUpload object with 0 and 0.

  7. Fire a progress event named progress with 0 and 0.

  8. Fire a progress event named event with 0 and 0.

  9. Fire a progress event named loadend with 0 and 0.

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 header list 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 header list has one header whose name is name, return its value.

  3. Return null.

The Fetch Standard filters response's header list. [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 response's header list, 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 response's header list. [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 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.


An XMLHttpRequest object has an associated response ArrayBuffer object, response Blob object, response Document object, and a response JSON object. Their shared initial value is null.

An arraybuffer response is the return value of these steps:

  1. If response ArrayBuffer object is non-null, return it.

  2. Let bytes be the empty byte sequence, if response's body is null, and response's body otherwise.

  3. Set response ArrayBuffer object to a new ArrayBuffer object representing bytes and return it.

A blob response is the return value of these steps:

  1. If response Blob object is non-null, return it.

  2. Let type be the empty string, if final MIME type is null, and final MIME type otherwise.

  3. Let bytes be the empty byte sequence, if response's body is null, and response's body otherwise.

  4. Set response Blob object to a new Blob object representing bytes with type type and return it.

A document response is the return value of these steps:

  1. If response Document object is non-null, return it.

  2. Let bytes be response's body.

  3. If bytes is null, return null.

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

  5. 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.

  6. 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 bytes 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 bytes 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.

  7. Otherwise, let document be a document that represents the result of parsing the bytes 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.

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

  9. Set document's encoding to charset.

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

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

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

  13. Set response Document object to document and return it.

A JSON response is the return value of these steps:

  1. If response JSON object is non-null, return it.

  2. Let bytes be response's body.

  3. If bytes is null, return null.

  4. Let JSON text be the result of running utf-8 decode on byte stream bytes.

  5. Let JSON object be the result of invoking the initial value of the parse property of the JSON object, with JSON text as its only argument. If that threw an exception, return null. [ECMASCRIPT]

  6. Set response JSON object to JSON object and return it.

A text response is the return value of these steps:

  1. Let bytes be response's body.

  2. If bytes is null, return the empty string.

  3. Let charset be the final charset.

  4. 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.

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

  6. Return the result of running decode on byte stream bytes 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's 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.

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

  2. If responseType is "arraybuffer"

    Return the arraybuffer response.

    If responseType is "blob"

    Return the blob response.

    If responseType is "document"

    Return the document response.

    If responseType is "json"

    Return the JSON response.

4.6.10 The responseText attribute

client . responseText

Returns the text response.

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.

4.6.11 The responseXML attribute

client . responseXML

Returns the document response.

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.

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 ScalarValueString) FormDataEntryValue;

[Constructor(optional HTMLFormElement form),
 Exposed=(Window,Worker)]
interface FormData {
  void append(ScalarValueString name, Blob value, optional ScalarValueString filename);
  void append(ScalarValueString name, ScalarValueString value);
  void delete(ScalarValueString name);
  FormDataEntryValue? get(ScalarValueString name);
  sequence<FormDataEntryValue> getAll(ScalarValueString name);
  boolean has(ScalarValueString name);
  void set(ScalarValueString name, Blob value, optional ScalarValueString filename);
  void set(ScalarValueString name, ScalarValueString 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 object and not a File object, set value to a new File object, representing the same bytes, whose name attribute value is "blob".

  4. If value is a File object 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 = false;
  unsigned long long loaded = 0;
  unsigned long long total = 0;
}

Events using the ProgressEvent interface indicate some kind of progression.

The lengthComputable, loaded, and total attributes must return the value they were initialized to.

6.1 Firing events using the ProgressEvent interface

To fire an progress event named e given transmitted and length, fire an event named e with an event using the ProgressEvent interface that also meets these conditions:

6.2 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.3 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.4 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.
[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, Alan Thomas, 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, Manish Goregaokar, 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!)