From Wikipedia, the free encyclopedia

XMLHttpRequest (XHR) is a DOM API that can be used inside a web browser scripting language, such as JavaScript, to send an HTTP or an HTTPS request directly to a web server and load the server response data directly back into the scripting language.^[1] Once the data is within the scripting language, it is available as both an XML document, if the response was valid XML markup,^[2] and as plain text.^[3] The XML data can be used to manipulate the currently active document in the browser window without the need of the client loading a new web page document. Plain text data can be evaluated within the scripting language to manipulate the document, too; in the example of JavaScript, the plain text may be formatted as JSON by the web server and evaluated within JavaScript to create an object of data for use on the current DOM.

XMLHttpRequest has an important role in the AJAX web development technique. It is currently used by many websites to implement responsive and dynamic web applications. Examples of these web applications include Gmail, Google Maps, Bing Maps, the MapQuest dynamic map interface, Facebook, and others.

History and support

The concept behind the XMLHttpRequest object was originally created by the developers of Outlook Web Access for Microsoft Exchange Server 2000.^[4] An interface called IXMLHTTPRequest was developed and implemented into the second version of the MSXML library using this concept.^[4][5] The second version of the MSXML library was shipped with Internet Explorer 5.0 in March 1999, allowing access, via ActiveX, to the IXMLHTTPRequest interface using the XMLHTTP wrapper of the MSXML library.^[6]

The Mozilla Foundation developed and implemented an interface called nsIXMLHttpRequest into the Gecko layout engine. This interface was modelled to work as closely to Microsoft's IXMLHTTPRequest interface as possible.^[7][8] Mozilla created a wrapper to use this interface through a JavaScript object which they called XMLHttpRequest.^[9] The XMLHttpRequest object was accessible as early as Gecko version 0.6 released on December 6 of 2000,^[10][11] but it was not completely functional until as late as version 1.0 of Gecko released on June 5 of 2002.^[10][11] The XMLHttpRequest object became a de facto standard amongst other major user agents, implemented in Safari 1.2 released in February 2004,^[12] Konqueror, Opera 8.0 released in April 2005,^[13] and iCab 3.0b352 released in September 2005.^[14]

The World Wide Web Consortium ("W3C") published a Working Draft specification for the XMLHttpRequest object on April 5 of 2006, edited by Anne van Kesteren of Opera Software and Dean Jackson of W3C.^[15] Its goal is "to document a minimum set of interoperable features based on existing implementations, allowing Web developers to use these features without platform-specific code." The last revision to the XMLHttpRequest object specification was on November 19 of 2009, being a last call working draft.^{[16] [17]}

Microsoft added the XMLHttpRequest object identifier to its scripting languages in Internet Explorer 7.0 released in October 2006, six months after the initial draft of the XMLHttpRequest specification.^[6]

The W3C has since published another Working Draft specification for the XMLHttpRequest object, "XMLHttpRequest Level 2," on February 25 of 2008.^[18] Level 2 consists of extended functionality to the XMLHttpRequest object, including, but not currently limited to, progress events, support for cross-site requests, and the handling of byte streams. The last revision to the XMLHttpRequest Level 2 specification was on September 30 of 2008, still being a working draft.^[19]

Support in Internet Explorer versions 5, 5.5 and 6

Internet Explorer versions 5 and 6 did not define the XMLHttpRequest object identifier in their scripting languages as the XMLHttpRequest identifier itself was not standard at the time of their releases.^[6] Backward compatibility can be achieved through object detection if the XMLHttpRequest identifier does not exist.

An example of how to instantiate an XMLHttpRequest object with support for Internet Explorer versions 5 and 6 in JavaScript is below.^[20]

