XMLHttpRequest (PR #321)

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.status == 200 &&
    this.responseXML != null &&
    this.responseXML.getElementById('test').textContent) {
    // success!
    processData(this.responseXML.getElementById('test').textContent);
  } else {
    // something went wrong
    …
  }
}

var client = new XMLHttpRequest();
client.onload = 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.onload = function() {
    // in case of network errors this might not give reliable results
    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, Feature Policy, Fetch, File API, HTML, HTTP, URL, Web IDL, and XML.

[DOM] [DOMPS] [ENCODING] [FEATURE-POLICY] [FETCH] [FILEAPI] [HTML] [HTTP] [URL] [WEBIDL] [XML] [XMLNS]

It uses the typographic conventions from HTML. [HTML]

4. Interface XMLHttpRequest

[Exposed=(Window,DedicatedWorker,SharedWorker)]
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,DedicatedWorker,SharedWorker)]
interface XMLHttpRequestUpload : XMLHttpRequestEventTarget {
};

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

[Exposed=(Window,DedicatedWorker,SharedWorker)]
interface XMLHttpRequest : XMLHttpRequestEventTarget {
  constructor();

  // 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, USVString url);
  void open(ByteString method, USVString url, boolean async, optional USVString? username = null, optional USVString? password = null);
  void setRequestHeader(ByteString name, ByteString value);
           attribute unsigned long timeout;
           attribute boolean withCredentials;
  [SameObject] readonly attribute XMLHttpRequestUpload upload;
  void send(optional (Document or XMLHttpRequestBodyInit)? body = null);
  void abort();

  // response
  readonly attribute USVString 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 USVString responseText;
  [Exposed=Window] readonly attribute Document? responseXML;
};

An XMLHttpRequest object has an associated XMLHttpRequestUpload object.

An XMLHttpRequest object has an associated state, which is one of unsent, opened, headers received, loading, and done. Unless stated otherwise it is unsent.

An XMLHttpRequest object has an associated send() flag. Unless stated otherwise it is unset.

4.1. Constructors

client = new XMLHttpRequest()

Returns a new XMLHttpRequest object.

The XMLHttpRequest() constructor, when invoked, must return a new XMLHttpRequest object.

4.2. Garbage collection

An XMLHttpRequest object must not be garbage collected if its state is either opened with the send() flag set, headers received, or 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 ongoing fetch operated by the XMLHttpRequest object.

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 client’s state.

The readyState attribute’s getter must return the value from the table below in the cell of the second column, from the row where the value in the cell in the first column is context object’s 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, upload listener flag, and timed out flag.

The author request headers is an initially empty header list.

The request body is initially null.

The synchronous flag, upload complete flag, upload listener flag and timed out flag are initially unset.

Registering one or more event listeners on an XMLHttpRequestUpload object will result in a CORS-preflight request. (That is because registering an event listener causes the upload listener flag to be set, which in turn causes the use-CORS-preflight flag to be set.)

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" DOMException if either method is not a valid HTTP method or url cannot be parsed.

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

Throws an "InvalidAccessError" DOMException if async is false, current global object is a Window object, and the timeout attribute is not zero or the responseType attribute is not the empty string.

Synchronous XMLHttpRequest outside of workers is in the process of being removed from the web platform as it has detrimental effects to the end user’s experience. (This is a long process that takes many years.) Developers must not pass false for the async argument when current global object is a Window object. User agents are strongly encouraged to warn about such usage in developer tools and may experiment with throwing an "InvalidAccessError" DOMException when it occurs.

The open(method, url) and open(method, url, async, username, password) methods, when invoked, must run these steps:

1. Let settingsObject be context object’s relevant settings object.

2. If settingsObject has a responsible document and it is not fully active, then throw an "InvalidStateError" DOMException.

3. If method is not a method, then throw a "SyntaxError" DOMException.

4. If method is a forbidden method, then throw a "SecurityError" DOMException.

5. Normalize method.

6. Let parsedURL be the result of parsing url with settingsObject’s API base URL and settingsObject’s API URL character encoding.

