RESTFul Web API with Node.js and swagger

It is inevitable that any software application being developed will at some point need to be integrated or have the ability to easily integrated with other software projects. The best way to do that is through APIs, the downside is for a long time there hasnâ€™t been any industry standard for designing and documenting APIs.

In this post, I will discuss a few scenarios and reasons why developers will often need to develop API's and then how we can develop a Simple Web API using node.js and then document that API using Swagger.

https://github.com/garywoodfine/nodeRest

Software development is a complex process requiring more than just writing code

We need to plan and define the base of our application first. This is what is commonly referred to as Solution Architecture. Involving more than just thinking about what you need your application to do, but rather how you intend to structure the application to meet the needs of your users.

Application Layers

Software solutions are broken up into areas and objects of interest, which we call Layers.

Similarly to property development, software development needs to start from a solid foundation. Although software development approach may be slightly different in that you can start developing different areas of the application independently and ultimately wire up the different components of the application at a later date.

Producing feature after feature without actually caring about code quality may work initially, but after a period of time it will start becoming un-maintainable and ultimately slower to continue adding new features and eventually your software development costs just start to become a bottomless pit for money! Typically referred to as brute-force-driven development.

The issue is that software development is nothing more than just building blocks of functionality on top of one another. If the lower layers of our program are poorly designed, then the whole solution will suffer because of this.

Customer Driven Development

A customer may contact you, with a requirement for a new service their company would like to launch and requires a solution based on some very sketchy details and totally unrealistic timescales. Customers also generally expect comprehensive documentation explaining how to make use of the feature.

Budget constraints are always an issue and customers never have the appropriate infrastructure in place to live up to their expectations!

This often works hand in hand, with the perception that Software is a malleable entity, in that you can easily bend and shape it to your needs as required. For the most part that is accurate, however, it is the definition of easy that becomes the sticking point.

Everything is easy once you know how
Janis Joplin

Objective

A vast majority of applications will require some mechanism to store and retrieve data from some sort of Data Repository. This may require some actions to perform on the data, either to transform it to a state it is required or even to break it up into smaller pieces that can be sent/extracted to several different repositories.

Typically this is implemented via a series of services. Modern application stacks these are implemented as RestFul Services. If you're new to developing API's you may want to quickly read through What is a Rest API .

We'll go through the process of developing a Web API making use of node.js and Swagger.

In order to build a RESTful API we need to understand how to ; <

How to specify a web API
How to implement routes
How to test your API
Content negotiation
What is CORS
API Versioning
What is HATEOS ?

Simple node Web Server

Creating a web-server in node is trivial task, and ultimately only involves an initial 8 lines of code

var http = require('http');
 
http.createServer(function (req, res) {
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('Web Api works\n');
}).listen(5000, '127.0.0.1');
 
console.log('Server running at http://127.0.0.1:5000/');

Simple lightweight nodejs webserver

This web server doesn't do much, but it works. Assuming you have saved the code above to a file server.js you can simply run it from the terminal window by navigating to the directory and node server.js .

This is a really simple web server, and it serves as the basis of a typical Web API. However, to make it truly functional and robust requires additional development effort. <

Get your swagger on

We could go through the whole process of painfully developing each layer of our application, but who's got time for that? The customer wants the API today! So we'll go ahead and use the swagger API generator.

When developing API's the key requirement to enable other developers to use your API is to create documentation. We don't want to spend hours writing documentation when we can just generate it and wouldn't it be cool if we could generate a lot of the Grunt work too?

Enter Swagger , a popular open-source framework to help you develop and document RESTful APIs.

You may need to install swagger if you haven't done so already. It's simple just execute the following from the terminal

npm install -g swagger

We can now generate our project

 swagger project create simpleApi

Ensure you select Express when prompted for which framework to use. Once completed, the project directory will looks as follows:

Api - everything related to the API development, the controllers, mocks, helpers.
config - configuration
test - test for controllers and helpers

Swagger Editor

Before we run and inspect the new application, we first need learn about a new tool that has also been installed as part of the Swagger. The Swagger Editor is an elegant browser-based editor which really simplifies developing a web API.

