DEV Community: Filipe Domingues

Learning Node.js building a simple Express API - Part II

Filipe Domingues — Wed, 23 Aug 2017 19:52:53 +0000

Hi again!
Before we start I would like to say a big thank you for all the feedback on the first Part hope you like this one too. You can read the first part here and the solution for all the parts on my github @FilipeDominguesGit.

On this part I'll focus mainly on routes, the REST architecture and how to take advantage of it on an Express project. I wont focus too much on each route logic for now, so keep in mind that there will be some bugs and missing validations. We will be using an in memory Mock Database for now and on the next part we will start using MongoDB since all of you voted for it.

REST

So before we start hacking lets talk a bit about REST and some basic principles we will use on our project. I won't go into too much details here so feel free to post some questions on the comments.

REST (Representational State Transfer) is an Architectural style defined by Roy Fielding in his 2000 PhD dissertation. This architecture is not restricted to HTTP but it is commonly associated with it. An HTTP web service that implements a REST architecture is called a RESTful web service.
Having this in mind lets talk about some principle and architectural constraints of a RESTful service.

Resource-based

REST is a resource-based architecture, that in contrast with the classic RCP web services, focus on the resources instead of the actions. For example:

RPC API (verbs)	REST API (nouns)
www.example.com/api/createUser	www.example.com/api/Users
www.example.com/api/getTodos	www.example.com/api/Todos

Every resource should have an identifier so it can be accessed by its URI. For example:
www.example.com/api/todos/1
www.example.com/api/users/1337

Uniform interface

Using HTTP protocol as our server-client communication interface makes our architecture decoupled and simplified.
On the API requests we should use HTTP verbs to give them meaning. For example:

GET - Read a specific resource or a collection of resources.
PUT - Update a specific resource or a collection of resources. Can also be used to create a resource if the resource identifier is known.
DELETE - Delete a resource by an identifier.
POST - Create a new resource and used for operations that don't fit into the other verbs.

On our API responses we should always use the correct HTTP status codes. The most commonly used are:

2xx for Success responses.
4xx for Request errors ( Unauthenticated request, missing parameter, requested resource not found, etc..)
5xx for Server Errors.

Communicate statelessly

The requests should have enough information that the server should be able to process it without needing to keep state. If you need to keep any kind of state save it on the client side or as a server side resource. This will make it easier to scale and this way changes on the Server side will not affect the client.

Multiple representations

Your resource should be independent of their representations therefore you should be able to provide multiple representations of the same resource (xml,json,csv,etc..). Using the HTTP Headers Accept and Content-Type we can easily do this. This mechanism is defined on HTTP RFC and its called Content Negotiation.

Link resources

You can and should link your resources with its sub-resources and possible actions. It facilitates the way the client can navigate and discovers your API. This is known as Hypermedia as the Engine of Application State or HATEOAS. For example:

{
  "content": [{
    "amout": "500",
    "orderId": "123",
    "_links":{
      "_rel": "self",
      "href": "/orders/123"
    }
  }],
  "_links": [{
    "_rel": "order.product",
    "href": "/products/1"
  }]
}

I will leave HATEOASfor a future blog post so don't worry too much about it for now.

Keep in mind that this is a very simplified definition of REST but should get you started and help you through this article. Now lets start coding our routes!

Routes

Lets start by creating a new directory on the project src called routes and a home.js file. On this file we will define the handler for our home route like this :

// src/routes/home.js

const express = require('express');

// create router
const router = express.Router();

// GET http://localhost:3001/ 
router.get('/',(req,res) => {
  res.send('Hello Dev.to!');
});

module.exports = router;

Nothing very fancy here right? We are just creating a router object that will manage our routes and adding an handler for the GET / request.

The arrow function notation can be a bit tricky if you are new to it. To make this a bit clearer :

const getHandler = function(request,response){
  response.send('Hello Dev.to!');
};

router.get('/',getHandler);

Now to add this route to our Api lets first create an index.js file on our routes directory and add the following code:

// src/routes/index.js

const express = require('express');
const router = express.Router();

const homeRoute = require('./home');

router.use('/', homeRoute);

module.exports = router;

We will use this index.js file to make importing other routes easy and clean.

Ok now we are just missing one step. On the app.js file we need to import our routes and add them to our express server.

// src/app.js

...

const routes = require('./routes'); 
app.use(routes);

...

Now lets test this! Just start the server typing npm start on the command line and open your browser on http://localhost:3001/.
If all went well you should see the message Hello Dev.to! on your browser!

Now that we know how to setup routes lets start implementing our todos route. Create an api directory on src/routes and add a todos.js file.

Lets start with listing all our todo items.

// src/routes/api/todos.js

const express = require('express');
const router = express.Router();

const inMemoryTodoDB = [
    {id:0,name:'Part I',description:'Write Part I', done:true},
    {id:1,name:'Part II',description:'Write Part II', done:false}
];

router.get('/',(req,res)=>{
  res.status(200)
    .json(inMemoryTodoDB);
});


module.exports = router;

So here we have our in memory mock Database inMemoryTodoDB and the GET handler for /api/todos/ request. The only difference this time is on our response, we are now sending a 200 http status code response indicating success and the todos list as a json object.
Easy right?