/* Provide the XMLHttpRequest class for IE 5.x-6.x:
   Other browsers (including IE 7.x-8.x) ignore this
   when XMLHttpRequest is predefined
   This example is based on findings at:
   http://blogs.msdn.com/xmlteam/archive/2006/10/23/using-the-right-version-of-msxml-in-internet-explorer.aspx
*/
if (typeof XMLHttpRequest == "undefined") {
  XMLHttpRequest = function () {
    try { return new ActiveXObject("Msxml2.XMLHTTP.6.0"); }
      catch (e1) {}
    try { return new ActiveXObject("Msxml2.XMLHTTP.3.0"); }
      catch (e2) {}
    try { return new ActiveXObject("Msxml2.XMLHTTP"); }
      catch (e3) {}
    //Microsoft.XMLHTTP points to Msxml2.XMLHTTP.3.0 and is redundant
    throw new Error("This browser does not support XMLHttpRequest.");
  };
}

Web pages that use XMLHttpRequest or XMLHTTP can mitigate the current minor differences in the implementations either by encapsulating the XMLHttpRequest object in a JavaScript wrapper, or by using an existing framework that does so. In either case, the wrapper should detect the abilities of current implementation and work within its requirements.

HTTP request

The following is how a request using the XMLHttpRequest object functions in a conforming user agent based on the W3C Working Draft. As the W3C standard for the XMLHttpRequest object is still a draft, user agents may not abide by all the functionings of the W3C definition and any of the following is subject to change. Extreme care should be taken into consideration when scripting with the XMLHttpRequest object across multiple user agents. This article will try to list the inconsistencies between the major user agents.

The open method

The HTTP and HTTPS requests of the XMLHttpRequest object must be initialized through the open method. This method must be invoked prior to the actual sending of a request to validate and resolve the request method, URL, and URI user information to be used for the request. This method does not assure that the URL exists or the user information is correct. This method can accept up to five parameters, but requires only two, to initialize a request.

The first parameter of the method is a text string indicating the HTTP request method to use. The request methods that must be supported by a conforming user agent, defined by the W3C draft for the XMLHttpRequest object, are currently listed as the following.^[21]

• GET (Supported by IE7+, Mozilla 1+)
• POST (Supported by IE7+, Mozilla 1+)
• HEAD (Supported by IE7+)
• PUT
• DELETE
• OPTIONS (Supported by IE7+)

However, request methods are not limited to the ones listed above. The W3C draft states that a browser may support additional request methods at their own discretion.

The second parameter of the method is another text string, this one indicating the URL of the HTTP request. The W3C recommends that browsers should raise an error and not allow the request of a URL with either a different port or ihost URI component from the current document.^[22]

The third parameter, a boolean value indicating whether or not the request will be asynchronous, is not a required parameter by the W3C draft. The default value of this parameter should be assumed to be true by a W3C conforming user agent if it is not provided. An asynchronous request ("true") will not wait on a server response before continuing on with the execution of the current script. It will instead invoke the onreadystatechange event listener of the XMLHttpRequest object throughout the various stages of the request. A synchronous request ("false") however will hang execution of the current script until the request has been completed, not invoking the onreadystatechange event listener.

The fourth and fifth parameters are the URI user and password, respectively. These parameters are not required and should default to the current user and password of the document if not supplied, as defined by the W3C draft.

The setRequestHeader method

Upon successful initialization of a request, the setRequestHeader method of the XMLHttpRequest object can be invoked to send HTTP headers with the request. The first parameter of this method is the text string name of the header. The second parameter is the text string value. This method must be invoked for each header that needs to be sent with the request. Any headers attached here will be removed the next time the open method is invoked in a W3C conforming user agent.

The send method

To send an HTTP request, the send method of the XMLHttpRequest must be invoked. This method accepts a single parameter containing the content to be sent with the request. This parameter may be omitted if no content needs to be sent. The W3C draft states that this parameter may be any type available to the scripting language as long as it can be turned into a text string, with the exception of the DOM document object. If a user agent cannot stringify the parameter, then the parameter should be ignored.

