basyt

minimalist package to create JSON API server. Typical scenario to use basyt is when you need a rest-like JSON API that provides create/read/update/delete/query actions for your data entities.

Installation

$ npm install basyt
$ npm install basyt-mongodb-collection

Features

• is an extension over awesome nodejs framework expressjs
• generates CRUDL API and routing based on entities and controllers located in corresponding folders at the startup
• provides json web token based authentication
• provides redis based notification for entity updates
• provides user management and role based access control

Please review test folder, there you will find a sample web application exposing test_entity and test_relation entities.

Quick Start

To utilize basyt as foundation of your API, you need several declarations. Firstly basyt needs global APP_CONFIG object.

GLOBAL.APP_CONFIG = {
    base_folder: __dirname + '/',
    //base_folder definition is required, you probably will keep this line as it is

    package_file: GLOBAL.APP_CONFIG.base_folder + 'package.json',
    //path for package.json file. basyt uses package.json to get application name and version.
    //when not defined package_file is set to base_folder + 'package.json'

    basyt: { //scope for basyt related configuration
        port: 5850,
        //port number that basyt HTTP server will listen
        entity_path: '/',
        //url base path for entity API endpoints. default is '/'
        //if it is set to 'foo' then base address for entity is http://hostname/foo/entity
        entities_folder: GLOBAL.APP_CONFIG.base_folder + 'entities',
        //path for folder that contains entity definitions.
        //when not defined, entities_folder is set to base_folder + 'entities'
        controllers_folder: GLOBAL.APP_CONFIG.base_folder + 'controllers',
        //path for folder that contains entity-free controller definitions.
        //when not defined, controllers_folder is set to base_folder + 'controllers'
        enable_ws: true,
        //enables socket.io based websocket. default true
        enable_cors: true,
        //enables CORS setup. default false
        enable_auth: true,
        //enables user management and authentication. default true
        cors: {
          //CORS headers to be setup. Required only when enable_cors is true
          //following values can be set for CORS setup.
          //Content_Type header field is allowed by default
          //Authorization header is allowed when auth is enabled
            origin: 'http://localhost:8580',
            methods: 'GET,PUT,POST,DELETE',
            headers: ['accept']
        },
        auth: {
          //required when enable_auth is true.
            secret_key: 'your.secret.key',
            //key to be used for generating json web token
            method: 'jwt'
            //currently only supported method is jwt
        }
        disable_discovery: false,
        //when discovery is enabled, GET request to server's base address will provide all possible API
    },
    mongodb: { //scope for mongodb collection configuration
        connection: 'mongodb://localhost/basyt_db'
    }
};

after declaring global APP_CONFIG, you simply instantiate basyt

var basyt = require('basyt');
var basytApp = basyt();

basyt explores entities and controllers in corresponding folders and generates API endpoints. In entities folder, entity declarations are like in the following example

module.exports = {
    collection: { //collection is database aspect of entity
        storage: "mongodb",
        //currently the only storage option is mongodb. it is used to select collection
        name: "test_entity",
        //name of entity, used for url path and as collection name
        strict: true,
        //when collection is NOT strict, it accepts attributes that are not defined in attributes list
        attributes: { //list of the attributes of entity
            //following attributes are given as example
            name: {type: "string", required: true},
            email: "email",
            url: "url",
            telephone: {
                type: "numeric",
                minLength: 7,
                maxLength: 11
            }
        },
        event_channels: ['{{obj.email}}:test_entity'],
        //basyt emits redis event for entity updates.
        //By default, it emits entity:{{entity name}}:{{object id}} event
        //for additional events event_channels list is used.
        methods: {
          //list of collection methods
          //here hook functions for entity can be defined. for instance beforeCreate, afterCreate etc.
          //see basyt-base-collection/index.js hook functions for complete hook functions and their
          //signature
        }
    },
    auth_levels: {
      //authentication levels for API actions for entity. Default authentication level is 'USER'
      'read': 'USER',
      'list': 'USER',
      'update': 'USER',
      'update_bulk': 'USER',
      'query': 'USER',
      'create': 'USER',
      'create_bulk': 'USER',
      'delete': 'USER',
      'delete_bulk': 'USER'
    },
    //you can disable/enable any API action for entity.
    disable_read: false,
    disable_list: false,
    disable_update: false,
    disable_delete_bulk: true,
    disable_create_bulk: true,
    disable_update_bulk: true,
    customActions: {
      //here you can define any other actions for the entity
      test: {
        path: '/:entity_id/test',
        //url path that action will bind to
        method: 'put',
        //HTTP method for the action
        auth_level: 'ADMIN',
        //Authentication level for the action
        action: function custom_action(req, res) {
          //action function
          return res.json({success: true});
        }
      }
    }
};

In controllers folder, entity-free controllers are declared. Those controller files include definitions similar to customActions field of entity declarations.

module.exports = {
    example_action: {
      path: '/example_action',
      //url path that action will bind to
      method: 'GET',
      //HTTP method for the action
      auth_level: 'USER',
      //Authentication level for the action
      action: function example_action(req, res) {
        //action function
        return res.json({success: true});
      }
    }
  };

For a controller file named test\_controller.js with content given above, there will be an api for address http://hostname/test_controller/example_action.

That's all for a quick start. Wiki pages are coming soon!

Why do we call it basyt

In Turkish basit means simple. That is the motivation: an extension over expressjs to make things simpler. Since our company's initials are YT, we decided to call the project basyt, simple web package from Yonca Teknoloji.