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.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, 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 TLS client certificates. Specifically it does not refer to proxy authentication or the Origin header. [COOKIES]

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

[Constructor,
 Exposed=(Window,DedicatedWorker,SharedWorker)]
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, 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 BodyInit)? 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.

An XMLHttpRequest object has an associated stop timeout 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 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 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, and upload listener 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 listener 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, entry settings object's 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 entry settings object's 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 exception when it occurs.

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

1. If context object's relevant settings object has a responsible document and it is not fully active, throw an InvalidStateError exception.

2. If method is not a method, throw a SyntaxError exception.

3. If method is a forbidden method, throw a SecurityError exception.

4. Normalize method.

5. Let parsedURL be the result of parsing url with context object's relevant settings object's API base URL.

6. If parsedURL is failure, throw a SyntaxError exception.

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

8. If parsedURL's host is non-null, run these substeps:

   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.

9. If async is false, entry settings object's 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 exception.

10. Terminate the request.

    A fetch can be ongoing at this point.

11. Set variables associated with the object as follows:

    • Unset the send() flag, stop timeout 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 ArrayBuffer object to null.

    • Set response Blob object to null.

    • Set response Document object to null.

    • Set response JSON object to null.

12. If the state is not opened, run these substeps:

    1. Set 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 either state is not opened or 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 state is not opened, throw an InvalidStateError exception.

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

3. Normalize value.

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

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

When set: throws an InvalidAccessError exception if the synchronous flag is set and entry settings object's 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 entry settings object's global object is a Window object 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 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, throw an InvalidStateError exception.

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

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 optional argument provides the request body. The argument is ignored if request method is GET or HEAD.

Throws an InvalidStateError exception 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, 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 with the require well-formed flag set, converted to Unicode, and utf-8 encoded. Rethrow any exceptions.

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

   BodyInit

   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, then set all the `charset` parameters whose value is not a case-insensitive match for encoding of that `Content-Type` header's value to encoding.

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. If req's body is null, set the upload complete flag.

9. Set the send() flag.

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

    1. Fire a progress event named loadstart 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 on the XMLHttpRequestUpload object with 0 and req's body's total bytes.

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

       Run these subsubsteps in parallel:

       1. Let milliseconds be zero.

       2. Every millisecond, as long as the stop timeout flag is unset, queue a microtask to run these subsubsubsteps:

          1. Increase milliseconds by one.

          2. If milliseconds is equal or greater than the timeout attribute value and the timeout attribute value is not zero, terminate fetching with reason timeout.

       To process request body for request, run these subsubsteps:

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

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

       These subsubsteps are only invoked when new bytes are transmitted.

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

       1. Set the upload complete flag.

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

       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 on the XMLHttpRequestUpload object with transmitted and length.

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

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

       To process response for response, run these subsubsteps:

       1. If the stop timeout flag is unset, set the stop timeout flag.

       2. Set response to response.

       3. Handle errors for response.

       4. If response is a network error, return.

       5. Set state to headers received.

       6. Fire an event named readystatechange.

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

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

       9. Let reader be the result of getting a reader from response's body's stream.

          This operation will not throw an exception.

       10. 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 subsubsubsteps and then run the above subsubstep again:

           1. Append the value property to received bytes.

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

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

           4. Fire an event named readystatechange.

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

           5. Fire a progress event named progress with response's body's transmitted bytes and response's body's total bytes.

           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.

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

    1. Let response be the result of fetching req.

       If the timeout attribute value is not zero, terminate this fetch if it has not returned within the amount of milliseconds from the timeout attribute value with reason timeout.

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

    3. Let reader be the result of getting a reader from response's body's stream.

       This operation will not throw an exception.

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

    5. Wait for promise to be fulfilled or rejected.

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

    7. 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. Fire a progress event named progress with transmitted and length.

6. Set state to done.

7. Unset the send() flag.

8. Fire an event named readystatechange.

9. Let transmitted be response's body's transmitted bytes.

10. Let length be response's body's total bytes.

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. Set 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. 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 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. If upload listener flag is unset, then terminate these substeps.

   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 event with 0 and 0.

8. 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, when invoked, must run these steps:

1. Terminate the request.

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

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 must run these steps:

1. If response's header list has no header whose name is name, then return null.

2. Return the combined value given name and response's header list.

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 == this.HEADERS_RECEIVED) {
    print(client.getResponseHeader("Content-Type"));
  }
}

text/plain; charset=UTF-8

4.6.5 The getAllResponseHeaders() method

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

1. Let output be an empty byte sequence.

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

3. For each header in headers, run these substeps:

   1. Append header's name, followed by a 0x3A 0x20 byte pair, followed by header's value, to output.

   2. If header is not the last pair in headers, then append a 0x0D 0x0A byte pair, to output.

4. 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());
  }
}

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. Set response ArrayBuffer object to a new ArrayBuffer object representing received bytes. If this throws an exception, then set response ArrayBuffer object to null and set received bytes to the empty byte sequence.

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

3. Return response ArrayBuffer object.

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. Set response Blob object to a new Blob object representing received 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. If response's body is null, then return null.

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

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

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

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

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

8. Set document's encoding to charset.

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

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

11. Set document's origin to context object's relevant settings object's origin.

12. 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. If response's body is null, then return null.

3. Let JSON text be the result of running utf-8 decode on received bytes.

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

5. Set response JSON object to JSON object 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 final MIME type is either null, text/xml, application/xml or ends in +xml, use the rules set forth in the XML specifications to determine the encoding. Let charset be the determined encoding. [XML] [XMLNS]

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

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

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

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

Throws an InvalidStateError exception if 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 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 entry settings object's global object is not a Window object.

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

When set: throws an InvalidAccessError exception if the synchronous flag is set and entry settings object's 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 entry settings object's global object is not a Window object and the given value is "document", terminate these steps.

2. If state is loading or done, throw an InvalidStateError exception.

3. If entry settings object's global object is a Window object 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 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 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 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 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 USVString) FormDataEntryValue;

[Constructor(optional HTMLFormElement form),
 Exposed=(Window,Worker)]
interface FormData {
  void append(USVString name, USVString value);
  void append(USVString name, Blob value, 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 value, optional USVString filename);
  iterable<USVString, FormDataEntryValue>;
};

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 its value is a string and "file" otherwise. If an entry's type is "file", its 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, set fd's entries to the result of constructing the form data set for form.

3. Return fd.

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

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

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

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

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

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

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

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

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

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

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

The value pairs to iterate over are the entries with the key being the name and the value the value.

6 Interface ProgressEvent

[Constructor(DOMString type, optional ProgressEventInit eventInitDict),
 Exposed=(Window,DedicatedWorker,SharedWorker)]
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 a 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

Thanks to Addison Phillips, Adrian Bateman, Ahmed Kamel, Alan Thomas, Alex Hopmann, Alex Vincent, Alexey Proskuryakov, Andrea Marchesini, Asbjørn Ulsberg, Bertrand Guay-Paquet, Björn Höhrmann, Boris Zbarsky, Caitlin Potter, Cameron McCormack, 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, Geoffrey Sneddon, Gideon Cohn, Glenn Adams, Gorm Haug Eriksen, Håkon Wium Lie, Hallvord R. M. Steen, Henri Sivonen, Hiroshige Hayashizaki, Huub Schaeks, 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, 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 Jägenstedt, Philip Taylor, Robin Berjon, Rune F. Halvorsen, Ruud Steltenpool, 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, 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).

Per CC0, to the extent possible under law, the editor has waived all copyright and related or neighboring rights to this work.