{% extends "includes/base-layout.twig" %} {% block title %}Configuration | Merest{% endblock %} {% block content %}

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:

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:

Signature of Model method that can be exposed

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

For example the instance method could be defined with following interface: 
/**
 * @param  {Object} params
 * @param  {Function} callback
 * @return {undefined}
 */
modelSchema.methods.methodName = function (params, callback) {
  // this -- referencies the document instance
}
and the static method with the same: 
/**
 * @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.


Next (Installation) >
{% endblock %}