7. If parsedURL is failure, then throw a "SyntaxError" DOMException.

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 host is non-null, then:

   1. If the username argument is not null, set the username given parsedURL and username.

   2. If the password argument is not null, set the password given parsedURL and password.

10. If async is false, current global object is a Window object, and the timeout attribute value is not zero or the responseType attribute value is not the empty string, then throw an "InvalidAccessError" DOMException.

11. Terminate the ongoing fetch operated by the XMLHttpRequest object.

    A fetch can be ongoing at this point.

12. Set variables associated with the object as follows:

    • Unset the send() flag and upload listener flag.

    • 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 received bytes to the empty byte sequence.

    • Set response object to null.

    Override MIME type is not overridden here as the overrideMimeType() method can be invoked before the open() method.

13. If the state is not opened, then:

    1. Set state to opened.

    2. Fire an event named readystatechange at this.

The reason there are two open() methods defined is due to a limitation of the editing software used to write the XMLHttpRequest Standard.

4.5.2. The setRequestHeader() method

client . setRequestHeader(name, value)

Combines a header in author request headers.

Throws an "InvalidStateError" DOMException if either state is not opened or the send() flag is set.

Throws a "SyntaxError" DOMException if name is not a header name or if value is not a header value.

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

1. If state is not opened, then throw an "InvalidStateError" DOMException.

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

3. Normalize value.

4. If name is not a name or value is not a value, then throw a "SyntaxError" DOMException.

   An empty byte sequence represents an empty header value.

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

6. 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" DOMException will be thrown otherwise (for the send() method).

When set: throws an "InvalidAccessError" DOMException if the synchronous flag is set and current global object is a Window object.

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

Setting the timeout attribute must run these steps:

1. If current global object is a Window object and the synchronous flag is set, then throw an "InvalidAccessError" DOMException.

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 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" DOMException if state is not unsent or opened, or if the send() flag is set.

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

Setting the withCredentials attribute must run these steps:

1. If state is not unsent or opened, then throw an "InvalidStateError" DOMException.

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

3. 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 body argument provides the request body, if any, and is ignored if the request method is GET or HEAD.

Throws an "InvalidStateError" DOMException if either state is not opened or the send() flag is set.

The send(body) method must run these steps:

1. If state is not opened, then throw an "InvalidStateError" DOMException.

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

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

4. If body is not null, then:

   1. Let extractedContentType be null.

   2. If body is a Document, then set request body to body, serialized, converted, and UTF-8 encoded.

   3. Otherwise, set request body and extractedContentType to the result of extracting body.

   4. If author request headers contains `Content-Type`, then:

      1. If body is a Document or a USVString, then:

         1. Let originalAuthorContentType be the value of the header whose name is a byte-case-insensitive match for `Content-Type` in author request headers.

         2. Let contentTypeRecord be the result of parsing originalAuthorContentType.

         3. If contentTypeRecord is not failure, contentTypeRecord’s parameters["charset"] exists, and parameters["charset"] is not an ASCII case-insensitive match for "UTF-8", then:

            1. Set contentTypeRecord’s parameters["charset"] to "UTF-8".

            2. Let newContentTypeSerialized be the result of serializing contentTypeRecord.

            3. Set `Content-Type`/newContentTypeSerialized in author request headers.

   5. Otherwise:

      1. If body is an HTML document, set `Content-Type`/`text/html;charset=UTF-8` in author request headers.

      2. Otherwise, if body is an XML document, set `Content-Type`/`application/xml;charset=UTF-8` in author request headers.

      3. Otherwise, if extractedContentType is not null, set `Content-Type`/extractedContentType in author request headers.

5. If one or more event listeners are registered on the associated XMLHttpRequestUpload object, then set upload listener flag.

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

   method

   request method

   url

   request URL

   header list

   author request headers

   unsafe-request flag

   Set.

   body

   request body

   client

   context object’s relevant settings object

   synchronous flag

   Set if the synchronous flag is set.

   mode

   "cors"

   use-CORS-preflight flag

   Set if upload listener flag is set.

   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.

7. Unset the upload complete flag.

