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

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