express-mongodb-rest

Richard Wen
[email protected]

• Documentation
• Changes

Express middleware for MongoDB REST APIs

Install

1. Install MongoDB
2. Install Node.js
3. Install express and express-mongodb-rest via npm
4. Recommended: Install dotenv to load environmental variables

npm install --save express express-mongodb-rest
npm install --save dotenv

For the latest developer version, see Developer Install.

Usage

This package provides a flexible, customizable, and low-dependency Representational State Transfer (REST) Application Programming Interface (API) for mongodb using express.

It is recommended to use a .env file at the root of your project directory with the following contents:

• MONGODB_CONNECTION: MongoDB connection string
• MONGODB_DATABASE: MongoDB database name

MONGODB_CONNECTION=mongodb://localhost:27017
MONGODB_DATABASE=test

The .env file above can be loaded using dotenv:

require('dotenv').config();

See Documentation for more details.

GET (Default)

Given the route /api/:collection/:method:

Method | Route | Function | Query | Description --- | --- | --- | --- | --- GET | /api/:collection/find?q={"field":"value"} | find | {field: "value"} | Find all documents with field=value GET | /api/:collection/find?q={"field":{"$exists":"value"}} | find | {field: {$exists: "value"}} | Find all documents where field exists GET | /api/:collection/find?q={"$or":[{"field1":"value1"},{"field2":"value2"}]} | find | {$or: [{field1: value1}, {field2: value2}]} | Find all documents with field1=value1 or field2=value2

A simple GET API can be created with the following file named app.js:

require('dotenv').config();

// (packages) Load required packages
var express = require('express');
var api = require('express-mongodb-rest')();

// (app) Create express app
var app = express();
app.use('/api/:collection', api); // add MongoDB REST API
app.listen(3000);

Run the file app.js defined above:

node app.js

Go to localhost:3000/api/collection/find?q={"field":"value"} with a web browser to use the API, where:

• collection is the name of the collection in your MongoDB database
• find is the MongoDB collection method for querying
• field is a field or key name in the collection
• value is the value in field to query for

REST (Custom)

Given the route /api/:collection/:method:

Method | Route | Function | Query | Description --- | --- | --- | --- | --- GET | /api/:collection/find | find | {} | Find all documents in collection POST | /api/:collection/insertMany?docs=[{"field":"value"}]| insertMany| [{field: "value"}]| Insert [{field: "value"}] into :collection PUT | /api/:collection/updateMany?q={"field":{"$exists":1}}&update={"$set":{"field":"newvalue"}} | updateMany | {$set: {field: "newvalue"}} | Update [{field: value}] with [{field: newvalue}] DELETE | /api/:collection/deleteMany?q={"field":{"$exists":1}} | deleteMany | {field: {$exists: 1}} | Delete all documents where field exists

A custom RESTful API can be created with the following file named app.js:

require('dotenv').config();

// (packages) Load required packages
var express = require('express');
var api = require('express-mongodb-rest');

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

// (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_post) POST options
options.rest.POST = {};
options.rest.POST.method = 'insertMany';

// (options_put) PUT 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.use('/api/:collection', api(options)); // add MongoDB REST API
app.listen(3000);

Run the file app.js defined above:

node app.js

Go to localhost:3000/api/collection/method with a web browser to use the API, where:

• collection is the name of the collection in your MongoDB database
• method is the MongoDB collection method for querying

GET (Query String Format)

Given the route /api/:collection/:method:

Method | Route | Function | Query | Description --- | --- | --- | --- | --- GET | /api/:collection/find?q[field]=value | find | {field: "value"} | Find all documents with field=value GET | /api/:collection/find?q[field][$exists]=value | find | {field: {$exists: "value"}} | Find all documents where field exists GET | /api/:collection/find?q[$or][0][field1]=value1&q[$or][1][field2]=value2 | find | {$or: [{field1: value1}, {field2: value2}]} | Find all documents with field1=value1 or field2=value2

A simple GET API with the Express query string format can be created with the following file named app.js:

• Recommended: Install express-query-int for numeric support npm install --save express-query-int

require('dotenv').config();

// (packages) Load required packages
var express = require('express');
var api = require('express-mongodb-rest');
var queryInt = require('express-query-int');

// (options_qs) Use query string format
options = {express: {}};
options.express.parse = function(query) {return(query)};

// (app) Create express app
var app = express();
app.use(queryInt()); // allow queries with numbers (optional)
app.use('/api/:collection', api(options)); // add MongoDB REST API
app.listen(3000);

Run the file app.js defined above:

node app.js

Go to localhost:3000/api/collection/find?q[field]=value with a web browser to use the API, where:

• collection is the name of the collection in your MongoDB database
• find is the MongoDB collection method for querying
• field is a field or key name in the <collection>
• value is the value in field to query for

REST (Query String Format)

Given the route /api/:collection/:method:

Method | Route | Function | Query | Description --- | --- | --- | --- | --- GET | /api/:collection/find | find | {} | Find all documents in collection POST | /api/:collection/insertMany?docs[0][field]=value| insertMany| [{field: "value"}]| Insert [{field: "value"}] into :collection PUT | /api/:collection/update?q[field][$exists]=1&update[$set][field]=newvalue | updateMany | {$set: {field: "newvalue"}} | Update [{field: value}] with [{field: newvalue}] DELETE | /api/:collection/deleteMany?q[field][$exists]=1 | deleteMany | {field: {$exists: 1}} | Delete all documents where field exists