8. Unset the timed out 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, then:

    1. Fire a progress event named loadstart at this with 0 and 0.

    2. If the upload complete flag is unset and upload listener flag is set, then fire a progress event named loadstart at this’s XMLHttpRequestUpload object with 0 and req’s body’s total bytes.

    3. If state is not opened or the send() flag is unset, then return.

    4. Fetch req. Handle the tasks queued on the networking task source per below.

       Run these steps in parallel:

       1. Wait until either req’s done flag is set or

          1. the timeout attribute value number of milliseconds has passed since these steps started

          2. while timeout attribute value is not zero.

       2. If req’s done flag is unset, then set the timed out flag and terminate fetching.

       To process request body for request, run these steps:

       1. If not roughly 50ms have passed since these steps were last invoked, terminate these steps.

       2. If upload listener flag is set, then fire a progress event named progress at this’s XMLHttpRequestUpload object with request’s body’s transmitted bytes and request’s body’s total bytes.

       These steps are only invoked when new bytes are transmitted.

       To process request end-of-body for request, run these steps:

       1. Set the upload complete flag.

       2. If upload listener flag is unset, then terminate these steps.

       3. Let transmitted be request’s body’s transmitted bytes.

       4. Let length be request’s body’s total bytes.

       5. Fire a progress event named progress at this’s XMLHttpRequestUpload object with transmitted and length.

       6. Fire a progress event named load at this’s XMLHttpRequestUpload object with transmitted and length.

       7. Fire a progress event named loadend at this’s XMLHttpRequestUpload object with transmitted and length.

       To process response for response, run these steps:

       1. Set response to response.

       2. Handle errors for response.

       3. If response is a network error, return.

       4. Set state to headers received.

       5. Fire an event named readystatechange at this.

       6. If state is not headers received, then return.

       7. If response’s body is null, then run handle response end-of-body and return.

       8. Let reader be the result of getting a reader from response’s body’s stream.

          This operation will not throw an exception.

       9. Let read be the result of reading a chunk from response’s body’s stream with reader.

          When read is fulfilled with an object whose done property is false and whose value property is a Uint8Array object, run these steps and then run this step again:

          1. Append the value property to received bytes.

          2. If not roughly 50ms have passed since these steps were last invoked, then terminate these steps.

          3. If state is headers received, then set state to loading.

          4. Fire an event named readystatechange at this.

             Web compatibility is the reason readystatechange fires more often than state changes.

          5. Fire a progress event named progress at this with response’s body’s transmitted bytes and response’s body’s total bytes.

          These steps are only invoked when new bytes are transmitted.

          When read is fulfilled with an object whose done property is true, run handle response end-of-body for response.

          When read is rejected with an exception, run handle errors for response.

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

    1. If context object’s relevant settings object has a responsible document which is not allowed to use the "sync-xhr" feature, then run handle response end-of-body for a network error and return.

    2. Let response be the result of fetching req.

       If the timeout attribute value is not zero, then set the timed out flag and terminate fetching if it has not returned within the amount of milliseconds from the timeout.

    3. If response’s body is null, then run handle response end-of-body and return.

    4. Let reader be the result of getting a reader from response’s body’s stream.

       This operation will not throw an exception.

    5. Let promise be the result of reading all bytes from response’s body’s stream with reader.

    6. Wait for promise to be fulfilled or rejected.

    7. If promise is fulfilled with bytes, then append bytes to received bytes.

    8. Run handle response end-of-body for response.

To handle response end-of-body 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. Let transmitted be response’s body’s transmitted bytes.

6. Let length be response’s body’s total bytes.

7. If the synchronous flag is unset, fire a progress event named progress at this with transmitted and length.

8. Set state to done.

9. Unset the send() flag.

10. Fire an event named readystatechange at this.

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

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

To handle errors for response run these steps:

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

2. If the timed out flag is set, then run the request error steps for event timeout and exception "TimeoutError" DOMException.

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

4. Otherwise, if response’s body’s stream is errored, then:

   1. Set state to done.

   2. Unset the send() flag.

   3. Set response to a network error.

5. Otherwise, if response’s aborted flag is set, then run the request error steps for event abort and exception "AbortError" DOMException.

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

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

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

