Create A Simple RESTful API With Node.js

I’ve written a few tutorials regarding Node.js and the ExpressJS framework, but I never took a step back and explained how to make a super simple RESTful API for processing HTTP requests from a front-facing interface.

With this API created, you can use it with just about any application that can submit HTTP requests.  It is a great way to test a mobile application or one that uses JavaScript frameworks like jQuery, ReactJS, or AngularJS.

There are a few requirements prior to following this tutorial:

  • You must have Node.js installed on your computer.
  • The Node Package Manager (NPM) must be up to date.

With that noted, go ahead and create a new directory for the project to live.  I’m using a Mac and will be doing everything in a directory on the Desktop.  Don’t be alarmed by my use of the Terminal.  Create the directory like so:

Navigate into the new directory and initiate a new NPM project:

You’ll be asked a series of questions.  Answer them appropriately or just paste the following in the package.json file it creates at the end:

The project is now ready.

We’re going to use Express as our Node.js framework so this requires us to install two packages with NPM:

The body-parser package allows our API to process POST requests.

Before going any further, let’s take a look at our project structure:

SimpleAPI
—-> package.json
—-> app.js
—-> routes
——–> routes.js

We’ve already taken care of package.json so let’s move onto the app.js file.  It is a wrapper for all server configuration and included files.  For example we’ll determine what port to use and what routes to include in this file.  Create it and include the following code:

To explain what we just did, we are first including the two packages and configuring the body parser to accept JSON as well as url encoded values.

When the server starts, it will listen for requests on port 3000.

This leaves us with the following line:

All API endpoints will appear in this file.  So let’s go ahead and open routes/routes.js found in the project root and add the skeleton code for this file:

We are passing the app variable from app.js and then exporting the appRouter variable to be used by whatever calls it in our project.  This means anything found in that function will be usable.

So what might an example route look like?  Add the following into the appRouter function:

Alright that route isn’t the most exiting, but here is what it is doing.  When the root of the application is requested via a GET request, the text Hello World will be returned.  By root of the application I mean http://localhost:3000.

So how about creating some routes that are actually useful?  Let’s say we want to have a route for creating accounts and a route for getting account information.  Starting with getting particular accounts, look at the following:

Yes I put the password in plain text for my mock data.  Of course you shouldn’t do this in production.  Beyond that, what we’re doing is we’re accepting GET requests on the /account endpoint.  The request must contain a username query parameter.  If the username doesn’t exist or doesn’t match the one in our mock data we return an error.  Otherwise we return the mock data object.

In production you’ll probably want to go against a database rather than using mock data.

Now let’s look at an endpoint in our API for creating accounts.

You’ll notice I chose to use the same endpoint.  Instead of a GET request, this endpoint is only accessed over a POST request.  As long as the required body parameters exist in the request, we are just choosing to return them.  Again in production you’ll probably want to include some database logic.

We have a Node.js application with three API endpoints now.  Let’s go ahead and test it out.

Since we are requiring two packages (Express and Body Parser), we need to install the for the first time.  With the project as your current working directory in the Terminal or Command Prompt, run the following:

Now you can go ahead and run the application:

Try hitting one of the GET endpoints from your browser with the host as http://localhost:3000.  You should get a response.  You’ll need a browser extension or something else in order to test the POST endpoint.

Conclusion

We didn’t use a database in this example, but you saw how to make a very simple RESTful API using Node.js and the ExpressJS framework.  I personally whip something like this up when I need to test my Ionic Framework and React Native applications.  Even without real data it is still good for testing your front-end applications.

Nic Raboy

