Post
Ask Question

Restful API With ExpressJS And MongoDB - Part One

Apps are evolving and evolving very fast, they are getting more distributed and more diverse then ever with all the new breakthrough technological wonders that we are witnessing these days. I am working my way through a typical architecture that I guess is de-facto when its comes to building scalable, rock solid web apps which can withstand considerable amounts of web traffic with modest hardware requirements, you guessed it right, I am talking about MEAN-stack, MongoDb to store information, Express.js as web framework, Angular.js for front-end with marvellous user experience and finally node.js to power app with its raw beast like performance as a platform.

This article is going to be multi part, in the first few parts, we'll just try and build a stable RESTful api using express.js + mongodb and a whole lot of magic.

What's covered in this article?

  • Touch up on express.js and use express generator to quickly get started.
  • Install required packages and build our first "hello world" rest api.
  • And finally discuss few techniques that I have learned to speed up the development.

Pre-requirements

Before we get started, you might want to prepare your development machine as mentioned in this article. It's not necessary, but highly recommended as I'll be using tools mentioned in that article. But still, feel free to use what ever tools and OS you want, everything should work just fine! Depending on how you have installed node.js, you might want to use sudo while installing global packages (if you have used the script provided in the previously mentioned article to setup your development machine, then you don't have to worry, just execute commands as they are provided).

Throughout this article, I'll be providing shell scripts and commands, so it would be much easier for you to use them if your development machine is any *nix system, i.e. ubuntu, OS X etc.

Express.js

Express.js is a light weight, hackable and minimalistic web framework for node.js. I don't have much to say about it right now, but I'll shed light on various beautiful aspects and techniques that express.js enables us to utilise. We are going to use the official express generator for initial scaffolding. So what are we waiting for, lets fire up a terminal and type following command. 

  1. mkdir mongo-crud-express-api && cd $_ && express --hbs   

If the above command somehow fails, make sure that you have express generator installed, use following command to do so.

  1. npm install express-generator -g  

Thats it, a fully working hello world style express app is ready for you to mess around with. if you execute tree command following folder structure will show up, 

  1. .  
  2. ├── LICENSE  
  3. ├── README.md  
  4. ├── app.js  
  5. ├── bin  
  6. │ └── www  
  7. ├── package.json  
  8. ├── public  
  9. │ ├── images  
  10. │ ├── javascripts  
  11. │ └── stylesheets  
  12. │ └── style.css  
  13. ├── routes  
  14. │ ├── index.js  
  15. │ └── users.js  
  16. └── views  
  17. ├── error.hbs  
  18. ├── index.hbs  
  19. └── layout.hbs  
  20.   
  21. 7 directories, 11 files   

If tree is not installed, you can install it using, 

  1. sudo apt-get install tree   

Following is commented version, 

  1. .  
  2. ├── LICENSE  
  3. ├── README.md  
  4. ├── app.js (Our express app is created and configured here)  
  5. ├── bin  
  6. │ └── www (Code to create server, set up port here)  
  7. ├── package.json (Defines dependencies)  
  8. ├── public (This folder is exposed to host static content)  
  9. │ ├── images  
  10. │ ├── javascripts  
  11. │ └── stylesheets  
  12. │ └── style.css  
  13. ├── routes (Our routes are defined here)  
  14. │ ├── index.js  
  15. │ └── users.js  
  16. └── views (Our handlebar views reside here)  
  17. ├── error.hbs  
  18. ├── index.hbs  
  19. └── layout.hbs  
  20.   
  21. 7 directories, 11 files   

The solution is configured to use handlebars.js as template engine. For now, don't worry about it, as we are not going to use anyway, at least not for now. I'll dedicate a whole blog for this one if and when required. For now, we are almost there, our app is scaffolded and ready to be launched, we just need to install the dependencies (packages) defined in our package.json, 

  1. npm install   

Here is our package.json 

  1. {  
  2.    "name": "mongo-crud-express-api",  
  3.    "version": "0.0.0",  
  4.    "private": true,  
  5.    "scripts": {  
  6.       "start": "node ./bin/www"  
  7.    },  
  8.    "dependencies": {  
  9.       "body-parser": "~1.13.2",  
  10.       "cookie-parser": "~1.3.5",  
  11.       "debug": "~2.2.0",  
  12.       "express": "~4.13.1",  
  13.       "hbs": "~3.1.0",     
  14.       "morgan": "~1.6.1",  
  15.       "serve-favicon": "~2.3.0"  
  16.    }  
  17. }   

This command will install all packages and its dependencies mentioned in package.json's dependencies section under node_modules folder. Ok, Now the app has everything it needs to start, so lets fire it up, 

  1. npm start   

This command will execute ./bin/www script as mentioned in our package.json's scripts sections, ./bin/www is associated with command start.

We have our app up and running at http://localhost:3000 so load it up in browser and you'll see following, Outupt
Hurray!!

So far, so good. Just a few more tweaks and we'll have our first api ready in no time. Lets start, first of all we'll need to stop npm start which is currently executing and serving up our app, to do so press CTRL + C to terminate, then type atom . to open up the atom editor (or any other editor of your choice). Open ./routes/users.js. Following is commented version. 

  1. //Fetches express module  
  2. var express = require('express');  
  3. //creates router, using which we'll define our routes  
  4. var router = express.Router();  
  5.   
  6. /* GET users listing. */  
  7. router.get('/', function(req, res, next) {  
  8. //Send response back  
  9. res.send('respond with a resource');  
  10. });  
  11.   
  12. //export the router with the configured routes.  
  13. module.exports = router;   

This file defines routes for interacting with our users resource, to access it, let start our app, but this time we'll use a different, more smarter way to do so, type in nodemon and hit return, nodemon is a neat little tool, a very giving one - I must say. It'll just sit there for ever (until you ask it to stop by pressing CTRL+C) and keep a close watch on your file system (under current folder), as soon as it detects a change, it will re-run the app for you, because it knows you'd always want your latest changes up and running as soon as possible. Isn't it nice? It takes in all the load of re-runing your app and lets you concentrate on more important tasks, like writing awesome code. After thanking nodemon team for the awesome work they are doing, Load up your browser and visit http://localhost:3000/users you'll see respond with a resource displayed in browser. Thats what was returned from the users route we just saw. It's already a GET api; the only problem with it is that it does not respond in JSON, and as we are very much interested in writing JSON based RESTful api, we'd want to fix that. To do so just replace following line from ./routes/users.js. 

  1. res.send('respond with a resource');   

with, 

  1. res.json({message: 'Hello World'});    
If you refresh your browser now, you'll see that we have a JSON response now. The browser loads it as, 
  1. {"message":"Hello World"}   

Browsers are an excellent tool to see the result of countless hours of effort that we put in developing a web app, though, I personally feel that, they render worthless when it comes to see apis. You say how dare I? Well, I have my reasons, for starters, RESTful APIs are much more then just a JSON response, it consists of response headers, status codes, content type, ETag etc which are tough to see at a glance in a browser. Well not to worry, there are many tools available to the rescue, for now we'll look at curl and POSTMAN. Open up a new terminal and type, 

  1. curl -v http://localhost:3000/users   

It'll fill terminal with very valuable information on what headers were sent, what headers were return, what was the status code and finally the resource that was returned. The output looks like, 

  1. * Trying ::1...  
  2. * Connected to localhost (::1) port 3000 (#0)  
  3. > GET /users HTTP/1.1  
  4. > Host: localhost:3000  
  5. > User-Agent: curl/7.43.0  
  6. > Accept: */*  
  7. >  
  8. < HTTP/1.1 200 OK  
  9. < X-Powered-By: Express  
  10. < Content-Type: application/json; charset=utf-8  
  11. < Content-Length: 37  
  12. < ETag: W/"25-qqpeRLIrmh6jArUfHvRJTA"  
  13. < Date: Sun, 06 Dec 2015 20:06:38 GMT  
  14. < Connection: keep-alive  
  15. <  
  16. * Connection #0 to host localhost left intact  
  17. {"message":"Hello World"}   

If you have python installed, you can easily print pretty JSON using following command, 

  1. curl -vfsSl http://localhost:3000/users | python -m json.tool   
  1. * Trying ::1...  
  2. * Connected to localhost (::1) port 3000 (#0)  
  3. > GET /users HTTP/1.1  
  4. > Host: localhost:3000  
  5. > User-Agent: curl/7.43.0  
  6. > Accept: */*  
  7. >  
  8. < HTTP/1.1 200 OK  
  9. < X-Powered-By: Express  
  10. < Content-Type: application/json; charset=utf-8  
  11. < Content-Length: 37  
  12. < ETag: W/"25-qqpeRLIrmh6jArUfHvRJTA"  
  13. < Date: Sun, 06 Dec 2015 20:21:01 GMT  
  14. < Connection: keep-alive  
  15. <  
  16. { [37 bytes data]  
  17. * Connection #0 to host localhost left intact  
  18. {  
  19. "message": "Hello World"  
  20. }   

Observe JSON at bottom, my my, it looks so pretty! Well, if you are not a big fan of CLI (Command line interface), then you can always use POSTMAN. Its just like fiddler but only much better.

So, I guess that's it for now, lets conclude the first part here, we just build our first Hello World api. Full source code of what we have done so far can be found here; just in case if you get stuck somewhere.

In the next part, I'll go through and explain app.js, how ./routes/uses.js was mounted at http://localhost:3000/users and more.

Hope you guys had fun! Feel free to comment below, See you in part 2.

Cheers and Happy coding!!

Read more articles on Node.js:


Similar Articles