Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 201 lines (148 sloc) 7.128 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
14 npm link .
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
4ff3493 @mikeal Updates to README.md
mikeal authored
19 Request is designed to be the simplest way possible to make http calls. It support HTTPS and follows redirects by default.
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) {
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.
d67a041 @mikeal Moving basic example to the top.
mikeal authored
95
12a4cb8 @mikeal Matching node documentation style.
mikeal authored
96 #### request(options, callback)
758f598 @mikeal Initial commit. Request package.
mikeal authored
97
47314d7 @mikeal Greatly expanded documentation.
mikeal authored
98 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
99
fa72fcb @mikeal Updated documentation.
mikeal authored
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 {}
af66607 @Stanley Made specs pass
Stanley authored
103 * `body` - entity body for POST and PUT requests. Must be buffer or string.
fc2a7ef @mikeal Clearer wording for json option.
mikeal authored
104 * `json` - sets `body` but to JSON representation of value and adds `Content-type: application/json` header.
af66607 @Stanley Made specs pass
Stanley authored
105 * `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
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.
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
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.
cc76b10 @mbrevoort corrected spelling error in README
mbrevoort authored
112 * `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
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.
12a4cb8 @mikeal Matching node documentation style.
mikeal authored
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
47314d7 @mikeal Greatly expanded documentation.
mikeal authored
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
af66607 @Stanley Made specs pass
Stanley authored
127 Examples:
4ff3493 @mikeal Updates to README.md
mikeal authored
128
47314d7 @mikeal Greatly expanded documentation.
mikeal authored
129 ```javscript
af66607 @Stanley Made specs pass
Stanley authored
130 var request = require('request');
131 var rand = Math.floor(Math.random()*100000000).toString();
ab4c96b @mikeal Moved spec tests to normal node script tests. Style changes to code a…
mikeal authored
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 ]
af66607 @Stanley Made specs pass
Stanley authored
141 }
ab4c96b @mikeal Moved spec tests to normal node script tests. Style changes to code a…
mikeal authored
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 )
47314d7 @mikeal Greatly expanded documentation.
mikeal authored
151 ```
af66607 @Stanley Made specs pass
Stanley authored
152
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
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
f535fe1 @mikeal Doc fixes.
mikeal authored
182 ### request.defaults(options)
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
183
184 This method returns a wrapper around the normal request API that defaults to whatever options you pass in to it.
185
f535fe1 @mikeal Doc fixes.
mikeal authored
186 ### request.put
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
187
7c2899a @mikeal Doc fixes.
mikeal authored
188 Same as request() but defaults to `method: "PUT"`.
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
189
f535fe1 @mikeal Doc fixes.
mikeal authored
190 ### request.post
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
191
7c2899a @mikeal Doc fixes.
mikeal authored
192 Same as request() but defaults to `method: "POST"`.
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
193
f535fe1 @mikeal Doc fixes.
mikeal authored
194 ### request.head
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
195
7c2899a @mikeal Doc fixes.
mikeal authored
196 Same as request() but defaults to `method: "HEAD"`.
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
197
f535fe1 @mikeal Doc fixes.
mikeal authored
198 ### request.get
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
199
200 Alias to normal request method for uniformity.
Something went wrong with that request. Please try again.