jammin
Installation
npm install jammin
About
Jammin is the fastest way to build 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.
Quickstart
var App = ;var Mongoose = ;var Jammin = ;var API = 'mongodb://<username>:<password>@<mongodb_host>'; var PetSchema = Mongoose; var Pet = Mongoose;API;APIPet;APIPet; App;App;
> curl -X POST $HOST/v0/pets -d '{"name": "Lucy", "age": 2}'{"success": true}> curl $HOST/v0/pets/Lucy{"name": "Lucy", "age": 2}
Documentation
Database Operations
GET
get()
will use req.params
and req.query
to find an item or array of items in the database.
APIPet;APIPet
POST
post()
will use req.body
to create a new item or set of items in the database.
APIPet;APIPet;
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.
APIPet;APIPet;
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
APIPet;APIPet;
DELETE
delete()
will use req.params
and req.query
to remove an item or set of items from the database
APIPet;APIPet;
Schemas and Validation
See the documentation for Mongoose Schemas for the full set of features.
Require fields
var PetSchema = name: type: String required: true
Hide fields
var UserSchema = username: String password_hash: type: String select: false
Middleware
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
Examples
Here are three equivalent ways to sort the results and limit how many are returned.
var J = middleware // The following are all equivalentAPIPet;APIPet;APIPet
The example below alters req.query
to construct a complex Mongo query from user inputs.
APIPet;
A more complex example achieves lazy deletion:
APIrouter
Or resource ownership:
var { reqjammindocumentowner = requser_id; ;}var { reqjamminqueryowner = "$eq": requser_id; ;}APIPet;APIPet;APIPet;APIPet;
Manual Calls and Intercepting Results
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
If you'd like to handle errors manually, you can also access the underlying model:
APIPetmodel;