Node.JS RESTful API

REST stands for REpresentational State Transfer. REST is a standard web base architecture that relies on HTTP protocol. Simply put, REST treats every component of the web application as a resource which can be accessed via common HTTP interface. REST architecture is based upon server and client. A client requests for a resource to REST server via HTTP, REST server provides client, access to that resource. Each rest resource is identified by a global ID or a URL. A REST resource can be presented in the form of JSON, XML or simple text. However, JSON is the preferred representation. In this article we shall study how to implement node.js RESTful API architecture.

Node.js RESTful API Methods

The RESTful API methods are HTTP methods commonly used in RESTful APIs. There are four major HTTP methods. 1) Get: It provides read only access to HTTP resource. 2) PUT: It creates a new resource. 3) Delete: This method is used to delete an existing resource.

RESTful Web Services

Web services provide communication facilities between applications written in different languages and deployed on different platforms. Web services make use of some open web standards used for communication between different devices. RESTful web services are web services that implement node.js RESTful API architecture.

Creating a RESTful API

Enough of theory, let’s jump into some coding now. Suppose we have a JSON database of student records which looks like this.

{
   "Student1" : {
      "name" : "John",
      "Age" : 10,
      "Gender" : "Male",
      "id":1
   },
  "Student2" : {
      "name" : "Susan",
      "Age" : 9,
      "Gender" : "Female",
      "id":2
   },
  "Student3" : {
      "name" : "Josh",
      "Age" : 11,
      "Gender" : "Male",
      "id":3
   },
  "Student4" : {
      "name" : "Sofia",
      "Age" : 8,
      "Gender" : "Female",
      "id":4
   }
}

Download the file

Now we have a resource named students.json. We shall now provide HTTP methods so that clients can access this resource in different ways. We will provide four HTTP methods for this resource.

  • listStudents: This method will use HTTP get and will display list of all students.
  • addStudent: This method adds a new student via POST method.
  • deleteStudent: This method deletes a student via HTTP delete
  • :Name: Retrieves record of a student.

Implementing listStudents Method

The first method that we shall implement is the listStudent method. But before that, make sure you have a global installation of express module since this application makes use of it. If you do not have express module installed. Type the following command in your node.js command window “npm install express –save”. This will install express module globally. Now, take a look at the following code.

var express = require('express');
var expapp = express();
var fileSystem = require("fs");

expapp.get('/listStudents', function (req, res) {
   fileSystem.readFile( __dirname + "/" + "students.json", 'utf8', function (err, data) {
      console.log( data );
      res.end( data );
   });
})

var rserver = expapp.listen(9006, function () {
   var hostaddr = rserver.address().address
   var portaddr = rserver.address().port

   console.log("Example app listening at http://%s:%s", hostaddr, portaddr)
})

Download the code Try the code

In the above code, we implement the get method of the express module. This method is similar to HTTP get. This method makes server respond with contents of students.json file whenever a request arrive for listStudents. Run this code and then type http://127.0.0.1:9006/listStudents. You shall see all the student records printed in your browser.

In the next tutorial, we shall implement the addStudent, deleteStudent and :Name methods. Keep visiting this site.

Node.js HTTP Client

In the last article we studied how we can create a web server via node.js which listens to HTTP requests and sends back HTTP response. We created a simple “main.htm” file and placed it in the root directory of the code file for server. We then used our browser to access that file. Here browser worked as HTTP client. However, as we wrote node.js HTTP web server, we can also write node.js HTTP client

Before we execute the code for node.js HTTP client and test its ability to access the file “main.htm” on the server, you must have your server running and you should also have “main.htm” file placed in the root directory if the code file for the server. If you do not know how to set up an HTTP server and how to create and place file “main.htm”, go back to the previous article and do that. Then come back and follow the article from here.

Creating a Node.js HTTP Client

The following code creates an HTTP client that requests for file “main.htm” from the server “localhost” running at port 9006. Take a look at this code.

var http = require('http');

