express-mongodb-rest

3.1.0
Need help reading this?

api

Express middleware for MongoDB REST APIs

api
Parameters
options (Object = {}) options for this function.
Name Description
options.express Object (default {}) options for express JavaScript package
options.express.database string (default 'database') route parameter name in path (e.g. /:database ) for MongoDB database
  • options.express.database takes priority over options.rest.<METHOD>.database and options.mongodb.database
options.express.collection string (default 'collection') route parameter name in path (e.g. /:collection ) for MongoDB collection
  • options.express.collection takes priority over options.rest.<METHOD>.collection and options.mongodb.collection
options.express.method string (default 'method') route parameter name in path (e.g. /:method ) for MongoDB method
  • options.express.method takes priority over options.rest.<METHOD>.method and options.mongodb.method
options.express.parse function function for parsing the query string into an appropriate format to be passed to each options.mongodb.handler or options.rest.<METHOD>.handler
  • options.express.parse is the form of `function(query){return(query);};
  • query is the query string object from a request
  • By default, the first level key in the query string object is converted into a JSON object
options.express.handler function function for handling responses after connecting to MongoDB
  • options.express.handler is in the form of function(req, res, next, data){}
  • req is the request Object
  • res is the response Object
  • next is a function that can be called to skip the remaining lines ahead and move to the next router
  • data is an object containing REST and MongoDB data
  • data.rest contains the REST related data
  • data.rest.database is database name of the request
  • data.rest.collection is the collection name of the request
  • data.rest.method is the collection method name
  • data.rest.query is a query string object after parsing with options.express.parse
  • data.mongodb contains the MongoDB related data
  • data.mongodb.client is the MongoDB client object
  • data.mongodb.database is the MongoDB database object
  • data.mongodb.collection is the MongoDB collection object
  • By default, options.express.handler will handle find, findOne, updateMany, updateOne, insertMany, insertOne, deleteMany, and deleteOne
options.express.allow Object (default {}) options for allowing access to databases and collections
options.express.allow.database Array (default []) names of MongoDB databases to allow API access to
  • By default, the API is allowed access to all databases
options.express.allow.collection Array (default []) names of MongoDB collections to allow API access to
  • By default, the API is allowed access to all collections
options.express.allow.method Array (default []) names of MongoDB methods to allow API access to
  • By default, the API is allowed access to all defined methods in options.mongodb.handler or options.rest.<METHOD>.handler
options.express.allow.code number (default 400) response status code when a request is not allowed
options.express.deny Object (default {}) options for denying access to databases and collections
  • options.express.deny takes priority over options.express.allow
options.express.deny.database Array (default ['admin']) names of MongoDB databases to deny API access to
  • By default, the API is denied access to the admin database only
options.express.deny.collection Array (default []) names of MongoDB collections to deny API access to
  • By default, the API is not denied access to any collections
options.express.deny.method Array (default []) names of MongoDB methods to deny API access to
  • By default, the API is not denied access to any defined methods in options.mongodb.handler or options.rest.<METHOD>.handler
options.express.deny.code number (default 400) response status code when a request is denied
options.mongodb Object (default {}) default options for MongoDB database.
options.mongodb.connection string (default process.env.MONGODB_CONNECTION||'mongodb://localhost:27017') MongoDB connection string .
options.mongodb.options (Object | string) (default process.env.MONGODB_OPTIONS) Mongodb connect options .
options.mongodb.database string (default process.env.MONGODB_DATABASE||'test') database name.
  • By default, options.mongodb.database is used only if options.express.database and options.rest.database are not available
options.mongodb.collection string (default process.env.MONGODB_COLLECTION||'express_mongodb_rest') collection name
  • By default, options.mongodb.collection is used only if options.express.collection and options.rest.<METHOD>.collection are not available
options.rest Object (default {}) options for REST API definitions
  • options.rest is in the form of options.rest.<METHOD>.<OPTION>
  • Each key in options.rest is the REST API method such as GET, POST, PUT, DELETE, etc
  • options.rest values take priority over options.mongodb and options.express values
  • GET is used as an example below, but can be changed to POST, PUT, DELETE, etc
options.rest.GET Object (default {}) example of REST API definition for GET
options.rest.GET.database string (default options.mongodb.database) default database name for GET request
options.rest.GET.collection string (default options.mongodb.collection) default collection name for GET request
options.rest.GET.method string (default 'find') default collection method name for GET request
options.rest.GET.query Array base query when URL query is not provided for collection method defined by options.rest.GET.method
  • By default, options.rest.GET.method is not called when query strings are not provided
  • A query string is not provided when a URL does not contain ? such as localhost:3000
options.rest.GET.handler Object (default {}) object containing handler functions as defined in options.express.handler
  • The default handler for options.rest.GET.method is options.express.handler
  • Each key in options.rest.GET.handler defines a handler function for a collection method for route /:method
options.rest.GET.handler.find function (default options.express.handler) function to handle responses for a method after connecting to mongodb as defined in options.express.handler
  • In this case, the method is find, and the function defined will handle all GET requests with method find
Returns
function: Express middleware compatible with app.use .
Example
var express = require('express');
var api = require('express-mongodb-rest');

// (options) Initialize options object
var options = {mongodb: {}, rest: {}};

// (connection_mongodb) Setup mongodb connection
// Format: 'mongodb://<user>:<password>@<host>:<port>'
options.mongodb.connection = 'mongodb://localhost:27017'; // process.env.MONGODB_CONNECTION
options.mongodb.options = {poolSize: 10};
options.mongodb.database = 'test'; // process.env.MONGODB_DATABASE
options.mongodb.collection = 'express_mongodb_rest'; // process.env.MONGODB_COLLECTION

// (options_get) GET options
options.rest.GET = {};
options.rest.GET.method = 'find';
options.rest.GET.query = {q: {}}; // return all if no query string provided

// (options_get_limit) Limit number of documents for GET to 100
options.rest.GET.handler = {};
options.rest.GET.handler.find = function(req, res, next, data) {
  var collection = data.mongodb.collection;
  var query = data.rest.query;
  collection.find(query.q, query.options, function(err, result) {
    if (err) next(err);
    result.limit(100).toArray(function(err, docs) {
      if (err) next(err);
      res.json(docs);
    });
  });
};

// (options_get_count) Handle count collection method
options.rest.GET.handler = {};
options.rest.GET.handler.count = function(req, res, next, data) {
  var collection = data.mongodb.collection;
  var query = data.rest.query;
  collection.count(query.q, query.options, function(err, result) {
    if (err) next(err);
    res.json({count: result};
  });
};

// (options_post) POST options
options.rest.POST = {};
options.rest.POST.method = 'insertMany';

// (options_post) POST options
options.rest.PUT = {};
options.rest.PUT.method = 'updateMany';

// (options_delete) DELETE options
options.rest.DELETE = {};
options.rest.DELETE.method = 'deleteMany';

// (app) Create express app
var app = express();

// (app_middleware) Add MongoDB REST API on localhost:3000/api
app.use('/api', api(options);
app.use('/api/:collection', api(options)); // enable other collections
app.use('/api/:database/:collection', api(options)); // enable other databases and collections
app.use('/api/:database/:collection/:method', api(options)); // enable other databases, collections, and methods

// (app_start) Listen on localhost:3000
app.listen(3000);