XMLHttpRequest
Summary
XMLHttpRequest allows JavaScript to make HTTP requests, and is the most basic part of AJAX. It allows a website to dynamically request more content, without reloading the entire page.
Overview
The XMLHttpRequest property is available on the window object.
var xhr = new XMLHttpRequest();
With the XMLHttpRequest object, clients can make HTTP requests to a URL without reloading the entire page. Despite the term “XML” in the name, this object can be used to retrieve any type of data.
Properties
- readyState
- Returns the current state of the XMLHttpRequest.
- response
- Returns the response entity body, which is the fragment of the entity body of the response received so far (if LOADING) or the complete entity body of the response (if DONE).
- responseText
- Returns the text response entity body, a string representing the response entity body, which is the fragment of the entity body of the response received so far (if LOADING) or the complete entity body of the response (if DONE).
- responseType
- Returns or sets the format the response will be returned in.
- responseXML
- Returns the response to the request as a DOM Document object, or null if the request was unsuccessful, has not yet been sent, or cannot be parsed as XML or HTML.
- status
- Returns the HTTP result code (status) of the response to the request.
- statusText
- Returns the HTTP status text.
- timeout
- Returns or sets the number of milliseconds a request can take before automatically being terminated.
- upload
- Returns the associated XMLHttpRequestUpload object. It can be used to gather transmission information when data is transferred to a server.
- withCredentials
- Returns or sets whether cross-site Access-Control requests should be made using credentials such as cookies or authorization headers.
Methods
- abort
- Stops an asynchronous XMLHttpRequest in progress.
- getAllResponseHeaders
- Returns all the response headers as a string, or null if no response has been received.
- getResponseHeader
- Returns the string containing the text of the specified header, or null if the response has not been received or the header does not exist.
- open
- Initializes an XMLHttpRequest.
- overrideMimeType
- Overrides the MIME type returned by the server.
- send
- Initiates the request defined by the XMLHttpRequest.
- setRequestHeader
- Sets the value of an XMLHttpRequest header.
Events
- abort
- When the request has been aborted. For instance, by invoking the abort() method.
- error
- When the request has failed.
- load
- When the request has successfully completed.
- loadend
- When the request has completed (either in success or failure).
- loadstart
- When the request starts.
- progress
- While sending and loading data.
- readystatechange
- Fires whenever the readyState of the request changes. Mostly used to determine whether the body of the response is available for handling.
- timeout
- When the author specified timeout has passed before the request could complete.
Examples
The following script demonstrates how to create and use the XMLHttpRequest object. For best client-side performance, the request is asynchronous and uses an onreadystatechange event handler to process the data returned by the call.
function handler() {
if (xhr.readyState === 4 /* complete */) {
if (xhr.status === 200) {
console.log(xhr.responseText);
}
}
}
var xhr = new XMLHttpRequest();
xhr.open("GET", "http://localhost/test.xml", true);
xhr.onreadystatechange = handler;
xhr.send();
This script demonstrates how to access resources that sits on a different domain. Example: siteA.com gets resource from siteB.com
// Create the XHR object.
function createCORSRequest(method, url) {
var xhr = new XMLHttpRequest();
if ("withCredentials" in xhr) {
// XHR for Chrome/Firefox/Opera/Safari.
xhr.open(method, url, true);
} else if (typeof XDomainRequest != "undefined") {
// XDomainRequest for IE 9 and earlier.
xhr = new XDomainRequest();
xhr.open(method, url);
} else {
// CORS not supported.
xhr = null;
}
return xhr;
}
// Helper method to parse the title tag from the response.
function getTitle(text) {
return text.match('<title>(.*)?</title>')[1];
}
// Make the actual CORS request.
function makeCorsRequest() {
// All HTML5 Rocks properties support CORS.
var url = 'http://updates.html5rocks.com';
var xhr = createCORSRequest('GET', url);
if (!xhr) {
alert('CORS not supported');
return;
}
// Response handlers.
xhr.onload = function() {
var text = xhr.responseText;
var title = getTitle(text);
alert('Response from CORS request to ' + url + ': ' + title);
};
xhr.onerror = function() {
alert('Woops, there was an error making the request.');
};
xhr.send();
}
Usage
The XMLHttpRequest object can be used to make either same-origin or cross-origin requests.
Same-origin requests are subject to the browser’s same-origin policy: http://en.wikipedia.org/wiki/Same_origin_policy This basically says that an XMLHttpRequest instance can make a request to a resource that lives on the same origin as the calling page.
Requests that go across origins (for example, a request from originA.com to originB.com) can also be made. But in order for them to work, the destination server must support Cross-Origin Resource Sharing (CORS, http://www.w3.org/TR/cors/). These are a set of headers included in the response that indicate how a resource can be accessed across domains.
Related specifications
- W3C XMLHttpRequest Specification
- W3C Working Draft
- Cross-Origin Resource Sharing
- W3C Candidate Recommendation 29 January 2013
See also
Related articles
XHR
XMLHttpRequest
Attributions
Microsoft Developer Network: Windows Internet Explorer API reference Article
Portions of this content come from HTML5Rocks! article