chrisenytc/demi: A wonderful API framework for node.js

#Demi.js

An wonderful API framework for node.js

Getting Started

1º Clone demi repo

git clone https://github.com/enytc/demi.git

2º Enter in demi directory

cd demi

3º Install dependencies

npm install

4º Configure the settings in api/config

5º Run demi

npm start

Test your demi app

npm test

Using Yeoman Generator

Install Demi.js generator

npm install -g generator-demi

Run Demi.js

yo demi

Learn to use the Demi.js generator

For more informations access this links.

NPM: npm link Repository: generator-demi

Documentation

Overview

Demi.js can work with HTTP or HTTPS. You can simply switch the settings in your enviroment.

INFO To use htps you need to generate or have a key and a certificate. e.g: cert.pem and key.pem

You can rename the files in api/config/<env>/ssl.json.

How to generate a ssl cert

How to generate a ssl cert with pem

Example:

Edit: api/config/<env>/app.json

{
  "https": true
}

Params to Demi.js constructor

Parameter: version Type: String Example: v1

Parameter: options Type: Object Example:

{
 http: {
  port: 80,
  options: {}
  },
 https: {
  port: 403,
  options: {}
  }
}

options are options that can be passed optionally to connect to database using mongoose.

Versioning

You can make many versions of your API. Every new instance of the API you can pass a string with the version and it will start this instance.

Example:

var demi = require('./lib/demi.js');
var api1 = api('v1');
var api2 = api('v2');

All requests must be made using the routes /v1 and /v2

Controllers

How to use controllers

There are two kinds of controllers, each with a different purpose and operation.

Default Controller

