Plugin API

Plugin API is normal way to extend Colibri.

Colibri request handlers are named "methods" and each method consists of several "steps" which are Express route middleware.

Each step may be extended with Resource#use().

Colibri resource structure.

get method

Gets single document.

Steps:

• begin - initialize
• input - gets _id from request and stores it in req.rest._id
• load - loads document using _id and stores it in req.rest.document
• serialize - stores req.rest.document to req.rest.response
• output - outputs req.rest.meta and req.rest.response

put method

Updates document.

Steps:

• begin - initialize
• input - gets _id from request and stores it in req.rest._id. Also gets fields from req.body and stores them in req.rest.fieldValues
• load - loads document using _id and stores it in req.rest.document
• update - updates req.rest.document fields from req.rest.fieldValues
• save - saves req.rest.document
• serialize - stores req.rest.document to req.rest.response
• output - outputs req.rest.meta and req.rest.response

del method

Deletes document.

Steps:

• begin - initialize
• input - gets _id from request and stores it in req.rest._id
• load - loads document using _id and stores it in req.rest.document
• remove - destroys req.rest.document
• output - outputs req.rest.meta and req.rest.response

post method

Creates document.

Steps:

• begin - initialize
• input - gets fields from req.body and stores them in req.rest.fieldValues
• create - creates new document, populates it with req.rest.fieldValues and stores it in req.rest.document
• save - saves req.rest.document
• serialize - stores req.rest.document to req.rest.response
• output - outputs req.rest.meta and req.rest.response

list method

Gets list of documents.

Steps:

• begin - initialize
• input - does nothing
• query - creates Mongoose query and stores it in req.rest.query
• load - loads documents list using req.rest.query and stores it in req.rest.documents
• serialize - stores req.rest.documents to req.rest.response
• output - outputs req.rest.meta and req.rest.response

Extending

By calling Resource#use() we specify middlewares that will be added after the corresponding method/step.

In our middleware we can access and/or modify any variables under req.rest namespace, used by Colibri to pass data across steps.

For example, if we want to restrict creating new documents for unauthorized users, we need to use some middleware that would check authentification after post.begin (assuming that req.session.currentUser is set for authenticated users only):

resource.use({
    post:{
        begin : function (req, res, next) {
            if(req.session.currentUser) {
                next();
                return;
            }
            res.send(403);
        }
    }
});

This way we can control lots of things.

Another good example is changing list query. If we want to add sorting and limitation and filtering to our list results, we may create the following plugin:

resource.use({
    list:{
        query : function (req, res, next) {
            //list.query step has created Mongoose query for us
            var query = req.rest.query;

            query.sort('mtime', -1);
            query.limit(100);
            query.where('userName').equals(req.param('userName'));

            next();
        }
    }
});

Plugins

TODO