restrap v1.3.2

restrap

Restrap is a modular blueprint built on top of Restify. It's primary purpose is to bring structure and organization when writing a REST API server.

Install

Install Starter App

Restrap comes with a cli for quickly building new apps. You can install globally by using:

$ sudo npm install restrap -g

Next, create a new app directory and install the base structure:

$ mkdir myapp && cd myapp
$ restrap

Start your app by running the following, and navigate to 127.0.0.1:9000.

$ node service.js

Install as a Module

You can install restrap as a local module to an existing project:

$ npm install restrap --save

Core

Restrap has six major components.

Modules

Modules are exported functions that have been mapped to a single HTTP request. They are attached with routes to public facing end-points. Modules serve, more or less, as your apps controller layer. Their scope contains:

• self.library() for full access to your custom libraries.
• self.config for access to your static configuration exports.
• self.success() to respond to a successful request.
• self.error() to respond to a failed request.

By default, modules live in ./module/ and can be grouped and nested to your liking.

Example

module.exports = function(self){

  // Access built-in custom libraries.
  // self.library('user');

  // Access request params.
  // self.param.foo

  // Return a 200 OK response.
  // return self.success(@mixed)

  // Return an error response.
  // return self.error(@mixed)

  return self.success();

};

Modules via CLI

Modules can also be called via the cli without being bound to a public route. For example, from service.js:

app.call('foo', '/user/read').then(function(res){
  console.log('Nice');
});

To execute via cli, run:

$ node service.js --use=foo

This enables you to write modules for private use or cron jobs the same way you write public routes.

Libraries

Libraries are custom helper functions that are made available throughout your app. You can use libraries to write database abstractions, utility functions, user management, etc.

Note: All libraries return a function, which in turn provides an invoked construct of the library. When libraries are injected into module functions, the parent function is called, returning a unique instance of the library for each request. Due to the way in which Node caches the require() method, this ensures complete isolation if each library, per request.

By default, libraries live in ./library/ and are registered with restrap like so:

app.library(['user', 'db', 'foo']);

Example

var user = function(self){
  return this;
};

user.prototype.read = function(){

};

module.exports = function(self){
  return new user(self);
};

One-Way Interdependency

You can import libraries to other libraries using self.library like so:

self.foo = self.library('foo') // unique instance of foo

This is useful for including common libraries such as a db layer or utility functions.

Routes

Routes are registered available HTTP requests, which map a public end-point to a module. Routes are also responsible for running any attached validations before executing the module.

Routes are created like so, with [@http_method, @public_route, @module_path].

app.route('get', '/user', '/user/read').validate(['user']);

Configuration

The config file accomplishes two things. It provides restrap with a few core configurations needed, and provides your libraries and modules with access to a static configuration file.

Your config file is registered with restrap like so:

app.config('./config');

Example

module.exports = {

  server: {
    port: 9000,
    cors: {
      'origins': (['*'])
    }
  },

  path: {
    lib: 'library',
    mod: 'module'
  }

};

Validations

Validations are functions that are registered and attached to any route. For example, you can write a user validation function that checks an incoming token and then allows / denies access to a module, based on the success of the validation.

Validations are provided with the following:

• self.library() for full access to your custom libraries.
• self.config for access to your static configuration exports.
• self.success() to respond to a successful request.
• self.error() to respond to a failed request.

After a successful validation, you can then inject a response object into a the module as a route param, like so:

Example

app.validate('user', function(self){

  var user = self.library('user');
  var uid  = user.token(self.param.user_token);

  if(uid){
    return self.success(uid);
  }
  else {
    return self.error('Invalid user token.');
  }

});

Service

Your main service.js file is the core of your app. It's where you register libraries, create new routes, and attach new validations.

var restrap = require('restrap');
var app     = restrap();

// Point to your local restrap configuration file.
app.config('./config');

// Import custom libraries from ./lib
app.library(['user']);

// Define a validation method required for certain requests.
app.validate('user', function(self){

  var user = self.library('user');
  var uid  = user.token(self.param.user_token);

  if(uid){
    return self.success(uid);
  }
  else {
    return self.error('Invalid user token.');
  }
});

// Define a set of routes (@type, @uri, @module)
// Chain array of validations to the route.

app.route('get',  '/user', '/user/read').validate(['user']);
app.route('post', '/user', '/user/create');
app.route('put',  '/user', '/user/update').validate(['user']);
app.route('del',  '/user', '/user/remove').validate(['user']);

// Start up the app.
app.listen();