If the parameter is a DOM document object, a user agent should assure the document is turned into well-formed XML using the encoding indicated by the inputEncoding property of the document object. If the Content-Type request header was not added through setRequestHeader yet, it should automatically be added by a conforming user agent as "application/xml;charset=charset," where charset is the encoding used to encode the document.

The onreadystatechange event listener

If the open method of the XMLHttpRequest object was invoked with the third parameter set to true for an asynchronous request, the onreadystatechange event listener will be automatically invoked for each of the following actions that change the readyState property of the XMLHttpRequest object.

• After the open method has been invoked successfully, the readyState property of the XMLHttpRequest object should be assigned a value of 1.
• After the send method has been invoked and the HTTP response headers have been received, the readyState property of the XMLHttpRequest object should be assigned a value of 2.
• Once the HTTP response content begins to load, the readyState property of the XMLHttpRequest object should be assigned a value of 3.
• Once the HTTP response content has finished loading, the readyState property of the XMLHttpRequest object should be assigned a value of 4.

The major user agents are inconsistent with the handling of the onreadystatechange event listener.

The HTTP response

After a successful and completed call to the send method of the XMLHttpRequest, if the server response was valid XML and the Content-Type header sent by the server is understood by the user agent as an Internet media type for XML, the responseXML property of the XMLHttpRequest object will contain a DOM document object. Another property, responseText will contain the response of the server in plain text by a conforming user agent, regardless of whether or not it was understood as XML.

See also

• Hypertext Transfer Protocol
• Representational State Transfer
• Ajax
• JsHttpRequest

References

External links

• Level 1 specification of the XMLHttpRequest object from W3C
• Level 2 specification of the XMLHttpRequest object from W3C
• Specification of the XMLHttpRequest object for Apple developers
• Specification of the XMLHttpRequest object for Microsoft developers
• Specification of the XMLHttpRequest object for Mozilla developers
• Specification of the XMLHttpRequest object for Opera developers
• "Attacking AJAX Applications", a presentation given at the Black Hat security conference. Discusses several issues involving XHR and the future of cross-domain AJAX.

From Wikibooks, the open-content textbooks collection

This is a guide and reference to the XMLHttpRequest object, a key component to know in Ajax programming.

Object reference

Methods

abort()

Cancels the current request.

getAllResponseHeaders()

Returns the complete set of HTTP headers as a string.

getResponseHeader(headerName)

Returns the value of the specified HTTP header.

open(method, URL)

open(method, URL, async)

open(method, URL, async, userName)

open(method, URL, async, userName, password)

Specifies the method, URL, and other optional attributes of a request.

• The method parameter can have a value of GET, POST, HEAD, PUT, DELETE, or a variety of other HTTP methods listed in the W3C specification.
• The URL parameter may be either a relative or complete URL.
• The async parameter specifies whether the request should be handled asynchronously or not – true means that script processing carries on after the send() method, without waiting for a response, and false means that the script waits for a response before continuing script processing.

send(content)

Sends the request. content can be a string or reference to a document.

setRequestHeader(label, value)

Adds a label/value pair to the HTTP header to be sent.

Properties

onreadystatechange

Specifies a reference to an event handler for an event that fires at every state change

readyState

Returns the state of the object as follows:

• 0 = uninitialized – open() has not yet been called.
• 1 = open – send() has not yet been called.
• 2 = sent – send() has been called, headers and status are available.
• 3 = receiving – Downloading, responseText holds partial data
• 4 = loaded – Finished.

responseText

Returns the response as a string.

responseXML

Returns the response as XML. This property returns an XML document object, which can be examined and parsed using W3C DOM node tree methods and properties.

responseBody

Returns the response as a binary encoded string. This property is not part of the native XMLHttpRequest wrapper. For this property to be available, the XHR object must be created with an ActiveX component. A JScript example:

if(typeof ActiveXObject != "undefined") {
  xmlhttp = new ActiveXObject("MSXML2.XMLHTTP");
  xmlhttp.open("GET", "#", false);
  xmlhttp.send(null);
  alert(xmlhttp.responseBody);
} else {
  alert("This browser does not support Microsoft ActiveXObjects.")
}