// Options to be used by request 
var reqparams = {
   host: '127.0.0.1',
   port: '9006',
   path: '/main.htm'  
};

var readResponse = function(response){

   var page = '';
   response.on('data', function(data) {
      page += data;
   });
   
   response.on('end', function() {
      console.log(page);
   });
}

var request = http.request(reqparams, readResponse);
request.end();

Download the code Try the code

Take a look at the above code. Here first we import the http module via require. This returns an http instance. Next we specify the parameters for the request. It is basically an associative array. Here first item is the host address, the second item is the port and the third one is the name of the file you wish to retrieve from server. Next, we create a callback function “readResponse”. Finally we call request function on http instance. This function takes two parameters, the request parameters in the form of associative array and the call back function used to read the response which in our case is “readResponse”. So as soon as the client starts receiving response it is added to the page variable. Finally when all the response has been received, the page variable is displayed via console.log. This should contain the html content of main.htm you created in last article.

Node.JS Web Server

We have covered most of the basic node.js concepts. Now is the time to move towards more advanced node.js concepts. In this article we shall study what node.js web server is and how to create it via node.js. But first, lets see what a web server in general is.

A web server

When you type URL of some website in your browser and hit enter, you basically generate an HTTP request for a webpage located at a remote computer. That remote computer that serves your HTTP requests is basically a web server. So a web server can be defined as a computer that listens to HTTP requests from clients such as web browser, and sends backs HTTP response in the form an HTML page. However, if the request page contains some server side scripting e.g PHP or ASP.NET etc, the server forwards the page to Application server which processes the server side code, make database requests if any and sends back the corresponding HTML which is then sent to client by the web server.

Take a look at the following code. Here we create a simple node.js web server.

var http = require('http');
var fileSystem = require('fs');
var path = require('url');

http.createServer( function (request, response) {  
 
   var filepath = path.parse(request.url).pathname;
   
  
   console.log("Client request received for " + filepath);
   

   fileSystem.readFile(filepath.substr(1), function (err, page) {
      if (err) {
         console.log(err);

         response.writeHead(404, {'Content-Type': 'text/html'});
      }else {	

         response.writeHead(200, {'Content-Type': 'text/html'});	
        
         response.write(page.toString());		
      }
 
      response.end();
   });   
}).listen(9006);


console.log('Server listening for requests at http://127.0.0.1:9006/');

Download the code Try the code

In the above example we use HTTP instance to create a web server by calling its “createServer” method. Create server is an asynchronous method which waits for the client requests for the execution of its callback function. As soon as client request is received, the contents of the requested file are read and sent to the client.

Sending Request to Web Server

To check if server is functioning correctly, create a file named “main.htm” and add the following code to it.

<html>
   <head>
      <title>Welcome Page</title>
   </head>
   
   <body>
      <h1>Welcome to knowledge hills.</h1>
   </body>
</html>

Download the code

Place the above file in the same directory where the code of your web server file is located.

Now type the following address in your browser, “http://127.0.0.1:9006/main.htm”. This is basically a request the server we created, for the file “main.htm”. The server will send back the html contents of main.htm. In the browser you will see “Welcome to knowledge hills.” printed in h1 heading. This is basically how your browser read the contents of the html document i.e. “main.htm”

Node.JS Global Objects

In almost all of the previous articles we import some module and then used its function to perform a particular task. For instance, in the last two articles we used “File System” module named “fs” and used its readFile() and writeFile() functions to read and write files. We used “require” command in order to import and use “fs” module. However there are some modules that globally available and we do not need “require” statement to include those modules into our applications. Rather, they are directly available. Such modules are called node.js global objects. These global objects can be classes, strings, functions etc. In this article we shall discuss some of these node.js global objects.

__dirname and __filename

The _direname global objects return full path of the directory in which the current script is running. Similarly, the __filename global object returns complete file name with the resolved absolute path. Take a look at the following example.

console.log( __dirname );
console.log( __filename );

Download the code Try the code

setTimeout(callback, milliseconds) and clearTimeout(callback, milliseconds)

