1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
<!-- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
The `request` module lets you make simple yet powerful network requests.
<api name="Request">
@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();
<api name="Request">
@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();
</api>
<api name="url">
@property {string}
</api>
<api name="headers">
@property {object}
</api>
<api name="content">
@property {string,object}
</api>
<api name="contentType">
@property {string}
</api>
<api name="response">
@property {Response}
</api>
<api name="get">
@method
Make a `GET` request.
@returns {Request}
</api>
<api name="post">
@method
Make a `POST` request.
@returns {Request}
</api>
<api name="put">
@method
Make a `PUT` request.
@returns {Request}
</api>
<api name="complete">
@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.
</api>
</api>
<api name="Response">
@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.
<api name="text">
@property {string}
The content of the response as plain text.
</api>
<api name="json">
@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`.
</api>
<api name="status">
@property {string}
The HTTP response status code (e.g. *200*).
</api>
<api name="statusText">
@property {string}
The HTTP response status line (e.g. *OK*).
</api>
<api name="headers">
@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]);
}
</api>
</api>
|