status

Returns the HTTP status code as a number (e.g. 404 for "Not Found" and 200 for "OK"). Some network-related status codes (e.g. 408 for "Request Timeout") cause errors to be thrown in Firefox if the status fields are accessed. If the server does not respond (properly), IE returns a WinInet Error Code (e.g 12029 for "cannot connect").

statusText

Returns the status as a string (e.g. "Not Found" or "OK").

Bugs and inconsistencies

Dealing with bugs and inconsistencies in XMLHttpRequest implementations:

Caching

Most of the implementations also realize HTTP caching. Internet Explorer and Firefox do, but there is a difference in how and when the cached data is revalidated. Firefox revalidates the cached response every time the page is refreshed, issuing an "If-Modified-Since" header with value set to the value of the "Last-Modified" header of the cached response.

Internet Explorer does so only if the cached response is expired (i.e., after the date of received "Expires" header). This raises some issues, since a bug exists in Internet Explorer, where the cached response is never refreshed.

It is possible to unify the caching behavior on the client. The following script illustrates an example approach:

var request = new XMLHttpRequest();
request.open("GET", url, false);
request.send(null);
if(!request.getResponseHeader("Date")) {
  var cached = request;
  request = new XMLHttpRequest();
  var ifModifiedSince =
    cached.getResponseHeader("Last-Modified") ||
    new Date(0); // January 1, 1970
  request.open("GET", url, false);
  request.setRequestHeader("If-Modified-Since", ifModifiedSince);
  request.send("");
  if(request.status == 304) {
    request = cached;
  }
}

In Internet Explorer, if the response is returned from the cache without revalidation, the "Date" header is an empty string. The workaround is achieved by checking the "Date" response header and issuing another request if needed. In case a second request is needed, the actual HTTP request is not made twice, as the first call would not produce an actual HTTP request.

The reference to the cached request is preserved, because if the response code/status of the second call is "304 Not Modified", the response body becomes an empty string ("") and then it is needed to go back to the cached object. A way to save memory and expenses of second object creation is to preserve just the needed response data and reuse the XMLHttpRequest object.

The above script relies on the assumption that the "Date" header is always issued by the server, which should be true for most server configurations. Also, it illustrates a synchronous communication between the server and the client. In case of asynchronous communication, the check should be made during the callback.

This problem is often overcome by employing techniques preventing the caching at all. Using these techniques indiscriminately can result in poor performance and waste of network bandwidth.

If script executes operation that has side effects (e.g. adding a comment, marking message as read) which requires that request always reaches the end server, it should use POST method instead.

Workaround

Internet Explorer will also cache dynamic pages and this is a problem because the URL of the page may not change but the content will (for example a news feed). A workaround for this situation can be achieved by adding a unique time stamp or random number, or possibly both, typically using the Date object and/or Math.random().

For simple document request the query string delimiter '?' can be used, or for existing queries a final sub-query can be added after a final '&' – to append the unique query term to the existing query. The downside is that each such request will fill up the cache with useless (never reused) content that could otherwise be used for other cached content (more useful data will be purged from cache to make room for these one-time responses).

A better workaround can be achieved by adding meta tags to dynamic pages in order to make them no-cachable:

<meta http-equiv="Pragma" content="no-cache" />
<meta http-equiv="Expires" content="-1" />

Reusing XMLHttpRequest Object in IE

In IE, if the open method is called after setting the onreadystatechange callback, there will be a problem when trying to reuse the XHR object. To be able to reuse the XHR object properly, use the open method first and set onreadystatechange later. This happens because IE resets the object implicitly in the open method if the status is 'completed'. For more explanation of reuse: Reusing XMLHttpRequest Object in IE. The downside to calling the open method after setting the callback is a loss of cross-browser support for readystates. See the quirksmode article.

Links

• W:XMLHttpRequest