The setTimeout(cb, ms) method is used to execute a particular function after specified amount of time. The function takes callback as the first parameter and time in milliseconds as the second parameter. Similarly, clearTimeout(timer) function clears or stop previously set timer. Take a look at the following code to see how these functions work.

function printWelcome(){
   console.log( "Welcome to Knowledge Hills!");
}

function printWelcome2(){
   console.log( "Welcome to Knowledge Hills Again");
}

var timer = setTimeout(printWelcome, 3000);
var timer2 = setTimeout(printWelcome2, 3000);

clearTimeout(timer2);

Download the code Try the code

In the above code we declare two functions “printWelcome” and “printWelcome2”. Next we use setTimeout function twice and add both “printWelcome” and “printWelcome2” functions a callbacks. The time for the execution of these callback functions is set to three seconds. Next, we use clearTimeout function and pass it the timer for the “printWelcome2” function. This clears the timer for the second function. Now if you run the above code, you shall see that the first method i.e. “printWelcome()” shall execute after three seconds, however the second method i.e.”printWelcome2()” shall not execute since its timer has been cleared via clearTimeout function.

Node.JS File System Useful Functions

In the previous article we saw what node.js file system module is. We also saw how to use asynchronous as well synchronous functions of node.js file system module with the help of an example. Finally we saw how fs “open” function is used to open any file. In this article we shall some more node.js file system useful functions.

Node.js File System Reading-Writing

To read contents of the file, the best way is to use “readFile()” which is asynchronous and takes two parameters. Error event and callback. Similarly to write data to a file, use “writeFile” function which is also asynchronous. Take a look at the following example to see how file reading/writing tasks are accomplished by File System module.

var fileSystem = require("fs");

console.log("Data Writing..");
fileSystem.writeFile('output3.txt', 'Knowledge Hills, Learning Platform',  function(err) {
   if (err) {
      return console.error(err);
   }
   
   console.log("Data writing complete");
   console.log("Data reading");
   fileSystem.readFile('output3.txt', function (err, data) {
      if (err) {
         return console.error(err);
      }
      console.log("Reading data asynchronously: " + data.toString());
   });
});

Download the code Try the code

From the above code, it can be seen that writeFile method takes three parameters: the path of the file, the data to be written on the file and error function as call back. Now if you go into the directory where you have placed your code file, you should see a file named “output3.txt” and the file should contain the string you passed as second parameter to the writeFile() function.

Creating and Removing Directory

Since we are discussing, node.js file system useful functions, it wouldnt be fair if we dont discuss directory functions. The file system module contains “mkdir” and “rmdir” functions that are respectively used to create and remove directories in node.js. Take a look at the following example. Here we create two directories.

var fileSystem = require("fs");

console.log("Creating new director /newdir/temp");
fileSystem.mkdir('/newdir',function(err){
   if (err) {
      return console.error(err);
   }
} )
fileSystem.mkdir('/newdir2',function(err){
   if (err) {
      return console.error(err);
   }
})

 console.log("New directories created.");

Download the code Try the code

You can see that the “mkdir” function takes two parameters. The path of the directory to create and the error callback function. Now if you go to your “C:” directory, you should find two new directories there i.e. newdir, newdir2.

Take a look at the following code, this will remove “newdir” in the “C:” drive. If directory doesnt exist, an exception shall be thrown.

var fileSystem = require("fs");

console.log("deleting director /newdir");
fileSystem.rmdir('/newdir',function(err){
   if (err) {
      return console.error(err);
   }
})
    
console.log("Directory removed successfully ...");

Download the code Try the code

Node.JS File System

Node.js File System module is used to perform file I/O operations in node.js. To import file system module, require command is used as follows: “var filesystem = require(“fs”)”.

All the functions of the “fs” have two variations. There are synchronous as well as their asynchronous counterparts. Asynchronous functions take a couple of parameters: First parameter is the callback in case if error occurs and the second function is the callback function which is called when function completes its execution. All the synchronous functions are blocking where as asynchronous functions are non-blocking. Therefore, you should always prefer asynchronous functions.

Example of Synchronous vs Asynchronous Functions

Take a look at the following example. Here we shall explain what is the difference between a synchronous and asynchronous function.

Create a text file named “myfile.txt” and add the following text in the file.

Knowledge hills is a website that contains free of cost programming tutorials

Learn and Build apps for free.

Now create a file named “filesystem1.js” in the same directory as “myfile.txt” and add the following line of code in it.

var fileSystem = require("fs");

// Asynchronous File Reading
fileSystem.readFile('myfile.txt', function (err, content) {
   if (err) {
      return console.error(err);
   }
   console.log("Asynchronous File Reading: " + content.toString());
});

// Synchronous File Reading
var content = fileSystem.readFileSync('myfile.txt');
console.log("Synchronous File Reading: " + content.toString());

console.log("Program execution completed.")

Download the code Try the code

Take a careful look at the above code. First we import the “fs” module and the call readFile() function on it. This is asynchronous function. Once it start reading the file, program execution shifts to the next piece of code. Here we use readFileSync() function which is a synchronous function. It will also read file. However, it will block the code until all the file is read. It then prints the contents of the file on console. Next when the first asynchronous call readFile() is complete reading the data. The callback function is executed which prints the contents of the file. Therefore, you can see how synchronous and asynchronous methods differ in terms of execution.

Opening a file via Node.js File System

To open a file via node.js file system module, the open function is used. This function takes four parameters: Path to the file, file permissions such as reading, writing or both, the mode and finally the callback with two arguments err and fd.

Take a look at the following example to see how to open a file via node.js file system.

var fileSystem = require("fs");

console.log("Before opening the file");
fileSystem .open('myfile.txt', 'r+', function(err, fd) {
   if (err) {
      return console.error(err);
   }
  console.log("After successfully opening the file.");     
});

Download the code Try the code

In the above code the flag used for opening the file is r+. This means that file should be asynchronously opened for both reading and writing purposes.

Node.JS Streams

Node.js streams are nothing but instances of eventEmitter class. Streams are used to write data to different destinations and read data from different destinations. There are four types of node.js streams.

  • Readable: Used to read data from different sources
  • Writeable: Used to write data to different sources
  • Dulplex: Used for both reading and writing purposes
  • Transform: A type of duplex stream where input is processed and output depends upon the input.

As discussed earlier, Streams are instances of eventEmitter class. This means that node.js streams can fire events. Following are some of the events that stream classes can fire.

  • error: This is the event fired if an error occurs while reading or writing data.
  • data: This event is fired when there is more data available for reading.
  • end: This event occurs when no more data is available for reading.
  • finish: This event is fired when all the data from the source has been read.

Reading data via Streams

To see how stream objects read data from some source, take a look at the following example.

Create a text file named “myfile.txt” and add the following text in the file.

Knowledge hills is a website that contains free of cost programming tutorials

Learn and Build apps for free.

Now create a file named “streams.js” in the same directory as “myfile.txt” and add the following line of code in it.

var filestream = require("fs");
var contents = '';
var rstream = filestream.createReadStream('myfile.txt');


rstream.setEncoding('UTF8');


rstream.on('data', function(data) {
   contents += data;
});

rstream.on('end',function(){
   console.log(contents);
});

rstream.on('error', function(err){
   console.log(err.stack);
});

rstream.on('finish', function(){
   console.log("Data reading complete");
});

console.log("Code After File Reading.");

Download the code Try the code

In the above code, we import “fs” module. We then call readFileStream() function on the object and pass it the path of the file. This gives us instance of readable stream. Next, we bind data, end and error events. Whenever data event occurs, we add newly read data to already read data stored in the content variable. When data reading is complete, we display the content variable. When you run the code you shall see that the line of code after data reading functionality shall be displayed first. This is because data reading is an asynchronous task and runs in parallel with other piece of code.

Writing data via Streams

