Request-Promise

Deprecated!

As of Feb 11th 2020, request is fully deprecated. No new changes are expected to land. In fact, none have landed for some time. This package is also deprecated because it depends on request.

Fyi, here is the reasoning of request's deprecation and a list of alternative libraries.

---

The simplified HTTP request client 'request' with Promise support. Powered by Bluebird.

Request and Bluebird are pretty awesome, but I found myself using the same design pattern. Request-Promise adds a Bluebird-powered .then(...) method to Request call objects. By default, http response codes other than 2xx will cause the promise to be rejected. This can be overwritten by setting options.simple = false.

Also check out the new libraries that are very similar to request-promise v4: - request-promise-native v1 – Does not depend on Bluebird and uses native ES6 promises instead. - request-promise-any v1 – Allows you to register any Promise library supported by any-promise.

---

Migration from v3 to v4

1. request became a peer dependency. Thus make sure that request is installed into your project as a direct dependency. (npm install --save request)
2. Continuation Local Storage is no longer supported. However, you can get back the support by using request-promise-any.
3. When you migrated your transform function to v3 and had to add if (!(/^2/.test('' + response.statusCode))) { return resolveWithFullResponse ? response : body; } you may now set the option transform2xxOnly = true instead.

Migration from v2 to v3

1. The handling of the transform function got overhauled. This has two effects:

   • StatusCodeError.response is the transformed instead of the original response now. This error is thrown for non-2xx responses when options.simple is true (default). Please update your transform functions to also cover the transformation of non-2xx responses. To get the old behavior you may add if (!(/^2/.test('' + response.statusCode))) { return resolveWithFullResponse ? response : body; } to the first line of your transform functions that are used for requests with options.simple === true. However, you may prefer updating your transform functions to being able to transform 2xx as well as non-2xx responses because this decouples their implementation from the use of the simple option when doing requests.
   • If a transform operation throws an error, the request will be rejected with a TransformError. Its cause attribute contains the error thrown by the transform operation. Previously, the request was rejected directly with the error thrown by the transform operation. Wrapping it into a TransformError makes the error handling easier.

2. Bluebird got updated from v2 to v3. This won't make a difference for most use cases. However, if you use advanced Promise chains starting with the Promise returned by Request-Promise, please check Bluebird's new features and changes.

---

Installation

This module is installed via npm:

npm install --save request
npm install --save request-promise

request is defined as a peer-dependency and thus has to be installed separately.

Cheat Sheet

var rp = require('request-promise');

Since request-promise wraps around request everything that works with request also works with request-promise. Also check out the request docs for more examples.

Crawl a webpage

rp('http://www.google.com')
    .then(function (htmlString) {
        // Process html...
    })
    .catch(function (err) {
        // Crawling failed...
    });

Crawl a webpage better

var cheerio = require('cheerio'); // Basically jQuery for node.js

var options = {
    uri: 'http://www.google.com',
    transform: function (body) {
        return cheerio.load(body);
    }
};

rp(options)
    .then(function ($) {
        // Process html like you would with jQuery...
    })
    .catch(function (err) {
        // Crawling failed or Cheerio choked...
    });

GET something from a JSON REST API

var options = {
    uri: 'https://api.github.com/user/repos',
    qs: {
        access_token: 'xxxxx xxxxx' // -> uri + '?access_token=xxxxx%20xxxxx'
    },
    headers: {
        'User-Agent': 'Request-Promise'
    },
    json: true // Automatically parses the JSON string in the response
};

rp(options)
    .then(function (repos) {
        console.log('User has %d repos', repos.length);
    })
    .catch(function (err) {
        // API call failed...
    });

POST data to a JSON REST API

Set option.body to your data and json: true to encode the body as JSON. See below for HTML forms.

var options = {
    method: 'POST',
    uri: 'http://api.posttestserver.com/post',
    body: {
        some: 'payload'
    },
    json: true // Automatically stringifies the body to JSON
};

rp(options)
    .then(function (parsedBody) {
        // POST succeeded...
    })
    .catch(function (err) {
        // POST failed...
    });

POST like HTML forms do

Pass your data to options.form to encode the body the same way as HTML forms do:

var options = {
    method: 'POST',
    uri: 'http://posttestserver.com/post.php',
    form: {
        // Like <input type="text" name="name">
        name: 'Josh'
    },
    headers: {
        /* 'content-type': 'application/x-www-form-urlencoded' */ // Is set automatically
    }
};

rp(options)
    .then(function (body) {
        // POST succeeded...
    })
    .catch(function (err) {
        // POST failed...
    });

If you want to include a file upload then use options.formData:

var options = {
    method: 'POST',
    uri: 'http://posttestserver.com/post.php',
    formData: {
        // Like <input type="text" name="name">
        name: 'Jenn',
        // Like <input type="file" name="file">
        file: {
            value: fs.createReadStream('test/test.jpg'),
            options: {
                filename: 'test.jpg',
                contentType: 'image/jpg'
            }
        }
    },
    headers: {
        /* 'content-type': 'multipart/form-data' */ // Is set automatically
    }
};