6. If the upload complete flag is unset, then:

   1. Set the upload complete flag.

   2. If the upload listener flag is set, then:

      1. Fire a progress event named event at this’s XMLHttpRequestUpload object with 0 and 0.

      2. Fire a progress event named loadend at this’s XMLHttpRequestUpload object with 0 and 0.

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

8. Fire a progress event named loadend at this with 0 and 0.

4.5.7. The abort() method

client . abort()

Cancels any network activity.

The abort() method, when invoked, must run these steps:

1. Terminate the ongoing fetch with the aborted flag set.

2. If state is either opened with the send() flag set, headers received, or loading, run the request error steps for event abort.

3. If state is done, then set state to unsent and response to a network error.

   No readystatechange event is dispatched.

4.6. Response

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

An XMLHttpRequest also has an associated received bytes (a byte sequence). Unless stated otherwise it is the empty byte sequence.

4.6.1. The responseURL attribute

The responseURL attribute must return the empty string if response’s url is null and its serialization with the exclude fragment flag set 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, when invoked, must return the result of getting name from response’s header list

The Fetch Standard filters response’s header list. [FETCH]

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

text/plain; charset=UTF-8

4.6.5. The getAllResponseHeaders() method

A byte sequence a is legacy-uppercased-byte less than a byte sequence b if the following steps return true:

1. Let A be a, byte-uppercased.

2. Let B be b, byte-uppercased.

3. Return A is byte less than B.

The getAllResponseHeaders() method, when invoked, must run these steps:

1. Let output be an empty byte sequence.

2. Let initialHeaders be the result of running sort and combine with response’s header list.

3. Let headers be the result of sorting initialHeaders in ascending order, with a being less than b if a’s name is legacy-uppercased-byte less than b’s name.

   Unfortunately, this is needed for compatibility with deployed content.

4. For each header in headers, append header’s name, followed by a 0x3A 0x20 byte pair, followed by header’s value, followed by a 0x0D 0x0A byte pair, to output.

5. Return output.

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 == this.HEADERS_RECEIVED) {
    print(this.getAllResponseHeaders());
  }
}

connection: Keep-Alive
content-type: text/plain; charset=utf-8
date: Sun, 24 Oct 2004 04:58:38 GMT
keep-alive: timeout=15, max=99
server: Apache/1.3.31 (Unix)
transfer-encoding: chunked

4.6.6. Response body

The response MIME type is the result of running these steps:

1. Let mimeType be the result of extracting a MIME type from response’s header list.

2. If mimeType is failure, then set mimeType to text/xml.

3. Return mimeType.

The override MIME type is initially null and can get a value when overrideMimeType() is invoked. The final MIME type is the override MIME type unless that is null in which case it is the response MIME type.

The final charset is the return value of these steps:

1. Let label be null.

2. If response MIME type’s parameters["charset"] exists, then set label to it.

3. If override MIME type’s parameters["charset"] exists, then set label to it.

4. If label is null, then return null.

5. Let encoding be the result of getting an encoding from label.

6. If encoding is failure, then return null.

7. Return encoding.

The above steps intentionally do not use the final MIME type as it would yield the wrong result.

An XMLHttpRequest object has an associated response object (an object, failure, or null). Unless stated otherwise it is null.

An arraybuffer response is the return value of these steps:

1. Set response object to a new ArrayBuffer object representing received bytes. If this throws an exception, then set response object to failure and return null.

   Allocating an ArrayBuffer object is not guaranteed to succeed. [ECMASCRIPT]

2. Return response object.

A blob response is the return value of these steps:

1. Set response object to a new Blob object representing received bytes with type set to the final MIME type.

2. Return response object.

A document response is the return value of these steps:

1. If response’s body is null, then return null.

2. If the final MIME type is not an HTML MIME type or an XML MIME type, then return null.

3. If responseType is the empty string and the final MIME type is an HTML MIME type, then return null.

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

4. If the final MIME type is an HTML MIME type, then:

   1. Let charset be the final charset.

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

   3. If charset is null, then set charset to UTF-8.

   4. Let document be a document that represents the result parsing received 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.

