request

Make simple network requests. For more advanced usage, check out the net/xhr module, based on the browser's XMLHttpRequest object.

Globals

Constructors

Request(options)

This constructor creates a request object that can be used to make network requests. The constructor takes a single parameter options which is used to set several properties on the resulting Request.

Parameters

options : object
Optional options:

var Request = require("sdk/request").Request;
var quijote = Request({
  url: "http://www.latin1files.org/quijote.txt",
  overrideMimeType: "text/plain; charset=latin1",
  onComplete: function (response) {
    console.log(response.text);
  }
});
quijote.get();

Request

The Request object is used to make GET, HEAD, POST, PUT, or DELETE network requests. It is constructed with a URL to which the request is sent. Optionally the user may specify a collection of headers and content to send alongside the request and a callback which will be executed once the request completes.

Once a Request object has been created a GET request can be executed by calling its get() method, a POST request by calling its post() method, and so on.

When the server completes the request, the Request object emits a "complete" event. Registered event listeners are passed a Response object.

Each Request object is designed to be used once. Attempts to reuse them will throw an error.

Since the request is not being made by any particular website, requests made here are not subject to the same-domain restriction that requests made in web pages are subject to.

With the exception of response, all of a Request object's properties correspond with the options in the constructor. Each can be set by simply performing an assignment. However, keep in mind that the same validation rules that apply to options in the constructor will apply during assignment. Thus, each can throw if given an invalid value.

The example below shows how to use Request to get the most recent tweet from the @mozhacks account:

var Request = require("sdk/request").Request;
var latestTweetRequest = Request({
  url: "https://api.twitter.com/1.1/statuses/user_timeline.json?screen_name=mozhacks&count=1",
  onComplete: function (response) {
    var tweet = response.json[0];
    console.log("User: " + tweet.user.screen_name);
    console.log("Tweet: " + tweet.text);
  }
});
// Be a good consumer and check for rate limiting before doing more.
Request({
  url: "https://api.twitter.com/1.1/application/rate_limit_status.json",
  onComplete: function (response) {
    if (response.json.remaining_hits) {
      latestTweetRequest.get();
    } else {
      console.log("You have been rate limited!");
    }
  }
}).get();

Methods

get()

Make a GET request.

head()

Make a HEAD request.

post()

Make a POST request.

put()

Make a PUT request.

delete()

Make a DELETE request.

Properties

url

headers

content

contentType

response

Events

complete

The Request object emits this event when the request has completed and a response has been received.

Arguments

Response : Listener functions are passed the response to the request as a Response object.

Response

The Response object contains the response to a network request issued using a Request object. It is returned by the get(), head(), post(), put() or delete() method of a Request object.

All members of a Response object are read-only.

Properties

url

The URL of the response content.

text

The content of the response as plain text.

json

The content of the response as a JavaScript object. The value will be null if the document cannot be processed by JSON.parse.

status

The HTTP response status code (e.g. 200).

statusText

The HTTP response status line (e.g. OK).

headers

The HTTP response headers represented as key/value pairs.

To print all the headers you can do something like this:

for (var headerName in response.headers) {
  console.log(headerName + " : " + response.headers[headerName]);
}

anonymous

Boolean indicating if the request was anonymous.