# HttpRequest Objects

This class is similar to the standard XmlHttpRequest class in Web browsers. It provides access to network resources via the HTTP protocol, using asynchronous requests.

## System requirements

The HttpRequest object depends upon the Windows MSXML system component. This is normally installed as part of the basic Windows installation, but as with any component on Windows, it's always possible that it's missing due to some past configuration change or setup error. If you get an error ("Required system component MSXML is not installed") when trying to create an HttpRequest object, you should be able to correct it by installing the latest MSXML from the Microsoft support site.

## Basic usage

Other than the slightly different name, HttpRequest works mostly like XmlHttpRequest in a browser. The main difference is how it handles completion notifications. HttpRequest uses the modern Javascript "Promise" mechanism, whereas the XmlHttpRequest in browsers uses an older ad hoc event handler scheme.

There are four steps to sending a basic HTTP request:

- Create an HttpRequest object with `new`
- Set up the HTTP verb and URL via the open() method
- Initiate the actual network transaction via the send() method
- Handle the response in a "then" function

If you've used XmlHttpRequest in a browser, you're already familiar with this process. The first three steps are exactly the same, right down to the method names and parameters (apart from the the different class name). The process diverges - very slightly - in the final step, where we handle the response. In a browser, you have to set up a callback function before you do the send() operation, typically by setting the "onreadystatechange" property. The callback has to monitor the "readyState" property of the request object and wait until it changes to the special state "4", meaning "done". Our version is a little simpler and nicer, since it's based on the Promise mechanism, which was added to Javascript specifically so that there'd be a clean and consistent way to handle asynchronous tasks like this.

With HttpRequest, you don't have to set up a state-change callback ahead of time. Instead, the send() method returns a Promise object, and you use that to handle the completion event. The Promise object is a standard ES6 feature, so you can find lots of information about it on the Web, but the basics are pretty simple. Promise has two main methods that you use to set up completion handlers: then(), which invokes a function when the operation completes successfully, and catch(), which invokes a function if the operation fails.

The actual handling of the completion event is up to you, and that part is just like in a browser. The main difference with the Promise approach is that the syntax is simpler.

Here's an example of a simple HTTP GET operation to fetch a page from a Web site.

// create the request object let request = new HttpRequest(); // Set up the HTTP verb and URL. Important: always use true for the // "async" parameter. If you make the request synchronous, the main // user interface window will freeze while Javascript waits for the // request to finish. Note that this only *prepares* the request; // this doesn't trigger any network activity yet. request.open("GET", "http://mjrnet.org/pinscape/", true); // Initiate the network request, and set up handlers for // completion and failure. request.send().then(function(reply) { // This function handles successful completion. "reply" is a // string containing the text of the page from the Web server. }).catch(function(error) { // This function handles errors. "error" is an Error object // describing the HTTP or network error. });

## Methods and properties

abort(): Call this method to cancel an asynchronous request in progress.

getAllResponseHeaders(): Returns a string containing the full set of HTTP headers in the response, separated by CR/LF ("\r\n") line ending sequences.

getResponseHeader(name): Returns a string with the value of the header matching the given name.

open(method, url, asynchronous, user, password): Sets up the verb (e.g., "GET", "POST") and URL ("http://...") for the request. Optionally sets the username and password (also as strings). The username and password will be used if necessary for HTTP authentication. (HTTP authentication is rarely used these days; it's not the kind where you fill in text boxes on the site's login page, but rather the kind where the browser itself prompts you for credentials.)

Important: always set asynchronous to true. If you don't, the user interface windows will freeze while Javascript waits for the network request to complete. You don't want that.

The open() call just prepares the request; it doesn't actually initiate the network operation. The network operation doesn't start until you call send().

setRequestHeader(name, value): Adds an HTTP header to the request, to be sent to the site with the request data. You can use this to set cookies, for example.

send(body): Send the request. body is an optional string containing the "body" data to send with the request, which is needed for verbs like "POST" and "PUT" that include request bodies. ("GET" doesn't use a request body, so you shouldn't use a body argument with "GET".)

Returns a standard Javascript Promise object that keeps track of the completion state of the request. Use the returned Promise object to set completion handlers. Use .then() to set a handler that will be invoked when the request completes successfully, and .catch() to set an error handler.

readyState: A read-only property indicating how much progress the request has made so far: 0 (uninitialized), 1 (loading), 2 (response headers received), 3 (partial body received), 4 (completed). In most cases, you won't need to monitor this, since you probably won't need to do anything with a request until it signals completion by calling the "then" handler via the Promise returned from send(). However, some applications use the ready state to update incremental status indicators in the UI; you could do that, for example, by checking this property periodically in a timer callback.

responseText: A read-only property with a string containing the full text of the response from the server. Valid only after the request has completed.

responseXML: An XML document object (as an OLE Automation object) containing the parsed XML version of the response. You can use this to interpret response formatted as XML.

status: A read-only property giving the numeric HTTP status code returned from the server. Only valid after the request has completed. 200 is the standard status code for normal, successful completion. Codes 400 and above indicate errors (e.g., 404 = not found, 500 = internal server error, etc). The full set of HTTP status codes can be found in numerous tutorials and references online.

statusText: A read-only property with a string giving the full text of the server status response (e.g., "200 OK"). Only valid after the request has completed.