Nic Raboy is an advocate of modern web and mobile development technologies. He has experience in Java, JavaScript, Golang and a variety of frameworks such as Angular, NativeScript, and Apache Cordova. Nic writes about his development experiences related to making web and mobile development easier to understand.

  • Tiago Winehouse

    Fantastico this NodeJS, every day I fall in love more.. Thank you Nic for another learning..

    • No problem! Thanks for the compliment 🙂

  • Simple and straightforward. Thanks. =]

  • Ahmad Ayyaz

    Cannot GET /
    I am getting this as a response

    • My assumption is you’ve not matched the content that I provided. Do you have any logs? You might throw your code on GitHub and I’ll take a look.

      Best,

    • Karen Gonzalez

      Did you forget the model name in the url?
      http://localhost:3000/account

  • Nice post! To complement it, take a look this cool ebook about building apis with node.js using ES6:
    https://leanpub.com/building-apis-with-nodejs

  • Ketav Chotaliya

    Getting error : app is not defined at routes/routes.js:1:63

    • That would make sense if you forgot to pass app from the app.js file:

      var routes = require(“./routes/routes.js”)(app);

      Best,

      • Ketav Chotaliya

        app.js

        var express = require(“express”);
        var bodyParser = require(“body-parser”);
        var app = express();

        app.use(bodyParser.json());
        app.use(bodyParser.urlencoded({ extended: true }));

        var routes = require(“./routes/routes.js”)(app);

        var server = app.listen(3000, function () {
        console.log(“Listening on port %s…”, server.address().port);
        });

        routes.js

        var express = require(“express”);
        var bodyParser = require(“body-parser”);
        var express = require(‘express’);
        var app = express();
        app.get(“”, function(req, res) {
        var accountMock = {
        “username”: “nraboy”,
        “password”: “1234”,
        “twitter”: “@nraboy”
        }
        return res.send(accountMock);

        });

        The error I’m getting :

        TypeError: object is not a function
        at Object. (/var/www/html/nodeJs/nodeApi/app.js:8:43)
        at Module._compile (module.js:449:26)
        at Object.Module._extensions..js (module.js:467:10)
        at Module.load (module.js:356:32)
        at Function.Module._load (module.js:312:12)
        at Module.runMain (module.js:492:10)
        at process.startup.processNextTick.process._tickCallback (node.js:244:9)
        sotsys-213@sotsys213:/var/www/html/nodeJs/nodeApi$

        • Why are you trying to reinitialize express in both the app.js and routes.js file? This is not what I do in the article. That should be the reason for your problem.

  • Jeremy Davis

    Nice article!

  • Johnathan Amit Kanarek

    Simple indeed.
    I want to recommend on my REST server best practice post: http://restafar.com/create-new-rest-server/

  • Veerapandian Manimuthu

    An easy and understandable read 🙂

  • JR

    Thank you so much for this. Really helpful for someone like me just starting development in restful services

  • Diego Haz

    I’ve recently posted a video about creating and deploying a RESTful API with NodeJS, MongoDB and Express. Hope you like it: https://www.youtube.com/watch?v=6x-ijyG-ack

  • Andrey Kolybelnikov

    Great article! Exactly what I’ve been looking for. I had written some APIs to handle MongoDB requests for User schema but failed to validate the data at the endpoints, so that the app was crashing everytime an undefined data was posted. Thanks to you, its more stable now, but I cannot figure out the condition to check the Id in User.findById. If I send a nonexistent ID in request with Postman, its just not getting any response for ages. I have tried if(!user.params._id) and many other options, but I cant get it right. Any tips for me please?

    • Sounds like a MongoDB issue, something I don’t have any experience in.

      • Andrey Kolybelnikov

        Hi Nic, thanks for the tip though! I started looking in the direction of MongoDB and I think I have found a solution.

  • Peter Phelan

    Ok figured it out, I had the url configured wrong:
    http://localhost:3000/account?username=nraboy

    Returns:
    {“username”:”nraboy”,”password”:”1234″,”twitter”:”@nraboy”}

    Not working:
    URL:
    http://localhost:3000/account=nraboy
    Cannot GET /account=nraboy

    Works:
    URL:
    http://localhost:3000/account
    {“status”:”error”,”message”:”missing username”}

    • In the examples you provided, account is a URL path, not a query parameter.