The swagger editor helps with testing your API, by providing you a UI to access your API functionality. It also provides

Validation and endpoint routing
Docs on the fly generation
Easy-to-read Yaml.

We can launch our application and the Swagger UI

swagger project start

Then open a new terminal window navigate to your project directory

swagger project edit

If everything went well the editor should open your browser. On the right side of the page you should notice the example path for a GET request to /hello, so open the tab and, at the bottom, click on the button try this operation.

Take some time to explore the yaml

x-swagger-router-controller: This is the controller, the file we have in the /api/controllers/hello_world.js.

The HTTP methods are listed.

operationId: This refers to the function, in the controller, in charge of the business logic.

parameters: The list of required parameters are defined here. The parameter name is the only one and you may see that it is in the path, it is not required and it is a string.

Responses

Swagger shows its potential:

You can define a different response for each situation, given the HTTP status or errors, a particular response can be defined.

In the example, for the status, 200there is a pointer $ref to a response definition while for other statuses, we go to default with its own $ref.
In order to keep the yaml file clean, we can define all our response under definitions while at the same time reusing the definition for different responses.

Controllers

Examine the /api/controllers/hello_world.js controller, just to get familiar with thte coding style. You'll notice that code pattern follows the JavaScript Module Pattern

I have removed the comments for brevity so we can focus solely on the generated code. I recommend go through the comments as they actually do provide some additional information. Unlike most comments, I have encountered in code bases!

'use strict';
 
var util = require('util');
 
 
module.exports = {
  hello: hello
};
 
function hello(req, res) {
 
  var name = req.swagger.params.name.value || 'stranger';
  var hello = util.format('Hello, %s!', name);
  res.json(hello);
}

At first glance, there is nothing too complicated here. However, I just wanted to point out the req object (Request) has a new property available, which is not typical of the native request object, it has a swagger property. The swagger property will enable access to any prperties that have been defined i.e. Parameters.

Working with Mocks

During the course of your development, you may not necessarily want to access the database or whatever data repository. Ideally, you want things to be quick and have the ability to create certain data conditions you want to develop against. This is where working with Mock objects comes into its own.

Swagger makes working with Mocks really easy. You don't even have to create your Mock objects using the code, its simply just a matter of editing your yaml file in the swagger editor.

In order to edit the Mocks. We need to start the application again. However, this time we are going to instruct it to make use of the mocks

 swagger project start -m

adding the flag -m to the command start Swagger in mock mode. We now need to open the second terminal window and start the editor again.

swagger project edit

Create New Mock

We now want to create our new Mock for our sample application. In our example, we want to return a list of coffee cafe's that exist in a geographical area. To start off with we will keep it really simple and just return a full list of cafe's.

To Do this, in your Swagger Editor just Delete contents. Now we will add our own Methods

`GET /cafe`

swagger: "2.0"
info:
  version: "0.0.1"
  title: Get Coffee Cafe
# during dev, should point to your local machine
host: localhost:10010
# basePath prefixes all resource paths 
basePath: /
# 
schemes:
  # tip: remove http to make production-grade
  - http
  - https
# format of bodies a client can send (Content-Type)
consumes:
  - application/json
# format of the responses to the client (Accepts)
produces:
  - application/json
paths:
  /cafe:
    # binds a127 app logic to a route
    x-swagger-router-controller: cafe
    get:
      description: get a cafe list
      # used as the method name of the controller
      operationId: index
      responses:
        "200":
          description: Success
          schema:
            # a pointer to a definition
            $ref: "#/definitions/GetCafeListResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

Lines 1 - 19 just supply additional pre-amble information about your API declaration. Explicitly detailing how the API is developed using Swagger and the expected return types etc.
You could omit this information, as it may not be strictly necessary, but it is best practice to add it.

Lines 20 - 35 , actually start defining our API. We are defining a cafe controller with one Get method . At this stage we are not defining any additional parameters. We also define a Response which is going to comprise of a GetCafeListResponse, also if there is a failure we will aim to provide an error response.

Now lets go ahead and define our Response.

