In most browsers, XMLHttpRequest is a standard Javascript class, so you just create a new instance XMLHttpRequest. However, Microsoft were the inventors of XMLHttpRequest, and until IE7, IE only offered it as an ActiveX object. To make things even more fun, there are different versions of that object. The following code shows a factory function that works on all browsers that support XMLHttpRequest:

    function createXMLHttpRequest() {
        try { return new ActiveXObject("Msxml2.XMLHTTP"); } catch (e) {}
        try { return new ActiveXObject("Microsoft.XMLHTTP"); } catch (e) {}
        try { return new XMLHttpRequest(); } catch(e) {}
        alert("XMLHttpRequest not supported");
        return null;
      }
      ...
    var xhReq = createXMLHttpRequest();

You really need to use a function like this for maximum portability. Once you have the object, its basic functionality and API are pretty consistent across browsers, but be sure to test carefully as there are a few subtle implementation differences in some browsers. (If you're curious, the “HTTP Streaming” Solution highlights one such inconsistency.)

You can also reuse an XMLHttpRequest, and it's worthwhile doing so in order to prevent memory leaks. To be safe, only start a new call when there's not one already in progress. As explained below, it's possible to inspect the status of a call, and you should only start a call if the status is 0 or 4. So if it's anything else, first call the abort() method to reset status.

I previously mentioned that under synchronous mode, "the code will block until a response comes back". Some hardened readers probably writhed uncomfortably at the thought. We all know that some requests take a long time to process, and some don't come back at all. Pity the user when a server script is buried in an infinite loop.

In practice, XMLHttpRequest Calls should almost always be asynchronous. That means the browser and the user can continue working on other things while waiting for a response to come back. How will you know when the response is ready? The XMLHttpRequest's readyState always reflects the current point in the call's lifecycle. When the object is born, it's at 0. After open() has been called, it's 1. The progression continues until the response is back, at which point the value is 4.

So, to catch the response, you need to watch for a readyState of 4. That's easy enough, because XMLHttpRequest fires readystatechange events. You can declare a callback function using the onreadystatechange field. The callback will then receive all state changes. The states below 4 aren't especially useful and are somewhat inconsistent across browser types anyway. So most of the time, all we're interested in is, "Are you in state 4 (i.e. complete) or not?"

Based on all that, here's an asynchronous version of the code shown earlier:

    var xhReq = createXMLHttpRequest();
    xhReq.open("GET", "sumGet.phtml?figure1=5&figure2=10", true);
    xhReq.onreadystatechange = onSumResponse;
    xhReq.send(null);
    ...
    function onSumResponse() {
      if (xhReq.readyState != 4)  { return; }
      var serverResponse = xhReq.responseText;
      ...
    }

As shown, you declare the callback method in XMLHttpRequest's onreadystatechange property. In addition, the third argument of open() is now true. This argument is actually called the "asynchronous flag", which explains why we're now setting it to true. The callback function, "onSumResponse", is registered using onreadystatechange and contains a guard clause to ensure the readyState is 4 before any processing can occur. At that point, we have the full response in responseText.

Javascript also supports "closures" - a form of anonymous function - which suggests a more concise boilerpolate structure for asynchronous calls:

    var xhReq = createXMLHttpRequest();
    xhReq.open("get", "sumget.phtml?figure1=10&figure2=20", true);
    xhReq.onreadystatechange = function() {
      if (xhReq.readyState != 4)  { return; }
      var serverResponse = xhReq.responseText;
      ...
    };
    xhReq.send(null);

Use closures sparingly, because you're defining a new function each time. It's slower than referring to an existing one, and might also lead to memory leaks.

Asynchronous calls are essential, but also more error-prone. If you look at the callback mechanism, you might notice the potential for a subtle, but serious, bug. The problem arises when the same instance of XMLHttpRequest is simultaneously used for different calls. If Call 2 is issued while the object is still waiting for the response of Call 1, what will the callback function receive? In fact, it's even possible the callback function itself is changed before the first call returns. There are ways to deal with this problem, and they're the topic of the “Call Tracking” pattern.

Sometimes, a request doesn't come back as you expected it, maybe not at all. You scripted the call wrong, or there's a bug in the server, or some part of the infrastructure just screwed up. Thinking asynchronously is the first step to dealing with these problems, because at least your application isn't blocked. But you need to do more than that.

To detect a server error, you can check the response status using XMLHttpRequest's status flag. This is just a standard HTTP code. For example, if the resource is missing, XMLHttpRequest.status will take on the famous "404" value. In most cases, you can assume anything other than 200 is an error situation. This suggests adding a new check to the callback function of the previous section:

    xhReq.onreadystatechange = function() {
      if (xhReq.readyState != 4)  { return; }
      if (xhReq.status != 200)  {
        // Handle error, e.g. Display error message on page
        return;
      }
      var serverResponse = xhReq.responseText;
      ...
    };

That's great if the browser knows a problem occurred, but sometimes the request will be lost forever. Thus, you usually want some kind of timeout mechanism as well. Establish a “Scheduling” timer to track the session. If the request takes too long, the timer will kick in and you can then handle the error. XMLHttpRequest has an abort() function which you should also invoke in a timeout situation. Here's a code sample:

    var xhReq = createXMLHttpRequest();
    xhReq.open("get", "infiniteLoop.phtml", true); // Server stuck in a loop.
    var requestTimer = setTimeout(function() {
        xhReq.abort();
        // Handle timeout situation, e.g. Retry or inform user.
      }, MAXIMUM_WAITING_TIME);
    xhReq.onreadystatechange = function() {
      if (xhReq.readyState != 4)  { return; }
      clearTimeout(requestTimeout);
      if (xhReq.status != 200)  {
        // Handle error, e.g. Display error message on page
        return;
      }
      var serverResponse = xhReq.responseText;
      ...
    };

Compared to the previous example, a timer has been introduced. The onreadystatechange() callback function will clear the timer once it receives the full response (even if that response happens to be erroneous). In the absence of this clearance, the timer will fire, and in this case, the setTimeout sequence stipulates that abort() will be called and some recovery action can then take place.

Up to this point, requests have been simple GET queries - pass in a URL and grab the response. As dicussed in the “RESTful Service” pattern, real-world projects need to work with other request types as well. POST, for example, is suited to calls which affect server state or upload substantial quantities of data. To illustrate, let's now create a new service, sumPostGeneric.phtml, that does the same thing as postGet.phtml but with a POST message. It's called "generic" because it reads the full message body text, as opposed to a CGI-style form submission. In this case, it expects a body like "Calculate this sum: 5+6", and returns the sum value:

    <?
      $body = readBody();
      ereg("Calculate this sum: ([0-9]+)\+([0-9]+)", $body, $groups);
      echo $groups[1] + $groups[2];

      // A PHP method to read arbitrary POST body content.
      function readBody() {
        $body="";
        $putData = fopen("php://input", "r");
        while ($block = fread($putData, 1024)) {
          $body = $body.$block;
        }
        fclose($putData);
        return $body;
      }
    ?>

To POST an arbitrary body, we give XMLHttpRequest a request type of POST and pass the body in as an argument to send(). Note that with GET queries, the send() argument is null as there's no body content.

    var xhreq = createxmlhttprequest();
    xhreq.open("post", "sumPostGeneric.phtml", true);
    xhreq.onreadystatechange = function() {
      if (xhreq.readystate != 4) { return; }
      var serverResponse = xhreq.responsetext;
      ...
    };
    xhreq.send("calculate this sum: 5+6");

Quite often, though, you'll be posting key-value pairs, so you want the message to look as if it were submitted from a POST-based form. You'd do that because it's more standard, and server-side libraries make it easy to write web services that accept standard form data. The service below, sumPostForm.php shows how PHP makes light work of such submissions, and the same is true for most languages:

    <?
      echo $_POST["figure1"] + $_POST["figure2"];
    ?>

For the browser script to make a CGI-style upload, two additional steps are required. First, declare the style in a "Content-Type" header; as the example below shows, XMLHttpRequest lets you directly set request headers. The Second step is to make the body a set of name-value pairs:

    var xhreq = createxmlhttprequest();
    xhReq.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');

    xhreq.open("post", "sumPostForm.phtml", true);
    xhreq.onreadystatechange = function() {
      if (xhreq.readystate != 4) { return; }
      var serverresponse = xhreq.responsetext;
      ...
    };
    xhreq.send("calculate this sum: 5+6");

GET and POST are virtually ubiquitous, but “RESTful Service” points out there's a time and place for other request methods too, such as PUT and DELETE. You don't have to do anything special with those other methods; just set the request type in the open() call, and send() an appropriate body (the item you're putting in the case of PUT; a null argument in the case of DELETE).

On discovering XMLHttpRequest, a common reaction is to start dreaming up an interface that pulls in content from popular websites and mashes it altogether to into one big Web 2.0 soufflé. Unfortunately, it's not so simple because of a key security rule imposed by all major browsers: XMLHttpRequest can only access content from the originating server. If your application lives at http://ajax.shop/admin, then your XMLHttpRequest objects can happily reach http://ajax.shop/admin/products.html and http://ajax.shop/products/contents.html, shouldn't be able to reach http://books.ajax.shop/contents.html, and definitely won't have access to http://google.com.

This "same-origin policy" (or "same-domain policy") will be familiar to developers of Java applets and Flash, where the policy has always been in place. It's there to prevent all kinds of abuse, such as a malicious script grabbing confidential content from one server and uploading it to another server under their own control. Some have suggested it's possibly overkill, that most of the risks it tries to prevent are already possible by other means. However, restrictions like this won't be lifted lightly; the rule's likely to be around for the long term, so we had better learn to work with it.

Given same-origin restrictions, then, how do all those Ajax mashup sites work? The answer is that the cross-domain transfers usually run through the originating server, which acts as a kind of proxy - or tunnel - allowing XMLHttpRequests to communicate with external domains. “Cross-Domain Proxy” elaborates on the pattern and its Alternatives section lists some clever workarounds that do allow the originating server to be bypassed.

The discussion here has swiftly ignored the big elephant in the room: XML. XMLHttpRequest, as its name suggests, was originally designed with, yes, XML in mind. As we've already seen, it will actually accept any kind of response, so what's special about XML? With XMLHttpRequest, any responses can be read via the responseText field, but there's also an alternative accessor: responseXML. If the response header indicates the content is XML, and the response text is a valid XML string, then responseXML will be the DOM object that results from parsing the XML.

The ??? patterns have already illustrated how Javascript supports manipulation of DOM objects. In those patterns, we were only interested in one particular DOM object, the HTML (or XHTML) document representing the current web page. But you can manipulate any other DOM object just as easily. Thus, it's sometimes convenient to have a web service output XML content and manipulate the corresponding DOM object.

The prerequisite here is a “Web Service” that outputs valid XML. There are many libraries and frameworks around for automatically generating XML from databases, code objects, files, or elsewhere. But don't think you have to start learning some fancy XML library in order to create XML web services, because it's fairly easy to hand-code them too, at least for simple data. The service just needs to output an XML Content-type header followed by the entire XML document. Here's an XML version of the sum service shown earlier - it outputs an XML document containing the input figures as well as the sum result:

    <?
      header("Content-Type: text/xml");
      $sum = $_GET["figure1"] + $_GET["figure2"];
      echo <<< END_OF_FILE
    <sum>
      <inputs>
        <figure id="1">{$_GET["figure1"]}</figure>
        <figure id="2">{$_GET["figure2"]}</figure>
      </inputs>
      <outputs>$sum</outputs>
    </sum>
    END_OF_FILE
    ?>

The call sequence is the same as before, but the callback function now extracts the result using responseXML. It then has a first-class DOM object and can interrogate it using the standard DOM API:

    var xhReq = createXMLHttpRequest();
    xhReq.open("GET", "sumXML.phtml?figure1=10&figure2=20", true);
    xhReq.onreadystatechange = function() {
      if (xhReq.readyState != 4) { return; }
      xml = xhReq.responseXML;
      var figure1 = xml.getElementsByTagName("figure")[0].firstChild.nodeValue;
      var figure2 = xml.getElementsByTagName("figure")[1].firstChild.nodeValue;
      var sum = xml.getElementsByTagName("outputs")[0].firstChild.nodeValue;
      ...
    };
    xhReq.send(null);
  });