rp(options)
    .then(function (body) {
        // POST succeeded...
    })
    .catch(function (err) {
        // POST failed...
    });

Include a cookie

var tough = require('tough-cookie');

// Easy creation of the cookie - see tough-cookie docs for details
let cookie = new tough.Cookie({
    key: "some_key",
    value: "some_value",
    domain: 'api.mydomain.com',
    httpOnly: true,
    maxAge: 31536000
});

// Put cookie in an jar which can be used across multiple requests
var cookiejar = rp.jar();
cookiejar.setCookie(cookie, 'https://api.mydomain.com');
// ...all requests to https://api.mydomain.com will include the cookie

var options = {
    uri: 'https://api.mydomain.com/...',
    jar: cookiejar // Tells rp to include cookies in jar that match uri
};

rp(options)
    .then(function (body) {
        // Request succeeded...
    })
    .catch(function (err) {
        // Request failed...
    });

Get the full response instead of just the body

var options = {
    method: 'DELETE',
    uri: 'http://my-server/path/to/resource/1234',
    resolveWithFullResponse: true    //  <---  <---  <---  <---
};

rp(options)
    .then(function (response) {
        console.log("DELETE succeeded with status %d", response.statusCode);
    })
    .catch(function (err) {
        // Delete failed...
    });

Get a rejection only if the request failed for technical reasons

var options = {
    uri: 'http://www.google.com/this-page-does-not-exist.html',
    simple: false    //  <---  <---  <---  <---
};

rp(options)
    .then(function (body) {
        // Request succeeded but might as well be a 404
        // Usually combined with resolveWithFullResponse = true to check response.statusCode
    })
    .catch(function (err) {
        // Request failed due to technical reasons...
    });

---

For more options checkout the Request docs.

---

API in Detail

Consider Request-Promise being:

• A Request object
  • With an identical API: require('request-promise') == require('request') so to say
  • However, STREAMING THE RESPONSE (e.g. .pipe(...)) is DISCOURAGED because Request-Promise would grow the memory footprint for large requests unnecessarily high. Use the original Request library for that. You can use both libraries in the same project.
• Plus some methods on a request call object:
  • rp(...).then(...) or e.g. rp.post(...).then(...) which turn rp(...) and rp.post(...) into promises
  • rp(...).catch(...) or e.g. rp.del(...).catch(...) which is the same method as provided by Bluebird promises
    • Errors that the request library would pass to the callback are wrapped by request-promise and then passed to the catch handler. See code example below.
  • rp(...).finally(...) or e.g. rp.put(...).finally(...) which is the same method as provided by Bluebird promises
  • rp(...).cancel() or e.g. rp.get(...).cancel() which cancels the request
  • rp(...).promise() or e.g. rp.head(...).promise() which returns the underlying promise so you can access the full Bluebird API
• Plus some additional options:
  • simple = true which is a boolean to set whether status codes other than 2xx should also reject the promise
  • resolveWithFullResponse = false which is a boolean to set whether the promise should be resolved with the full response or just the response body
  • transform which takes a function to transform the response into a custom value with which the promise is resolved
  • transform2xxOnly = false which is a boolean to set whether the transform function is applied to all responses or only to those with a 2xx status code

The objects returned by request calls like rp(...) or e.g. rp.post(...) are regular Promises/A+ compliant promises and can be assimilated by any compatible promise library.

The methods .then(...), .catch(...), and .finally(...) - which you can call on the request call objects - return a full-fledged Bluebird promise. That means you have the full Bluebird API available for further chaining. E.g.: rp(...).then(...).spread(...) If, however, you need a method other than .then(...), .catch(...), or .finally(...) to be FIRST in the chain, use .promise(): rp(...).promise().bind(...).then(...)

.then(onFulfilled, onRejected)

// As a Request user you would write:
var request = require('request');

request('http://google.com', function (err, response, body) {
    if (err) {
        handleError({ error: err, response: response, ... });
    } else if (!(/^2/.test('' + response.statusCode))) { // Status Codes other than 2xx
        handleError({ error: body, response: response, ... });
    } else {
        process(body);
    }
});

// As a Request-Promise user you can now write the equivalent code:
var rp = require('request-promise');

rp('http://google.com')
    .then(process, handleError);

// The same is available for all http method shortcuts:
request.post('http://example.com/api', function (err, response, body) { ... });
rp.post('http://example.com/api').then(...);

.catch(onRejected)

rp('http://google.com')
    .catch(handleError);

// ... is syntactical sugar for:

rp('http://google.com')
    .then(null, handleError);


// However, this:
rp('http://google.com')
    .then(process)
    .catch(handleError);

// ... is safer than:
rp('http://google.com')
    .then(process, handleError);

For more info on .then(process).catch(handleError) versus .then(process, handleError), see Bluebird docs on promise anti-patterns.

.finally(onFinished)

rp('http://google.com')
    .finally(function () {
        // This is called after the request finishes either successful or not successful.
    });

.cancel()

This method cancels the request using [Bluebird's cancellation