npm install jammin
Jammin is a concise, extensible framework for building REST APIs in NodeJS. It consists of:
- A light-weight wrapper around Mongoose to perform database operations
- An Express router to link database operations to HTTP operations
Jammin is built for Express and is fully extensible via middleware to support things like authentication, sanitization, and resource ownership.
Use API.addModel()
to add an existing Mongoose model. You can attach HTTP routes to each model that will use req.params
and req.query
to query the database and req.body
to update it.
var App = require('express')();
var Mongoose = require('mongoose');
var Jammin = require('jammin');
var API = new Jammin.API('mongodb://<username>:<password>@<mongodb_host>');
var PetSchema = Mongoose.Schema({
name: String,
age: Number
});
var Pet = Mongoose.model('Pet', PetSchema);
API.addModel('Pet', Pet);
API.Pet.get('/pets/:name');
API.Pet.post('/pets');
App.use('/v0', API.router);
App.listen(3000);
> curl -X POST $HOST/v0/pets -d '{"name": "Lucy", "age": 2}'
{"success": true}
> curl $HOST/v0/pets/Lucy
{"name": "Lucy", "age": 2}
GET
get()
will use req.params
and req.query
to find an item or array of items in the database.
API.Pet.get('/pets/:name');
API.Pet.getMany('/pets')
POST
post()
will use req.body
to create a new item or set of items in the database.
API.Pet.post('/pets');
API.Pet.postMany('/pets');
PATCH
patch()
will use req.params
and req.query
to find an item or set of items in the database, and use req.body
to update those items.
API.Pet.patch('/pets/:name');
API.Pet.patchMany('/pets');
PUT
put()
will use req.params
and req.query
to find an item or set of items in the database, and use req.body
to update those items, or create a new item if none exists
API.Pet.put('/pets/:name');
API.Pet.putMany('/pets');
DELETE
delete()
will use req.params
and req.query
to remove an item or set of items from the database
API.Pet.delete('/pets/:name');
API.Pet.deleteMany('/pets');
See the documentation for Mongoose Schemas for the full set of features.
var PetSchema = {
name: {type: String, required: true}
}
var UserSchema = {
username: String,
password_hash: {type: String, select: false}
}
You can use middleware to intercept database calls, alter the request, perform authentication, etc.
Change req.jammin.query
to alter how Jammin selects items from the database (GET, PATCH, PUT, DELETE).
Change req.jammin.document
to alter the document Jammin will insert into the database (POST, PATCH, PUT).
Change req.jammin.method
to alter how Jammin interacts with the database.
Jammin also comes with prepackaged middleware to support the following Mongoose operations:
limit
, sort
, skip
, projection
, populate
, select
Here are three equivalent ways to sort the results and limit how many are returned.
var J = require('jammin').middleware
// The following are all equivalent
API.Pet.getMany('/pets', J.limit(20), J.sort('+name'));
API.Pet.getMany('/pets', J({limit: 20, sort: '+name'}));
API.Pet.getMany('/pets', function(req, res, next) {
req.jammin.limit = 20;
req.jammin.sort = '+name';
next();
})
The example below alters req.query
to construct a complex Mongo query from user inputs.
API.Pet.getMany('/search/pets', function(req, res, next) {
req.jammin.query = {
name: { "$regex": new RegExp(req.query.q) }
};
next();
});
A more complex example achieves lazy deletion:
API.router.use('/pets', function(req, res, next) {
if (req.method === 'DELETE') {
req.jammin.method = 'PATCH';
req.jammin.document = {deleted: true};
} else if (req.method === 'GET') {
req.jammin.query.deleted = {"$ne": true};
} else if (req.method === 'POST' || req.method === 'PUT') {
req.jammin.document.deleted = false;
}
next();
}
Or resource ownership:
var setOwnership = function(req, res, next) {
req.jammin.document.owner = req.user._id;
next();
}
var ownersOnly = function(req, res, next) {
req.jammin.query.owner = {"$eq": req.user._id};
next();
}
API.Pet.get('/pets');
API.Pet.post('/pets', setOwnership);
API.Pet.patch('/pets/:id', ownersOnly);
API.Pet.delete('/pets/:id', ownersOnly);
You can manually run a Jammin query and view the results before sending them to the user. Simply call the operation you want without a path.
Jammin will automatically handle 404 and 500 errors, but will pass the results of successful operations to your callback.
app.get('/pets', J.limit(20), function(req, res) {
API.Pet.getMany(req, res, function(pets) {
res.json(pets);
})
})
If you'd like to handle errors manually, you can also access the underlying model:
API.Pet.model.findOneAndUpdate(...);