definitions:
  GetCafeListResponse:
    required:
      - cafes
    properties:
      cafes:
        type: array
        items:
          $ref: "#/definitions/Cafe" 
 
  Cafe:
       required:
          - name
          - description 
       properties:
        name:
          type: string
          description: Cafe name
        description: 
          type: string
          description: Brief description of the cafe
  ErrorResponse:
      required:
      - message
      properties:
       message:
        type: string

In the example, we defined an operationId, which contains the Method on the controller action which will be used to service the request. If we attempt to send a request we'll just get a sample response.

`POST /cafe`

Create a method to enable adding a new cafe to the list.

post:
      description: add a new cafe to the list
      operationId: create
      parameters: 
         - name: cafe
           in: body
           required: true
           description: New cafe details to add
           schema:
               $ref:  "#/definitions/CafeBody"
      responses:
        "200":
          description: Successfully saved new cafe
          schema:
            $ref: "#/definitions/CafeBody"
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

Advice

You do not need to use the Swagger Editor to edit your .yaml
You can use any text-based editor just navigate to (project folder)/api/swagger/swagger.yaml

You would continue to do so for all the methods you want to define. All code is available on Github

Start the Coding

We'll go ahead now and implement the logic for our system. The back-end for this system is going to be MongoDB. So we'll need to take care of some pre-requisites.

One of the pre-requisites is to ensure MongoDB is installed. You can make use of either the Docker Images or ll-mongodb-ubuntu-14-04/" target="_blank" rel="noopener noreferrer"> install MongoDb on your ubuntu desktop .

We also need to install mongoose and lodash into our project

npm install mongoose 
npm install lodash

We also need to update our app.js

'use strict';
 
var SwaggerExpress = require('swagger-express-mw');
var app = require('express')();
var mongoose = require('mongoose');
var bluebird = require('bluebird');
 
module.exports = app; // for testing
 
var config = {
  appRoot: __dirname // required config
};
 
SwaggerExpress.create(config, function(err, swaggerExpress) {
  if (err) { throw err; }
 
  // install middleware
  swaggerExpress.register(app);
  var port = process.env.PORT || 10010;
  mongoose.Promise = bluebird;
  mongoose.connect('mongodb://localhost/cafelist');
  mongoose.connection.on('error', console.error.bind(console, 'connection error:'));
  mongoose.connection.once('open', function(){
     
      app.listen(port);
  });
  if (swaggerExpress.runner.swagger.paths['/cafe']) {
    console.log('try this:\ncurl http://127.0.0.1:' + port + '/cafe');
  }
});

The only thing really worth explaining in the code above, is that Mongoose no longer has a default promises library so we will configure Mongoose to use bluebird.

If not installed simply : npm install bluebird

We also need to add some Models so we need to create a new folder called models and add a new file cafe.js

var mongoose = require('mongoose');
mongoose.Promise = global.Promise;
module.exports = mongoose.model('Cafe', new mongoose.Schema({
    name: String,
    description: String
}));

Implement Controller Methods

We're now able to complete the controller logic in the cafe.js

'use strict';
 
var Cafe = require('../models/cafe');
 
module.exports ={
index: function(req,res){
    Cafe.find({"name":{$ne:null}}, function(err,cafes){
        if(err){
            res.status(500).json(err).end();
            return;
        }
 
        res.json({
            cafes : cafes
        }).end();
    });
},
 
    create: function(req,res){
 
        var cafe = new Cafe(req.swagger.params.cafe.value.cafe);
        cafe.save(function(err){
            if(err){
                res.status(500).json(err).end();
                return;
            }
 
            res.json({
                cafe: cafe
            }).end();
        })
    }
}

Summary

Swagger helps to develop a robust RESTful API while at the same time providing an elegant documentation that can boost up cooperation among developers.

Taken the approach of Documenting as you go, helps you to focus on what you're developing.

About
Latest Posts

Gary Woodfine

Technical Director at threenine.co.uk

Gary is Technical Director at threenine.co.uk, an independent software vendor specialising in IoT, Field Service and associated managed services,enabling customers to be efficient, productive, secure and scale-able.