Baucis is Express middleware that creates configurable REST APIs using Mongoose schemata.

Like Baucis and Philemon of old, this library provides REST to the weary traveler. The goal is to create a JSON REST API for Mongoose & Express that matches as closely as possible the richness and versatility of the HTTP 1.1 protocol.

Baucis uses semver.

A change log has been added with info about each new release. Check there for the latest update notes.

Swagger support is being added. Most basic functionality is tested and seems to be working well! Want to check it out? Create your API with the swagger option enabled:

app.use('/api/v1', baucis({ swagger: true }));

Next, download the swagger-ui client.

git clone [email protected]:wordnik/swagger-ui.git
open swagger-ui/dist/index.html

Point it at your API. Something like:

http://localhost:8012/api/v1/api-docs

Now you have documentation and a test client for free!

• Example REST API server built with Node and Baucis
• Examples with Backbone
• Examples with jQuery

David Rijckaert - Philemon and Baucis Giving Hospitality to Jupiter and Mercury

To install:

npm install baucis

An example of creating a REST API from a couple Mongoose schemata:

var Vegetable = new mongoose.Schema({ name: String });
var Fruit = new mongoose.Schema({ name: String });

// Note that Mongoose middleware will be executed as usual
Vegetable.pre('save', function () { ... });

// Register the schemata
mongoose.model('vegetable', Vegetable);
mongoose.model('fruit', Fruit);

// Create the API routes
baucis.rest('vegetable');
baucis.rest('fruit');

// Create the app and listen for API requests
var app = express();
app.use('/api/v1', baucis());
app.listen(80);

Later, make requests:

It is not permitted to use the select query option to select deselected paths. This is to allow a mechanism for hiding fields from client software.

The select option of populate is disallowed. Only paths deselected at the model level will be deselected in populate queries.

You can deselect paths in the schema definition using select: false or in the controller options using select: '-foo' and your server middleware will be able to select these fields as usual using query.select, while preventing the client from selecting the field.

baucis.rest returns an instance of the controller created to handle the schema's API routes.

var controller = baucis.rest({ ... });

For simple controllers, only the schema name need be passed.

var controller = baucis.rest('robot');

Controllers are Express apps; they may be used as such.

var controller = baucis.rest('robot');

// Add middleware before API routes
controller.use('/qux', function (request, response, next) {
  // Do something cool…
  next();
});

controller.get('/readme', function (request, response, next) {
  // Send a readme document about the resource (for example)
  next();
});

// Do other stuff...
controller.set('some option name', 'value');
controller.listen(3000);

Customize them with plain old Express/Connect middleware, including pre-existing modules like passport. Middleware can be registered like so:

controller.request(function (request, response, next) {
  if (request.isAuthenticated()) return next();
  return response.send(401);
});

Baucis adds middleware registration functions for three stages of the request cycle:

Each of these functions has three forms:

To apply middleware to all API routes, just pass the function or array to the method for the appropriate stage:

controller.request(function (request, response, next) {
  if (request.isAuthenticated()) return next();
  return response.send(401);
});

controller.documents(function (request, response, next) {
  if (typeof request.baucis.documents === 'number') return next();
  if (!Array.isArray(request.baucis.documents)) return next();

  request.baucis.documents.pop();
  next();
});

To add middleware that applies only to specific HTTP verbs, use the second form. It adds a paramater that must contain a space-delimted list of HTTP verbs that the middleware should be applied to.

controller.query('head get put', function (request, response, next) {
  request.baucis.query.sort('-created');
  next();
});

The final form is the most specific. The first argument lets you specify whether the middleware applies to document instances (paths like /foos/:id) or to collection requests (paths like /foos).

controller.request('instance', 'head get del', middleware);
controller.request('collection', 'post', middleware);

An example of embedding a controller within another controller

var subcontroller = baucis.rest({
  singular: 'bar',
  basePath: '/:fooId/bars',
  publish: false
});

subcontroller.query(function (request, response, next) {
  // Only retrieve bars that are children of the given foo
  request.baucis.query.where('parent', request.params.fooId);
  next();
});

// Didn't publish, so have to manually initialize
subcontroller.initialize();

var controller = baucis.rest('foo');

// Embed the subcontroller at /foos/:fooId/bars
controller.use(subcontroller);

• http://kun.io/
• @wprl

© 2012-2013 William P. Riley-Land