corbel composer

A corbel-composer is a middleware based in nodeJS with express, to offer developers to make his own specific application API bsed in corbel-js

Homepage

Overview

[text]

Diagram

[image]

QuickStart

• install

  npm install -g bq/corbel-composer
  

• run server

  corbel-composer
  

Postman Playground

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

https://raw.githubusercontent.com/bq/corbel-composer/master/doc/postman.json

3. Enjoy!

Phrase Model

{
  "url": "phraseName",
  "get": {
    "code": "res.render('index', {title: 'hello world'});",
    "description": "Phrase description",
    "query": {
      "param1": {
        "type": "Number",
        "description": "Param description",
        "default": 0
      }
    },
    "responses": {
      "200": {
        "body": {
          "application/json": {
            "schema": {
              "type": "object",
              "description": "A canonical song",
              "properties": {
                "title": {
                  "type": "String"
                },
                "artist": {
                  "type": "String"
                }
              },
              "required": [
                "title",
                "artist"
              ]
            }
          }
        }
      }
    }
  }
}

Example Phrases

count value in collections query

{
    "url": "countExample",
    "get": {
        "code": "CORBEL-JS_SNIPPET"
    }
}

where code should be a string with this corbel-js snippet:

var count;
corbelDriver.resources.collection('test:ComposrTest').get(undefined, {
    aggregation: {
        $count: '*'
    }
}).then(function(response) {
    count = response.data.count;
    return corbelDriver.resources.collection('test:ComposrTest').get();
}).then(function(response) {
    res.send({
        data: response.data,
        'count': count
    });
}).catch(function(error) {
    res.send(error);
});

Path & query parameters

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

Reference

• corbel-js API
• Request object
• Response object
• RAML for phrase definition

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) Deletes a specific ticket

Versioning your phrases

A simple way to achieve this is definning 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-composer .
  

• run container

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

• start/stop container

  docker start/stop corbel-composer
  

Tests

npm test

Coverage

grunt test:coverage

Debug

Requires node-inspector

npm install -g node-inspector

• Server

  npm run debug
  

• Tests

  npm run test:debug