What does RESTful API really mean?

REST stands for Representational State Transfer. It is an architecture that allows client-server communication through a uniform interface. It is also stateless, cache-able and has a property called idempotence (for most of its verbs), which means that multiple identical requests have the same cumulated side effects as a single request would.

HTTP RESTful APIs are composed of:

  • HTTP methods, e.g. GET, PUT, DELETE, PATCH, POST, …
  • Base URI, e.g. http://localhost:3000
  • URL path, e.g /todos/2/
  • Media type, e.g. html, JSON, XML …

In this article I will show you how to use LoopBack to create a RESTful API. LoopBack is a highly extensible, open-source Node.js framework. For more details on our Node.js experience, you can browse our technology stack. Not a Node.js kind of dev? Then check out our articles on converting between web frameworks and programming languages (part 1 and part 2 – data). With Node.js and LoopBack, you can quickly create dynamic end-to-end REST APIs. That being said, the following example is for a task management (TODO) application.


Understanding the MEAN Stack

Recent years have seen a shift from classical web applications to a Back-End and Front-End segregation, in modern one-page applications. This makes it easier for servers to communicate not only with a web browser, but also with a variety of mobile devices, without having to change one single line of code. One of the most popular approaches is MEAN, a JavaScript stack for building web sites and web applications. MEAN comprises MongoDB, Express, AngularJS and NodeJS.

Throughout this article, I will use three of MEAN’s four components: MongoDb, Node and Express. Node and Express are the foundations upon which LoopBack is built and are bundled here as well. I won’t talk about Angular, but if you are interested, be sure to check out our articles on the topic. You might be interested in validations, charts or complex animations.


Although NodeJS is a JavaScript-based programming language, it runs outside the browser. In fact, we will run our NodeJS code on the server.

To install it, go to NodeJS Website and follow the instructions. Or, alternatively, if you are using Mac and brew, run brew install nodejs  in the console. Ubuntu users can use nvm  to install NodeJS. Either way, if the installation was successful, you can check Node’s and NPM’s installed versions like this:

Make sure you treat any errors and warnings before continuing.


There is a large variety of data storage options available to every programmer. However, in this article I have chosen to use MongoDB, in order to stay true to the MEAN stack.

MongoDB is a document-oriented NoSQL database, so we could say it is Big Data-ready. Mongo stores data in a JSON-like format and allows the user to perform SQL-like queries against it.

You can install MongoDB following the instructions here. If you have a Mac and brew, simply run: brew install mongodb && mongod , while in Ubuntu the command is sudo apt-get -y install mongodb .

Don’t forget to check version, in order to make sure everything is all right:


LoopBack is a highly-extensible, open-source Node.js framework. IBM and the StrongLoop team are committed to maintaining and improving LoopBack as an open-source project. As they put it:

Building on LoopBack’s success as an open-source Node.js framework, IBM API Connect provides the newest tools to use with LoopBack projects. It includes a graphical tool with many of the API composition features of StrongLoop Arc, plus assembly and testing of API Gateway policies using the local Micro Gateway. Some features are still available only in Arc but these will be added to API Connect in the next few months.

API Connect also provides its own command-line tool, integrated with API management and gateway features. A free version of API Connect called API Connect Essentials is available for developers to install, free of charge.

Install it using npm:

Notice the -g  option. It means your strongloop installation will be global. Strongloop will also be added in the PATH, so you can run it from anywhere.

Let’s check version:

For the examples I run in this article, note that I use the version above. The MEAN world is highly dynamic and new versions get cleared and released frequently, so you might have a different one. Please remember that, if reproducing any steps below gives you trouble, it might be a problem of incompatibility between my versions and yours. I recommend you to mimic my library versions for this tutorial, or at least check if your versions are compatible.

Creating the project

If you followed the previous steps, you should have all you need to complete this tutorial. Basically, we are going to build an API that allows users to CRUD (Create-Read-Update-Delete) Todo tasks from the database.

Before starting the project, I need to run MongoDB.

Now that the database is running, I can start creating a RESTful server with LoopBack.

Run the following to create the project:

Here I leave everything blank, so the project is generated in the current folder, with the name “Todos”. Now I will select what kind of project I need:

After the project is created, it’s time to start server:

LoopBack created a user model for the API and all the basic routes needed. If you open a browser and access , you will see something like this:

Screen Shot 2016-04-06 at 13.33.36

The explorer entries are proof of LoopBack creating an API for User objects. Later you will see in more depth how the explorer works. If you add new models in the LoopBack project, the corresponding routes will be created automatically. The explorer interface makes manual testing straightforward, so use it wisely. After I will set up my database and add all the models, I will use this explorer to show you how it works.

MongoDB Connection

LoopBack models connect to backend systems such as databases via data sources that provide create, retrieve, update, and delete (CRUD) functions. Data sources are backed by connectors that implement the data exchange logic using database drivers or other client APIs. In general, applications don’t use connectors directly, rather they go through data sources using the DataSource and PersistedModel APIs.

LoopBack provides connectors for most popular relational and NoSQL databases. These connectors implement create, retrieve, update, and delete operations as a common set of methods of PersistedModel. When you attach a model to a data source backed by one of the database connectors, the model automatically acquires the create, retrieve, update, and delete methods from  PersistedModel.  The data access methods on a persisted model are exposed to REST by default. You can connect models using relations to reflect relationships among data.

Here you can see LoopBack create a RESTful server with all routes for user model. I add a data source and new models, by first stopping the server and then running the following commands:

After I set the name for my data source, I will select a connector. Let’s pick MongoDB connector:

MongoDB connector and all LoopBack connectors will need to be configured after you select them.

Create Models

Remember our “Working with data” article? A LoopBack model represents data in backend systems such as databases, and by default has both Node and REST APIs.  Additionally, you can add functionality such as validation rules and business logic to models.

Every LoopBack application has a set of predefined built-in models such as User, Role, and Application.  You can extend built-in models to suit your application’s needs.

After we hook up the project database (with MongoDB), it is time to create models. This operation is very simple, just like the ones you’ve done so far:

After you create the todos  model, you need to add properties:

Named the first property, then set property type:

You also need to set a flag representing if the property is required or not. Leave the answer blank to stick with defaults (non-required):

Last you need to set a default value, if needed. I don’t want a default value here, so I leave this line blank:

After all these steps, I added in the  todos  model a property with name: name, type: string, required: No, default value: none. For the next three properties, repeat the required steps and set them as such:

To quit the property setter you just need to leave the Property name empty and press Enter:

After all these properties are set, the todos model will look like this:

Here we can see that we don’t need to write code for a schema model, all we need to do is to run some LoopBack commands in the terminal, and LoopBack will do our job! The only code we need to write is code for custom routes or operations. Now we will play a little with this API in the explorer, to see what we can do. I hope you will enjoy this game. Start the server, and you can see loopback again create all the basic routes for the todos model:

Let’s access the explorer to see what happens with this API created with LoopBack:

Screen Shot 2016-04-07 at 18.10.35

Here you can see all the basic routes created by LoopBack without writing any code. Now we will try to use this explorer to test the routes. The first operation I do is to try to create a todo:

Screen Shot 2016-04-08 at 12.36.29

After completing the list of parameters, press “Try it out!” and see what happens:

Screen Shot 2016-04-08 at 12.40.18

In Response Body you can see that our object was created but…. the problem is with the “updated_at” field, because we introduced a string and not an actual object creation date. We will solve this in the file server/models/todos.json. We will need to change this:

Into this:

I changed the default in defaultFn. But… Why ? The answer comes from LoopBack. It has some predefined commands in a json file for cases just like this one. Read about LoopBack predefined commands to find out more details. For now, let’s retry creating our todo and see what happens now:

Screen Shot 2016-04-08 at 13.01.05

This time we get a more satisfying answer.Screen Shot 2016-04-08 at 13.01.42The updated_at  field has the correct value. Now let’s see how to delete an object. The first step is to make a GET request to /todos  :

Screen Shot 2016-04-08 at 13.29.49

After this request we get a response, from which we will take the object’s id:

Screen Shot 2016-04-08 at 13.38.51Take the id from the First TODO and now we need to do a DELETE request to /todos/{id}  in order to get rid of our previous mistake (adding a todo with an erroneous date).

Screen Shot 2016-04-08 at 13.50.25

This is the request and the response for the object I want to delete from the database. We notice the response is ok and the the object was deleted from the database, but we can also check with a new GET request to /todos :

Screen Shot 2016-04-08 at 13.53.26Onlt one todo object in the database (the correct one), and we can also see the erroneous object was deleted. Now our CRUD for todos is done.

Loopback Relations

Individual models are easy to understand and work with. But, in reality, models are often connected or related. When you build a real-world application with multiple models, you’ll typically need to define relations between models.

Now we have a RESTful API with two models: User and Todos. Now we want to add a relation between these two models. This relation will be many-to-one. Like what I did before adding this relation, I will use a loopback command to add this relation to the project:

After I select the model for the relation, I set its type:

Selecting “has one” means that every todo will have one user.

Loopback ACL

The first step in specifying user roles is to determine what roles your application needs. Most applications will have un-authenticated or anonymous users (those who have not logged in) and authenticated users (those who have logged in). Additionally, many applications will have an administrative role that provides broad access rights. Applications can have any number of additional user roles as appropriate.

LoopBack applications access data through models, so controlling access to data means putting restrictions on models; that is, specifying who or what can read and write the data or execute methods on the models. LoopBack access controls are determined by access control lists or ACLs. Setting an ACL for the Todo model is an easy task and we can achieve it through another loopback command.

First we deny all users access to Todos, and afterwards we set some exceptions: users who do have access to the todos:

After we set access control for todos, our todos.json  looks like this:

I will start testing this, by going to the explorer and making a GET request on todos:

Screen Shot 2016-04-08 at 16.15.01

In the response we can see a message that didn’t appear before setting access control for todos. Now, to be able to see the todos, as before, we need to create a user. Make the following request:

Screen Shot 2016-04-08 at 16.28.35Screen Shot 2016-04-08 at 16.29.56

Now we have a user who can create todos. Before you can do that, though, you need to log in with this user:

Screen Shot 2016-04-08 at 16.32.02This login generates an access token which is found in the “id” field. Copy the token and put it in the access token case:

Screen Shot 2016-04-08 at 16.33.45

We can now start playing with todos API:

Screen Shot 2016-04-08 at 16.36.06

The CRUD for todos is working again, but this time you need to be logged in with a user in order to access them.


LoopBack is a NodeJs framework which enables you to write less code, at least compared to the likes of Express and some other frameworks. To use LoopBack it is enough to know how commands work and sometimes write some minimal code, mostly for customising a thing or another. LoopBack will create your basic routes when you add a model into the application. Overall, the idea is to work with terminal commands to effortlessly build an API. This framework is easy to learn and understand. And if you want to have it even easier, try our loopback aliases, for even more concise commands.

If you enjoyed this article please take a moment and share it with your friends: