xhr.spec.whatwg.orgXMLHttpRequest Standard

XMLHttpRequest Living Standard — Last Updated 19 February 2024 Participate: GitHub whatwg/xhr ( new issue , open issues ) Chat on Matrix Commits: GitHub whatwg/xhr/commits Snapshot as of this commit @xhrstandard Tests: web-platform-tests xhr/ ( ongoing work ) Translations (non-normative) : 日本語 Abstract The defines an API that provides scripted client functionality for transferring data between a client and a server. Table of Contents 1 Introduction 1.1 Specification history 2 Terminology 3 Interface XMLHttpRequest 3.1 Constructors 3.2 Garbage collection 3.3 Event handlers 3.4 States 3.5 Request 3.5.1 The open() method 3.5.2 The setRequestHeader() method 3.5.3 The timeout getter and setter 3.5.4 The withCredentials getter and setter 3.5.5 The upload getter 3.5.6 The send() method 3.5.7 The abort() method 3.6 Response 3.6.1 The responseURL getter 3.6.2 The status getter 3.6.3 The statusText getter 3.6.4 The getResponseHeader() method 3.6.5 The getAllResponseHeaders() method 3.6.6 Response body 3.6.7 The overrideMimeType() method 3.6.8 The responseType getter and setter 3.6.9 The response getter 3.6.10 The responseText getter 3.6.11 The responseXML getter 3.7 Events summary 4 Interface FormData 5 Interface ProgressEvent 5.1 Firing events using the ProgressEvent interface 5.2 Suggested names for events using the ProgressEvent interface 5.3 Security considerations 5.4 Example Acknowledgments Intellectual property rights Index Terms defined by this specification Terms defined by reference References Normative References IDL Index 1. Introduction This section is non-normative. The XMLHttpRequest object is an API for fetching resources. The name XMLHttpRequest is historical and has no bearing on its functionality. Some simple code to do something with data from an XML document fetched over the network: function processData ( data ) { // taking care of data } function handler () { if ( this . 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 (); If you just want to log a message to the server: function log ( message ) { var client = new XMLHttpRequest (); client . open ( "POST" , "/log" ); client . setRequestHeader ( "Content-Type" , "text/plain;charset=UTF-8" ); client . send ( message ); } Or if you want to check the status of a document on the server: function fetchStatus ( address ) { var client = new XMLHttpRequest (); client . 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. Terminology This specification depends on the Infra Standard. [INFRA] This specification uses terminology from DOM, DOM Parsing and Serialization, Encoding, Fetch, File API, HTML, URL, Web IDL, and XML. [DOM] [DOM-PARSING] [ENCODING] [FETCH] [FILEAPI] [HTML] [URL] [WEBIDL] [XML] [XML-NAMES] 3. 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 undefined open ( ByteString method , USVString url ); undefined open ( ByteString method , USVString url , boolean async , optional USVString ? username = null , optional USVString ? password = null ); undefined setRequestHeader ( ByteString name , ByteString value ); attribute unsigned long timeout ; attribute boolean withCredentials ; [ SameObject ] readonly attribute XMLHttpRequestUpload upload ; undefined send ( optional ( Document or XMLHttpRequestBodyInit )? body = null ); undefined abort (); // response readonly attribute USVString responseURL ; readonly attribute unsigned short status ; readonly attribute ByteString statusText ; ByteString ? getResponseHeader ( ByteString name ); ByteString getAllResponseHeaders (); undefined 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: upload object An XMLHttpRequestUpload object. state One of unsent , opened , headers received , loading , and done ; initially unsent . send() flag A flag, initially unset. timeout An unsigned integer, initially 0. cross-origin credentials A boolean, initially false. request method A method . request URL A URL . author request headers A header list , initially empty. request body Initially null. synchronous flag A flag, initially unset. upload complete flag A flag, initially unset. upload listener flag A flag, initially unset. timed out flag A flag, initially unset. response A response , initially a network error . received bytes A byte sequence , initially the empty byte sequence. response type One of the empty string, " arraybuffer ", " blob ", " document ", " json ", and " text "; initially the empty string. response object An object, failure, or null, initially null. fetch controller A fetch controller , initially a new fetch controller . The send() method sets it to a useful fetch controller , but for simplicity it always holds a fetch controller . override MIME type A MIME type or null, initially null. Can get a value when overrideMimeType() is invoked. 3.1. Constructors client = new XMLHttpRequest() Returns a new XMLHttpRequest object. The new XMLHttpRequest() constructor steps are: Set this ’s upload object to a new XMLHttpRequestUpload object. 3.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 XMLHttpRequest object’s fetch controller . 3.3. Event handlers The following are the event handlers (and their corresponding event handler event types ) that must be supported on objects implementing an interface that inherits from XMLHttpRequestEventTarget as attributes: event...