Skip to content
This repository
Newer
Older
100644 287 lines (224 sloc) 9.146 kb
758f598d »
2010-05-07 Initial commit. Request package.
1 # Request -- Simplified HTTP request method
2
12a4cb88 »
2010-05-07 Matching node documentation style.
3 ## Install
758f598d »
2010-05-07 Initial commit. Request package.
4
5 <pre>
6 npm install request
7 </pre>
8
02f6b38c » Stanley
2011-01-30 Added specs for body option
9 Or from source:
10
11 <pre>
12 git clone git://github.com/mikeal/request.git
13 cd request
fe4d2210 »
2011-08-12 Fix for newer npm
14 npm link
02f6b38c » Stanley
2011-01-30 Added specs for body option
15 </pre>
16
12a4cb88 »
2010-05-07 Matching node documentation style.
17 ## Super simple to use
758f598d »
2010-05-07 Initial commit. Request package.
18
f4b87cf4 » TehShrike
2012-06-12 I'm not OCD seriously
19 Request is designed to be the simplest way possible to make http calls. It supports HTTPS and follows redirects by default.
4ff34937 »
2010-05-19 Updates to README.md
20
47314d7c »
2011-08-12 Greatly expanded documentation.
21 ```javascript
22 var request = require('request');
23 request('http://www.google.com', function (error, response, body) {
24 if (!error && response.statusCode == 200) {
d8c53fce »
2011-09-17 Removing legacy call to sys.puts
25 console.log(body) // Print the google web page.
47314d7c »
2011-08-12 Greatly expanded documentation.
26 }
27 })
28 ```
29
30 ## Streaming
31
32 You can stream any response to a file stream.
33
34 ```javascript
35 request('http://google.com/doodle.png').pipe(fs.createWriteStream('doodle.png'))
36 ```
37
38 You can also stream a file to a PUT or POST request. This method will also check the file extension against a mapping of file extensions to content-types, in this case `application/json`, and use the proper content-type in the PUT request if one is not already provided in the headers.
39
40 ```javascript
e77a1695 »
2012-02-08 fixing streaming example. fixes #164
41 fs.createReadStream('file.json').pipe(request.put('http://mysite.com/obj.json'))
47314d7c »
2011-08-12 Greatly expanded documentation.
42 ```
43
44 Request can also pipe to itself. When doing so the content-type and content-length will be preserved in the PUT headers.
45
46 ```javascript
47 request.get('http://google.com/img.png').pipe(request.put('http://mysite.com/img.png'))
48 ```
49
50 Now let's get fancy.
51
52 ```javascript
53 http.createServer(function (req, resp) {
54 if (req.url === '/doodle.png') {
55 if (req.method === 'PUT') {
56 req.pipe(request.put('http://mysite.com/doodle.png'))
57 } else if (req.method === 'GET' || req.method === 'HEAD') {
58 request.get('http://mysite.com/doodle.png').pipe(resp)
59 }
60 }
61 })
62 ```
63
64 You can also pipe() from a http.ServerRequest instance and to a http.ServerResponse instance. The HTTP method and headers will be sent as well as the entity-body data. Which means that, if you don't really care about security, you can do:
65
66 ```javascript
67 http.createServer(function (req, resp) {
68 if (req.url === '/doodle.png') {
69 var x = request('http://mysite.com/doodle.png')
70 req.pipe(x)
71 x.pipe(resp)
72 }
73 })
74 ```
75
76 And since pipe() returns the destination stream in node 0.5.x you can do one line proxying :)
77
78 ```javascript
79 req.pipe(request('http://mysite.com/doodle.png')).pipe(resp)
80 ```
81
82 Also, none of this new functionality conflicts with requests previous features, it just expands them.
83
84 ```javascript
85 var r = request.defaults({'proxy':'http://localproxy.com'})
86
87 http.createServer(function (req, resp) {
88 if (req.url === '/doodle.png') {
89 r.get('http://google.com/doodle.png').pipe(resp)
90 }
91 })
92 ```
93
94 You can still use intermediate proxies, the requests will still follow HTTP forwards, etc.
d67a0417 »
2011-02-11 Moving basic example to the top.
95
668a2910 »
2011-11-16 Adding some documentation for OAuth signing support.
96 ## OAuth Signing
97
98 ```javascript
04faa3bf »
2011-11-16 Minor improvements in example
99 // Twitter OAuth
668a2910 »
2011-11-16 Adding some documentation for OAuth signing support.
100 var qs = require('querystring')
101 , oauth =
04faa3bf »
2011-11-16 Minor improvements in example
102 { callback: 'http://mysite.com/callback/'
668a2910 »
2011-11-16 Adding some documentation for OAuth signing support.
103 , consumer_key: CONSUMER_KEY
04faa3bf »
2011-11-16 Minor improvements in example
104 , consumer_secret: CONSUMER_SECRET
668a2910 »
2011-11-16 Adding some documentation for OAuth signing support.
105 }
04faa3bf »
2011-11-16 Minor improvements in example
106 , url = 'https://api.twitter.com/oauth/request_token'
668a2910 »
2011-11-16 Adding some documentation for OAuth signing support.
107 ;
108 request.post({url:url, oauth:oauth}, function (e, r, body) {
109 // Assume by some stretch of magic you aquired the verifier
110 var access_token = qs.parse(body)
111 , oauth =
112 { consumer_key: CONSUMER_KEY
113 , consumer_secret: CONSUMER_SECRET
114 , token: access_token.oauth_token
115 , verifier: VERIFIER
116 , token_secret: access_token.oauth_token_secret
117 }
118 , url = 'https://api.twitter.com/oauth/access_token'
119 ;
120 request.post({url:url, oauth:oauth}, function (e, r, body) {
121 var perm_token = qs.parse(body)
122 , oauth =
123 { consumer_key: CONSUMER_KEY
124 , consumer_secret: CONSUMER_SECRET
125 , token: perm_token.oauth_token
126 , token_secret: perm_token.oauth_token_secret
127 }
0fddc179 »
2011-11-16 Another small fix to the url in the docs.
128 , url = 'https://api.twitter.com/1/users/show.json?'
668a2910 »
2011-11-16 Adding some documentation for OAuth signing support.
129 , params =
130 { screen_name: perm_token.screen_name
131 , user_id: perm_token.user_id
132 }
133 ;
134 url += qs.stringify(params)
135 request.get({url:url, oauth:oauth, json:true}, function (e, r, user) {
136 console.log(user)
137 })
138 })
139 })
140 ```
141
142
143
7b2f7882 »
2011-08-12 More doc cleanup.
144 ### request(options, callback)
758f598d »
2010-05-07 Initial commit. Request package.
145
47314d7c »
2011-08-12 Greatly expanded documentation.
146 The first argument can be either a url or an options object. The only required option is uri, all others are optional.
12a4cb88 »
2010-05-07 Matching node documentation style.
147
fa72fcb9 »
2011-01-22 Updated documentation.
148 * `uri` || `url` - fully qualified uri or a parsed url object from url.parse()
0f240517 » csainty
2012-02-19 Renamed query to qs. It was actually my first choice, but there appea…
149 * `qs` - object containing querystring values to be appended to the uri
fa72fcb9 »
2011-01-22 Updated documentation.
150 * `method` - http method, defaults to GET
151 * `headers` - http headers, defaults to {}
af666072 » Stanley
2011-01-30 Made specs pass
152 * `body` - entity body for POST and PUT requests. Must be buffer or string.
f51c32bd » petejkim
2011-12-30 added "form" option to readme.
153 * `form` - sets `body` but to querystring representation of value and adds `Content-type: application/x-www-form-urlencoded; charset=utf-8` header.
bc6cd6ca » jphaas
2012-03-22 documenting additional behavior of json option
154 * `json` - sets `body` but to JSON representation of value and adds `Content-type: application/json` header. Additionally, parses the response body as json.
af666072 » Stanley
2011-01-30 Made specs pass
155 * `multipart` - (experimental) array of objects which contains their own headers and `body` attribute. Sends `multipart/related` request. See example below.
fa72fcb9 »
2011-01-22 Updated documentation.
156 * `followRedirect` - follow HTTP 3xx responses as redirects. defaults to true.
d2d9b545 » jroes
2012-02-03 add line to docs describing followAllRedirects option
157 * `followAllRedirects` - follow non-GET HTTP 3xx responses as redirects. defaults to false.
fa72fcb9 »
2011-01-22 Updated documentation.
158 * `maxRedirects` - the maximum number of redirects to follow, defaults to 10.
06cdfaa3 » John Hewson
2011-12-11 return body as buffer when encoding is null
159 * `encoding` - Encoding to be used on `setEncoding` of response data. If set to `null`, the body is returned as a Buffer.
897a7ef0 »
2011-02-11 Fixes for streams, docs, and convenience methods.
160 * `pool` - A hash object containing the agents for these requests. If omitted this request will use the global pool which is set to node's default maxSockets.
161 * `pool.maxSockets` - Integer containing the maximum amount of sockets in the pool.
cc76b109 » mbrevoort
2011-07-01 corrected spelling error in README
162 * `timeout` - Integer containing the number of milliseconds to wait for a request to respond before aborting the request
c63e6e96 »
2011-08-12 Adding proxy to docs, don't know why this wasn't already in.
163 * `proxy` - An HTTP proxy to be used. Support proxy Auth with Basic Auth the same way it's supported with the `url` parameter by embedding the auth info in the uri.
337649a0 »
2011-11-16 Add oauth to options.
164 * `oauth` - Options for OAuth HMAC-SHA1 signing, see documentation above.
4c840010 » isaacs
2011-09-30 Document strictSSL option
165 * `strictSSL` - Set to `true` to require that SSL certificates be valid. Note: to use your own certificate authority, you need to specify an agent that was created with that ca as an option.
856a65cd » alessioalex
2011-11-13 Update jar documentation in the options also
166 * `jar` - Set to `false` if you don't want cookies to be remembered for future use or define your custom cookie jar (see examples section)
4c840010 » isaacs
2011-09-30 Document strictSSL option
167
12a4cb88 »
2010-05-07 Matching node documentation style.
168
06cdfaa3 » John Hewson
2011-12-11 return body as buffer when encoding is null
169 The callback argument gets 3 arguments. The first is an error when applicable (usually from the http.Client option not the http.ClientRequest object). The second in an http.ClientResponse object. The third is the response body String or Buffer.
12a4cb88 »
2010-05-07 Matching node documentation style.
170
7b2f7882 »
2011-08-12 More doc cleanup.
171 ## Convenience methods
172
173 There are also shorthand methods for different HTTP METHODs and some other conveniences.
174
175 ### request.defaults(options)
176
177 This method returns a wrapper around the normal request API that defaults to whatever options you pass in to it.
178
179 ### request.put
180
181 Same as request() but defaults to `method: "PUT"`.
47314d7c »
2011-08-12 Greatly expanded documentation.
182
183 ```javascript
184 request.put(url)
7b2f7882 »
2011-08-12 More doc cleanup.
185 ```
186
187 ### request.post
188
189 Same as request() but defaults to `method: "POST"`.
190
191 ```javascript
47314d7c »
2011-08-12 Greatly expanded documentation.
192 request.post(url)
7b2f7882 »
2011-08-12 More doc cleanup.
193 ```
194
195 ### request.head
196
197 Same as request() but defaults to `method: "HEAD"`.
198
199 ```javascript
47314d7c »
2011-08-12 Greatly expanded documentation.
200 request.head(url)
7b2f7882 »
2011-08-12 More doc cleanup.
201 ```
202
203 ### request.del
204
205 Same as request() but defaults to `method: "DELETE"`.
206
207 ```javascript
47314d7c »
2011-08-12 Greatly expanded documentation.
208 request.del(url)
209 ```
210
7b2f7882 »
2011-08-12 More doc cleanup.
211 ### request.get
212
213 Alias to normal request method for uniformity.
214
215 ```javascript
216 request.get(url)
217 ```
6181b7a8 » alessioalex
2011-11-13 Documented request.cookie() and request.jar()
218 ### request.cookie
219
220 Function that creates a new cookie.
221
222 ```javascript
223 request.cookie('cookie_string_here')
224 ```
225 ### request.jar
226
227 Function that creates a new cookie jar.
228
229 ```javascript
230 request.jar()
231 ```
7b2f7882 »
2011-08-12 More doc cleanup.
232
233
234 ## Examples:
4ff34937 »
2010-05-19 Updates to README.md
235
e477369b »
2011-08-12 Doc refinements.
236 ```javascript
237 var request = require('request')
238 , rand = Math.floor(Math.random()*100000000).toString()
239 ;
ab4c96be »
2011-01-30 Moved spec tests to normal node script tests. Style changes to code a…
240 request(
241 { method: 'PUT'
4e4d4285 » jhs
2011-11-23 Update to Iris Couch URL
242 , uri: 'http://mikeal.iriscouch.com/testjs/' + rand
ab4c96be »
2011-01-30 Moved spec tests to normal node script tests. Style changes to code a…
243 , multipart:
244 [ { 'content-type': 'application/json'
245 , body: JSON.stringify({foo: 'bar', _attachments: {'message.txt': {follows: true, length: 18, 'content_type': 'text/plain' }}})
246 }
247 , { body: 'I am an attachment' }
248 ]
af666072 » Stanley
2011-01-30 Made specs pass
249 }
ab4c96be »
2011-01-30 Moved spec tests to normal node script tests. Style changes to code a…
250 , function (error, response, body) {
251 if(response.statusCode == 201){
4e4d4285 » jhs
2011-11-23 Update to Iris Couch URL
252 console.log('document saved as: http://mikeal.iriscouch.com/testjs/'+ rand)
ab4c96be »
2011-01-30 Moved spec tests to normal node script tests. Style changes to code a…
253 } else {
e477369b »
2011-08-12 Doc refinements.
254 console.log('error: '+ response.statusCode)
255 console.log(body)
ab4c96be »
2011-01-30 Moved spec tests to normal node script tests. Style changes to code a…
256 }
257 }
258 )
47314d7c »
2011-08-12 Greatly expanded documentation.
259 ```
b5190441 » alessioalex
2011-11-13 request.defaults({jar: false}) disables cookies && also updated README
260 Cookies are enabled by default (so they can be used in subsequent requests). To disable cookies set jar to false (either in defaults or in the options sent).
261
262 ```javascript
263 var request = request.defaults({jar: false})
264 request('http://www.google.com', function () {
265 request('http://images.google.com')
266 })
267 ```
268
269 If you to use a custom cookie jar (instead of letting request use its own global cookie jar) you do so by setting the jar default or by specifying it as an option:
8323eed4 » alessioalex
2011-11-13 Closed issue 82 : handling cookies - added tests too
270
271 ```javascript
272 var j = request.jar()
273 var request = request.defaults({jar:j})
274 request('http://www.google.com', function () {
275 request('http://images.google.com')
276 })
277 ```
278 OR
3db7f7d3 » alessioalex
2011-11-13 Updated README
279
8323eed4 » alessioalex
2011-11-13 Closed issue 82 : handling cookies - added tests too
280 ```javascript
281 var j = request.jar()
3db7f7d3 » alessioalex
2011-11-13 Updated README
282 var cookie = request.cookie('your_cookie_here')
6c22041a » alessioalex
2011-11-13 changed README
283 j.add(cookie)
fc44260d » alessioalex
2011-11-13 Tiny cookie example error on README
284 request({url: 'http://www.google.com', jar: j}, function () {
8323eed4 » alessioalex
2011-11-13 Closed issue 82 : handling cookies - added tests too
285 request('http://images.google.com')
286 })
287 ```
Something went wrong with that request. Please try again.