npm's top HTTP client, request, packaged for Meteor
Motivation
Meteor's http
package is great, but it doesn't support retrieving binary data (useful, for example, when downlading an image). There are no plans to add this feature since the http
package should behave the same on the client as on the server.
Example
1var result = request.getSync("https://meteor.com/meteor-logo.png", { 2 encoding: null 3}); 4 5var buffer = result.body;
This Buffer can be stored in the database or written to a file.
Setup
- Install
meteor add froatsnook:request
- Don't forget to import if using meteor 1.3 or later
1import { request } from "meteor/froatsnook:request";
API
1var res0 = request.sync(uri, options); // sync version of calling request directly 2var res1 = request.putSync(uri, options); // sync version of calling request.put 3var res2 = request.patchSync(uri, options); // sync version of calling request.patch 4var res3 = request.postSync(uri, options); // sync version of calling request.post 5var res4 = request.headSync(uri, options); // sync version of calling request.head 6var res5 = request.delSync(uri, options); // sync version of calling request.del 7var res6 = request.getSync(uri, options); // sync version of calling request.get
Response object
Callbacks passed to request
are called with 3 parameters. The error
, the response
, and the body
. The response
and body
are returned as an object: { response, body }
. And error
is thrown (see below).
1// request.js 2request("http://www.google.com", function(error, response, body) { 3 if (!error && response.statusCode == 200) { 4 console.log(body) // Show the HTML for the Google homepage. 5 } 6}) 7 8// meteor-request 9try { 10 var res = request.sync("http://google.com"); 11 if (res.response.statusCode == 200) { 12 console.log(res.body); 13 } 14} catch (error) { 15 // See below for info on errors 16}
Errors
Normal errors generate non-2XX status codes.
1var res = request.getSync(urlThatDoesNotExist); 2console.assert(res.response.statusCode === 404);
Other errors (mostly from http.ClientRequest
) are thrown. This happens when request
gives an error in its first callback parameter.
1try { 2 var res = request.getSync(urlThatHangs, { 3 timeout: 1000 4 }); 5} catch (err) { 6 console.assert(err.code === "ETIMEDOUT"); 7}
Params
The uri
and options
are both optional, but either uri
or options.uri
(or alias options.url
) should be set as a fully qualified uri or a parsed URL object from url.parse
. The options
are passed on to request
. See here for supported options.
request.defaults
request.defaults
returns a wrapper around the normal request API that defaults to whatever options you pass to it. As of meteor-request
2.53.1, the returned wrapper includes getSync
and friends.
1var requestWithToken = request.defaults({ 2 headers: { "X-TOKEN": "d0d0309d-69cb-4435-bd43-8f3ac9266039" } 3}); 4 5// Both of these requests send the X-TOKEN header. 6var res1 = requestWithToken.getSync(url1); 7var res2 = requestWithToken.getSync(url2);
Example with Buffer POST body and response
1var buffer = new Buffer([0, 1]); 2var res = request.postSync("http://example.com/echoPostBody", { 3 body: buffer, 4 encoding: null 5}); 6 7console.assert(res.body instanceof Buffer); 8console.assert(res.body.length === 2); 9console.assert(res.body[0] === 0); 10console.assert(res.body[1] === 1);
Why forked from czbaker:request?
I added tests, removed the native dependency on fibers
(by using Meteor.wrapAsync
), updated to the latest request
, and added new features like request.defaults
support.
Versioning
This project doesn't use semver since it tracks request's version numbers. Sorry for the inconvenience.
License
MIT