In any application framework, one basic need is to be able to make REST calls over HTTP/HTTPS as they are widely used and a very handful in case of API interactions, web scraping, etc. We can use the NodeJS core modules or http https to perform these calls but that is a bit cumbersome process and Request makes it dead simple to perform these HTTP(S) calls. In this tutorial we will learn about how to get started with the request module to perform HTTP(S) calls.

Installing Request Module

Request is a third party module, hence in order to install request module, simply run the following command in your project directory:

npm install request

If you’re unaware, npm is a package manager which provides a central repository for custom open sourced modules for Node.js and JavaScript. npm makes it dead simple to manage modules, their versions and distribution. We used the command npm install to install the required module in our project.

Getting started with Request Module

Request a module is built in a way that it makes it very simple to make HTTP(S) calls as well as it also follows redirects by default, though that is configurable. In this section, we will use shorthand notations of the request module to get our job done.

Simple GET call over HTTP

Let’s try to print the HTML of the modulus.io website’s homepage:

[cc lang=”javascript”]

//Load the request module
var request = require(‘request’);
//Lets try to make a HTTP GET request to modulus.io’s website.
request(‘http://www.modulus.io’, function (error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body); // Show the HTML for the Modulus homepage.
}
});

[/cc]

In the above example, we did not specify the GET method anywhere as by default request module makes a GET request if not specified explicitly.

The function callback contains three parameters: 1. Error: This is the first parameter of the callback function. It will be in null case there is no error or else it will contain the object with error appropriate details. You should always check for the error first before continuing to process the response. 2. Response: This is the second parameter in the callback function. This contains the objecthttp.IncomingMessage which contains additional data about the http/https request i.e status Code, headers etc. 3. Body: This is the third parameter and contains the body of the http/https response. This is a string type containing the contents of the body if the response is in text format, body is a buffer if the response data is in the binary/octet stream encoding, finally, body is a JSON object if the response is in JSON encoding.

Simple GET call over HTTPS

For making HTTPS calls the request module automatically detects it from the URL and routes your requests via https module internally. For making HTTPS calls all you have to do is that in the UEL specify the protocol as the https. Lets see an example of the HTTPS call below:

[cc lang=”javascript”]

//Load the request module
var request = require(‘request’);

//Lets try to make a HTTPS GET request to modulus.io’s website.
//All we did here to make HTTPS call is changed the `http` to `https` in URL.
request(‘https://modulus.io’, function (error, response, body) {
//Check for error
if(error){
return console.log(‘Error:’, error);
}

//Check for right status code
if(response.statusCode !== 200){
return console.log(‘Invalid Status Code Returned:’, response.statusCode);
}

//All is good. Print the body
console.log(body); // Show the HTML for the Modulus homepage.

});

[/cc]

Making Simple PUT/POST/DELETE calls

Request module has some shorthand notations for making calls in common REST methods like POST, PUT or DELETE. Lets see some examples below:

First we need to load the request module, will ignore this line in coming examples for simplicity.

[cc lang=”javascript”]

//Load the request module
var request = require(‘request’);

[/cc]

Now to make POST call we just invoke request.post method as described below:

[cc lang=”javascript”]

//Lets try to make a HTTP POST call.
request.post(‘https://modulus.io’, function (error, response, body) {
//Check for error
if(error){
return console.log(‘Error:’, error);
}

//Check for right status code. If POST is not supported then there will be 404
if(response.statusCode !== 200){
return console.log(‘Invalid Status Code Returned[POST]:’, response.statusCode);
}

//If POST is honored. Print the body
console.log(body); // Show the HTML for the Modulus homepage.

});

[/cc]

Now to make DELETE call we just invoke request.del method as described below:

[cc lang=”javascript”]

//Lets try to make a HTTP DELETE call.
request.del(‘https://modulus.io’, function (error, response, body) {
//Check for error
if(error){
return console.log(‘Error:’, error);
}

//Check for right status code. If DELETE is not supported then there will be 404
if(response.statusCode !== 200){
return console.log(‘Invalid Status Code Returned[DELETE]:’, response.statusCode);
}

//If DELETE is honored. Print the body
console.log(body); // Show the HTML for the Modulus homepage.

});

[/cc]

Now to make PUT call we just invoke request.put method as described below:

[cc lang=”javascript”]

//Lets try to make a HTTP PUT call.
request.put(‘https://modulus.io’, function (error, response, body) {
//Check for error
if(error){
return console.log(‘Error:’, error);
}

//Check for right status code. If PUT is not supported then there will be 404
if(response.statusCode !== 200){
return console.log(‘Invalid Status Code Returned[PUT]:’, response.statusCode);
}

//If PUT is honored. Print the body
console.log(body); // Show the HTML for the Modulus homepage.

});

[/cc]

Now to make PATCH call we just invoke request.patch method as described below:

[cc lang=”javascript”]

//Lets try to make a HTTP PATCH call.
request.patch(‘https://modulus.io’, function (error, response, body) {
//Check for error
if(error){
return console.log(‘Error:’, error);
}

//Check for right status code. If PATCH is not supported then there will be 404
if(response.statusCode !== 200){
return console.log(‘Invalid Status Code Returned[PATCH]:’, response.statusCode);
}

//If PATCH is honored. Print the body
console.log(body); // Show the HTML for the Modulus homepage.

});

