{% extends "includes/base-layout.twig" %}

{% block title %}Configuration | Merest{% endblock %}
{% block content %}
<h1 class="page-title">API Configuration</h1>
<section>
    <article>

<a name='end-point'></a>
<h3>End-point configuration options:</h3>
<p>To configure end-point you should to specify appropriate router-level paramter with end-point
  configuration object. For instance, like that:</p>
<pre class="prettyprint source lang-javascript"><code>var api = new merest.ModelAPIExpress();
api.expose(models.Book, {
  details: { populate: 'author' }
});</code></pre>

<h4>All end-point configuration parameters are the following:</h4>
<ul>
<li><strong>path</strong>: <code>String</code> - <code>additional-path</code> of end-point</li>
<li><strong>method</strong>: <code>String</code> -- HTTP-method to mount appropriate end-point</li>
<li><strong>filter</strong>: <code>Object|Function</code> - Mongoose query-object or function that returns such object. The function receives <code>request</code> (Express Incoming Message) as only parameter. The function is executing in synchronous mode.</li>
<li><strong>fields</strong>: <code>Object|Array|String</code> - Mongoose field-selection parameter</li>
<li><strong>readonly</strong>: <strong>reserved</strong>,</li>
<li><strong>queryFields</strong>: <code>Object</code> - keys of the objects are names of fields. If value of the key is equal to false, the correspondent field will be excluded from the query. Affects on <code>search</code> end-point only.</li>
<li><strong>readonly</strong>: <code>Array|Object|String</code> - the list of fields that couldn't be passed to the request. If <code>!</code> specified after the field name and this fields is in request, the API will raise an exception - 422 - Invalid entity </li>
<li><strong>populate</strong>: <code>Array|Object|String</code> - Mongoose field population parameter</li>
<li><strong>skip</strong>: <code>Boolean</code> - allows or disables skipping documents in the search result. Affects on <code>search</code> end-point only.</li>
<li><strong>limit</strong>: <code>Boolean</code> - allows on denies limitation of documents in the search result. Affects on <code>search</code> end-point only.</li>
<li><strong>sort</strong>: <code>Boolean|Object</code> -- allows or denies (in case of <code>false</code>) the sorting. Object keys are names of the fields. The value of appropriate key allows or denies to sort by this field. Affects on <code>search</code> end-point only. The mongodb field paths could be used as keys of <code>sort</code>-object.</li>
<li><strong>middlewares</strong>: <code>Function|Array</code> - middleware function or array of such functions. The middleware(s) will be mounted to the end-point route as usual express middleware</li>
<li><strong>title</strong>: <code>String</code> - the description of the end-point</li>
</ul>
<p>Allmost all of described above options (excl. <code>method</code>, <code>path</code>, <code>title</code>) could be assigned also
on the router-level. In this case it will be applied to all applicable end-points if end-point doesn't override appropriate parameter directly.</p>
<pre class="prettyprint source lang-javascript"><code>var api = new merest.ModelAPIExpress();
api.expose(models.Vector, { // Model-routes level
  options: false, // end-point level
  update: 'put', // end-point level - update controller will be mounted on the PUT HTTP-method
  search: { // end-point level - search controller will be mounted
    method: 'post',  // on the POST HTTP-method
    path: '/search'  // on /search
  }
  fields: { // Model-routes level
    x: true,
    y: true,
    _id: false
  }
});</code></pre><p>Calling API:</p>
<pre class="prettyprint source lang-shell"><code>curl -X OPTIONS http://localhost:1337/api/v1/</code></pre><p>Output:</p>
<pre class="prettyprint source lang-shell"><code>[
  ["options", "/api/v1/", "List all end-points of current application"],
  ["post", "/api/v1/vectors/search", "List/Search all vectors"],
  ["post", "/api/v1/vectors/", "Create a new Vector"],
  ["get", "/api/v1/vectors/:id", "Find a Vector by Id"],
  ["put", "/api/v1/vectors/:id", "Find a Vector by Id and update it (particulary)"],
  ["delete", "/api/v1/vectors/:id", "Find a Vector by Id and delete it."]
]</code></pre><p>If paraneter <strong>path</strong> is assigned on the router-level it will be used as end-point sub-path
instead of Model collection name (plural).</p>
<br class="clear">
<hr>
<a href='installation.html'>Next (Installation) ></a>
</article>
</section>
{% endblock %}