Skip to content
This repository
Newer
Older
100644 212 lines (160 sloc) 7.111 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
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) {
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
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
7b2f7882 »
2011-08-12 More doc cleanup.
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.
4c840010 » isaacs
2011-09-30 Document strictSSL option
114 * `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.
8323eed4 » alessioalex
2011-11-13 Closed issue 82 : handling cookies - added tests too
115 * `jar` - Set to `request.jar()` if you don't want cookies to be remembered for future use
4c840010 » isaacs
2011-09-30 Document strictSSL option
116
12a4cb88 »
2010-05-07 Matching node documentation style.
117
118 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.
119
7b2f7882 »
2011-08-12 More doc cleanup.
120 ## Convenience methods
121
122 There are also shorthand methods for different HTTP METHODs and some other conveniences.
123
124 ### request.defaults(options)
125
126 This method returns a wrapper around the normal request API that defaults to whatever options you pass in to it.
127
128 ### request.put
129
130 Same as request() but defaults to `method: "PUT"`.
47314d7c »
2011-08-12 Greatly expanded documentation.
131
132 ```javascript
133 request.put(url)
7b2f7882 »
2011-08-12 More doc cleanup.
134 ```
135
136 ### request.post
137
138 Same as request() but defaults to `method: "POST"`.
139
140 ```javascript
47314d7c »
2011-08-12 Greatly expanded documentation.
141 request.post(url)
7b2f7882 »
2011-08-12 More doc cleanup.
142 ```
143
144 ### request.head
145
146 Same as request() but defaults to `method: "HEAD"`.
147
148 ```javascript
47314d7c »
2011-08-12 Greatly expanded documentation.
149 request.head(url)
7b2f7882 »
2011-08-12 More doc cleanup.
150 ```
151
152 ### request.del
153
154 Same as request() but defaults to `method: "DELETE"`.
155
156 ```javascript
47314d7c »
2011-08-12 Greatly expanded documentation.
157 request.del(url)
158 ```
159
7b2f7882 »
2011-08-12 More doc cleanup.
160 ### request.get
161
162 Alias to normal request method for uniformity.
163
164 ```javascript
165 request.get(url)
166 ```
167
168
169 ## Examples:
4ff34937 »
2010-05-19 Updates to README.md
170
e477369b »
2011-08-12 Doc refinements.
171 ```javascript
172 var request = require('request')
173 , rand = Math.floor(Math.random()*100000000).toString()
174 ;
ab4c96be »
2011-01-30 Moved spec tests to normal node script tests. Style changes to code a…
175 request(
176 { method: 'PUT'
177 , uri: 'http://mikeal.couchone.com/testjs/' + rand
178 , multipart:
179 [ { 'content-type': 'application/json'
180 , body: JSON.stringify({foo: 'bar', _attachments: {'message.txt': {follows: true, length: 18, 'content_type': 'text/plain' }}})
181 }
182 , { body: 'I am an attachment' }
183 ]
af666072 » Stanley
2011-01-30 Made specs pass
184 }
ab4c96be »
2011-01-30 Moved spec tests to normal node script tests. Style changes to code a…
185 , function (error, response, body) {
186 if(response.statusCode == 201){
e477369b »
2011-08-12 Doc refinements.
187 console.log('document saved as: http://mikeal.couchone.com/testjs/'+ rand)
ab4c96be »
2011-01-30 Moved spec tests to normal node script tests. Style changes to code a…
188 } else {
e477369b »
2011-08-12 Doc refinements.
189 console.log('error: '+ response.statusCode)
190 console.log(body)
ab4c96be »
2011-01-30 Moved spec tests to normal node script tests. Style changes to code a…
191 }
192 }
193 )
47314d7c »
2011-08-12 Greatly expanded documentation.
194 ```
8323eed4 » alessioalex
2011-11-13 Closed issue 82 : handling cookies - added tests too
195 The jar holds the state of the cookies being set, each request sends the proper cookies for that domain. The boiler is easy to get rid of with `defaults` or per each request if you set `options.jar`.
196
197 ```javascript
198 var j = request.jar()
199 var request = request.defaults({jar:j})
200 request('http://www.google.com', function () {
201 request('http://images.google.com')
202 })
203 ```
204 OR
205 ```javascript
206 var j = request.jar()
207 // you can also set a cookie like so:
208 j.add('sid=LsoJ7tV9wfwz2VkE9lxC4EqU.%2BXxV0F9i1hfCMb4uNKZTpAUJLTwlf57FewvHne%2BAGVI; path=/; expires=Sun, 23 Nov 2011 16:50:21 GMT; httpOnly')
209 request(url: 'http://www.google.com', jar: j, function () {
210 request('http://images.google.com')
211 })
212 ```
Something went wrong with that request. Please try again.