{"id":23061816,"url":"https://github.com/rrwen/express-mongodb-rest","last_synced_at":"2025-08-15T08:33:03.328Z","repository":{"id":91307849,"uuid":"114347442","full_name":"rrwen/express-mongodb-rest","owner":"rrwen","description":"Express middleware for MongoDB REST APIs","archived":false,"fork":false,"pushed_at":"2018-01-18T03:11:33.000Z","size":1421,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-26T05:21:24.993Z","etag":null,"topics":["api","app","collection","database","delete","express","expressjs","function","get","link","mdb","middleware","mongo","mongod","mongodb","post","query","rest","string","url"],"latest_commit_sha":null,"homepage":"https://rrwen.github.io/express-mongodb-rest","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rrwen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-12-15T08:38:02.000Z","updated_at":"2023-09-08T17:33:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"ae628c20-2e90-4dc9-8d4e-c61c0d80db3a","html_url":"https://github.com/rrwen/express-mongodb-rest","commit_stats":{"total_commits":86,"total_committers":2,"mean_commits":43.0,"dds":0.06976744186046513,"last_synced_commit":"11cc6066ec7ce2ba601682d94c400ea57c941520"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrwen%2Fexpress-mongodb-rest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrwen%2Fexpress-mongodb-rest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrwen%2Fexpress-mongodb-rest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrwen%2Fexpress-mongodb-rest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rrwen","download_url":"https://codeload.github.com/rrwen/express-mongodb-rest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229901951,"owners_count":18141802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","app","collection","database","delete","express","expressjs","function","get","link","mdb","middleware","mongo","mongod","mongodb","post","query","rest","string","url"],"created_at":"2024-12-16T03:18:34.061Z","updated_at":"2024-12-16T03:18:34.708Z","avatar_url":"https://github.com/rrwen.png","language":"JavaScript","funding_links":["https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=NQNSAHK5X46D2"],"categories":[],"sub_categories":[],"readme":"# express-mongodb-rest\n\nRichard Wen  \nrrwen.dev@gmail.com  \n\n* [Documentation](https://rrwen.github.io/express-mongodb-rest)\n* [Changes](#changes)\n\nExpress middleware for MongoDB REST APIs\n\n[![npm version](https://badge.fury.io/js/express-mongodb-rest.svg)](https://badge.fury.io/js/express-mongodb-rest)\n[![Build Status](https://travis-ci.org/rrwen/express-mongodb-rest.svg?branch=master)](https://travis-ci.org/rrwen/express-mongodb-rest)\n[![Coverage Status](https://coveralls.io/repos/github/rrwen/express-mongodb-rest/badge.svg?branch=master)](https://coveralls.io/github/rrwen/express-mongodb-rest?branch=master)\n[![npm](https://img.shields.io/npm/dt/express-mongodb-rest.svg)](https://www.npmjs.com/package/express-mongodb-rest)\n[![GitHub license](https://img.shields.io/github/license/rrwen/express-mongodb-rest.svg)](https://github.com/rrwen/express-mongodb-rest/blob/master/LICENSE)\n[![Donarbox Donate](https://img.shields.io/badge/donate-Donarbox-yellow.svg)](https://donorbox.org/rrwen)\n[![PayPal Donate](https://img.shields.io/badge/donate-PayPal-yellow.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=NQNSAHK5X46D2)\n[![Twitter](https://img.shields.io/twitter/url/https/github.com/rrwen/express-mongodb-rest.svg?style=social)](https://twitter.com/intent/tweet?text=Express%20middleware%20for%20MongoDB%20REST%20APIs:%20https%3A%2F%2Fgithub.com%2Frrwen%2Fexpress-mongodb-rest%20%23nodejs%20%23npm)\n\n## Install\n\n1. Install [MongoDB](https://www.mongodb.com/)\n2. Install [Node.js](https://nodejs.org/en/)\n3. Install [express](https://www.npmjs.com/package/express) and [express-mongodb-rest](https://www.npmjs.com/package/express-mongodb-rest) via `npm`\n4. **Recommended:** Install [dotenv](https://www.npmjs.com/package/dotenv) to load environmental variables\n\n```\nnpm install --save express express-mongodb-rest\nnpm install --save dotenv\n```\n\nFor the latest developer version, see [Developer Install](#developer-install).\n\n## Usage\n\nThis package provides a flexible, customizable, and low-dependency Representational State Transfer (REST) Application Programming Interface (API) for [mongodb](https://www.npmjs.com/package/mongodb) using [express](https://www.npmjs.com/package/express).  \n  \nIt is recommended to use a `.env` file at the root of your project directory with the following contents:\n\n* `MONGODB_CONNECTION`: MongoDB [connection string](https://docs.mongodb.com/manual/reference/connection-string/)\n* `MONGODB_DATABASE`: MongoDB database name\n\n```\nMONGODB_CONNECTION=mongodb://localhost:27017\nMONGODB_DATABASE=test\n```\n\nThe `.env` file above can be loaded using [dotenv](https://www.npmjs.com/package/dotenv):\n\n```javascript\nrequire('dotenv').config();\n```\n\nSee [Documentation](https://rrwen.github.io/express-mongodb-rest) for more details.\n\n### GET (Default)\n\nGiven the route `/api/:collection/:method`:\n\nMethod | Route | Function | Query | Description\n--- | --- | --- | --- | ---\nGET | /api/:collection/find?q={\"field\":\"value\"} | [find](https://mongodb.github.io/node-mongodb-native/3.0/api/Collection#find) | {field: \"value\"} | Find all documents with `field=value`\nGET | /api/:collection/find?q={\"field\":{\"$exists\":\"value\"}} | [find](https://mongodb.github.io/node-mongodb-native/3.0/api/Collection#find) | {field: {$exists: \"value\"}} | Find all documents where `field` exists\nGET | /api/:collection/find?q={\"$or\":[{\"field1\":\"value1\"},{\"field2\":\"value2\"}]} | [find](https://mongodb.github.io/node-mongodb-native/3.0/api/Collection#find) | {$or: [{field1: value1}, {field2: value2}]} | Find all documents with `field1=value1` or `field2=value2`\n\nA simple `GET` API can be created with the following file named `app.js`:\n\n```javascript\nrequire('dotenv').config();\n\n// (packages) Load required packages\nvar express = require('express');\nvar api = require('express-mongodb-rest')();\n\n// (app) Create express app\nvar app = express();\napp.use('/api/:collection', api); // add MongoDB REST API\napp.listen(3000);\n```\n\nRun the file `app.js` defined above:\n\n```\nnode app.js\n```\n\nGo to `localhost:3000/api/collection/find?q={\"field\":\"value\"}` with a web browser to use the API, where:\n\n* `collection` is the name of the collection in your MongoDB database\n* `find` is the MongoDB [collection method](https://mongodb.github.io/node-mongodb-native/3.0/api/Collection) for querying\n* `field` is a field or key name in the `collection`\n* `value` is the value in `field` to query for\n\n### REST (Custom)\n\nGiven the route `/api/:collection/:method`:\n\nMethod | Route | Function | Query | Description\n--- | --- | --- | --- | ---\nGET | /api/:collection/find | [find](https://mongodb.github.io/node-mongodb-native/3.0/api/Collection#find) | {} | Find all documents in collection\nPOST | /api/:collection/insertMany?docs=[{\"field\":\"value\"}]| [insertMany](https://mongodb.github.io/node-mongodb-native/3.0/api/Collection#insertMany)| [{field: \"value\"}]| Insert `[{field: \"value\"}]` into `:collection`\nPUT | /api/:collection/updateMany?q={\"field\":{\"$exists\":1}}\u0026update={\"$set\":{\"field\":\"newvalue\"}} | [updateMany](https://mongodb.github.io/node-mongodb-native/3.0/api/Collection#updateMany) | {$set: {field: \"newvalue\"}} | Update `[{field: value}]` with `[{field: newvalue}]`\nDELETE | /api/:collection/deleteMany?q={\"field\":{\"$exists\":1}} | [deleteMany](https://mongodb.github.io/node-mongodb-native/3.0/api/Collection#deleteMany) | {field: {$exists: 1}} | Delete all documents where `field` exists\n\nA custom RESTful API can be created with the following file named `app.js`:\n\n```javascript\nrequire('dotenv').config();\n\n// (packages) Load required packages\nvar express = require('express');\nvar api = require('express-mongodb-rest');\n\n// (options) Initialize options object\nvar options = {rest: {}, mongodb: {}};\n\n// (options_get) GET options\noptions.rest.GET = {};\noptions.rest.GET.method = 'find';\noptions.rest.GET.query = {q: {}}; // return all if no query string provided\n\n// (options_post) POST options\noptions.rest.POST = {};\noptions.rest.POST.method = 'insertMany';\n\n// (options_put) PUT options\noptions.rest.PUT = {};\noptions.rest.PUT.method = 'updateMany';\n\n// (options_delete) DELETE options\noptions.rest.DELETE = {};\noptions.rest.DELETE.method = 'deleteMany';\n\n// (app) Create express app\nvar app = express();\napp.use('/api/:collection', api(options)); // add MongoDB REST API\napp.listen(3000);\n```\n\nRun the file `app.js` defined above:\n\n```\nnode app.js\n```\n\nGo to `localhost:3000/api/collection/method` with a web browser to use the API, where:\n\n* `collection` is the name of the collection in your MongoDB database\n* `method` is the MongoDB [collection method](https://mongodb.github.io/node-mongodb-native/3.0/api/Collection) for querying\n\n### GET (Query String Format)\n\nGiven the route `/api/:collection/:method`:\n\nMethod | Route | Function | Query | Description\n--- | --- | --- | --- | ---\nGET | /api/:collection/find?q[field]=value | [find](https://mongodb.github.io/node-mongodb-native/3.0/api/Collection#find) | {field: \"value\"} | Find all documents with `field=value`\nGET | /api/:collection/find?q[field][$exists]=value | [find](https://mongodb.github.io/node-mongodb-native/3.0/api/Collection#find) | {field: {$exists: \"value\"}} | Find all documents where `field` exists\nGET | /api/:collection/find?q[$or][0][field1]=value1\u0026q[$or][1][field2]=value2 | [find](https://mongodb.github.io/node-mongodb-native/3.0/api/Collection#find) | {$or: [{field1: value1}, {field2: value2}]} | Find all documents with `field1=value1` or `field2=value2`\n\nA simple `GET` API with the [Express query string format](http://expressjs.com/en/api.html#req.query) can be created with the following file named `app.js`:\n\n* **Recommended:** Install [express-query-int](https://www.npmjs.com/package/express-query-int) for numeric support `npm install --save express-query-int`\n\n```javascript\nrequire('dotenv').config();\n\n// (packages) Load required packages\nvar express = require('express');\nvar api = require('express-mongodb-rest');\nvar queryInt = require('express-query-int');\n\n// (options_qs) Use query string format\noptions = {express: {}};\noptions.express.parse = function(query) {return(query)};\n\n// (app) Create express app\nvar app = express();\napp.use(queryInt()); // allow queries with numbers (optional)\napp.use('/api/:collection', api(options)); // add MongoDB REST API\napp.listen(3000);\n```\n\nRun the file `app.js` defined above:\n\n```\nnode app.js\n```\n\nGo to `localhost:3000/api/collection/find?q[field]=value` with a web browser to use the API, where:\n\n* `collection` is the name of the collection in your MongoDB database\n* `find` is the MongoDB [collection method](https://mongodb.github.io/node-mongodb-native/3.0/api/Collection) for querying\n* `field` is a field or key name in the `\u003ccollection\u003e`\n* `value` is the value in `field` to query for\n\n### REST (Query String Format)\n\nGiven the route `/api/:collection/:method`:\n\nMethod | Route | Function | Query | Description\n--- | --- | --- | --- | ---\nGET | /api/:collection/find | [find](https://mongodb.github.io/node-mongodb-native/3.0/api/Collection#find) | {} | Find all documents in collection\nPOST | /api/:collection/insertMany?docs[0][field]=value| [insertMany](https://mongodb.github.io/node-mongodb-native/3.0/api/Collection#insertMany)| [{field: \"value\"}]| Insert `[{field: \"value\"}]` into `:collection`\nPUT | /api/:collection/update?q[field][$exists]=1\u0026update[$set][field]=newvalue | [updateMany](https://mongodb.github.io/node-mongodb-native/3.0/api/Collection#updateMany) | {$set: {field: \"newvalue\"}} | Update `[{field: value}]` with `[{field: newvalue}]`\nDELETE | /api/:collection/deleteMany?q[field][$exists]=1 | [deleteMany](https://mongodb.github.io/node-mongodb-native/3.0/api/Collection#deleteMany) | {field: {$exists: 1}} | Delete all documents where `field` exists\n\nA custom RESTful API with the [Express query string format](http://expressjs.com/en/api.html#req.query) can be created with the following file named `app.js`:\n\n* **Recommended:** Install [express-query-int](https://www.npmjs.com/package/express-query-int) for numeric support `npm install --save express-query-int`\n\n```javascript\nrequire('dotenv').config();\n\n// (packages) Load required packages\nvar express = require('express');\nvar api = require('express-mongodb-rest');\nvar queryInt = require('express-query-int');\n\n// (options) Initialize options object\nvar options = {express: {}, rest: {}, mongodb: {}};\n\n// (options_qs) Use query string format\noptions.express.parse = function(query) {return(query)};\n\n// (options_get) GET options\noptions.rest.GET = {};\noptions.rest.GET.method = 'find';\noptions.rest.GET.keys = ['q', 'options'];\noptions.rest.GET.query = {q: {}}; // return all if no query string provided\n\n// (options_post) POST options\noptions.rest.POST = {};\noptions.rest.POST.method = 'insertMany';\n\n// (options_put) PUT options\noptions.rest.PUT = {};\noptions.rest.PUT.method = 'updateMany';\n\n// (options_delete) DELETE options\noptions.rest.DELETE = {};\noptions.rest.DELETE.method = 'deleteMany';\n\n// (app) Create express app\nvar app = express();\napp.use(queryInt()); // allow queries with numbers (optional)\napp.use('/api/:collection', api(options)); // add MongoDB REST API\napp.listen(3000);\n```\n\nRun the file `app.js` defined above:\n\n```\nnode app.js\n```\n\nGo to `localhost:3000/api/collection/method` with a web browser to use the API, where:\n\n* `collection` is the name of the collection in your MongoDB database\n* `method` is the MongoDB [collection method](https://mongodb.github.io/node-mongodb-native/3.0/api/Collection) for querying\n\n## Contributions\n\n### Report Contributions\n\nReports for issues and suggestions can be made using the [issue submission](https://github.com/rrwen/express-mongodb-rest/issues) interface.\n\nWhen possible, ensure that your submission is:\n\n* **Descriptive**: has informative title, explanations, and screenshots\n* **Specific**: has details of environment (such as operating system and hardware) and software used\n* **Reproducible**: has steps, code, and examples to reproduce the issue\n\n### Code Contributions\n\nCode contributions are submitted via [pull requests](https://help.github.com/articles/about-pull-requests/):\n\n1. Ensure that you pass the [Tests](#tests)\n2. Create a new [pull request](https://github.com/rrwen/express-mongodb-rest/pulls)\n3. Provide an explanation of the changes\n\nA template of the code contribution explanation is provided below:\n\n```\n## Purpose\n\nThe purpose can mention goals that include fixes to bugs, addition of features, and other improvements, etc.\n\n## Description\n\nThe description is a short summary of the changes made such as improved speeds or features, and implementation details.\n\n## Changes\n\nThe changes are a list of general edits made to the files and their respective components.\n* `file_path1`:\n\t* `function_module_etc`: changed loop to map\n\t* `function_module_etc`: changed variable value\n* `file_path2`:\n\t* `function_module_etc`: changed loop to map\n\t* `function_module_etc`: changed variable value\n\n## Notes\n\nThe notes provide any additional text that do not fit into the above sections.\n```\n\nFor more information, see [Developer Install](#developer-install) and [Implementation](#implementation).\n\n## Developer Notes\n\n### Developer Install\n\nInstall the latest developer version with `npm` from github:\n\n```\nnpm install git+https://github.com/rrwen/express-mongodb-rest\n```\n  \nInstall from `git` cloned source:\n\n1. Ensure [git](https://git-scm.com/) is installed\n2. Clone into current path\n3. Install via `npm`\n\n```\ngit clone https://github.com/rrwen/express-mongodb-rest\ncd express-mongodb-rest\nnpm install\n```\n\n### Tests\n\n1. Clone into current path `git clone https://github.com/rrwen/express-mongodb-rest`\n2. Enter into folder `cd express-mongodb-rest`\n3. Ensure [devDependencies](https://docs.npmjs.com/files/package.json#devdependencies) are installed and available\n4. Run tests with a `.env` file (see [tests/README.md](tests/README.md))\n5. Results are saved to [tests/log](tests/log) with each file corresponding to a version tested\n\n```\nnpm install\nnpm test\n```\n\n### Documentation\n\nUse [documentationjs](https://www.npmjs.com/package/documentation) to generate html documentation in the `docs` folder:\n\n```\nnpm run docs\n```\n\nSee [JSDoc style](http://usejsdoc.org/) for formatting syntax.\n\n### Upload to Github\n\n1. Ensure [git](https://git-scm.com/) is installed\n2. Inside the `express-mongodb-rest` folder, add all files and commit changes\n3. Push to github\n\n```\ngit add .\ngit commit -a -m \"Generic update\"\ngit push\n```\n\n### Upload to npm\n\n1. Update the version in `package.json`\n2. Run tests and check for OK status (see [tests/README.md](tests/README.md))\n3. Generate documentation\n4. Login to npm\n5. Publish to npm\n\n```\nnpm test\nnpm run docs\nnpm login\nnpm publish\n```\n\n### Implementation\n\n\nThe module [express-mongodb-rest](https://www.npmjs.com/package/express-mongodb-rest) uses the following [npm](https://www.npmjs.com/) packages for its implementation:\n\nnpm | Purpose\n--- | ---\n[express](https://www.npmjs.com/package/express) | Serve REST API application to handle query string requests and data responses\n[mongodb](https://www.npmjs.com/package/mongodb) | Query MongoDB database using query string requests\n\n```\n express      \u003c-- Handle query requests and JSON responses\n    |\n mongodb      \u003c-- query data using request\n```\n\n### Changes\n\n#### v3.1.0\n\n* Now uses route `/:method` handlers with `options.express.handler` and `options.rest.\u003cMETHOD\u003e.handler`\n* Added `options.express.handler`\n* Added `options.express.allow.method` and `options.express.deny.method`\n* Removed `options.mongodb.keys` and `options.rest.\u003cMETHOD\u003e.keys`\n* Removed `options.mongodb.methods` and `options.rest.\u003cMETHOD\u003e.methods`\n* Removed `options.mongodb.method` and `options.mongodb.query`\n\n#### v3.0.0\n\n* Methods are now available in the route parameters (`/:method`)\n* Databases are re-added to route parameters (`/:database`) with connection pooling\n* Modified `options.mongodb.method` and `options.rest.\u003cMETHOD\u003e.method` to be the default methods\n* Added `options.mongodb.methods` and `options.rest.\u003cMETHOD\u003e.methods` as Objects defining functions that are called before and after a query\n* Added `options.express.method` for defining the route parameter name (such as `/:method`) for the collection method used\n* Added `options.express.database` and `options.rest.\u003cMETHOD\u003e.database`\n* Added `options.express.deny.database` and `options.express.allow.database`\n* Removed `options.mongodb.callback` and `options.rest.\u003cMETHOD\u003e.callback`\n* Removed `options.mongodb.parse` and `options.rest.\u003cMETHOD\u003e.parse`\n\n#### v2.5.0\n\n* Now uses [connection pooling](https://mongodb.github.io/node-mongodb-native/driver-articles/mongoclient.html#mongoclient-connection-pooling) for faster queries\n* Removed `options.express.database`, you can no longer access at the database level through urls\n* Removed `options.express.deny.database` and `options.express.allow.database` as user now has to manually set the database\n* Added `options.mongodb.options` for connection options\n\n#### v2.0.0\n\n* Default now uses JSON object format for url queries (`q={\"field\":\"value\"}` instead of `q[field]=value`)\n* Both JSON object format and query string formats supported\n* Added option to change response codes for `options.express.deny.code` and `options.express.allow.code` (See [Documentation](https://rrwen.github.io/express-mongodb-rest))\n\n#### v1.0.0\n\n* Initial release\n* Default is query string format for url queries (`q[field]=value`)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frrwen%2Fexpress-mongodb-rest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frrwen%2Fexpress-mongodb-rest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frrwen%2Fexpress-mongodb-rest/lists"}