A utility for retrieving data from a URL.

HttpRequest can be used to obtain data from http, ftp, and file protocols.

For example, suppose we're developing these API docs, and we wish to retrieve the HTML of the top-level page and print it out. The easiest way to do that would be:

HttpRequest.getString('http://api.dartlang.org').then((response) {
  print(response);
});

Important: With the default behavior of this class, your code making the request should be served from the same origin (domain name, port, and application layer protocol) as the URL you are trying to access with HttpRequest. However, there are ways to get around this restriction.

See also:

• Dart article on using HttpRequests
• JS XMLHttpRequest
• Using XMLHttpRequest

@DomName('XMLHttpRequest')
class HttpRequest extends EventTarget native "XMLHttpRequest" {

 /**
  * Creates a URL get request for the specified [url].
  *
  * The server response must be a `text/` mime type for this request to
  * succeed.
  *
  * This is similar to [request] but specialized for HTTP GET requests which
  * return text content.
  *
  * See also:
  *
  * * [request]
  */
 static Future<String> getString(String url,
     {bool withCredentials, void onProgress(ProgressEvent e)}) {
   return request(url, withCredentials: withCredentials,
       onProgress: onProgress).then((xhr) => xhr.responseText);
 }

 /**
  * Creates a URL request for the specified [url].
  *
  * By default this will do an HTTP GET request, this can be overridden with
  * [method].
  *
  * The Future is completed when the response is available.
  *
  * The [withCredentials] parameter specified that credentials such as a cookie
  * (already) set in the header or
  * [authorization headers](http://tools.ietf.org/html/rfc1945#section-10.2)
  * should be specified for the request. Details to keep in mind when using
  * credentials:
  *
  * * Using credentials is only useful for cross-origin requests.
  * * The `Access-Control-Allow-Origin` header of `url` cannot contain a wildcard (*).
  * * The `Access-Control-Allow-Credentials` header of `url` must be set to true.
  * * If `Access-Control-Expose-Headers` has not been set to true, only a subset of all the response headers will be returned when calling [getAllRequestHeaders].
  *
  * Note that requests for file:// URIs are only supported by Chrome extensions
  * with appropriate permissions in their manifest. Requests to file:// URIs
  * will also never fail- the Future will always complete successfully, even
  * when the file cannot be found.
  *
  * See also: [authorization headers](http://en.wikipedia.org/wiki/Basic_access_authentication).
  */
 static Future<HttpRequest> request(String url,
     {String method, bool withCredentials, String responseType,
     String mimeType, Map<String, String> requestHeaders, sendData,
     void onProgress(ProgressEvent e)}) {
   var completer = new Completer<HttpRequest>();

   var xhr = new HttpRequest();
   if (method == null) {
     method = 'GET';
   }
   xhr.open(method, url, async: true);

   if (withCredentials != null) {
     xhr.withCredentials = withCredentials;
   }

   if (responseType != null) {
     xhr.responseType = responseType;
   }

   if (mimeType != null) {
     xhr.overrideMimeType(mimeType);
   }

   if (requestHeaders != null) {
     requestHeaders.forEach((header, value) {
       xhr.setRequestHeader(header, value);
     });
   }

   if (onProgress != null) {
     xhr.onProgress.listen(onProgress);
   }

   xhr.onLoad.listen((e) {
     // Note: file:// URIs have status of 0.
     if ((xhr.status >= 200 && xhr.status < 300) ||
         xhr.status == 0 || xhr.status == 304) {
       completer.complete(xhr);
     } else {
       completer.completeError(e);
     }
   });

   xhr.onError.listen((e) {
     completer.completeError(e);
   });

   if (sendData != null) {
     xhr.send(sendData);
   } else {
     xhr.send();
   }

   return completer.future;
 }

 /**
  * Checks to see if the Progress event is supported on the current platform.
  */
 static bool get supportsProgressEvent {
   var xhr = new HttpRequest();
   return JS('bool', '("onprogress" in #)', xhr);
 }

 /**
  * Checks to see if the current platform supports making cross origin
  * requests.
  *
  * Note that even if cross origin requests are supported, they still may fail
  * if the destination server does not support CORS requests.
  */
 static bool get supportsCrossOrigin {
   var xhr = new HttpRequest();
   return JS('bool', '("withCredentials" in #)', xhr);
 }

