simplyrest

simplyrest is a REST API Framework based on ExpressJS. simplyrest uses nodeannotations library to provide hassle-free and easy way to expose REST APIs via Annotations.

To Expose a REST API, create a controller class and annotate with the predefined annotations.

Find complete examples in the example folder.

Table Of Contents

• Tutorial
  • Installing simplyrest
  • Configuring simplyrest
  • Creating a Controller
    • Supported HTTP Methods
    • Support for router.param
  • Adding Middlewares
  • Adding Templating Engine
  • Adding Error Handler
  • Starting simplyrest Server
• Examples
• Documentation
  • simplyrest.config(options)
  • simplyrest.use(middleware)
  • simplyrest.errorHandler(handler)
  • simplyrest.listen([, port])

Tutorial

Installing simplyrest

npm install --save simplyrest

Configuring simplyrest

let options = {
    // Put your options here
};

simplyrest.config(options);

Creating a Controller

• Step 1 : Create a file under the [project root]/controllers folder (or the custom configured controllers folder)

• Step 2 : Create a class and Annotate with @Controller

  /**
   * @Controller("/")
   */
  class MyController {
  
  }
  

  NOTE :

  • Annotations should be defined as shown above.
  • URLs should contain trailing slashes and not leading slashes

• Step 3 : Create functions and annotate with supported HTTP Method to expose it as a REST API.

  /**
  * @Controller("/")
  */
  class MyController {
      /**
       * @Get("/")
       */
      rootMethod(req, res, next) {
          res.send("Welcome");
      }
  
      /**
       * @Get("helloWorld/")
       */
      helloWorld(req, res, next) {
          res.send("Hello World");
      }
  }
  

  NOTE :

  • Annotations should be defined as shown above.
  • Method can be named according to choice.
  • simplyrest expects the method signature to be (req, res, next) just like ExpressJS Router Methods.
  • URLs should contain trailing slashes and not leading slashes.

Supported HTTP Methods

• GET : @Get(url)
• POST : @Post(url)
• PUT : @Put(url)
• PATCH : @Patch(url)
• DELETE : @Delete(url)
• HEAD : @Head(url)
• OPTIONS : @Options(url)
• TRACE : @Trace(url)
• CONNECT : @Connect(url)
• ALL : @All(url)

Support for router.param

router.param functionality is supported via @Param(paramName) Annotation.
Example :

/**
 * @Controller("/")
 */
class MyController {
    /**
     * @Get("/printName/:name")
     */
    rootMethod(req, res, next) {
        res.send("Welcome "+req.params.name);
    }

    /**
     * @Param("name")
     */
    paramNameHandler(req, res, next) {
        console.log("Route with Param name called...");

        next();
    }
}

Adding Middlewares

To add a middleware, call the use function with an Express Middleware.

simplyrest.use((req, res, next) => {
    console.log("Middleware called");
});

Adding Templating Engine

Any Templating Engine can be used to render the templates.

• Step 1 : Install the Templating engine
  npm install --save pug
• Step 2 : Configure the view engine by setting viewEngine to pug in the options.

let options = {
    [...]
    "viewEngine": "pug",
    [...]
};

simplyrest.config(options);

Adding Error Handler

To add an error handler, call the errorHandler function with an Express Error Handler.

simplyrest.errorHandler((err, req, res, next) => {
    res.send(err.message);
});

If no error handler is supplied, by default an error handler is attached with the server which will display the error status, error message and error stack. The following error handler is added by default :

(err, req, res, next) => {
    res.status(err.status || 500);

    res.send(`<h1>${err.message}</h1><h2>${err.status}</h2><pre>${err.stack}</pre>`);
};

Starting simplyrest Server

The simplyrest Server can be started by calling the listen function.

The server will listen on port provided via options if no argument is passed while calling listen(). If port is not configured via options, then the server will listen on the default port 3000.

simplyrest.listen();

The server will listen on port provided via argument even when the port is configured via options.

simplyrest.listen(8080);

Examples

Find two complete examples in the examples folder.

Documentation

simplyrest.config(options)

• options <Object>
  • controllersPath : Relative Path to Controllers Folder
    • Type : <string>
    • Default : "/controllers"
  • viewsPath : Relative Path to Views Folder
    • Type : <string>
    • Default : "/views"
  • publicPath : Relative Path to Public Folder
    • Type : <string>
    • Default : "/public"
  • viewEngine : Templating engine to Render the Templates
    • Type : <string>
    • Default : "ejs"
  • port Port on which the server will listen
    • Type : <integer>
    • Default : 3000

simplyrest.use(middleware)

• middleware : Expects an Express Middleware
  • Type : <Function>

simplyrest.errorHandler(handler)

• handler : Expects an Express Error Handler
  • Type : <Function>

simplyrest.listen([, port])

• port : Port on which the server will listen
  • Type : <integer>
  • Optional