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

{% block title %}Merest{% endblock %}
{% block content %}
<h1 class="page-title">merest</h1>

<section>
    <article>
      <h2><u>M</u>ongoose <u>E</u>xpress <u>REST</u>-full API</h2>
      <p>
        <strong>merest</strong> provides easy way to expose Mongoose models as REST-full api.
        It creates pointed bellow end-points:
      </p>
      For each api-application:
      <ul>
        <li><code>all api options</code>: <strong>OPTIONS</strong>..\</li>
      </ul>
      For each exposed model:
      <ul>
        <li><code>model api options</code>: <strong>OPTIONS ..\model-plural-name\</strong></li>
        <li><code>search</code>: <strong>GET ..\model-plural-name\</strong></li>
        <li><code>create</code>: <strong>POST ..\model-plural-name\</strong></li>
        <li><code>details</code>: <strong>GET ..\model-plural-name\:id</strong></li>
        <li><code>update</code>: <strong>POST ..\model-plural-name\:id</strong></li>
        <li><code>delete</code>: <strong>DELETE ..\model-plural-name\:id</strong></li>
      </ul>
      <p>Generally <strong>merest</strong> allows to:</p>
      <ul>
        <li>create rest api for many models</li>
        <li>create many rest interfaces for one model</li>
        <li>restrict the set of documents that are accessible via API</li>
        <li>configure of each mentioned above end-points</li>
        <li>expose static and instance methods of the Model</li>
        <li>create and expose swagger documentation of your rest api</li>
        <li>serve the swagger-ui</li>
      </ul>

<h3>Getting started with <strong>merest</strong></h3>
<pre class="prettyprint source lang-javascript"><code>'use strict';

const merest = require('merest');
const express = require('express');
const bodyParser = require('body-parser');
const methodOverride = require('method-override');

// Defining model
const mongoose = require('mongoose');
const Contact = mongoose.model('Contact', new mongoose.Schema({
  name: { type: String, required: true },
  email: { type: String, required: true },
  phone: String,
  tags: [String]
}));
mongoose.connect('mongodb://localhost/merest-sample');

// Creating the Express application to serve API
const api = new merest.ModelAPIExpress();

api.use(bodyParser.json()); // Parsing JSON-bodies
api.use(methodOverride()); // Supporting HTTP OPTIONS and HTTP DELETE methods

api.expose(Contact); // Exposing our API

api.listen(8000, () => {
  console.log('Express server listening on port 8000');
});</code></pre><p>Calling API:</p>
<pre class="prettyprint source lang-shell"><code>curl -X OPTIONS http://localhost:8000/</code></pre>
<p>Output:</p>
<pre class="prettyprint source lang-shell"><code>[
  ["options","/","List all end-points of current application"],
  ["options","/contacts/","List API-options for contacts"],
  ["get","/contacts/","List/Search all contacts"],
  ["post","/contacts/","Create a new Contact"],
  ["get","/contacts/:id","Find a Contact by Id"],
  ["post","/contacts/:id","Find a Contact by Id and update it (particulary)"],
  ["delete","/contacts/:id","Find a Contact by Id and delete it."]
]</code></pre>

<p>Getting contact list:</p>
<pre class="prettyprint source lang-shell"><code>curl -X GET http://localhost:8000/contacts</code></pre>
<pre class="prettyprint source lang-shell"><code>[
  {
    "_id": "58503799b1ab13090f2eeb31",
    "name": "Jack London",
    "email": "j.l@mail.uk",
    "__v": 0,
    "phone": "+4123464575647",
    "tags": ["author", "american"]
  }, {
    "_id": "585276ca2aadb34477ad4034",
    "name": "Taras Shevchenko",
    "email": "t.sh@mail.ua",
    "__v": 0,
    "tags": ["author", "poet", "painter", "national hero", "ukrainian"]
  }
]</code></pre>

<h3>Integrating <strong>merest</strong> into existing projects</h3>
<pre class="prettyprint source lang-javascript"><code>'use strict';

const merest = require('merest-swagger'); // to support SwaggerUI
const express = require('express');
const bodyParser = require('body-parser');
const methodOverride = require('method-override');

// Defining model
const mongoose = require('mongoose');
const Contact = mongoose.model('Contact', new mongoose.Schema({
  name: { type: String, required: true },
  email: { type: String, required: true },
  phone: String,
  tags: [String]
}));
mongoose.connect('mongodb://localhost/merest-sample');

const app = express();
// Creating the Express application to serve API
const api = new merest.ModelAPIExpress({
  title: 'Contact List API',
  host: 'localhost:8000', // Assign correct host that could be accessed from your network
  path: '/api/v1',
  options: false // we do not need the OPTIONS any more
});

app.use(bodyParser.json()); // Parsing JSON-bodies
app.use(methodOverride()); // Supporting HTTP OPTIONS and HTTP DELETE methods

api.expose(Contact); // Exposing our API
api.exposeSwaggerUi(); // Exposing swagger-ui

app.use('/api/v1', api); // mounting API as usual sub-application

app.listen(8000, () => {
  console.log('Express server listening on port 8000');
});</code></pre>


<p>Going to <strong>swagger-ui</strong> in browser: <code>http://localhost:8000/swagger-ui</code>:</p>
<img src="images/merest-swagger.gif">


      <br class="clear">
      <hr>
      <a href='installation.html'>Next (Installation) ></a>
    </article>
</section>
{% endblock %}