merest
Version:
Express based REST-full API for Mongoose models
226 lines (203 loc) • 9.79 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>Configuration | Merest</title>
<script src="scripts/prettify/prettify.js"> </script>
<script src="scripts/prettify/lang-css.js"> </script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>
<body>
<div id="main">
<h1 class="page-title">API Configuration</h1>
<section>
<article>
<a name="methods"></a>
<h3>Model methods</h3>
<p>As pointed <a href="conf-router.html#expose">above</a> the router level has two parameters that allow to call model methods through the api.
These parameters are:</p>
<ul>
<li>expose: <code>Object</code> - configuration for end-points that expose the instance methods defined on its schema</li>
<li>exposeStatic: <code>Object</code> - configuration for end-points that expose static model methods defined on its schema.</li>
</ul>
<p>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: <code>Boolean</code>|<code>String</code>|<code>Object</code></p>
<pre class="prettyprint source lang-javascript"><code>{
expose: {
methodName: `Boolean` | `String` | `Object`,
methodName: `Boolean` | `String` | `Object`
...
},
exposeStatic: {
methodName: `String` | `Object`,
...
}
}</code></pre>
<h4>In case of <code>Boolean</code></h4>
<p>the value means if method-end-point is allowed (<code>true</code>) or is disabled (<code>false</code>).
<p>There is a special key <code>"*"</code> that allows to enable or to disable all methods together.</p>
<pre class="prettyprint source lang-javascript"><code>{
expose: {'*': true} // all instance method will be exposed
}</code></pre>
<h4>In case of <code>String</code></h4>
<p><strong>merest</strong> mounts controller that calls correspondent method
to the HTTP-method specified by value (if value is on of Express-supported HTTP-methods).</p>
<p>Otherwise (the value is not a HTTP-method) <strong>merest</strong> mounts appropriate controller
to POST (or other method specified directly) and adds created method-end-point
to list with value as description.</p>
<h4>In case of <code>Object</code></h4>
<p><strong>merest</strong> uses the value to configure method-end-point with the following parameters:</p>
<ul>
<li><strong>method</strong>:<code>String</code> - the HTTP method to mount method-end-point (if omitted the method-controller will be mount on the POST)</li>
<li><strong>path</strong>: <code>String</code> - the <code>additional-path</code> to mount method-controller</li>
<li><strong>exec</strong>:<code>Function</code> - 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 <code>this</code>.</li>
<li><strong>middlewares</strong>: <code>Function|Array</code> - middleware function or array of such functions. The middleware(s) will be mounted to the method-end-point route as usual express middleware</li>
<li><strong>title</strong>: <code>String</code> - the description of the end-point</li>
</ul>
<h4>Signature of Model method that can be exposed</h4>
<p>The controller that calls certain Model method passes to the one two parameters:</p>
<ul>
<li><strong>params</strong>: <code>Object</code> - parameters sent from client (in the Query String or in Request
Body dependent on the HTTP method used to mount method-end-point)
</li>
<li><strong>callback</strong>: <code>Function</code> - Function that should be called after method processed.</li>
</ul>
For example the instance method could be defined with following interface:
<pre class="prettyprint source lang-javascript"><code>/**
* @param {Object} params
* @param {Function} callback
* @return {undefined}
*/
modelSchema.methods.methodName = function (params, callback) {
// this -- referencies the document instance
}
</code></pre>
and the static method with the same:
<pre class="prettyprint source lang-javascript"><code>/**
* @param {Object} params
* @param {Function} callback
* @return {undefined}
*/
modelSchema.statics.methodName = function (params, callback) {
// this -- referencies the model
}
</code></pre>
<p><strong>Signature of callback-function</strong>:</p>
<pre class="prettyprint source lang-javascript"><code>/**
* @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) {
...
}</code></pre>
<p>For example:</p>
<pre class="prettyprint source lang-javascript"><code>VectorSchema.methods.reverse = function(params, callback) {
this.x = -this.x;
this.y = -this.y;
return this.save(callback);
}</code></pre><p>or in case of <code>statics</code>:</p>
<pre class="prettyprint source lang-javascript"><code>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);
});
}</code></pre><p>Exposing the methods</p>
<pre class="prettyprint source lang-javascript"><code>var api = new merest.ModelAPIExpress();
api.expose(models.Vector, { // Model-routes level
fields: 'x y',
expose: { reverse: 'get' },
exposeStatic: { reverse: 'get' }
});</code></pre>
<p>Getting the vector details:</p>
<pre class="prettyprint source lang-shell"><code>curl -g http://localhost:1337/api/v1/vectors/573f19d35b54089f3993605f/</code></pre>
<p>Output:</p>
<pre class="prettyprint source lang-shell"><code>{"_id": "573f19d35b54089f3993605f", "x": 1, "y": 2}</code></pre>
<p>Calling method-end-point:</p>
<pre class="prettyprint source lang-shell"><code>curl -g http://localhost:1337/api/v1/vectors/573f19d35b54089f3993605f/reverse</code></pre>
<p>Output:</p>
<pre class="prettyprint source lang-shell"><code>{"__v": 1, "_id": "573f19d35b54089f3993605f", "x": -1, "y": -2}</code></pre>
<p>Getting the vector details again:</p>
<pre class="prettyprint source lang-shell"><code>curl -g http://localhost:1337/api/v1/vectors/573f19d35b54089f3993605f/</code></pre>
<p>Output:</p>
<pre class="prettyprint source lang-shell"><code>{"_id": "573f19d35b54089f3993605f", "x": -1, "y": -2}</code></pre>
<p>Calling the static method:</p>
<pre class="prettyprint source lang-shell"><code>curl -g http://localhost:1337/api/v1/vectors/reverse</code></pre>
<p>Output:</p>
<pre class="prettyprint source lang-shell"><code>[
{"_id": "...", "x": -1, "y": -2},
{"_id": "...", "x": 0, "y": -3}
]</code></pre>
<p>And after that calling againg with parameters</p>
<pre class="prettyprint source lang-shell"><code>curl -g http://localhost:1337/api/v1/vectors/reverse?x=0</code></pre>
<p>Output:</p>
<pre class="prettyprint source lang-shell"><code>[
{"_id": "...", "x": 0, "y": 3}
]</code></pre>
<p>Lookout the <strong>merest</strong> doesn't clean the response from exposed methods.
So, you should do it by your own code.</p>
<br class="clear">
<hr>
<a href='installation.html'>Next (Installation) ></a>
</article>
</section>
</div>
<nav><h2>
<a href="index.html">merest</a>
</h2>
<h3><a href="installation.html">Installation</a></h3>
<ul>
<li><a href="installation.html#prerequisites">Prerequisites</a></li>
<li><a href="installation.html#npm-install">npm installation</a></li>
<li><a href="installation.html#development">Development</a></li>
</ul>
<h3><a href="cook-book.html">Cook-book</a></h3>
<h3><a href="conf-levels.html">API Configuration</a></h3>
<ul>
<li><a href="conf-levels.html">Configuration levels</a></li>
<li><a href="conf-app.html">API Application</a></li>
<li><a href="conf-router.html">Router</a></li>
<li><a href="conf-end-points.html">End-point</a></li>
<li><a href="conf-methods.html">Model methods</a></li>
</ul>
<h3><a href="end-points.html">API Requests and Responses</a></h3>
<ul>
<li><a href="end-points.html">Common reponses</a></li>
<li><a href="end-points.html#ep_options">Options</a></li>
<li><a href="end-points.html#ep_search">Search</a></li>
<li><a href="end-points.html#ep_create">Create</a></li>
<li><a href="end-points.html#ep_details">Details</a></li>
<li><a href="end-points.html#ep_update">Update</a></li>
<li><a href="end-points.html#ep_delete">Delete</a></li>
<li><a href="end-points.html#transform-response">Custom response</a></li>
</ul>
<h3><a href="swagger.html">Swagger support</a></h3>
<ul>
<li><a href="swagger.html#install">Installation</a></li>
<li><a href="swagger.html#api-conf">Configure API</a></li>
<li><a href="swagger.html#document">Creating <code>swagger.json</code></a></li>
<li><a href="swagger.html#api-docs">Exposing the api-docs</a></li>
<li><a href="swagger.html#swagger-ui">Embedded swagger-ui</a></li>
</ul>
<h3>Specifications</h3>
<ul>
<li><a href="ModelAPIExpress.html">ModelAPIExpress</a></li>
<li><a href="merest-swagger.html">Swagger-support methods</a></li>
<li><a href="ModelAPIRouter.html">ModelAPIRouter</a></li>
<li><a href="ModelAPIError.html">ModelAPIError</a></li>
</ul>
</nav>
<br class="clear">
<footer>
Documentation generated with <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.4.3</a>
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>