 /**
  * Checks to see if the LoadEnd event is supported on the current platform.
  */
 static bool get supportsLoadEndEvent {
   var xhr = new HttpRequest();
   return JS('bool', '("onloadend" in #)', xhr);
 }

 /**
  * Checks to see if the overrideMimeType method is supported on the current
  * platform.
  */
 static bool get supportsOverrideMimeType {
   var xhr = new HttpRequest();
   return JS('bool', '("overrideMimeType" in #)', xhr);
 }


 @DomName('XMLHttpRequest.abortEvent')
 @DocsEditable
 static const EventStreamProvider<ProgressEvent> abortEvent = const EventStreamProvider<ProgressEvent>('abort');

 @DomName('XMLHttpRequest.errorEvent')
 @DocsEditable
 static const EventStreamProvider<ProgressEvent> errorEvent = const EventStreamProvider<ProgressEvent>('error');

 @DomName('XMLHttpRequest.loadEvent')
 @DocsEditable
 static const EventStreamProvider<ProgressEvent> loadEvent = const EventStreamProvider<ProgressEvent>('load');

 @DomName('XMLHttpRequest.loadendEvent')
 @DocsEditable
 static const EventStreamProvider<ProgressEvent> loadEndEvent = const EventStreamProvider<ProgressEvent>('loadend');

 @DomName('XMLHttpRequest.loadstartEvent')
 @DocsEditable
 static const EventStreamProvider<ProgressEvent> loadStartEvent = const EventStreamProvider<ProgressEvent>('loadstart');

 @DomName('XMLHttpRequest.progressEvent')
 @DocsEditable
 static const EventStreamProvider<ProgressEvent> progressEvent = const EventStreamProvider<ProgressEvent>('progress');

 @DomName('XMLHttpRequest.readystatechangeEvent')
 @DocsEditable
 static const EventStreamProvider<ProgressEvent> readyStateChangeEvent = const EventStreamProvider<ProgressEvent>('readystatechange');

 /**
  * General constructor for any type of request (GET, POST, etc).
  *
  * This call is used in conjunction with [open]:
  *
  *     var request = new HttpRequest();
  *     request.open('GET', 'http://dartlang.org')
  *     request.on.load.add((event) => print('Request complete'));
  *
  * is the (more verbose) equivalent of
  *
  *     var request = new HttpRequest.get('http://dartlang.org',
  *         (event) => print('Request complete'));
  */
 @DomName('XMLHttpRequest.XMLHttpRequest')
 @DocsEditable
 factory HttpRequest() {
   return HttpRequest._create_1();
 }
 static HttpRequest _create_1() => JS('HttpRequest', 'new XMLHttpRequest()');

 @DomName('XMLHttpRequest.DONE')
 @DocsEditable
 static const int DONE = 4;

 @DomName('XMLHttpRequest.HEADERS_RECEIVED')
 @DocsEditable
 static const int HEADERS_RECEIVED = 2;

 @DomName('XMLHttpRequest.LOADING')
 @DocsEditable
 static const int LOADING = 3;

 @DomName('XMLHttpRequest.OPENED')
 @DocsEditable
 static const int OPENED = 1;

 @DomName('XMLHttpRequest.UNSENT')
 @DocsEditable
 static const int UNSENT = 0;

 /**
  * Indicator of the current state of the request:
  *
  * <table>
  *   <tr>
  *     <td>Value</td>
  *     <td>State</td>
  *     <td>Meaning</td>
  *   </tr>
  *   <tr>
  *     <td>0</td>
  *     <td>unsent</td>
  *     <td><code>open()</code> has not yet been called</td>
  *   </tr>
  *   <tr>
  *     <td>1</td>
  *     <td>opened</td>
  *     <td><code>send()</code> has not yet been called</td>
  *   </tr>
  *   <tr>
  *     <td>2</td>
  *     <td>headers received</td>
  *     <td><code>sent()</code> has been called; response headers and <code>status</code> are available</td>
  *   </tr>
  *   <tr>
  *     <td>3</td> <td>loading</td> <td><code>responseText</code> holds some data</td>
  *   </tr>
  *   <tr>
  *     <td>4</td> <td>done</td> <td>request is complete</td>
  *   </tr>
  * </table>
  */
 @DomName('XMLHttpRequest.readyState')
 @DocsEditable
 final int readyState;

