merest
Version:
Express based REST-full API for Mongoose models
225 lines (190 loc) • 8.19 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>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">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>
</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>