WebKit DOM Programming Topics: Fetching with XMLHttpRequest

Safari, Dashboard, and WebKit-based applications support the JavaScript XMLHttpRequest object. XMLHttpRequest (often abbreviated as XHR) allows you to easily fetch content from a server and use it within your webpage or widget without requiring a page reload.

For example, you can use XHR to update a store search page so that when the user enters a Zip code, your site can display stores within a reasonable distance. Clicking on a store could then fill a particular content div with details on that store.

Of course, you could do any of these things without XHR (by requiring a full page load or by including information about every store in the country in a single page), but XHR provides a way to do this more efficiently with less bandwidth.

About XMLHttpRequest

XMLHttpRequest is a JavaScript object provided by WebKit that fetches data via HTTP for use within your JavaScript code. It’s tuned for retrieving XML data but can be used to perform any HTTP request. XML data is made available in a DOM object that lets you use standard DOM operations, as discussed in Using the Document Object Model, to extract data from the request response.

Typically, you define an XMLHttpRequest object’s options and provide an onload or onreadystatechange handler, then send the request. When the request is complete, you work with either the request’s response text or its response XML, as discussed in XMLHttpRequest Responses.

Defining an XMLHttpRequest Object

To create a new instance of the XMLHttpRequest object, call the object’s constructor with the new keyword and save the result in a variable, like this:

var myRequest = new XMLHttpRequest();

After you have created a new XMLHttpRequest object, call open to initialize the request:

myRequest.open("GET", "http://www.apple.com/");

The open method requires two arguments: the HTTP method and the URI of the data to fetch. It also can take three more arguments: an asynchronous flag, a username, and a password. By default, XMLHttpRequest executes asynchronously.

After you open the request, use setRequestHeader to provide any optional HTTP headers for the request, like this:

myRequest.setRequestHeader("Cache-Control", "no-cache");

Note

This particular header asks web caches between the browser and the server to not serve the request from a cache. Not all caches respect these flags, however, and some browsers do not consistently respect it, either.

This can be problematic if, for example, you send a request in an onChange handler on a form field. If that request can be cached, any request that changes the field back to a previous value won’t ever reach the server, resulting in the UI not matching the actual values stored on the server.

Thus, if it is absolutely essential that a request not be served from a cache, you should err on the side of caution by adding a timestamp or other nonrecurring value to the end of each URL. For example: http://mysite.mydomain.top/file.html?junktimevalue=1187999959.

To handle the different states of a request, set a handler function for the onreadystatechange event:

myRequest.onreadystatechange = myReadyStateChangeHandlerFunction;

If the only state you’re concerned about is the loaded state (state 4), try using the onload event instead:

myRequest.onload = myOnLoadHandlerFunction;

When the request is ready, use the send method to send it:

myRequest.send();

If your request is sending content, like a string or DOM object, pass it in as the argument to the send method.

XMLHttpRequest Responses

After you send your request, you can abort it using the abort method:

myRequest.abort();

If you provided an onreadystatechange handler, you can query your request to find its current state using the readyState property:

var myRequestState = myRequest.readyState;

A readyState value of 4 means that content has loaded. This is similar to providing an onload handler, which is called when a request’s readyState equals 4.

When a request is finished loading, you can query its HTTP status using the status and statusText properties:

        var myRequestStatus = myRequest.status;
var myRequestStatusText = myRequest.statusText;

Also, you can fetch the request’s HTTP response headers using the getResponseHeader method:

var aResponseHeader = myRequest.getResponseHeader("Content-Type");

To obtain a list of all of the response headers for a request, use getAllResponseHeaders:

var allResponseHeaders = myRequest.getAllResponseHeaders();

To obtain the request’s response XML as a DOM object, use the responseXML property:

var myResponseXML = myRequest.responseXML;

This object responds to standard DOM methods, like getElementsByTagName. If the response is not in a valid XML format, use the responseText property to access the raw text response:

var myResponseText = myRequest.responseText;

Security Considerations

Within Safari, the XMLHttpRequest object can only make requests to http and https URIs in the same domain as the webpage.

As an exception, however, beginning with Safari 4.0, a website can allow content served by other websites to request data from specific http and https URLs on their servers.

Using XMLHttpRequest for Cross-Site Requests

For the most part, the XMLHttpRequest object works the same way when used in a cross-site fashion. There are a few exceptions, however.