The name "XMLHttpRequest" relates to its two primary functions: handling HTTP requests and converting XML responses. The former function is critical and the latter is best considered a bonus. There are certainly good applications for XML responses - see “XML Message”, “XML Data Island”, and “Browser-Side XSLT” - but keep in mind that XML is not a requirement of Ajax systems.

You can also upload XML from browser to server. In this case, XMLHttpRequest doesn't offer any special XML functionality; you just send the XML message as you would any other message, and with an appropriate request type (e.g. POST or PUT). To support the receiving web service, the Javascript should generally declare the XML content type in a request header:

    xhReq.setRequestHeader('Content-Type',  "text/xml");

We've looked at how to achieve typical tasks with XMLHttpRequest, and now here's a quick summary of its properties and methods based on an Apple Developer Connection article. The API is supported by IE5+, the Mozilla family (including all Firefox releases), and Safari 1.2+.

XMLHttpRequest has the following properties:

And these are XMLHttpRequest's methods:

It's possible that an XMLHttpRequest response will be cached by the browser. Sometimes, that's what you want and sometimes it's not, so you need to exert some control over caching.

With cache control, we're talking about GET based requests. Use GET for read-only queries and other request types for operations that affect server state. If you use POST to get information, that information usually won't be cached. Likewise, if you use GET to change state, you run the risk that the call won't always reach the server, because the browser will cache the call locally. There are other reasons to follow these this advice too; see “RESTful Service”.

