Contribute on GitHub

Getting started


package.json

{
  "dependencies": {
    "express-restify-mongoose": "^3.0.0",
    "mongoose": "^4.0.0"
  }
}

From the command line

npm install express-restify-mongoose --save

While the source and examples are now written in ES2015, the module is transpiled and published as ES5 using Babel and remains fully compatible with Node 0.10 and newer.

Express 4 app

This snippet…

const express = require('express')
const bodyParser = require('body-parser')
const methodOverride = require('method-override')
const mongoose = require('mongoose')
const restify = require('express-restify-mongoose')
const app = express()
const router = express.Router()

app.use(bodyParser.json())
app.use(methodOverride())

mongoose.connect('mongodb://localhost/database')

restify.serve(router, mongoose.model('Customer', new mongoose.Schema({
  name: { type: String, required: true },
  comment: { type: String }
})))

app.use(router)

app.listen(3000, function () {
  console.log('Express server listening on port 3000')
})

…automatically generates those endpoints.

GET http://localhost/api/v1/Customer/count
GET http://localhost/api/v1/Customer
POST http://localhost/api/v1/Customer
DELETE http://localhost/api/v1/Customer

GET http://localhost/api/v1/Customer/:id
GET http://localhost/api/v1/Customer/:id/shallow
PUT http://localhost/api/v1/Customer/:id
POST http://localhost/api/v1/Customer/:id
PATCH http://localhost/api/v1/Customer/:id
DELETE http://localhost/api/v1/Customer/:id

Usage with request

let request = require('request')

request({
  url: '/api/v1/Model',
  qs: {
    query: JSON.stringify({
      $or: [{
        name: '~Another'
      }, {
        $and: [{
          name: '~Product'
        }, {
          price: '<=10'
        }]
      }],
      price: 20
    })
  }
})

Querying


All the following parameters (sort, skip, limit, query, populate, select and distinct) support the entire mongoose feature set.

When passing values as objects or arrays in URLs, they must be valid JSON

Sort

GET /Customers?sort=name
GET /Customers?sort=-name
GET /Customers?sort={"name":1}
GET /Customers?sort={"name":0}

Skip

GET /Customers?skip=10

Limit

Only overrides options.limit if the queried limit is lower

GET /Customers?limit=10

Query

Supports all operators ($regex, $gt, $gte, $lt, $lte, $ne, etc.) as well as shorthands: ~, >, >=, <, <=, !=

GET /Customers?query={"name":"Bob"}
GET /Customers?query={"name":{"$regex":"^(Bob)"}}
GET /Customers?query={"name":"~^(Bob)"}
GET /Customers?query={"age":{"$gt":12}}
GET /Customers?query={"age":">12"}
GET /Customers?query={"age":{"$gte":12}}
GET /Customers?query={"age":">=12"}
GET /Customers?query={"age":{"$lt":12}}
GET /Customers?query={"age":"<12"}
GET /Customers?query={"age":{"$lte":12}}
GET /Customers?query={"age":"<=12"}
GET /Customers?query={"age":{"$ne":12}}
GET /Customers?query={"age":"!=12"}

Populate

Works with create, read and update operations

GET/POST/PUT /Invoices?populate=customer
GET/POST/PUT /Invoices?populate={"path":"customer"}
GET/POST/PUT /Invoices?populate=[{"path":"customer"},{"path":"products"}]

Select

_id is always returned unless explicitely excluded

GET /Customers?select=name
GET /Customers?select=-name
GET /Customers?select={"name":1}
GET /Customers?select={"name":0}

Distinct

GET /Customers?distinct=name

Reference


serve

restify.serve(router, model[, options])

router: express.Router() instance (Express 4), app object (Express 3) or server object (restify)

model: mongoose model

options: object typedefaultversion

When version is unspecified, the feature is available in the initial major release (3.0.0)

prefix

string/api

Path to prefix to the REST endpoint.

version

string/v1

API version that will be prefixed to the rest path. If prefix or version contains /:id, then that will be used as the location to search for the id.

Example

Generates /api/v1/Entities/:id/Model and /api/v1/Entities/Model for all pertinent methods.

version: '/v1/Entities/:id'

idProperty

string_id

findById will query on the given property.

restify

booleanfalse

Enable support for restify instead of express.

name

stringmodel name

Endpoint name

readPreference

stringprimary

Determines the MongoDB nodes from which to read. Read more

totalCountHeader

boolean|stringfalse

When totalCountHeader: true, execute a count query on GET /Model requests ignoring limit and skip and setting the result in the a response header. It can also be set to a string to allow for a custom header. This is useful when it’s necessary to know in advance how many matching documents exist.

Examples

Boolean

totalCountHeader: true

Response:

Headers: {
  'X-Total-Count': 5
}

String

totalCountHeader: 'X-Custom-Count-Header'

Response:

Headers: {
  'X-Custom-Count-Header': 5
}

private

array

Array of fields which are only to be returned by queries that have private access.

Example

Defined in options

private: ['topSecret', 'fields']

Defined in mongoose schema

new Schema({
  topSecret: { type: String, access: 'protected' },
  fields: { type: String, access: 'protected' }
})

protected

array

Array of fields which are only to be returned by queries that have private or protected access.

Examples

Defined in options

