Stable
Examples outlined in this document are no longer relevent and need to be updated
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:
Name | Type | |
---|---|---|
url | string,url |
This is the url to which the request will be made. Can either be a String or an instance of the SDK's URL. |
onComplete | function |
This function will be called when the request has received a response (or in terms of XHR, when |
headers | object |
An unordered collection of name/value pairs representing headers to send with the request. |
content | string,object |
The content to send to the server. If For |
contentType | string |
The type of content to send to the server. This explicitly sets the |
overrideMimeType | string |
Use this string to override the MIME type returned by the server in the response's Content-Type header. You can use this to treat the content as a different MIME type, or to force text to be interpreted using a specific character. For example, if you're retrieving text content which was encoded as ISO-8859-1 (Latin 1), it will be given a content type of "utf-8" and certain characters will not display correctly. To force the response to be interpreted as Latin-1, use 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(); |
anonymous | boolean | If true , the request will be sent without cookies or authentication headers. This option sets the mozAnon property in the underlying XMLHttpRequest object. Defaults to false . |
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.