5. Otherwise, let document be a document that represents the result of running the XML parser with XML scripting support disabled on received bytes. If that fails (unsupported character encoding, namespace well-formedness error, etc.), then return null. [HTML]

   Resources referenced will not be loaded and no associated XSLT will be applied.

6. If charset is null, then set charset to UTF-8.

7. Set document’s encoding to charset.

8. Set document’s content type to the final MIME type.

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

10. Set document’s origin to context object’s relevant settings object’s origin.

11. Set response object to document and return it.

A JSON response is the return value of these steps:

1. If response’s body is null, then return null.

2. Let jsonObject be the result of running parse JSON from bytes on received bytes. If that threw an exception, then return null.

3. Set response object to jsonObject and return it.

A text response is the return value of these steps:

1. If response’s body is null, then return the empty string.

2. Let charset be the final charset.

3. If responseType is the empty string, charset is null, and the final MIME type is an XML MIME type, then 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, then set charset to UTF-8.

5. Return the result of running decode on received 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)

Acts as if the `Content-Type` header value for response is mime. (It does not actually change the header though.)

Throws an "InvalidStateError" DOMException if state is loading or done.

The overrideMimeType(mime) method, when invoked, must run these steps:

1. If state is loading or done, then throw an "InvalidStateError" DOMException.

2. Set override MIME type to the result of parsing mime.

3. If override MIME type is failure, then set override MIME type to application/octet-stream.

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 current global object is not a Window object.

When set: throws an "InvalidStateError" DOMException if state is loading or done.

When set: throws an "InvalidAccessError" DOMException if the synchronous flag is set and current global object is a Window object.

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 current global object is not a Window object and the given value is "document", terminate these steps.

2. If state is loading or done, then throw an "InvalidStateError" DOMException.

3. If current global object is a Window object and the synchronous flag is set, then throw an "InvalidAccessError" DOMException.

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 state is not loading or done, return the empty string.

2. Return the text response.

Otherwise

1. If state is not done, return null.

2. If response object is failure, then return null.

3. If response object is non-null, then return it.

4. 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" DOMException 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", then throw an "InvalidStateError" DOMException.

2. If state is not loading or done, then return the empty string.

3. Return the text response.

4.6.11. The responseXML attribute

client . responseXML

Returns the document response.

Throws an "InvalidStateError" DOMException 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", then throw an "InvalidStateError" DOMException.

2. If state is not done, then return null.

3. Assert: response object is not failure.

4. If response object is non-null, then return it.

5. Return the document response.

4.7. Events summary

This section is non-normative.

The following events are dispatched on XMLHttpRequest or XMLHttpRequestUpload objects:

4.8. Permissions Policy integration

This specification defines a policy-controlled feature identified by the string "sync-xhr". Its default allowlist is *.

5. Interface FormData

typedef (File or USVString) FormDataEntryValue;

[Exposed=(Window,Worker)]
interface FormData {
  constructor(optional HTMLFormElement form);

  void append(USVString name, USVString value);
  void append(USVString name, Blob blobValue, optional USVString filename);
  void delete(USVString name);
  FormDataEntryValue? get(USVString name);
  sequence<FormDataEntryValue> getAll(USVString name);
  boolean has(USVString name);
  void set(USVString name, USVString value);
  void set(USVString name, Blob blobValue, optional USVString filename);
  iterable<USVString, FormDataEntryValue>;
};

Each FormData object has an associated entry list (a list of entries). It is initially the empty list.

An entry consists of a name and a value.

For the purposes of interaction with other algorithms, an entry’s filename is the empty string if value is not a File object, and otherwise 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, then set value to a new File object, representing the same bytes, whose name attribute value is "blob".

4. If value is (now) a File object and filename is given, then 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, then:

   1. Let list be the result of constructing the entry list for form.

   2. If list is null, then throw an "InvalidStateError" DOMException.

   3. Set fd’s entry list to list.

3. Return fd.

The append(name, value) and append(name, blobValue, filename) methods, when invoked, must run these steps:

1. Let value be value if given, and blobValue otherwise.

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

3. Append entry to the context object’s entry list.

The reason there is an argument named value as well as blobValue is due to a limitation of the editing software used to write the XMLHttpRequest Standard.