Lets add this route to the src\routes\index.js file so we can test it.

// src/routes/index.js
...
  const homeRoute = require('./home');
  const todosRoute = require('./api/todos');

  router.use('/', homeRoute);
  router.use('/api/todos', todosRoute);
...

Pretty straight forward and clean.
We can now test the route we have just created by starting the server as usual and open the browser on http://localhost:3001/api/todos. You should see a json object with all the todo items.
Now lets add a route so we can get a specific todo item! Lets add the GET /api/todos/:id route.

// src/routes/api/todos.js

router.get('/:id',(req,res)=>{

  const { id } = req.params;

  const todoItem = inMemoryTodoDB.filter((todo)=> todo.id==id)[0];

  if(!todoItem){
    res.sendStatus(404);
  }
  else{
    res.status(200).json(todoItem);
  }
});

As you can see now we are passing the id on the uri. We can access this on the req.params object. I've used a bit of Object destructuringhere to make it cleaner .

// this:
const { id } = req.params;
// is the same as this:
const id = req.params.id;

I will probably do a post about destructuring in javascript one the next few days.
Now that we have the id we will try to find it on our Mock DB using Array.filter. (If you have any doubts about filter just let me know on the comments.)
This time our response will depend on if we find the item or not. If we find the todo item we can just send it back as a json object and a 200 status code like we did before. If we don't find a item with the given id we're going to send a 404 Not Found.

Now that we can list all todo items and get a specific todo item, lets create one!

// src/routes/api/todos.js

router.post('/',(req,res)=>{

  const { name,description,done } = req.body;

  // getting last used id from our Mock DB 
  const lastId = inMemoryTodoDB[inMemoryTodoDB.length-1].id;
  const id = lastId + 1;

  const newTodo = { id,name,description,done };

  inMemoryTodoDB.push(newTodo);

  res.status(201)
    .location(`/api/todos/${id}`)
    .json(newTodo);

});

So we have a lot of new things here!
We are now using POST instead of GET which allow us to send data on the request's body.
This time I'm getting the information we need to create a new todo from the request's body (req.body) instead of the req.params.
Now on the response we send a HTTP Status code 201 created indicating we have created a new resource with success, we add the location Header with the new resource endpoint and lastly we return the new resource as Json object.

Now before we can test this route we need to add one Express middleware that will parse the requests bodies and make it available under the req.body property.
Lets first install the dependency:

npm i body-parser --save

and on src\app.js and add it like this:

// src/app.js

const express = require('express');

// Import body-parser
const bodyParser = require('body-parser');

const port = process.env.PORT ||  3001;

const app = express();
// add body-parser middleware
app.use(bodyParser.json());
...

You can now start the server and test it using Postman or with Curl like this:

curl -XPOST -H "Content-type: application/json" -d '{"name":"todo 3","description":"description here 3", "done":false}' 'http://localhost:3001/api/todos/'

Nice, we can now add new todo tasks!

Now lets add our delete route:

// src/routes/api/todos.js
router.delete('/:id',(req,res)=>{

  const {id} = req.params;

  const todoItem = inMemoryTodoDB.filter((todo)=> todo.id==id)[0];

  if(!todoItem)
  {
    res.sendStatus(404);
    return;
  }
  inMemoryTodoDB.splice(inMemoryTodoDB.indexOf((todo)=>todo.id==id),1);

  res.sendStatus(200);

});

Nothing new here we are just removing the todo if we find it or returning a 404 Not Found if we don't. Let me know if you have any doubts on this route.

Now lets add a route to set our todo task as done or not done:

router.put('/:id/done',(req,res)=>{

  let  { done }  = req.body;
  const {id} = req.params;

  // check if its a boolean 
  if(typeof(done) != 'boolean' )
  {
    res.sendStatus(400);
    return;
  }

  const exists = inMemoryTodoDB.filter((todo)=> todo.id==id).length > 0;    

  if(!exists){
    res.sendStatus(404);
    return;
  }

  inMemoryTodoDB.map((todo)=>{
    if(todo.id == id) {
      todo.done = done;
    }
  });

  res.sendStatus(200);
});

The only think different here is the boolean type checking on the input here:

  if(typeof(done) != 'boolean' )
  {
    res.sendStatus(400);
    return;
  }

If the client sends a non boolean we are replying with a 400 Bad Request indicating that there is something wrong with the request. If the input is valid and we can find a todo with the given id we just update its value and reply with a 200 OK.

Summary

So what have we learned today?

Basic REST principles
How to setup basic routes
How to use HTTP verbs to give meaning to our Requests
How to use HTTP status codes to indicate status of our responses

And our API looks like this:

Verb	Route
GET	api/todos	Lists all the todos collection
GET	api/todos/:id	Returns a representation of the todo task with given `:id`
POST	api/todos	Adds a new todo to the collection
PUT	api/todos/:id/done	Updates the `done` property value of the todo task with given `:id`
DELETE	api/todos/:id	Deletes the todo task with given `:id`

I left content negotiation, hypermedia and versioning out of this part because I would like to go into this topics with a bit more detail.