Now, you know how to read data via streams. Writing data via streams is also very similar. Take a look at the following example.

var filestream = require("fs");
var content = 'Knowledge Hills, Learning Platform';


var wStream = filestream.createWriteStream('output.txt');


wStream.write(content,'UTF8');

wStream.end();

wStream.on('finish', function() {
    console.log("Content Writing Completed");
});

wStream.on('error', function(error){
   console.log(error.stack);
});

console.log("Code After Data Writing");

Download the code Try the code

Now when you execute the above code, you shall see that a file named “output.txt” will be created in the root directory of the code file. The file shall contain the string “Knowledge Hills, Learning Platform”. In the above code we used “createWriteStream” function which returns a writable stream.

Node.JS Buffer II

In the previous article we started a discussion on buffers. We saw different ways of creating buffers in Node.js. We also saw how to write data to a node.js buffer and how to read data from node.js buffer. We also saw how we can convert node.js buffer to JSON. In this article we will study some more buffer functionalities. We shall see how to concatenate two buffers, how to compare two buffers, how to copy two buffers and how to slice buffers. So, let’s get started with the first one.

Buffer Concatenation

Buffer concatenation refers to joining data stored inside two or more than two buffers. To concat buffers, Buffer.concat(arraylist[], total_length ) is used. Here first parameter is the arraylist of all the buffer to concatenate while second argument is the length of each buffer. Take a look at the following example to see buffer concatenation in action.

var buf1 = new Buffer('Knowledge Hills ');
var buf2 = new Buffer('Learn Programming Tutorials');
var buf3 = Buffer.concat([buf1,buf2]);
console.log("Concatenated Buffer: " + buf3.toString());

Download the code Try the code

Buffer Comparison

Buffer comparison compares whether the buffer being compared comes before the first buffer in sort order, or it is same as the first buffer or it comes after the first buffer in the sort order. Buffer.compare(buffer2) method is used for buffer comparison. It returns a number less than zero if the first buffer comes before the second buffer. In case if the two buffers are same, this method returns 0. And finally if first buffer comes after the second buffer, compare method returns a number greater than 0. Take a look at the following example.

var buf1 = new Buffer('Knowledge');
var buf2 = new Buffer('Hills');
var compres = buf1.compare(buf2);

if(compres < 0) {
   console.log(buf1 +" comes earlier than" + buf2);
}else if(compres == 0){
   console.log(buf1 +" is similar to" + buf2);
}else {
   console.log(buf1 +" comes after " + buf2);
}

Download the code Try the code

Buffer Copy

To copy to buffers, buffer.copy(buffer2) method is used. This method copies, contents of the first buffer into buffer2. Take a look at the following example.s

var buf1 = new Buffer('Knowledge');


var buf2 = new Buffer(9);
buf1.copy(buf2);
console.log("Contents of Copied Buffer: " + buf2.toString());

Download the code Try the code

Buffer Slicing

You can also slice contents of a buffer. This is similar to substring method. To slice a buffer, the method buffer.slice(start, end) method is used. Here start specifies index where slicing begins. Similarly, end specifies index where slicing ends. Take a look at the following example.

var buf1 = new Buffer('Knowledgehills');

var buf2 = buf1.slice(9,14);
console.log("Contents of sliced buffer: " + buf2.toString());

Download the code Try the code

Node.JS Buffers

We have covered most of the basic concepts of Node.js in previous articles. In this article we shall discuss a bit more advanced topic i.e. node.js buffers. Node.js applications are written in JavaScript. JavaScript is very powerful when it comes to dealing with unicode data. However, we run node.js application outside the browser. Therefore, we often need to interact with octet stream and store them on the memory heap in the form of binary data. Node.js contains a global buffer class that is used to read and write octet streams

Initializing Node.js Buffers

There are three ways to initialize buffers in Node.js.

  • var bf = new Buffer(20) : This creates a buffer of 20 Octets
  • var buf = new Buffer([7,14,21,28,35]): This creates a buffer from array
  • var buf = new Buffer(“Knowledge Hills”, “utf-8”) : This creates a buffer from string along with encoding type.

