XMLHttpRequest

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.

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();

function log(message) {
  var client = new XMLHttpRequest();
  client.open("POST", "/log");
  client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8");
  client.send(message);
}

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:

• whatwg@whatwg.org
• public-webapps@w3.org
• public-webapi@w3.org
• public-appformats@w3.org

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, 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 (ArrayBufferView or Blob or Document or ScalarValueString 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 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:

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

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

   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:

    • Set request method to method.

    • Set request URL to parsedURL.

    • Set the synchronous flag, if async is false, and unset the synchronous flag otherwise.

    • Empty author request headers.

    • Set response to a network error.

    • Set response ArrayBuffer object to null.

    • Set response Blob object to null.

    • Set response Document object to null.

    • Set response JSON object to null.

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.

// 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 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, go to the next step.

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

   ArrayBufferView

   Set request body to a copy of the bytes represented by data.

   Blob

   If the data's type attribute value is not the empty string, set mime type to its value.

   Set request body to a copy of the bytes represented by data.

   document

   Set encoding to `UTF-8`.

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

   Set request body to 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

   Set encoding to `UTF-8`.

   Set mime type to `text/plain;charset=UTF-8`.

   Set request body to data, utf-8 encoded.

   FormData

   Set mime type to `multipart/form-data;boundary=`, followed by the multipart/form-data boundary string generated by the multipart/form-data encoding algorithm.

   Set request 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.

   URLSearchParams

   Set encoding to `UTF-8`.

   Set mime type to `application/x-www-form-urlencoded;charset=UTF-8`.

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

   If author request headers contains no header named `Content-Type`, append `Content-Type`/mime type to author request headers.

   Otherwise, if the header named `Content-Type` in author request headers has 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

   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]

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"));
  }
}

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]

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

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:

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:

• Set the loaded attribute value to transmitted.

• If length is not 0, set the lengthComputable attribute value to true and the total attribute value to length.

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.

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

<!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>

References

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!)