 /**
  * The data received as a reponse from the request.
  *
  * The data could be in the
  * form of a [String], [ArrayBuffer], [Document], [Blob], or json (also a
  * [String]). `null` indicates request failure.
  */
 @DomName('XMLHttpRequest.response')
 @DocsEditable
 @SupportedBrowser(SupportedBrowser.CHROME)
 @SupportedBrowser(SupportedBrowser.FIREFOX)
 @SupportedBrowser(SupportedBrowser.IE, '10')
 @SupportedBrowser(SupportedBrowser.SAFARI)
 @Creates('ByteBuffer|Blob|Document|=Object|=List|String|num')
 final Object response;

 /**
  * The response in string form or `null on failure.
  */
 @DomName('XMLHttpRequest.responseText')
 @DocsEditable
 final String responseText;

 /**
  * [String] telling the server the desired response format.
  *
  * Default is `String`.
  * Other options are one of 'arraybuffer', 'blob', 'document', 'json',
  * 'text'. Some newer browsers will throw NS_ERROR_DOM_INVALID_ACCESS_ERR if
  * `responseType` is set while performing a synchronous request.
  *
  * See also: [MDN responseType](https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest#responseType)
  */
 @DomName('XMLHttpRequest.responseType')
 @DocsEditable
 String responseType;

 @JSName('responseXML')
 /**
  * The request response, or null on failure.
  *
  * The response is processed as
  * `text/xml` stream, unless responseType = 'document' and the request is
  * synchronous.
  */
 @DomName('XMLHttpRequest.responseXML')
 @DocsEditable
 final Document responseXml;

 /**
  * The http result code from the request (200, 404, etc).
  * See also: [Http Status Codes](http://en.wikipedia.org/wiki/List_of_HTTP_status_codes)
  */
 @DomName('XMLHttpRequest.status')
 @DocsEditable
 final int status;

 /**
  * The request response string (such as \"200 OK\").
  * See also: [Http Status Codes](http://en.wikipedia.org/wiki/List_of_HTTP_status_codes)
  */
 @DomName('XMLHttpRequest.statusText')
 @DocsEditable
 final String statusText;

 /**
  * [EventTarget] that can hold listeners to track the progress of the request.
  * The events fired will be members of [HttpRequestUploadEvents].
  */
 @DomName('XMLHttpRequest.upload')
 @DocsEditable
 final HttpRequestUpload upload;

 /**
  * True if cross-site requests should use credentials such as cookies
  * or authorization headers; false otherwise.
  *
  * This value is ignored for same-site requests.
  */
 @DomName('XMLHttpRequest.withCredentials')
 @DocsEditable
 bool withCredentials;

 /**
  * Stop the current request.
  *
  * The request can only be stopped if readyState is `HEADERS_RECIEVED` or
  * `LOADING`. If this method is not in the process of being sent, the method
  * has no effect.
  */
 @DomName('XMLHttpRequest.abort')
 @DocsEditable
 void abort() native;

 @JSName('addEventListener')
 @DomName('XMLHttpRequest.addEventListener')
 @DocsEditable
 void $dom_addEventListener(String type, EventListener listener, [bool useCapture]) native;

 @DomName('XMLHttpRequest.dispatchEvent')
 @DocsEditable
 bool dispatchEvent(Event evt) native;

 /**
  * Retrieve all the response headers from a request.
  *
  * `null` if no headers have been received. For multipart requests,
  * `getAllResponseHeaders` will return the response headers for the current
  * part of the request.
  *
  * See also [HTTP response headers](http://en.wikipedia.org/wiki/List_of_HTTP_header_fields#Responses)
  * for a list of common response headers.
  */
 @DomName('XMLHttpRequest.getAllResponseHeaders')
 @DocsEditable
 String getAllResponseHeaders() native;

 /**
  * Return the response header named `header`, or `null` if not found.
  *
  * See also [HTTP response headers](http://en.wikipedia.org/wiki/List_of_HTTP_header_fields#Responses)
  * for a list of common response headers.
  */
 @DomName('XMLHttpRequest.getResponseHeader')
 @DocsEditable
 String getResponseHeader(String header) native;

