Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 123 lines (89 sloc) 4.53 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
d67a041 @mikeal Moving basic example to the top.
mikeal authored
21 <pre>
22 var request = require('request');
23 request({uri:'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 </pre>
29
12a4cb8 @mikeal Matching node documentation style.
mikeal authored
30 #### request(options, callback)
758f598 @mikeal Initial commit. Request package.
mikeal authored
31
12a4cb8 @mikeal Matching node documentation style.
mikeal authored
32 The first argument is an options object. The only required option is uri, all others are optional.
33
fa72fcb @mikeal Updated documentation.
mikeal authored
34 * `uri` || `url` - fully qualified uri or a parsed url object from url.parse()
35 * `method` - http method, defaults to GET
36 * `headers` - http headers, defaults to {}
af66607 @Stanley Made specs pass
Stanley authored
37 * `body` - entity body for POST and PUT requests. Must be buffer or string.
fc2a7ef @mikeal Clearer wording for json option.
mikeal authored
38 * `json` - sets `body` but to JSON representation of value and adds `Content-type: application/json` header.
af66607 @Stanley Made specs pass
Stanley authored
39 * `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
40 * `followRedirect` - follow HTTP 3xx responses as redirects. defaults to true.
41 * `maxRedirects` - the maximum number of redirects to follow, defaults to 10.
42 * `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".
43 * `encoding` - Encoding to be used on response.setEncoding when buffering the response data.
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
44 * `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.
45 * `pool.maxSockets` - Integer containing the maximum amount of sockets in the pool.
12a4cb8 @mikeal Matching node documentation style.
mikeal authored
46
47 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.
48
af66607 @Stanley Made specs pass
Stanley authored
49 Examples:
4ff3493 @mikeal Updates to README.md
mikeal authored
50
af66607 @Stanley Made specs pass
Stanley authored
51 <pre>
52 var request = require('request');
53 var rand = Math.floor(Math.random()*100000000).toString();
ab4c96b @mikeal Moved spec tests to normal node script tests. Style changes to code and ...
mikeal authored
54 request(
55 { method: 'PUT'
56 , uri: 'http://mikeal.couchone.com/testjs/' + rand
57 , multipart:
58 [ { 'content-type': 'application/json'
59 , body: JSON.stringify({foo: 'bar', _attachments: {'message.txt': {follows: true, length: 18, 'content_type': 'text/plain' }}})
60 }
61 , { body: 'I am an attachment' }
62 ]
af66607 @Stanley Made specs pass
Stanley authored
63 }
ab4c96b @mikeal Moved spec tests to normal node script tests. Style changes to code and ...
mikeal authored
64 , function (error, response, body) {
65 if(response.statusCode == 201){
66 console.log('document saved as: http://mikeal.couchone.com/testjs/'+ rand);
67 } else {
68 console.log('error: '+ response.statusCode);
69 console.log(body);
70 }
71 }
72 )
af66607 @Stanley Made specs pass
Stanley authored
73 </pre>
74
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
75 **Notice for 2.0**
76
77 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.
78
79 requestBodyStream and responseBodyStream are also deprecated in favor of a more standard pipe interface documented below.
80
81 ### stream.pipe(request(options)) and request(options).pipe(stream)
82
83 Previous versions of request had no return value and only accepted callbacks and streams for pumping in the options object.
84
85 Node has solidified it's Stream interface and request 2.0 is now compliant with that interface.
86
87 The return value of request() is now a Request object, which is a valid stream.
88
89 As a writable stream it accepts the body of an HTTP request. As a readable stream it emits the data events for the response.
90
91 <pre>
92 var r = request(
93 { url: "http://mysite.com/image.png"
94 , method: 'PUT'
95 , headers: {'content-type': 'image/png'}
96 }
97 )
98 fs.createReadStream('image.png').pipe(r)
99 r.pipe(fs.createWriteStream('pushlog.txt'))
100 </pre>
101
102 # Convenience methods
103
f535fe1 @mikeal Doc fixes.
mikeal authored
104 ### request.defaults(options)
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
105
106 This method returns a wrapper around the normal request API that defaults to whatever options you pass in to it.
107
f535fe1 @mikeal Doc fixes.
mikeal authored
108 ### request.put
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
109
7c2899a @mikeal Doc fixes.
mikeal authored
110 Same as request() but defaults to `method: "PUT"`.
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
111
f535fe1 @mikeal Doc fixes.
mikeal authored
112 ### request.post
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
113
7c2899a @mikeal Doc fixes.
mikeal authored
114 Same as request() but defaults to `method: "POST"`.
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
115
f535fe1 @mikeal Doc fixes.
mikeal authored
116 ### request.head
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
117
7c2899a @mikeal Doc fixes.
mikeal authored
118 Same as request() but defaults to `method: "HEAD"`.
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
119
f535fe1 @mikeal Doc fixes.
mikeal authored
120 ### request.get
897a7ef @mikeal Fixes for streams, docs, and convenience methods.
mikeal authored
121
122 Alias to normal request method for uniformity.
Something went wrong with that request. Please try again.