Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 288 lines (224 sloc) 9.146 kb
758f598 @mikeal Initial commit. Request package.
mikeal authored
1 # Request -- Simplified HTTP request method
2
12a4cb8 @mikeal Matching node documentation style.
mikeal authored
3 ## Install
758f598 @mikeal Initial commit. Request package.
mikeal authored
4
5 <pre>
6 npm install request
7 </pre>
8
02f6b38 @Stanley Added specs for body option
Stanley authored
9 Or from source:
10
11 <pre>
12 git clone git://github.com/mikeal/request.git
13 cd request
fe4d221 @mikeal Fix for newer npm
mikeal authored
14 npm link
02f6b38 @Stanley Added specs for body option
Stanley authored
15 </pre>
16
12a4cb8 @mikeal Matching node documentation style.
mikeal authored
17 ## Super simple to use
758f598 @mikeal Initial commit. Request package.
mikeal authored
18
f4b87cf @TehShrike I'm not OCD seriously
TehShrike authored
19 Request is designed to be the simplest way possible to make http calls. It supports HTTPS and follows redirects by default.
4ff3493 @mikeal Updates to README.md
mikeal authored
20
47314d7 @mikeal Greatly expanded documentation.
mikeal authored
21 ```javascript
22 var request = require('request');
23 request('http://www.google.com', function (error, response, body) {
24 if (!error && response.statusCode == 200) {
d8c53fc @mikeal Removing legacy call to sys.puts
mikeal authored
25 console.log(body) // Print the google web page.
47314d7 @mikeal Greatly expanded documentation.
mikeal authored
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
e77a169 @mikeal fixing streaming example. fixes #164
mikeal authored
41 fs.createReadStream('file.json').pipe(request.put('http://mysite.com/obj.json'))
47314d7 @mikeal Greatly expanded documentation.
mikeal authored
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.
d67a041 @mikeal Moving basic example to the top.
mikeal authored
95
668a291 @mikeal Adding some documentation for OAuth signing support.
mikeal authored
96 ## OAuth Signing
97
98 ```javascript
04faa3b @mikeal Minor improvements in example
mikeal authored
99 // Twitter OAuth
668a291 @mikeal Adding some documentation for OAuth signing support.
mikeal authored
100 var qs = require('querystring')
101 , oauth =
04faa3b @mikeal Minor improvements in example
mikeal authored
102 { callback: 'http://mysite.com/callback/'
668a291 @mikeal Adding some documentation for OAuth signing support.
mikeal authored
103 , consumer_key: CONSUMER_KEY
04faa3b @mikeal Minor improvements in example
mikeal authored
104 , consumer_secret: CONSUMER_SECRET
668a291 @mikeal Adding some documentation for OAuth signing support.
mikeal authored
105 }
04faa3b @mikeal Minor improvements in example
mikeal authored
106 , url = 'https://api.twitter.com/oauth/request_token'
668a291 @mikeal Adding some documentation for OAuth signing support.
mikeal authored
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 }
0fddc17 @mikeal Another small fix to the url in the docs.
mikeal authored
128 , url = 'https://api.twitter.com/1/users/show.json?'
668a291 @mikeal Adding some documentation for OAuth signing support.
mikeal authored
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
7b2f788 @mikeal More doc cleanup.
mikeal authored
144 ### request(options, callback)
758f598 @mikeal Initial commit. Request package.
mikeal authored
145
47314d7 @mikeal Greatly expanded documentation.
mikeal authored
146 The first argument can be either a url or an options object. The only required option is uri, all others are optional.
12a4cb8 @mikeal Matching node documentation style.
mikeal authored
147
fa72fcb @mikeal Updated documentation.
mikeal authored
148 * `uri` || `url` - fully qualified uri or a parsed url object from url.parse()
0f24051 @csainty Renamed query to qs. It was actually my first choice, but there appeared...
csainty authored
149 * `qs` - object containing querystring values to be appended to the uri
fa72fcb @mikeal Updated documentation.
mikeal authored
150 * `method` - http method, defaults to GET
151 * `headers` - http headers, defaults to {}
af66607 @Stanley Made specs pass
Stanley authored
152 * `body` - entity body for POST and PUT requests. Must be buffer or string.
f51c32b @petejkim added "form" option to readme.
petejkim authored
153 * `form` - sets `body` but to querystring representation of value and adds `Content-type: application/x-www-form-urlencoded; charset=utf-8` header.
bc6cd6c @jphaas documenting additional behavior of json option
jphaas authored
154 * `json` - sets `body` but to JSON representation of value and adds `Content-type: application/json` header. Additionally, parses the response body as json.
af66607 @Stanley Made specs pass
Stanley authored
155 * `multipart` - (experimental) array of objects which contains their own headers and `body` attribute. Sends `multipart/related` request. See example below.
fa72fcb @mikeal Updated documentation.
mikeal authored
156 * `followRedirect` - follow HTTP 3xx responses as redirects. defaults to true.
d2d9b54 @jroes add line to docs describing followAllRedirects option
jroes authored
157 * `followAllRedirects` - follow non-GET HTTP 3xx responses as redirects. defaults to false.
fa72fcb @mikeal Updated documentation.
mikeal authored
158 * `maxRedirects` - the maximum number of redirects to follow, defaults to 10.
06cdfaa return body as buffer when encoding is null
John Hewson authored
159 * `encoding` - Encoding to be used on `setEncoding` of response data. If set to `null`, the body is returned as a Buffer.
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
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.
cc76b10 @mbrevoort corrected spelling error in README
mbrevoort authored
162 * `timeout` - Integer containing the number of milliseconds to wait for a request to respond before aborting the request
c63e6e9 @mikeal Adding proxy to docs, don't know why this wasn't already in.
mikeal authored
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.
337649a @mikeal Add oauth to options.
mikeal authored
164 * `oauth` - Options for OAuth HMAC-SHA1 signing, see documentation above.
4c84001 @isaacs Document strictSSL option
isaacs authored
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.
856a65c Update jar documentation in the options also
alessioalex authored
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)
4c84001 @isaacs Document strictSSL option
isaacs authored
167
12a4cb8 @mikeal Matching node documentation style.
mikeal authored
168
06cdfaa return body as buffer when encoding is null
John Hewson authored
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.
12a4cb8 @mikeal Matching node documentation style.
mikeal authored
170
7b2f788 @mikeal More doc cleanup.
mikeal authored
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"`.
47314d7 @mikeal Greatly expanded documentation.
mikeal authored
182
183 ```javascript
184 request.put(url)
7b2f788 @mikeal More doc cleanup.
mikeal authored
185 ```
186
187 ### request.post
188
189 Same as request() but defaults to `method: "POST"`.
190
191 ```javascript
47314d7 @mikeal Greatly expanded documentation.
mikeal authored
192 request.post(url)
7b2f788 @mikeal More doc cleanup.
mikeal authored
193 ```
194
195 ### request.head
196
197 Same as request() but defaults to `method: "HEAD"`.
198
199 ```javascript
47314d7 @mikeal Greatly expanded documentation.
mikeal authored
200 request.head(url)
7b2f788 @mikeal More doc cleanup.
mikeal authored
201 ```
202
203 ### request.del
204
205 Same as request() but defaults to `method: "DELETE"`.
206
207 ```javascript
47314d7 @mikeal Greatly expanded documentation.
mikeal authored
208 request.del(url)
209 ```
210
7b2f788 @mikeal More doc cleanup.
mikeal authored
211 ### request.get
212
213 Alias to normal request method for uniformity.
214
215 ```javascript
216 request.get(url)
217 ```
6181b7a Documented request.cookie() and request.jar()
alessioalex authored
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 ```
7b2f788 @mikeal More doc cleanup.
mikeal authored
232
233
234 ## Examples:
4ff3493 @mikeal Updates to README.md
mikeal authored
235
e477369 @mikeal Doc refinements.
mikeal authored
236 ```javascript
237 var request = require('request')
238 , rand = Math.floor(Math.random()*100000000).toString()
239 ;
ab4c96b @mikeal Moved spec tests to normal node script tests. Style changes to code and ...
mikeal authored
240 request(
241 { method: 'PUT'
4e4d428 @jhs Update to Iris Couch URL
jhs authored
242 , uri: 'http://mikeal.iriscouch.com/testjs/' + rand
ab4c96b @mikeal Moved spec tests to normal node script tests. Style changes to code and ...
mikeal authored
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 ]
af66607 @Stanley Made specs pass
Stanley authored
249 }
ab4c96b @mikeal Moved spec tests to normal node script tests. Style changes to code and ...
mikeal authored
250 , function (error, response, body) {
251 if(response.statusCode == 201){
4e4d428 @jhs Update to Iris Couch URL
jhs authored
252 console.log('document saved as: http://mikeal.iriscouch.com/testjs/'+ rand)
ab4c96b @mikeal Moved spec tests to normal node script tests. Style changes to code and ...
mikeal authored
253 } else {
e477369 @mikeal Doc refinements.
mikeal authored
254 console.log('error: '+ response.statusCode)
255 console.log(body)
ab4c96b @mikeal Moved spec tests to normal node script tests. Style changes to code and ...
mikeal authored
256 }
257 }
258 )
47314d7 @mikeal Greatly expanded documentation.
mikeal authored
259 ```
b519044 request.defaults({jar: false}) disables cookies && also updated README
alessioalex authored
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:
8323eed Closed issue 82 : handling cookies - added tests too
alessioalex authored
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
3db7f7d Updated README
alessioalex authored
279
8323eed Closed issue 82 : handling cookies - added tests too
alessioalex authored
280 ```javascript
281 var j = request.jar()
3db7f7d Updated README
alessioalex authored
282 var cookie = request.cookie('your_cookie_here')
6c22041 changed README
alessioalex authored
283 j.add(cookie)
fc44260 Tiny cookie example error on README
alessioalex authored
284 request({url: 'http://www.google.com', jar: j}, function () {
8323eed Closed issue 82 : handling cookies - added tests too
alessioalex authored
285 request('http://images.google.com')
286 })
287 ```
Something went wrong with that request. Please try again.