Often, you want to suppress caching in order to get the latest server information, in which case a few techniques are relevant. Since browsers and servers vary, the standard advice is spread the net as wide as possible by combining some of these techniques:

On the other hand, caching is a good thing when the service is time-consuming and unlikely to have changed recently. To encourage caching, you can reverse the above advice, e.g. set the "Expires" headers to a suitable time in the future. In addition, a good approach for smaller data is to cache it in the program itself, using a Javascript data structure. “Browser-Side Cache” explains how.

The section on error detection left open the question of what to do once we discover a server timeout or non-standard error code. There are three possible actions:

Brett Stimmerman's Lace Chat is an Ajax chat application that uses XMLHttpRequest in two ways: to upload messages you type, and to download all the latest messages from the server (Figure 1.7, “Lace Chat”).

Figure 1.7. Lace Chat

Backbase's Demo RSS Reader, which uses XMLHttpRequest to pull down titles of recent articles (Figure 1.8, “Backbase RSS Reader”). When you click on one of those titles, a new XMLHttpRequest will pull down the entire content.

Figure 1.8. Backbase RSS Reader

Phil Endecott's Anyterm is an Ajax terminal emulator allowing you to run telnet or SSH within the browser. It uses XMLHttpRequest Calls to upload keystrokes and download the latest screen state.