The delete(name) method, when invoked, must remove all entries whose name is name from the context object’s entry list.

The get(name) method, when invoked, must return the value of the first entry whose name is name from the context object’s entry list, and null otherwise.

The getAll(name) method, when invoked, must return the values of all entries whose name is name, in order, from the context object’s entry list, and the empty list otherwise.

The has(name) method, when invoked, must return true if there is an entry whose name is name in the context object’s entry list, and false otherwise.

The set(name, value) and set(name, blobValue, filename) methods, when invoked, must run these steps:

1. Let value be value if given, and blobValue otherwise.

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

3. If there are any entries in the context object’s entry list whose name is name, then replace the first such entry with entry and remove the others.

4. Otherwise, append entry to the context object’s entry list.

The reason there is an argument named value as well as blobValue is due to a limitation of the editing software used to write the XMLHttpRequest Standard.

The value pairs to iterate over are the context object’s entry list’s entries with the key being the name and the value being the value.

6. Interface ProgressEvent

[Exposed=(Window,DedicatedWorker,SharedWorker)]
interface ProgressEvent : Event {
  constructor(DOMString type, optional ProgressEventInit eventInitDict = {});

  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 a progress event named e at target, given transmitted and length, means to fire an event named e at target, using ProgressEvent, with the loaded attribute initialized to transmitted, and if length is not 0, with the lengthComputable attribute initialized to true and the total attribute initialized 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>

Acknowledgments

Thanks to Addison Phillips, Adrian Bateman, Ahmed Kamel, Alan Thomas, Alex Hopmann, Alex Vincent, Alexey Proskuryakov, Ali Alabbas, Andrea Marchesini, Asbjørn Ulsberg, Bertrand Guay-Paquet, Björn Höhrmann, Boris Zbarsky, Caitlin Potter, Cameron McCormack, 白丞祐 (Cheng-You Bai), Chris Marrin, Christophe Jolif, Charles McCathieNevile, Dan Winship, David Andersson, David Flanagan, David Håsäther, David Levin, Dean Jackson, Denis Sureau, Domenic Denicola, Dominik Röttsches, Doug Schepers, Douglas Livingstone, Elliott Sprehn, Elliotte Harold, Eric Lawrence, Eric Uhrhane, Erik Arvidsson, Erik Dahlström, Feras Moussa, Gideon Cohn, Glenn Adams, Gorm Haug Eriksen, Gregory Terzian, Håkon Wium Lie, Hallvord R. M. Steen, Henri Sivonen, Hiroshige Hayashizaki, Huub Schaeks, Ian Clelland, Ian Davis, Ian Hickson, Ivan Herman, Jake Archibald, 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, Keith Yeung, 田村健人 (Kent TAMURA), Lachlan Hunt, Maciej Stachowiak, Magnus Kristiansen, Manish Goregaokar, Marc Hadley, Marcos Caceres, Mark Baker, Mark Birbeck, Mark Nottingham, Mark S. Miller, Martin Hassman, Mike Pennisi, Mohamed Zergaoui, Ms2ger, Odin Hørthe Omdal, Olli Pettay, Pawel Glowacki, Peter Michaux, Philip Jägenstedt, Philip Taylor, Robin Berjon, Rune F. Halvorsen, Ruud Steltenpool, Ryo Onodera, Sam Sneddon, Sergiu Dumitriu, Shivakumar Jagalur Matt, Sigbjørn Finne, Simon Pieters, Stewart Brodie, Sunava Dutta, Takeshi Kurosawa, Takeshi Yoshino, Thomas Roessler, Thomas Wisniewski, Tom Magliery, Travis Leithead, triple-underscore, Yaron Tausky, Yehuda Katz, Youenn Fablet, and Zhenbin Xu for their contributions to this standard.

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 to Ian Hickson for drafting an initial version of this specification in the HTML Standard (then Web Applications 1.0). [HTML]

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

This standard is written by Anne van Kesteren (Mozilla, annevk@annevk.nl).

Intellectual property rights

Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). This work is licensed under a Creative Commons Attribution 4.0 International License. To the extent portions of it are incorporated into source code, such portions in the source code are licensed under the BSD 3-Clause License instead.