This will be it for today. On the next part I will start implementing our Database module so if you want you can start installing MongoDB. You can check my solution for this part on my Github repository @FilipeDominguesGit.

Feel free to leave some feedback or suggestions! I'm still new to blog posting so all help is welcome!

Learning Node.js building a simple Express API - Part I

Filipe Domingues — Tue, 08 Aug 2017 20:39:23 +0000

Hi dev.to! I've been learning Node.js on my free time and I thought this would be a good place to share my experience and maybe help some of you.

We will build a simple Todo REST API and along the way I'll try to cover some additional software development topics like unit testing, Authentication, continuous delivery / continuous integration, etc.

I will try to do everything step by step so you can all do it without much difficulty. This part will probably be a bit boring for those of you that already have some node.js or javascript experience.

Before we start hacking lets setup our development environment.

Environment

Lets starts with as little as we can and add things as we need it.

Node.Js

I'll be using the latest Node.Js version ( 8.2.1 ) if you don't have it already you can get it here.

IDE - Visual Studio Code

I'll be using Visual Studio code(VSCode) with some basic extensions but feel free to use the IDE you are most confortable with.
You can get VSCode here.

Project structure

I'll be adapting the project structure as we go but for now lets start really basic.

As you can see nothing extraordinary here.
A docs directory so we can add any kind of documentation, a src directory where we'll put all our source code and finally our tests directory.

Lets get to the good stuff!

Ok, now that we have a nice setup lets get the show started.

npm

Npm is a javascript package manager. It comes with Node.js installation and we will use it to manager our project dependencies. You can find more information on npm here

Lets start by opening the command line on the root directory of the project and typing:


npm init

It will ask you some questions, if you don't know what to answer just press enter for now. At the end you'll get a package.json file that will look something like this:

{
  "name": "fd-node-todo-api",
  "version": "1.0.0",
  "description": "expressjs todo API for dev.to",
  "main": "index.js",
  "directories": {
    "doc": "docs",
    "test": "tests"
  },
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

Eslint

We will use Eslint as our linting tool. Lets add our first development dependency to the project! On the command line type:

npm install eslint --save-dev

Easy as that. When it finishes your package.json file will have our first dependency. It will look like this:

//...
"devDependencies": {
    "eslint": "^4.4.1"
  }
//...

Now we can setup our linting rules. On the command line type:

eslint --init

You can pick some popular style guide or configure it as you like. It will create a .eslintrc.js file with your rules. I'll post mine if you want to you it:

module.exports = {
    "env": {
        "es6": true,
        "node": true
    },
    "extends": "eslint:recommended",
    "rules": {
        "no-console":0,
        "indent": [
            "error",
            2
        ],
        "linebreak-style": [
            "error",
            "unix"
        ],
        "quotes": [
            "error",
            "single"
        ],
        "semi": [
            "error",
            "always"
        ]
    }
};

( yeah im a #2spaces and #allwaysUseSemiCollons programmer, don't hate me. )

If you are using VSCode i strongly recommend the Eslint extension. It integrates eslint into vscode perfectly and helps a lot with its auto fix on save option. If you need more help on this just let me know.

Express

Express is a web application framework for Node.js and we'll be using it to server our API.

Lets start by adding the dependency:

npm install express --save

This will add Express to our dependencies on package.json file.

 "dependencies": {
    "express": "^4.15.4"
  }

Notice that we've used --save and not --save-dev. This will add the dependency as a required dependency for our application to run, using --save-dev on the other hand will save it as development dependency only.

Lets create our entry point. Create a app.js file on our src directory and start importing our first dependency.

const express = require('express');

Easy right? Now lets create our server and start it up:

const app = express();


app.listen(port,  function() {
  console.log(`Express server listening on port 3001`);
});

You can add a variable to setup the connection port so you can easily change it and configure it.

In the end you should have something similar to this:

// Dependencies
const express = require('express');

// configs
const port = process.env.PORT ||  3001;

// ExpressJs Setup
const app = express();


// Starting up the server
app.listen(port,  function() {
  console.log(`Express server listening on port ${port}`);
});

module.exports = app;

Now on our package.json file lets add our start script to get our server up and running. Add this to the scripts :

"scripts": {
    "start": "node src/app.js"
  }

Lets try to run the script. On the command line type:

npm start

If you see something like this

Express server listening on port 3001

Good job!! you've made it! You've completed the 1st part of our journey!

If you want to check my solution for this part you can check it on my github @FilipeDominguesGit.

On the next part we will add our first routes and probably talk a bit about REST APIs in general.

Meanwhile you can help me decide what database you want to see on this project, MongoDb or PostgreSQL?

Hope you liked the 1st part! If you have any question or suggestion leave me a comment and i'll get back to you as soon as possible.

Hi, I'm Filipe Domingues

Filipe Domingues — Wed, 02 Aug 2017 21:30:47 +0000

I've been coding for 4 years.
I live in Porto, Portugal.
You can find me on GitHub as FilipeDominguesGit
I work for bitmaker-software
I mostly program in C#.
I am currently learning more about NodeJS and Elixir.

Nice to meet you.