A custom RESTful API with the Express query string format can be created with the following file named app.js:

• Recommended: Install express-query-int for numeric support npm install --save express-query-int

require('dotenv').config();

// (packages) Load required packages
var express = require('express');
var api = require('express-mongodb-rest');
var queryInt = require('express-query-int');

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

// (options_qs) Use query string format
options.express.parse = function(query) {return(query)};

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

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

// (options_put) PUT 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.use(queryInt()); // allow queries with numbers (optional)
app.use('/api/:collection', api(options)); // add MongoDB REST API
app.listen(3000);

Run the file app.js defined above:

node app.js

Go to localhost:3000/api/collection/method with a web browser to use the API, where:

• collection is the name of the collection in your MongoDB database
• method is the MongoDB collection method for querying

Contributions

Report Contributions

Reports for issues and suggestions can be made using the issue submission interface.

When possible, ensure that your submission is:

• Descriptive: has informative title, explanations, and screenshots
• Specific: has details of environment (such as operating system and hardware) and software used
• Reproducible: has steps, code, and examples to reproduce the issue

Code Contributions

Code contributions are submitted via pull requests:

1. Ensure that you pass the Tests
2. Create a new pull request
3. Provide an explanation of the changes

A template of the code contribution explanation is provided below:

## Purpose

The purpose can mention goals that include fixes to bugs, addition of features, and other improvements, etc.

## Description

The description is a short summary of the changes made such as improved speeds or features, and implementation details.

## Changes

The changes are a list of general edits made to the files and their respective components.
* `file_path1`:
	* `function_module_etc`: changed loop to map
	* `function_module_etc`: changed variable value
* `file_path2`:
	* `function_module_etc`: changed loop to map
	* `function_module_etc`: changed variable value

## Notes

The notes provide any additional text that do not fit into the above sections.

For more information, see Developer Install and Implementation.

Developer Notes

Developer Install

Install the latest developer version with npm from github:

npm install git+https://github.com/rrwen/express-mongodb-rest

Install from git cloned source:

1. Ensure git is installed
2. Clone into current path
3. Install via npm

git clone https://github.com/rrwen/express-mongodb-rest
cd express-mongodb-rest
npm install

Tests

1. Clone into current path git clone https://github.com/rrwen/express-mongodb-rest
2. Enter into folder cd express-mongodb-rest
3. Ensure devDependencies are installed and available
4. Run tests with a .env file (see tests/README.md)
5. Results are saved to tests/log with each file corresponding to a version tested

npm install
npm test

Documentation

Use documentationjs to generate html documentation in the docs folder:

npm run docs

See JSDoc style for formatting syntax.

Upload to Github

1. Ensure git is installed
2. Inside the express-mongodb-rest folder, add all files and commit changes
3. Push to github

git add .
git commit -a -m "Generic update"
git push

Upload to npm

1. Update the version in package.json
2. Run tests and check for OK status (see tests/README.md)
3. Generate documentation
4. Login to npm
5. Publish to npm

npm test
npm run docs
npm login
npm publish

Implementation

The module express-mongodb-rest uses the following npm packages for its implementation:

npm | Purpose --- | --- express | Serve REST API application to handle query string requests and data responses mongodb | Query MongoDB database using query string requests

 express      <-- Handle query requests and JSON responses
    |
 mongodb      <-- query data using request

Changes

v3.1.0

• Now uses route /:method handlers with options.express.handler and options.rest.<METHOD>.handler
• Added options.express.handler
• Added options.express.allow.method and options.express.deny.method
• Removed options.mongodb.keys and options.rest.<METHOD>.keys
• Removed options.mongodb.methods and options.rest.<METHOD>.methods
• Removed options.mongodb.method and options.mongodb.query

v3.0.0

• Methods are now available in the route parameters (/:method)
• Databases are re-added to route parameters (/:database) with connection pooling
• Modified options.mongodb.method and options.rest.<METHOD>.method to be the default methods
• Added options.mongodb.methods and options.rest.<METHOD>.methods as Objects defining functions that are called before and after a query
• Added options.express.method for defining the route parameter name (such as /:method) for the collection method used
• Added options.express.database and options.rest.<METHOD>.database
• Added options.express.deny.database and options.express.allow.database
• Removed options.mongodb.callback and options.rest.<METHOD>.callback
• Removed options.mongodb.parse and options.rest.<METHOD>.parse

v2.5.0

• Now uses connection pooling for faster queries
• Removed options.express.database, you can no longer access at the database level through urls
• Removed options.express.deny.database and options.express.allow.database as user now has to manually set the database
• Added options.mongodb.options for connection options

v2.0.0

• Default now uses JSON object format for url queries (q={"field":"value"} instead of q[field]=value)
• Both JSON object format and query string formats supported
• Added option to change response codes for options.express.deny.code and options.express.allow.code (See Documentation)

v1.0.0

• Initial release
• Default is query string format for url queries (q[field]=value)