The default controller is the model used to define routes based on `controller/action'

Conventions:

The file name and the methods will be used on the route. e.g: tasks.js => / or tasks/tasks/index
The default method always has to be the index
If you want to override the route use the option: path:'/newcustomroute/test '
Routes can optionally have a .json extension or without the extension. e.g: /tasks/all.json or /tasks/all
All models can be found at: global.models. e.g: global.models.Task
All configurations can be found at: global.configs. e.g: global.configs.app

Example:


var Model = global.models.Model;

module.exports = {

 /*
  * GET /
  */

 index: {
  method: 'GET',
  path: '/newcustomroute',
  fn: function (req, res) {
   res.jsonpp(200, {
    message: 'Request received successfully!'
   });
  }
 }
};

Restful Controller

The restful controller is responsible for providing restful routes following the model of restful applications.

Example:

module.exports = {

  /*
   * GET /tasks
   */

  index: function (req, res) {
    res.jsonpp(200, {
      welcome: 'Welcome to Demi API'
    });
  },

  /*
   * GET /tasks/new
   */

  new: function (req, res) {
    res.jsonp(200, {
      welcome: 'Welcome to Demi API'
    });
  },

  /*
   * POST /tasks
   */

  create: function (req, res) {
    res.jsonp(200, {
      welcome: 'Welcome to Demi API'
    });
  },

  /*
   * GET /tasks/:task
   */

  show: function (req, res) {
    res.jsonp(200, {
      welcome: 'Welcome to Demi API'
    });
  },

  /*
   * GET /tasks/:task/edit
   */

  edit: function (req, res) {
    res.jsonp(200, {
      welcome: 'Welcome to Demi API'
    });
  },

  /*
   * PUT /tasks/:task
   */

  update: function (req, res) {
    res.jsonp(200, {
      welcome: 'Welcome to Demi API'
    });
  },

  /*
   * DELETE /tasks/:task
   */

  destroy: function (req, res) {
    res.jsonp(200, {
      welcome: 'Welcome to Demi API'
    });
  }
};

Models

How to use Models

The models in demi.js uses the mongoose and follows the implementation of the example below:

var mongoose = require('mongoose');
var Schema = mongoose.Schema;

/**
 * Taks Schema
 */
var TaskSchema = new Schema({
  created: {
    type: Date,
    default: Date.now
  },
  title: {
    type: String,
    default: '',
    trim: true,
    required: true
  },
  slug: {
    type: String,
    trim: true,
    required: true,
    unique: true
  },
  content: {
    type: String,
    default: '',
    trim: true
  },
  closed: {
    type: Boolean,
    default: false
  }
});

//Exports model
module.exports = mongoose.model('Task', TaskSchema);

Middlewares

How to use middlewares

You can add and manage middlewares very easily in Demi.js and may activate it or deactivate it very easily and quickly.

The middleware Demi.js follow the format below:

module.exports = {

  /*
   * Set true if you want enable this middleware
   */
  enabled: false,
  fn: function () {
    return function (req, res, next) {
      //console.log('Called');
      next();
    };
  }
};

Shared Middlewares

You can create or use shared middlewares by the community Demi.js on NPM.

Using shared middlewares

1º Search for middlewares in https://npmjs.org/search?q=demi- or http://demijs.enytc.com/#/middlewares

2º Install middleware npm install demi-example --save

3º Declare and enable in api/config/<env>/middlewares.jsonp

Example:

[
  {
    "enabled": true,
    "name": "demi-example"
  }
]

Now your shared middlewares are ready to be used.

Creating your Demi.js middlewares

The middlewares of Demi.js are exactly the same as the middlewares of Express.js but just need to follow some conventions.

Conventions:

The name of the middleware must always start with demi-. e.g: demi-example.
The middleware should be sent to NPM.
The middlewares must have the tag demiddleware.

Following these conventions your middleware may appear in Demi.js site, so you can help many people.

Example:

/*
 * demi-example
 * https://github.com/chrisenytc/demi-example
 *
 * Copyright (c) 2014 Christopher EnyTC
 * Licensed under the MIT license.
 */

'use strict';

module.exports = function () {
  return function (req, res, next) {
    //console.log('Called');
    next();
};

Services

How to use services

Services are specific to provide static JSON files can be accessed via: /ws/nameofjsonfile.json

Conventions:

All services are on route /ws/
The name of the JSON file will be used as the name of the route. e.g: /ws/nameofjsonfile
Routes can use the .json extension optionally. e.g: /ws/nameofjsonfile.json

The services accept any valid JSON.

Example:

[
  {
    "name": "Bella"
  },
  {
    "name": "Livia"
  }
]

Sockets

How to use Sockets

The Demi.js uses socket.io, you need to follow some conventions to able to use it.

The file name and the method name will be used as socket path. e.g: test.js + index = test/index
You can listen or emit a message using that path. e.g: on: function(data){} or emit: 'message-example'
this variable has the scope of socket.io and can use all of its methods. e.g: this.on('test/index', function(data){});, this.emit('test/index', 'message-example') and more.

Example:

api/sockets/test.js

module.exports = {

  /*
   * SOCKET test
   */

  index: {
    on: function(data) {
      //show received data
      console.log(data);
      //emit new data
      this.emit('test/another/event', data);
    },
    emit: 'test this'
  }
};

For more information see the documentation of socket.io:

How to use Socket.io

Settings

How to use Settings

The Demi.js works with environments, you can have multiple configurations in your application.

The defaults environments are: development, test and production. You also create your own customized reports environments.

You can access the contents of environments using app.get('nameofconfigfile')

Conventions:

The name of the configuration files in app/config/<envs> are the names used to get the contents of the settings in: app.get('nameofconfigfile')

Custom Environments

How to create custom environments

1º Create mycustomenv folder in api/config/

2º Create config files in api/config/mycustomenv

3º Run your environment

NODE_ENV=mycustomenv node app

Example:

NODE_ENV=production node app

Contributing

See the CONTRIBUTING Guidelines

Support

If you have any problem or suggestion please open an issue here.

License

The BSD License

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the EnyTC Corporation nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

demi
demi copied to clipboard

Metadata

Getting Started

Using Yeoman Generator

Learn to use the Demi.js generator

Documentation

Overview

Params to Demi.js constructor

Versioning

Controllers

Default Controller

Restful Controller

Models

Middlewares

Shared Middlewares

Using shared middlewares

Creating your Demi.js middlewares

Services

Sockets

Settings

Custom Environments

Contributing

Support

License

← Metadata

Owner

Metadata

demi demi copied to clipboard

Metadata

Getting Started

Using Yeoman Generator

Learn to use the Demi.js generator

Documentation

Overview

Params to Demi.js constructor

Versioning

Controllers

Default Controller

Restful Controller

Models

Middlewares

Shared Middlewares

Using shared middlewares

Creating your Demi.js middlewares

Services

Sockets

Settings

Custom Environments

Contributing

Support

License

← Metadata

Owner

Metadata

demi
demi copied to clipboard