corbel-sdk-js
A SDK for corbel compatible with browsers and node.
Homepage
- Quickstart
- Installation
- What is corbel-sdk-js ?
- Usage
- Instance a new driver
- Driver options (with client/secret)
- Driver options (with accessToken)
- Driver options (with custom API endpoints)
- API
- IAM
- Create a token
- Client token
- User token (IAM Basic)
- Token refresh token
- Create a token
- Resources
- Collection
- Relations
- Relation model
- Resources
- Assets
- Domains
- Chainable API
- IAM
- library static methods
- Examples
Quickstart
Installation
-
browser
bower install corbel-sdk-js --save# for environments without promises supportbower install es6-promise --save -
node
npm install corbel-sdk-js --save
What is corbel-sdk-js ?
Corbel-sdk-js is a SDK for working with the Corbel backend.
Using corbel-sdk-js SDK would allow you to :
- Create collections and resources
- CRUD operations for your models
- Authenticate users
- ...(much more)
Usage
Instance a new driver
var corbelDriver = corbel;
Driver options (with client/secret)
var options = 'clientId': 'clientId' 'clientSecret': 'clientSecret' 'audience': 'audience' 'urlBase': 'http://localhost:8080/{{module}}' 'scopes': 'scopes' 'device_id' : 'device_id'
Driver options (with accessToken)
var options = 'iamToken': accessToken: 'token' expiresAt: 1442837305000 // optional refreshToken: 'token' // optional 'domain': 'app:domain' 'urlBase': 'http://localhost:8080/{{module}}'
Driver options (with custom API endpoints)
var options = /* ... */ 'oauthEndpoint': 'http://localhost:8084/v1.0/' 'resourcesEndpoint': 'http://localhost:8080/v1.0/' 'iamEndpoint': 'http://localhost:8082/v1.0/' 'evciEndpoint': 'http://localhost:8086/v1.0/' 'ecEndpoint': 'http://localhost:8088/v1.0/' 'assetsEndpoint': 'http://localhost:8092/v1.0/' 'notificationsEndpoint': 'http://localhost:8094/v1.0/' 'bqponEndpoint': 'http://localhost:8090/v1.0/' 'webfsEndpoint': 'http://localhost:8096/v1.0/' 'schedulerEndpoint': 'http://localhost:8098/v1.0/' 'borrowEndpoint': 'http://localhost:8100/v1.0/' 'composrEndpoint': 'http://localhost:3000/';
API
IAM
IAM is the corbel module to handle with client and user autentication, in order to access to the rest of corbel API, you should generate a client/user token first
Create a token
There is 2 types of tokens, client token for applications, and user token, for autenticated users
Client token
var corbelDriver = corbel.getDriver(options);
corbelDriver.iam.token).create().then(...);
User token (IAM Basic)
var corbelDriver = corbel.getDriver(options);
corbelDriver.iam.token().create({
claims: {
'basic_auth.username': username,
'basic_auth.password': password
}
}).then(...);
Token refresh token
When a driver is authenticated as a user, its tries to refresh token automatically when a 401
response is detected.
If your application needs to add some behavior when a token is updated with tokenRefresh
(update localStorage for example), you can do it with:
var corbelDriver = corbel.getDriver(options);
corbelDriver.iam.token().create({
claims: {
'basic_auth.username': username,
'basic_auth.password': password
}
}).then(...);
corbelDriver.on('token:refresh', yourTokenRefreshHandler);
Resources
The Resources API is a flexible programming interface for retrieval of resource's representations. Using the patterns described by this API we can deploy any kind of resource in our Corbel ecosystem with minimal impact on clients and server code. A request can contain URL parameters which can modify the content of representation returned or its transmission to the client. Parameter names must be specified on using its canonical form.
More info: http://docs.corbelresources.apiary.io/
http://corbel.io/docs/resources.html
Resources API
Resources is exposed to corbelDriver instance and It has static methods and variables inside corbel namespace:
-
Statics properties and methods in corbel.Resources:
-
create: Factory method for instantiating a Resources object
-
sort: Sort constants object
corbelResourcessortASCcorbelResourcessortDESC -
ALL: Constant for use to specify all resources wildcard
corbelResourcesALL
-
-
Instance methods
-
collection: Collection factory method collection('collectionName')
corbelDriverresources -
resource: Resource factory method resource('resourceName',id)
corbelDriverresources -
relation: Relation factory method relation('sourceResourceName', sourceResourceId, 'destResourceName')
corbelDriverresources
Collection
A collection is a container of resources that share the same type. For instance:
/resource/music:Album => All resources of type music:Album
/resource/book:Book => All resources of type book:Book
/resource/music:Artist => All resources of type music:Artist
Collection API
-
Factory method
corbelDriverresources -
get: Gets a collection of elements, filtered, paginated or sorted (requestOptionsObject)
corbelDriverresources -
add: Adds a new element to a collection (objectData,requestOptionsObject)
corbelDriverresources; -
update: Updates the elements of a collection (objectData,requestOptionsObject)
corbelDriverresources;
Examples:
** Adding an item to a collection **
collection;
** Updating a collection **
collection;
Collection request params API
Following params can be passed both as request options object and as chainable methods:
-
Conditions (only for update, updates a set of items that match a certain condition, same sintaxis than query):
{ condition: [{$eq: {} } ] } { conditions: [{ condition: [{$eq: {} } ] }, { condition: [{$eq: {} } ] } ] }
-
Pagination:
{ pagination: { page: 1, pageSize: 5 } }
-
Aggregations:
{ aggregation: { $count: '*' } }
-
Sort:
{ sort: { title: corbel.Resources.order.sort } }
-
Query:
{ query: [{$like: {} } ] } { queries: [{ query: [{$like: {} } ] }, { query: [{$like: {} } ] } ] }
-
Custom query parameters:
{ customQueryParams: {myParam: 'myValue', ... } }
-
Search (ElasticSearch):
{ search: {text: 'This is the text i want to search'} } { search: 'This is the text i want to search'}
Examples:
var collection = corbelDriverresources ; collection
var collection = corbelDriverresources ; collection;
collection;
Relations
A relation is a model that creates a relation between two different sets of resources or one resource and arbitrary data. The registers on the relation may have aditional information.
For example: Having 2 different resources, a set of car models and a set of car sellers.
If you want to populate the car sellers with some relations to the models available at the store, and also allowing to specify a different set of data for each car in each shop, you could use a relation.
.....CarModels..............Relation.................Sellers..
+---------------+ +----------------------+ +------------+
| | | | | |
| carModels | | carSellers_carModels | | carSellers |
| | | | | |
+---------------+ +----------------------+ +------------+
var sellerId = 'test-seller';var carModelId = 'nexus-alpha-1'; //Extra information on the relationvar data = priceDiscount : 02 amount : 10; corbelDriverresources ;
Relation model
The mandatory fields that define the relation are _src_id
and _dst_id
.
_src_id: "carSeller_id" _dst_id: "car-model-001" sendedAtAddress : 'street test'
Relation API
-
Factory method
corbelDriverresources -
get: List elements of a resource's relation (destId, requestOptionsObject)
corbelDriverresources -
add: Add new relation (destId, relationData, requestOptionsObject)
To some specific item on another resource:
var sourceId = 15;corbelDriverresources
Not using other resources on the relation
var sourceId = 15; corbelDriverresources
-
move: Move a relation (destId, pos, requestOptionsObject)
var sourceId = 'id1';corbelDriverresources -
delete: Delete a relation (destId, requestOptionsObject)
corbelDriverresources
Examples:
var relation = corbelDriverresources ; relation; relation; relation; relation;
Relation request params API
The same request params previously listed in the collection API.
Resources
A resource is a single object in a collection. For instance
/resource/music:Album/123 => The representation of a single object of type music:Album whose identifier is 123
Resources API
-
Factory method
corbelDriverresources -
get: Get a resource representation (requestOptionsObject)
corbelDriverresources -
update: Update a resource (resourceData, requestOptionsObject)
corbelDriverresources -
delete: Delete a resource (requestOptionsObject)
corbelDriverresources
Examples:
var resource = corbelDriverresources ; resource; resource; resource;
Images
The Resources API is capable to handle images and perform operations over it.
-
update: Update an image (resourceData, requestOptionsObject)
/*requestOptionsObject example*/requestOptionsObject :dataType: 'image/png') -
get: Get an image (requestOptionsObject)
/*requestOptionsObject example*/requestOptionsObject :dataType: 'image/png'query: 'image:operations=resize=(100,20)&image:format=gif'responseType: 'blob' /*arraybuffer is supported as well*/) -
delete: Delete an image (requestOptionsObject)
/*requestOptionsObject example*/requestOptionsObject :dataType: 'image/png')
For more information, visit: http://docs.corbelimage.apiary.io/
Assets
Assets are dynamic groups of scopes that a user can have for a certain period of time.
This is an example of an asset:
_id: "0b2dff5c39934c210d80056a94eb27bc6c6d6378" userId: "fooid" name: "assettest13" productId: "producttest13" expire: active: true scopes: "ec:purchase:user"
Imagine assets as a group of items that extend the user permissions. For example, a user buys a digital good, then an asset is created with the permission for accessing that digital book.
When you login a user, you may want to load the assets of the user (by default they are not loaded because we try to mantain each service isolated).
For doing that, you can access corbel
assets with corbelDriver
this way:
var corbelDriver = corbel; //Enable the user permissions for that accessTokencorbelDriverassets;
You can also request all the user assets if you want, for example, listing al the goods that a user has purchased:
corbelDriverassets;
Assets API
-
Factory method
corbelDriverassets -
get: Get all the assets (requestOptionsObject)
corbelDriverassets -
create: Create an asset (assetData)
corbelDriverassets -
delete: Delete an asset (assetId)
corbelDriverassets;
Domains
Corbel-sdk-js provides a mechanism for doing requests from a child domain to it's parents by using the .domain
method.
corbelDriverresourcesresource /*...*/
This will redirect the request from the client domain to myParentDomain
, doing this will allow the client to access it's parents collections (if it has permissions).
Chainable API
You can use a chainable api to set defaults parameters over any kind of resource:
Example:
var collection = corbelDriverresources ; collection ;
The parameters specified with the chainable api will be removed when a corbel-request is maden.
var collection = corbelDriverresources ; collection ; //Collection doesn't have the defaults chainable params //this get request will not use any request params previously definedcollection;
library static methods
corbeljwt;corbelrequest;corbelResources// ... more
Examples
Get an application token, add an item to a collection, then retrieve it
corbelDriveriam;