The `request` module lets you make simple yet powerful network requests.
@class
The `Request` object is used to make `GET`, `POST` or `PUT` 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,
or a `PUT` request by calling its `put()` method.
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. Once `GET`, `POST` or `PUT`
are called, attempting to call either 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 public tweet.
var Request = require("request").Request;
var latestTweetRequest = Request({
url: "http://api.twitter.com/1/statuses/public_timeline.json",
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: "http://api.twitter.com/1/account/rate_limit_status.json",
onComplete: function (response) {
if (response.json.remaining_hits) {
latestTweetRequest.get();
} else {
console.log("You have been rate limited!");
}
}
}).get();
@constructor
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`.
@param options {object}
@prop url {string}
This is the url to which the request will be made.
@prop [onComplete] {function}
This function will be called when the request has received a response (or in
terms of XHR, when `readyState == 4`). The function is passed a `Response`
object.
@prop [headers] {object}
An unordered collection of name/value pairs representing headers to send
with the request.
@prop [content] {string,object}
The content to send to the server. If `content` is a string, it should be
URL-encoded (use `encodeURIComponent`). If `content` is an object, it
should be a collection of name/value pairs. Nested objects & arrays should
encode safely.
For `GET` requests, the query string (`content`) will be appended to the
URL. For `POST` and `PUT` requests, the query string will be sent as the body
of the request.
@prop [contentType] {string}
The type of content to send to the server. This explicitly sets the
`Content-Type` header. The default value is `application/x-www-form-urlencoded`.
@prop [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 `overrideMimeType`:
var Request = require("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();
@property {string}
@property {object}
@property {string,object}
@property {string}
@property {Response}
@method
Make a `GET` request.
@returns {Request}
@method
Make a `POST` request.
@returns {Request}
@method
Make a `PUT` request.
@returns {Request}
@event
The `Request` object emits this event when the request has completed and a
response has been received.
@argument {Response}
Listener functions are passed the response to the request as a `Response` object.
@class
The Response object contains the response to a network request issued using a
`Request` object. It is returned by the `get()`, `post()` or `put()` method of a
`Request` object.
All members of a `Response` object are read-only.
@property {string}
The content of the response as plain text.
@property {object}
The content of the response as a JavaScript object. The value will be `null`
if the document cannot be processed by `JSON.parse`.
@property {string}
The HTTP response status code (e.g. *200*).
@property {string}
The HTTP response status line (e.g. *OK*).
@property {object}
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]);
}