cookies—Because the JavaScript code is not in the same domain, it is not possible to set or read cookies for that domain.
authentication tokens—As with cookies, it is not possible to add or read authentication information for the remote domain.

Note

Although authentication information cannot be provided by the script, authenticated HTTP requests are allowed; the user is asked to enter login credential information upon initial connection just as though the user had connected to the site manually.
Referer header—Because it can contain confidential path information, the Referer header is not sent to the remote site. You can, however, check the Origin header to determine the domain name of the referring page.
other headers—Most HTTP headers are explicitly scrubbed both when sending and receiving. The only headers that are sent are:
- Accept—a comma-separated list of Internet Media Type values (as defined in RFC 1590) that are acceptable as a response for the request. These may be tagged with quality values to indicate a preference for one type over another.
  
  For example, Accept: text/html, text/plain;q=.5 indicates that the caller prefers HTML data with an implied quality of 1, but will also accept plain text data with an explicit quality of 0.5
  
  The second field may be replaced with an asterisk (*) wildcard character (Accept: text/*, for example). The first field may also be a wildcard if and only if the second field contains a wildcard (Accept: */*).
- Accept-Language—a comma-separated list of natural languages preferred by the user, optionally tagged with quality values for each language. The language tag values are defined by RFC 1766.
  
  For example, Accept-Language: de, en-gb;q=.5, es indicates the user prefers German or Spanish with implied quality of 1, but will tolerate British English with an explicit quality of 0.5.
- Content-Language—the natural language of the content of the request (en-US, for example), as defined by RFC 1766.
- Content-Type—the Internet Media Type for the data in the request (Content-Type: text/html, for example), as defined in RFC 1590.
- Origin—sent by the browser to indicate the domain from which the request was sent. This field contains the non-path portion of the URL (http://example.com, for example).
  
  Note
  
  The Origin header is only sent when requesting the specified URI. If the cross-origin request returns a redirect to a different URI, when fetching the subsequent location or locations, the Origin header is set to null and the Referer header field is set to the previous location in the redirect chain.
The only headers your script can expect to receive from the server (after the browser filters them) are:
- Host—provides the host name and port number of the server sending a response.
- Cache-Control—provides caching policy information.
- Content-Language—a comma-separated list of natural language of the content (en-US, for example), as defined by RFC 1766.
- Content-Type—the Internet Media Type for the data in the response (Content-Type: text/html, for example), as defined in RFC 1590.
- Expires—the date and time at which any cache of this data should be discarded. The date format is specified by RFC 1123.
- Last-Modified—the most recent date and time when the document’s contents were modified. The date format is specified by RFC 1123.
- Pragma—used for optional implementation-specific directives that may apply to intermediate web caches, the browser, and so on.
All other headers may be scrubbed.

Access Control Request Headers

Before performing the actual request, the browser first sends an OPTIONS query to the server to ask if it is allowed to send the actual request. The following headers are sent by the browser as part of this query and may be used by scripts on the remote web server when deciding whether or not to allow the request:

Origin: Contains the non-path portion of the resource making the request (for example, http://example.com).
Access-Control-Request-Method: Contains the method that the actual request will use (GET or POST, for example).
Access-Control-Request-Headers: Indicates which HTTP headers will be sent in the actual request.

Access Control Response Headers

Before performing the actual request, the browser first sends an OPTIONS query to the server to ask if it is allowed to send the actual request. The following headers may be sent by the remote web server (or scripts running on that server) in response to this request to control cross-site access policies:

Access-Control-Allow-Origin: Indicates that a particular origin can access the resource. The value may be either a specific origin (http://example.com, for example) or an asterisk (*) wildcard, which allows any domain to access the resource.
Access-Control-Max-Age: Indicates how long a browser should continue to cache the site’s acceptance of requests from other domains. If your site only allows requests from other domains after some specific handshake by a user, for example, you might set this to a short value.
Access-Control-Allow-Credentials: Indicates that the request may be made with credentials. The only allowable value is true. To disallow credentials, omit this header.
Access-Control-Allow-Methods: Provides a request method that the script may use for future requests (GET or POST, for example). The valid methods are defined in RFC 2616. This field may be specified more than once to allow multiple methods.
Access-Control-Allow-Headers: Provides a header field name that the client has permission to use in the actual request.