Mint is a website statistics package. Site owners include Mint javascript on each page, which quietly inspects the user's browser settings and uploads them using an XMLHttpRequest.

The conventional way to communicate with the server is for the browser to request an entirely new page, which is pretty extreme when you stop and think about it. It might be appropriate if the user's navigating to a completely different part of a website, but it's overkill if you want to update a football score at the bottom of the page, or upload some user input. The most familiar kind of full page refresh is the hyperlink, which causes the browser to issue a GET request, clear the current page, and output the response. The other kind of full page refresh is a form submission, which causes the browser to pass some parameters with the request - which will be GET, POST, or some other method - and, as with a hyperlink, replace the previous page with the new response. With web remoting, any user-interface changes are completely at the discretion of the script running inside the page. These conventional techniques are still available, but most server communication uses XMLHttpRequest Call and related technologies.

“IFrame Call” is the main alternative to XMLHttpRequest. Like XMLHttpRequest, it allows for remote calls using GET, POST, and other request types. But whereas XMLHttpRequest is designed specifically for web remoting, IFrame Call exploits the IFrame to do something it was never really intended to do, and the code shows it. Here's a summary of XMLHttpRequest's strengths over “IFrame Call”s:

For all these reasons, XMLHttpRequest should be the default choice. However, there are some specialised situations where “IFrame Call” is superior:

“HTTP Streaming” also allows for web remoting, and unlike XMLHttpRequest, the connection remains open. Functionally, the key advantage over XMLHttpRequest is that the server can continuously push new information to the browser. From a resource perspective, streaming is good insofar as there's less starting and stopping of connections, but there are serious scaleability issues as it's rarely feasible to keep open a huge amounts of connections and maintain numerous server-side scripts.

The “Richer Plugin” pattern discusses Java, Flash, and other plugins and extensions. These components often have permission to call the server programmatically. and in some cases, can be used as proxies available to Javascript code.

“On-Demand Javascript” describes a couple of ways to download Javascript on the fly. One involves XMLHttpRequests (and therefore isn't foundational in itself), but the other is an alternative transport mechanism, a different technique for web remoting. It works by adding a script element to the document body, which has the effect of automatically pulling down a named Javascript file.

Brent Ashley's RSLite library is an unusual alternative based on images and cookies. An image's source property is set to the service URL, which is simply a means of invoking the service. The service writes its response into one or more cookies, which will then be accessible from the Javascript once the call has completed.

Another way to get at server state is to dynamically change a CSS stylesheet. Just like setting a new Javascript or image source, you set a stylesheet's href property to point to the web service. In Julien Lamarre's demo of this technique, the web service actually outputs a stylesheet, and the response is embedded in the URL of a background-image property!

An old - and pretty much obsolete - trick is to have the server respond with a 204 "No Content" response code. Browsers won't refresh the page when they see this code, meaning that your script can quietly submit a form to such a service with no impact on the page. However, you can only use the 204 trick for "fire-and-forget" calls - while the response may contain response information embedded in the headers, there's no way for a browser script to access it.

There's a technique specifically for retrieving XML documents which uses similar technology to XMLHttpRequest. Peter-Paul Koch described the technique back in 2000, and recently suggested it can now be written off.