Have ideas to improve npm?Join in the discussion! »

    express-mongodb-rest

    3.1.0 • Public • Published

    express-mongodb-rest

    Richard Wen
    rrwen.dev@gmail.com

    Express middleware for MongoDB REST APIs

    npm version Build Status Coverage Status npm GitHub license Donarbox Donate PayPal Donate Twitter

    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)

    Install

    npm i express-mongodb-rest

    DownloadsWeekly Downloads

    14

    Version

    3.1.0

    License

    MIT

    Last publish

    Collaborators

    • avatar