Skip to content

Latest commit

 

History

History
232 lines (181 loc) · 7.4 KB

README.md

File metadata and controls

232 lines (181 loc) · 7.4 KB
Raw

Logo GitHub license npm version GitHub stars

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 examples folder.

Table Of Contents

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
    • publicPath : Relative Path to Public Folder
    • viewEngine : Templating engine to Render the Templates
    • port Port on which the server will listen

simplyrest.use(middleware)

  • middleware : Expects an Express Middleware

simplyrest.errorHandler(handler)

  • handler : Expects an Express Error Handler

simplyrest.listen([, port])

  • port : Port on which the server will listen