API Configuration

Model methods

As pointed above the router level has two parameters that allow to call model methods through the api. These parameters are:

• expose: Object - configuration for end-points that expose the instance methods defined on its schema
• exposeStatic: Object - configuration for end-points that expose static model methods defined on its schema.

The keys of these paramters are the names of the Model methods (instance or static). The each value of the key could be on of types: Boolean|String|Object

{
  expose: {
    methodName: `Boolean` | `String` | `Object`,
    methodName: `Boolean` | `String` | `Object`
    ...
  },
  exposeStatic: {
    methodName: `String` | `Object`,
    ...
  }
}

In case of Boolean

the value means if method-end-point is allowed (true) or is disabled (false).

There is a special key "*" that allows to enable or to disable all methods together.

{
  expose: {'*': true} // all instance method will be exposed
}

In case of String

merest mounts controller that calls correspondent method to the HTTP-method specified by value (if value is on of Express-supported HTTP-methods).

Otherwise (the value is not a HTTP-method) merest mounts appropriate controller to POST (or other method specified directly) and adds created method-end-point to list with value as description.

In case of Object

merest uses the value to configure method-end-point with the following parameters:

• method:String - the HTTP method to mount method-end-point (if omitted the method-controller will be mount on the POST)
• path: String - the additional-path to mount method-controller
• exec:Function - the Function that will be called instead of Model instance/static method with context of Document or the Model. You could to call any Model method from this function using this.
• middlewares: Function|Array - middleware function or array of such functions. The middleware(s) will be mounted to the method-end-point route as usual express middleware
• title: String - the description of the end-point

Signature of Model method that can be exposed

The controller that calls certain Model method passes to the one two parameters:

• params: Object - parameters sent from client (in the Query String or in Request Body dependent on the HTTP method used to mount method-end-point)
• callback: Function - Function that should be called after method processed.

/**
 * @param  {Object} params
 * @param  {Function} callback
 * @return {undefined}
 */
modelSchema.methods.methodName = function (params, callback) {
  // this -- referencies the document instance
}

/**
 * @param  {Object} params
 * @param  {Function} callback
 * @return {undefined}
 */
modelSchema.statics.methodName = function (params, callback) {
  // this -- referencies the model
}

Signature of callback-function:

/**
 * @param  {Error} err                        exception raised in the method call
 * @param  {Object|Array|String} dataToReturn The data to be return in Response Body
 */
function callback(err, dataToReturn) {
  ...
}

For example:

VectorSchema.methods.reverse = function(params, callback) {
  this.x = -this.x;
  this.y = -this.y;
  return this.save(callback);
}

or in case of statics:

VectorSchema.statics.reverse = function(params, callback) {
  var self = this;
  self.update(params, {$mul: {x:-1, y:-1} }, {multi: true}, function (err) {
    if (err) return done(err);
    return self.find(callback);
  });
}

Exposing the methods

var api = new merest.ModelAPIExpress();
api.expose(models.Vector, { // Model-routes level
  fields: 'x y',
  expose: { reverse: 'get' },
  exposeStatic: { reverse: 'get' }
});

Getting the vector details:

curl -g http://localhost:1337/api/v1/vectors/573f19d35b54089f3993605f/

Output:

{"_id": "573f19d35b54089f3993605f", "x": 1, "y": 2}

Calling method-end-point:

curl -g http://localhost:1337/api/v1/vectors/573f19d35b54089f3993605f/reverse

Output:

{"__v": 1, "_id": "573f19d35b54089f3993605f", "x": -1, "y": -2}

Getting the vector details again:

curl -g http://localhost:1337/api/v1/vectors/573f19d35b54089f3993605f/

Output:

{"_id": "573f19d35b54089f3993605f", "x": -1, "y": -2}

Calling the static method:

curl -g http://localhost:1337/api/v1/vectors/reverse

Output:

[
  {"_id": "...", "x": -1, "y": -2},
  {"_id": "...", "x": 0, "y": -3}
]

And after that calling againg with parameters

curl -g http://localhost:1337/api/v1/vectors/reverse?x=0

Output:

[
  {"_id": "...", "x": 0, "y": 3}
]

Lookout the merest doesn't clean the response from exposed methods. So, you should do it by your own code.