Skip to content
This repository
Newer
Older
100644 200 lines (148 sloc) 7.128 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
14 npm link .
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
4ff34937 »
2010-05-19 Updates to README.md
19 Request is designed to be the simplest way possible to make http calls. It support HTTPS and follows redirects by default.
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) {
25 sys.puts(body) // Print the google web page.
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
41 fs.readStream('file.json').pipe(request.put('http://mysite.com/obj.json'))
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
12a4cb88 »
2010-05-07 Matching node documentation style.
96 #### request(options, callback)
758f598d »
2010-05-07 Initial commit. Request package.
97
47314d7c »
2011-08-12 Greatly expanded documentation.
98 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.
99
fa72fcb9 »
2011-01-22 Updated documentation.
100 * `uri` || `url` - fully qualified uri or a parsed url object from url.parse()
101 * `method` - http method, defaults to GET
102 * `headers` - http headers, defaults to {}
af666072 » Stanley
2011-01-30 Made specs pass
103 * `body` - entity body for POST and PUT requests. Must be buffer or string.
fc2a7ef3 »
2011-01-30 Clearer wording for json option.
104 * `json` - sets `body` but to JSON representation of value and adds `Content-type: application/json` header.
af666072 » Stanley
2011-01-30 Made specs pass
105 * `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.
106 * `followRedirect` - follow HTTP 3xx responses as redirects. defaults to true.
107 * `maxRedirects` - the maximum number of redirects to follow, defaults to 10.
108 * `onResponse` - If true the callback will be fired on the "response" event instead of "end". If a function it will be called on "response" and not effect the regular semantics of the main callback on "end".
109 * `encoding` - Encoding to be used on response.setEncoding when buffering the response data.
897a7ef0 »
2011-02-11 Fixes for streams, docs, and convenience methods.
110 * `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.
111 * `pool.maxSockets` - Integer containing the maximum amount of sockets in the pool.
cc76b109 » mbrevoort
2011-07-01 corrected spelling error in README
112 * `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.
113 * `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.
12a4cb88 »
2010-05-07 Matching node documentation style.
114
115 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 buffer.
116
47314d7c »
2011-08-12 Greatly expanded documentation.
117 There are also shorthand methods for different HTTP METHODs.
118
119 ```javascript
120 request.get(url)
121 request.put(url)
122 request.post(url)
123 request.head(url)
124 request.del(url)
125 ```
126
af666072 » Stanley
2011-01-30 Made specs pass
127 Examples:
4ff34937 »
2010-05-19 Updates to README.md
128
47314d7c »
2011-08-12 Greatly expanded documentation.
129 ```javscript
af666072 » Stanley
2011-01-30 Made specs pass
130 var request = require('request');
131 var rand = Math.floor(Math.random()*100000000).toString();
ab4c96be »
2011-01-30 Moved spec tests to normal node script tests. Style changes to code a…
132 request(
133 { method: 'PUT'
134 , uri: 'http://mikeal.couchone.com/testjs/' + rand
135 , multipart:
136 [ { 'content-type': 'application/json'
137 , body: JSON.stringify({foo: 'bar', _attachments: {'message.txt': {follows: true, length: 18, 'content_type': 'text/plain' }}})
138 }
139 , { body: 'I am an attachment' }
140 ]
af666072 » Stanley
2011-01-30 Made specs pass
141 }
ab4c96be »
2011-01-30 Moved spec tests to normal node script tests. Style changes to code a…
142 , function (error, response, body) {
143 if(response.statusCode == 201){
144 console.log('document saved as: http://mikeal.couchone.com/testjs/'+ rand);
145 } else {
146 console.log('error: '+ response.statusCode);
147 console.log(body);
148 }
149 }
150 )
47314d7c »
2011-08-12 Greatly expanded documentation.
151 ```
af666072 » Stanley
2011-01-30 Made specs pass
152
897a7ef0 »
2011-02-11 Fixes for streams, docs, and convenience methods.
153 **Notice for 2.0**
154
155 You should no longer recycle mutations in the options object. Because node 0.4.0 has an internal pooling mechanism the preferred way of sharing a connection is using agents which request simplifies with it's new pool API. Therefor options.client and some other mutations have been deprecated.
156
157 requestBodyStream and responseBodyStream are also deprecated in favor of a more standard pipe interface documented below.
158
159 ### stream.pipe(request(options)) and request(options).pipe(stream)
160
161 Previous versions of request had no return value and only accepted callbacks and streams for pumping in the options object.
162
163 Node has solidified it's Stream interface and request 2.0 is now compliant with that interface.
164
165 The return value of request() is now a Request object, which is a valid stream.
166
167 As a writable stream it accepts the body of an HTTP request. As a readable stream it emits the data events for the response.
168
169 <pre>
170 var r = request(
171 { url: "http://mysite.com/image.png"
172 , method: 'PUT'
173 , headers: {'content-type': 'image/png'}
174 }
175 )
176 fs.createReadStream('image.png').pipe(r)
177 r.pipe(fs.createWriteStream('pushlog.txt'))
178 </pre>
179
180 # Convenience methods
181
f535fe10 »
2011-02-11 Doc fixes.
182 ### request.defaults(options)
897a7ef0 »
2011-02-11 Fixes for streams, docs, and convenience methods.
183
184 This method returns a wrapper around the normal request API that defaults to whatever options you pass in to it.
185
f535fe10 »
2011-02-11 Doc fixes.
186 ### request.put
897a7ef0 »
2011-02-11 Fixes for streams, docs, and convenience methods.
187
7c2899a0 »
2011-02-11 Doc fixes.
188 Same as request() but defaults to `method: "PUT"`.
897a7ef0 »
2011-02-11 Fixes for streams, docs, and convenience methods.
189
f535fe10 »
2011-02-11 Doc fixes.
190 ### request.post
897a7ef0 »
2011-02-11 Fixes for streams, docs, and convenience methods.
191
7c2899a0 »
2011-02-11 Doc fixes.
192 Same as request() but defaults to `method: "POST"`.
897a7ef0 »
2011-02-11 Fixes for streams, docs, and convenience methods.
193
f535fe10 »
2011-02-11 Doc fixes.
194 ### request.head
897a7ef0 »
2011-02-11 Fixes for streams, docs, and convenience methods.
195
7c2899a0 »
2011-02-11 Doc fixes.
196 Same as request() but defaults to `method: "HEAD"`.
897a7ef0 »
2011-02-11 Fixes for streams, docs, and convenience methods.
197
f535fe10 »
2011-02-11 Doc fixes.
198 ### request.get
897a7ef0 »
2011-02-11 Fixes for streams, docs, and convenience methods.
199
200 Alias to normal request method for uniformity.
Something went wrong with that request. Please try again.