 /**
  * Specify the desired `url`, and `method` to use in making the request.
  *
  * By default the request is done asyncronously, with no user or password
  * authentication information. If `async` is false, the request will be send
  * synchronously.
  *
  * Calling `open` again on a currently active request is equivalent to
  * calling `abort`.
  */
 @DomName('XMLHttpRequest.open')
 @DocsEditable
 void open(String method, String url, {bool async, String user, String password}) native;

 /**
  * Specify a particular MIME type (such as `text/xml`) desired for the
  * response.
  *
  * This value must be set before the request has been sent. See also the list
  * of [common MIME types](http://en.wikipedia.org/wiki/Internet_media_type#List_of_common_media_types)
  */
 @DomName('XMLHttpRequest.overrideMimeType')
 @DocsEditable
 @SupportedBrowser(SupportedBrowser.CHROME)
 @SupportedBrowser(SupportedBrowser.FIREFOX)
 @SupportedBrowser(SupportedBrowser.SAFARI)
 void overrideMimeType(String override) native;

 @JSName('removeEventListener')
 @DomName('XMLHttpRequest.removeEventListener')
 @DocsEditable
 void $dom_removeEventListener(String type, EventListener listener, [bool useCapture]) native;

 /**
  * Send the request with any given `data`.
  *
  * See also:
  *
  *   * [send](https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest#send%28%29)
  * from MDN.
  */
 @DomName('XMLHttpRequest.send')
 @DocsEditable
 void send([data]) native;

 @DomName('XMLHttpRequest.setRequestHeader')
 @DocsEditable
 void setRequestHeader(String header, String value) native;

 /**
  * Event listeners to be notified when request has been aborted,
  * generally due to calling `httpRequest.abort()`.
  */
 @DomName('XMLHttpRequest.onabort')
 @DocsEditable
 Stream<ProgressEvent> get onAbort => abortEvent.forTarget(this);

 /**
  * Event listeners to be notified when a request has failed, such as when a
  * cross-domain error occurred or the file wasn't found on the server.
  */
 @DomName('XMLHttpRequest.onerror')
 @DocsEditable
 Stream<ProgressEvent> get onError => errorEvent.forTarget(this);

 /**
  * Event listeners to be notified once the request has completed
  * *successfully*.
  */
 @DomName('XMLHttpRequest.onload')
 @DocsEditable
 Stream<ProgressEvent> get onLoad => loadEvent.forTarget(this);

 /**
  * Event listeners to be notified once the request has completed (on
  * either success or failure).
  */
 @DomName('XMLHttpRequest.onloadend')
 @DocsEditable
 @SupportedBrowser(SupportedBrowser.CHROME)
 @SupportedBrowser(SupportedBrowser.FIREFOX)
 @SupportedBrowser(SupportedBrowser.IE, '10')
 @SupportedBrowser(SupportedBrowser.SAFARI)
 Stream<ProgressEvent> get onLoadEnd => loadEndEvent.forTarget(this);

 /**
  * Event listeners to be notified when the request starts, once
  * `httpRequest.send()` has been called.
  */
 @DomName('XMLHttpRequest.onloadstart')
 @DocsEditable
 Stream<ProgressEvent> get onLoadStart => loadStartEvent.forTarget(this);

 /**
  * Event listeners to be notified when data for the request
  * is being sent or loaded.
  *
  * Progress events are fired every 50ms or for every byte transmitted,
  * whichever is less frequent.
  */
 @DomName('XMLHttpRequest.onprogress')
 @DocsEditable
 @SupportedBrowser(SupportedBrowser.CHROME)
 @SupportedBrowser(SupportedBrowser.FIREFOX)
 @SupportedBrowser(SupportedBrowser.IE, '10')
 @SupportedBrowser(SupportedBrowser.SAFARI)
 Stream<ProgressEvent> get onProgress => progressEvent.forTarget(this);

 /**
  * Event listeners to be notified every time the [HttpRequest]
  * object's `readyState` changes values.
  */
 @DomName('XMLHttpRequest.onreadystatechange')
 @DocsEditable
 Stream<ProgressEvent> get onReadyStateChange => readyStateChangeEvent.forTarget(this);

}