[/cc]

Some More Configurations

In the previous section, we discussed on how to make simple request calls via quick shortcut methods. Here we will discuss another syntax where you can configure the request as per your need.

In place of a string URL, request module also optionally takes a config object where we can pass the desired configurations. The syntax is like: request(optionsObject, callback). Lets see an example below:

[cc lang=”javascript”]

//Load the request module
var request = require(‘request’);

//Lets configure and request
request({
url: ‘http://modulus.io’, //URL to hit
qs: {from: ‘blog example’, time: +new Date()}, //Query string data
method: ‘GET’, //Specify the method
headers: { //We can define headers too
‘Content-Type’: ‘MyContentType’,
‘Custom-Header’: ‘Custom Value’
}
}, function(error, response, body){
if(error) {
console.log(error);
} else console.log(response.statusCode, body);
});

[/cc]

In the above example you can see that we passed a configuration object with varius configuration, there is a huge list of configurations which you can use to configure your request. Here we just demonstrated how you can pass some headers, query data as well as define the HTTP method explicitly.

Posting a string body

In thi example we will see how we can post a String or Buffer body using the request module. In this example we will use the body configuration property for posting the data.

[cc lang=”javascript”]

//Load the request module
var request = require(‘request’);

//Lets configure and request
request({
url: ‘https://modulus.io/contact/demo’, //URL to hit
qs: {from: ‘blog example’, time: +new Date()}, //Query string data
method: ‘POST’,
headers: {
‘Content-Type’: ‘MyContentType’,
‘Custom-Header’: ‘Custom Value’
},
body: ‘Hello Hello! String body!’ //Set the body as a string
}, function(error, response, body){
if(error) {
console.log(error);
} else console.log(response.statusCode, body);
});

[/cc]

Posting as a form

Request module has a helper configuration to post forms. You just need to pss the form data as an object to the form configuration property and it will automatically url-encode it and put it in the body with the desired application/x-www-form-urlencoded content type. Lets see an example below:

[cc lang=”javascript”]

//Load the request module
var request = require('request');

//Lets configure and request
request({
url: ‘https://modulus.io/contact/demo’, //URL to hit
qs: {from: ‘blog example’, time: +new Date()}, //Query string data
method: ‘POST’,
//Lets post the following key/values as form
form: {
field1: ‘data’,
field2: ‘data’
}
}, function(error, response, body){
if(error) {
console.log(error);
} else console.log(response.statusCode, body);
});

[/cc]

Posting JSON data

If we have an object and we want to post it as the JSON data we can do that by passing that object in the json configuration property. Lets see an example below:

[cc lang=”javascript”]

//Load the request module
var request = require(‘request’);

//Lets configure and request
request({
url: ‘https://modulus.io/contact/demo’, //URL to hit
qs: {from: ‘blog example’, time: +new Date()}, //Query string data
method: ‘POST’,
//Lets post the following key/values as form
form: {
field1: ‘data’,
field2: ‘data’
}
}, function(error, response, body){
if(error) {
console.log(error);
} else console.log(response.statusCode, body);
});

[/cc]

Streams

Request module has a fantastic first citizen interface for Streams. Streams are like a continous flow of data from one source to a target. Streams from which the data flows is call. Using streams can really save us the memmory as well as helps us to work with large data. If possible use of streaming API is recommended.

We will cover some very basic streaming based approach here, but this is just a start as streams have infinite possibilities.

Let’s consider an example here where we want to send a request for an image to third party server and stream the response to a file.

[cc lang=”javascript”]

//Load the request module
var request = require(‘request’);
//Load fs module
var fs = require(‘fs’);

//Lets define a write stream for our destination file
var destination = fs.createWriteStream(‘./savedImage.png’);

//Lets save the modulus logo now
request(‘https://my.modulus.io/img/modulus-logoSmall-gray20.png’).pipe(destination);

[/cc]

Here all we are doing is piping the readStream from the request we mage to the writeStream of our destination file. This is as simple as it is. We can also listen to error events as described below:

[cc lang=”javascript”]
//Lets save the modulus logo now
request(‘https://my.modulus.io/img/modulus-logoSmall-gray20.png’)
.pipe(destination)
.on(‘error’, function(error){
console.log(error);
});

[/cc]

Sending data from a file to a request via streams

We can also read data from a file and send it to a remote server via our request. Lets consider an example below:

[cc lang=”javascript”]

//Load the request module
var request = require(‘request’);
//Load fs module
var fs = require(‘fs’);

//Lets define a read stream from our source file
var source = fs.createReadStream(‘./sampleData.json’);

//Lets send our data via POST request
source.pipe(request.post(‘https://modulus.io/contact/demo’));

[/cc]

In this example, we created a read stream from our source file and piped it to the request.

Conclusion

In this article, we learned about the basics and basic usage of the request module. We saw how we can use shorthand methods, custom configurations as well as basics of streaming API. For future, you can read about more detailed streams usage in request module as well as some of its sweet auth features.