protected: ['somewhatSecret', 'keys']

Defined in mongoose schema

new Schema({
  somewhatSecret: { type: String, access: 'protected' },
  keys: { type: String, access: 'protected' }
})

lean

booleantrue

Whether or not mongoose should use .lean() to convert results to plain old JavaScript objects. This is bad for performance, but allows returning virtuals, getters and setters.

findOneAndUpdate

booleantrue

Whether to use .findOneAndUpdate() or .findById() and then .save(), allowing document middleware to be called. For more information regarding mongoose middleware, read the docs.

findOneAndRemove

booleantrue

Whether to use .findOneAndRemove() or .findById() and then .remove(), allowing document middleware to be called. For more information regarding mongoose middleware, read the docs.

preMiddleware

function (req, res, next)

Middleware that runs before preCreate, preRead, preUpdate and preDelete.

Example
preMiddleware: function (req, res, next) {
  performAsyncLogic((err) => {
    next(err)
  })
}

preCreate

function (req, res, next)

Middleware that runs before creating a resource.

preCreate: function (req, res, next) {
  performAsyncLogic((err) => {
    next(err)
  })
}

preRead

function (req, res, next)

Middleware that runs before reading a resource.

preRead: function (req, res, next) {
  performAsyncLogic((err) => {
    next(err)
  })
}

preUpdate

function (req, res, next)

Middleware that runs before updating a resource.

preUpdate: function (req, res, next) {
  performAsyncLogic((err) => {
    next(err)
  })
}

When findOneAndUpdate: false, the document is available which is useful for authorization as well as setting values.

findOneAndUpdate: false,
preUpdate: function (req, res, next) {
  if (req.erm.document.user !== req.user._id) {
    return res.sendStatus(401)
  }

  req.erm.document.set('lastRequestAt', new Date())

  next()
}

preDelete

function (req, res, next)

Middleware that runs before deleting a resource.

preDelete: function (req, res, next) {
  performAsyncLogic((err) => {
    next(err)
  })
}

When findOneAndRemove: false, the document is available which is useful for authorization as well as performing non-destructive removals.

findOneAndRemove: false,
preDelete: function (req, res, next) {
  if (req.erm.document.user !== req.user._id) {
    return res.sendStatus(401)
  }

  req.erm.document.deletedAt = new Date()
  req.erm.document.save().then(function (doc) {
    res.sendStatus(204)
  }, function (err) {
    options.onError(err, req, res, next)
  })
}

access

function (req[, done])

Returns or yields ‘private’, ‘protected’ or ‘public’. It is called on GET, POST and PUT requests and filters out the fields defined in private and protected.

Examples

Sync

access: function (req) {
  if (req.isAuthenticated()) {
    return req.user.isAdmin ? 'private' : 'protected'
  } else {
    return 'public'
  }
}

Async

access: function (req, done) {
  performAsyncLogic(function (err, result) {
    done(err, result ? 'public' : 'private')
  })
}

contextFilter

function (model, req, done)

Allows request specific filtering.

Example
contextFilter: function (model, req, done) {
  done(model.find({
    user: req.user._id
  }))
}

postCreate

function (req, res, next)

Middleware that runs after successfully creating a resource. The unfiltered document is available on req.erm.result.

postCreate: function (req, res, next) {
  let result = req.erm.result         // unfiltered document or object
  let statusCode = req.erm.statusCode // 201

  performAsyncLogic((err) => {
    next(err)
  })
}

postRead

function (req, res, next)

Middleware that runs after successfully reading a resource. The unfiltered document(s), or object(s) when lean: false, is available on req.erm.result.

postRead: function (req, res, next) {
  let result = req.erm.result         // unfiltered document, object or array
  let statusCode = req.erm.statusCode // 200

  performAsyncLogic((err) => {
    next(err)
  })
}

postUpdate

function (req, res, next)

Middleware that runs after successfully updating a resource. The unfiltered document, or object when lean: false, is available on req.erm.result.

postUpdate: function (req, res, next) {
  let result = req.erm.result         // unfiltered document or object
  let statusCode = req.erm.statusCode // 200

  performAsyncLogic((err) => {
    next(err)
  })
}

postDelete

function (req, res, next)

Middleware that runs after successfully deleting a resource.

postDelete: function (req, res, next) {
  let result = req.erm.result         // undefined
  let statusCode = req.erm.statusCode // 204

  performAsyncLogic((err) => {
    next(err)
  })
}

outputFn

function (req, res)

Function used to output the result. The filtered object is available on req.erm.result.

Example
outputFn: function (req, res) {
  let result = req.erm.result         // filtered object

  res.status(req.erm.statusCode).json(result)
}

postProcess

function (req, res, next)

Middleware that is called after output, useful for logging. The filtered object is available on req.erm.result.

Not guaranteed to execute after output if async operations are performed inside outputFn

postProcess: function (req, res, next) {
  console.log(`${req.method} ${req.path} request completed with response code ${req.erm.statusCode}`)
}

onError

function (err, req, res, next)send the entire mongoose error

Leaving this as default may leak information about your database

Function used to output an error.

Example
onError: function (err, req, res, next) {
  next(err)
}

defaults

restify.defaults(options)

options: same as above, sets this object as the defaults for anything served afterwards