corbel-composr

                                                                             
   _|_|_|                                                  _|_|_|  _|_|_|    
 _|          _|_|    _|_|_|  _|_|    _|_|_|      _|_|    _|        _|    _|  
 _|        _|    _|  _|    _|    _|  _|    _|  _|    _|    _|_|    _|_|_|    
 _|        _|    _|  _|    _|    _|  _|    _|  _|    _|        _|  _|    _|  
   _|_|_|    _|_|    _|    _|    _|  _|_|_|      _|_|    _|_|_|    _|    _|  
                                     _|                                      
                                     _|                                      

Homepage

Overview

CompoSR is a nodeJS middleware, built on top of restify, for Corbel.

It uses the composr-core capabilities and offers developers the ability to make their own specific application API with a Corbel generic backend.

Composr is responsible for composing phrases of code than can be reused by multiple applications. Those phrases can use all the methods exposed by corbel-js and some extra useful libraries.

wiki: A composer (Latin com+ponere, literally "one who puts together") is a person who creates music.

wiki: In music and music theory, phrase and phrasing are concepts and practices related to grouping consecutive melodic notes, both in their composition and performance. A musical work is typically made up of a melody that consists of numerous consecutive phrases.

Features

• Built in PM2 configuration for cluster mode
• Bunyan Access logs
• Winston Logs (debug, info, warn, error)
• Endpoint documentation
• RabbitMQ connection for endpoint updates
• Status and Healthcheck endpoints
• Keymetrics and Newrelic support
• Docker Ready!
• Corbel ready!

QuickStart

• install

  npm install -g corbel-platform/corbel-composr
  

• run server

  corbel-composr
  

Configuration

You can send the following environment variables (or define a environment config file under src/config/[ENV].json).

Default config file

{
    "serverName" : "CompoSR",
    "bodylimit" : "50mb",
    "port": 3000,
    
    "rabbitmq.host": "RABBIT_HOST",
    "rabbitmq.port": "RABBIT_PORT",
    "rabbitmq.username": "RABBIT_USERNAME",
    "rabbitmq.password": "RABBIT_PASSWORD",
    "rabbitmq.reconntimeout": 10000,
    "rabbitmq.event": "class io.corbel.event.ResourceEvent",
    "rabbitmq.forceconnect": true,
    "rabbitmq.heartbgeat": 30,

    "bootstrap.retrytimeout": 10000,

    "phrases.timeout": 10000,

    "services.timeout": 5000,
    "services.retries": 30,
    "services.time": 1000,

    "corbel.composr.credentials": {
        "clientId": "CLIENT_ID",
        "clientSecret": "CLIENT_SECRET",
        "scopes": "composr:comp:base"
    },

    "corbel.driver.options": {
        "urlBase": "https://{{module}}corbel-domain.io/"
    },

    "bunyan.log" : true,
    "bunyan.syslog" : true,
    "bunyan.stdout": false,
    "bunyan.streamServer": false,

    "composrLog.accessLog" : true,
    "composrLog.accessLogFile" : "logs/access.log",
    "composrLog.logLevel": "error",
    "composrLog.logFile": "logs/composr.log",
    "composrLog.syslog" : false,

    "newrelic" : false,
    "newrelic.name": "",
    "newrelic.key": "",

    "keymetrics": true
}

Almost all of the vales in the configuration file can be overwriten by environment variables:

Environment variables

SERVER_NAME (Composr 2.0)
PORT (3000)
CREDENTIALS_CLIENT_ID
CREDENTIALS_CLIENT_SECRET
CREDENTIALS_SCOPES
URL_BASE
ACCESS_LOG => winston access log
ACCESS_LOG_FILE => winston access log file
LOG_LEVEL => winston log level
LOG_FILE => winston log file
BUNYAN_LOG(true) => Bunyan logs
BUNYAN_SYSLOG(true) => Send bunyan stream to syslog (127.0.0.1:514)
BUNYAN_STDOUT(false) => Bunyan output in terminal
BUNYAN_STREAM_SERVER (null) => Composr Stream Server endpoint
RABBITMQ_HOST
RABBITMQ_PORT
RABBITMQ_USERNAME
RABBITMQ_PASSWORD
RABBITMQ_FORCE_CONNECT => Only launch composr if rabbit is connected
RABBITMQ_HEARTBEAT => Heartbeat for the rabbitmq connection
SERVICES_TIMEOUT
SERVIES_RETRIES
SERVICES_TIME 
KEYMETRICS (true) => Keymetrics active
NRACTIVE => New relic active
NRAPPNAME => New relic app name
NRAPIKEY => New relic api key

Read:

What are Phrases or Snippets?

Routing endpoints

Corbel-CompoSR has a similar routing mechanism than restify. You can define urls by following this conventions:

• :param : Url parameter
• user : Fixed path value

Some examples

• user/:userId
• user/status/:parameter
• thing/one

{
    "url": "paramsExample/:pathparam",
    "get": {
        "code": "res.status(200).send('path param: ' + req.params.pathparam + ',  query param: ' + req.query.queryparam);"
    },
    "post": {
       /*...*/
    },
    "put": {
       /*...*/
    }
}

Reference

• composr-core
• corbel-js API
• RAML for phrase definition

Logs

CompoSR is shipped with built-in bunyan and winston support.

Winston logs:

You can set logFile and logLevel in your config file.

Available log levels can be found at winston's npm page:

• debug
• info
• warn
• error

Bunyan Logs:

Bunyan logs are enabled by default. You can disable them by turning bunyan.log to false in your configuration.

Tests

npm test

Coverage

npm run coverage

Debug

Requires node-inspector

npm install -g node-inspector

• Server

  npm run debug --myphrase.get
  

• Tests

  npm run test:debug
  

API design best practices

Naming

• Use nouns not verbs
• Use plural nouns

Resource	GET (read)	POST (create)	PUT (update)	DELETE
/cars	Returns a list of cars	Create a new ticket	Bulk update of cars	Delete all cars
/cars/711	Returns a specific car	Method not allowed (405)	Updates a specific ticket	Deletes a specific ticket
/purchase	Get al purchases	Create a new purchase	Bulk update of purschases	Delete all purchases
/purchase/85	Returns a purchase	Method not allowed (405)	Updates a specific purchase	Delete all purchases

Resource GET read POST create PUT update DELETE /cars Returns a list of cars Create a new ticket Bulk update of cars Delete all cars /cars/711 Returns a specific car Method not allowed (405) Deletes a specific ticket

Versioning your phrases

A simple way to achieve this is defining the phrase version in the url, like this

{
    "url": "v1/paramsExample/:pathparam",
    "get": { ... }
}

A phrase version should change only if the phrase contract is broken

Reference

• APIgee
• Principios de diseño de APIs REST
• Best Practices for Designing a Pragmatic RESTful API
• REST API Resoruces

Run in a docker container

• clone repo

• build image

  docker build -t <username>/corbel-composr .
  

• run container

  docker run -d -p 3000:3000 --name="corbel-composr"  <username>/corbel-composr
  

• start/stop container

  docker start/stop corbel-composr
  

Postman Playground

1. Get postman
2. Import corbel-composr collection:

https://raw.githubusercontent.com/corbel-platform/corbel-composr/master/doc/postman/postman.json

1. Import evironment example:

https://raw.githubusercontent.com/corbel-platform/corbel-composr/master/doc/postman/environment.example.json

1. Import globals:

https://raw.githubusercontent.com/corbel-platform/corbel-composr/master/doc/postman/globals.example.json

1. Enjoy!