Reading and writing 9 Digits to and from buffer

In the following example we shall create a buffer that stores octet values for digits 1 to 9. We shall then read this buffer via different encoding techniques. Take a look at the following example.

var bf = new Buffer(9);
for (var i = 0 ; i < 9 ; i++) {
  bf[i] = i + 49;
}

console.log( bf.toString('ascii'));       // outputs: 1234567489
console.log( bf.toString('ascii',0,6));   // outputs: 123456
console.log( bf.toString('utf8',0,6));    // outputs: 123456
console.log( bf.toString(undefined,0,3)); // default utf-8 encoding will be used 123

Download the code Try the code

In the above code we initialize a buffer with 9 octets. At each octet we specified the ASCII value for numeric integers 1 to 9. Next when we read the buffer we use buffer.toString() method. This method takes three parameters, first one is the encoding type, 2nd is the starting index to read and the third is ending index. Similarly if you are directly writing the buffer using a string you can use buffer.write method. It takes four parameters: string, offset, length and encoding.

Buffer to JSON Conversion

You can easily convert buffer data to JSON format via buffer.toJSON() function. Take a look at the following example.

var bf = new Buffer('Knowledge hills: learning website');
var jsn = bf.toJSON(bf);

console.log(jsn);

Download the code Try the code

The above piece of code will convert string passed to buffer into its JSON representation and will print it on screen.

Node.JS Event Emitter

In the previous article we saw how to generate and handle events in node.js. We saw that eventEmitter class of events module was responsible for binding events with event handler as well as firing events. However, node.js event emitter class has far more capabilities than this. It contains many useful functions that can be used to perform a variety of task. In this article we shall see those node.js event emitter functions in detail.

Common Node Event Emitter Functions

Following are some of the most commonly used functions

addListener(event, listener)

The addListener function binds the event passed as first parameter to the listener passed as second parameter. This function can be called multiple times. Each call binds listener at the end of the listener loop. The function returns the eventEmitter object.

removeListener(event, listener)

This event removes the listener specified as the second argument from the list of the listeners corresponding to the event specified as the first argument. It is important to note here that this method only remove one instance of the specified listener. If you have multiple listeners that you want to remove, you should call this method multiple times.

once(event, listener)

This function adds listener to the event and executes only once. When the event is fired for the first time, this listener executes and then it is removed from the list of the listeners.

on(event, listener)

This is similar to the addListener function. It binds the event passed as first parameter to the listener passed as second parameter. This function can be called multiple times. Each call binds listener at the end of the listener loop. The function returns the eventEmitter object.

listeners(event)

It returns array of all listeners bound with the event specified as a parameter.

Take a look at the following example. Here we shall implement some of the functions discusses above.

var events = require('events');
var eE = new events.EventEmitter();


var lis1 = function lis1() {
   console.log('First listener executed.');
}


var lis2 = function lis2() {
  console.log('Second Listener executed.');
}

var lis3 = function lis3() {
  console.log('Third Listener executed.');
}

eE.addListener('conn', lis1);


eE.on('conn', lis2);

eE.addListener('conn', lis3);

var eventListeners = require('events').EventEmitter.listenerCount
   (eE,'conn');
console.log(eventListeners + " listeners attached with connection event");


eE.emit('conn');


eE.removeListener('conn', lis1);
console.log("Lis1 removed from conn event.");


eE.emit('conn');

eventListeners = require('events').EventEmitter.listenerCount(eE,'conn');
console.log(eventListeners + " listeners attached with connection event.");

console.log("Program Execution Complete");

Download the code Try the code

In the above code, three listeners are added to the event loop of “conn” event. Then via eventEmitter object eE, the conn event is fired. This causes the three listeners to execute. Next, the first listeners is removed from the last. The conn event is fired again. However, this time only the second and third listeners shall execute.

Copyright 2005-2016 KnowledgeHills. Privacy Policy. Contact .