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
- Get postman
- Import corbel-composer collection:
https://raw.githubusercontent.com/bq/corbel-composer/master/doc/postman.json
- 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) | 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 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