Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 194 lines (142 sloc) 6.326 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
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) {
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
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
7b2f788 @mikeal More doc cleanup.
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.
4c84001 @isaacs Document strictSSL option
isaacs authored
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.
115
12a4cb8 @mikeal Matching node documentation style.
mikeal authored
116
117 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.
118
7b2f788 @mikeal More doc cleanup.
mikeal authored
119 ## Convenience methods
120
121 There are also shorthand methods for different HTTP METHODs and some other conveniences.
122
123 ### request.defaults(options)
124
125 This method returns a wrapper around the normal request API that defaults to whatever options you pass in to it.
126
127 ### request.put
128
129 Same as request() but defaults to `method: "PUT"`.
47314d7 @mikeal Greatly expanded documentation.
mikeal authored
130
131 ```javascript
132 request.put(url)
7b2f788 @mikeal More doc cleanup.
mikeal authored
133 ```
134
135 ### request.post
136
137 Same as request() but defaults to `method: "POST"`.
138
139 ```javascript
47314d7 @mikeal Greatly expanded documentation.
mikeal authored
140 request.post(url)
7b2f788 @mikeal More doc cleanup.
mikeal authored
141 ```
142
143 ### request.head
144
145 Same as request() but defaults to `method: "HEAD"`.
146
147 ```javascript
47314d7 @mikeal Greatly expanded documentation.
mikeal authored
148 request.head(url)
7b2f788 @mikeal More doc cleanup.
mikeal authored
149 ```
150
151 ### request.del
152
153 Same as request() but defaults to `method: "DELETE"`.
154
155 ```javascript
47314d7 @mikeal Greatly expanded documentation.
mikeal authored
156 request.del(url)
157 ```
158
7b2f788 @mikeal More doc cleanup.
mikeal authored
159 ### request.get
160
161 Alias to normal request method for uniformity.
162
163 ```javascript
164 request.get(url)
165 ```
166
167
168 ## Examples:
4ff3493 @mikeal Updates to README.md
mikeal authored
169
e477369 @mikeal Doc refinements.
mikeal authored
170 ```javascript
171 var request = require('request')
172 , rand = Math.floor(Math.random()*100000000).toString()
173 ;
ab4c96b @mikeal Moved spec tests to normal node script tests. Style changes to code a…
mikeal authored
174 request(
175 { method: 'PUT'
176 , uri: 'http://mikeal.couchone.com/testjs/' + rand
177 , multipart:
178 [ { 'content-type': 'application/json'
179 , body: JSON.stringify({foo: 'bar', _attachments: {'message.txt': {follows: true, length: 18, 'content_type': 'text/plain' }}})
180 }
181 , { body: 'I am an attachment' }
182 ]
af66607 @Stanley Made specs pass
Stanley authored
183 }
ab4c96b @mikeal Moved spec tests to normal node script tests. Style changes to code a…
mikeal authored
184 , function (error, response, body) {
185 if(response.statusCode == 201){
e477369 @mikeal Doc refinements.
mikeal authored
186 console.log('document saved as: http://mikeal.couchone.com/testjs/'+ rand)
ab4c96b @mikeal Moved spec tests to normal node script tests. Style changes to code a…
mikeal authored
187 } else {
e477369 @mikeal Doc refinements.
mikeal authored
188 console.log('error: '+ response.statusCode)
189 console.log(body)
ab4c96b @mikeal Moved spec tests to normal node script tests. Style changes to code a…
mikeal authored
190 }
191 }
192 )
47314d7 @mikeal Greatly expanded documentation.
mikeal authored
193 ```
Something went wrong with that request. Please try again.