This is an express node module to provide basic REST support to access mongodb documents via mongoose.
I use semantic versioning and my tag script to tag this module.
The library is fully tested with the mocha test framework and the should assertion library. If you contribute please make sure that you write tests for it.
The latest stable version is always in the master
branch. The develop
branch is
cutting edge where tests regularely won't completely pass. Only checkout the develop
branch
if you want to contribute.
With npm:
npm install mongo-rest
Or simply download the lates version from here, and put it in node_modules/mongo-rest
.
The usage of this module is quite straight forward:
- Include and instantiate
mongo-rest
. - Provide
mongo-rest
with the mongoose models you want to support. - Create a view file for each resource you want rendered as HTML.
- Optionally you can also define interceptors in case you want some resources to be handled exceptionally.
That's it, you're done.
MongoREST exposes a class you instatiate with your options. The long version looks like this:
var MongoRest = require('mongo-rest')
, mongoRest = new MongoRest(app, { viewPath: 'admin/resources/' });
The options for MongoRest are:
urlPath
The path prefix for the rest resources. Default to/
entityViewTemplate
The template that will be used as view name to render entity resources.{{singularName}}
and{{pluralName}}
can be used and will be substitutedcollectionViewTemplate
The template that will be used as view name to render collection resources.{{singularName}}
and{{pluralName}}
can be used and will be substitutedenableXhr
Enables a JSON interface for XMLHttpRequests. Make sure you don't leak important information!singleView
Whether there is a single view or not. If not, only the collection view will be used.
As a one liner it looks like this:
var mongoRest = new (require('mongo-rest'))(app, options);
When instantiated, MongoREST registers the routes with the app
so that all REST routes
become accessible. If you provided '/resources/'
as urlPath
then following urls will
become alive for the user
resource:
GET: /resources/users (Renders a list of all users)
POST: /resources/users (Creates a new user)
GET: /resources/user/12345 (Renders the user with ID 12345)
PUT: /resources/user/12345 (Updates the user with ID 12345)
DELETE: /resources/user/12345 (Deletes the user with ID 12345)
To tell mongo-rest
which resources it should support you simple add each mongoose model.
Normally you do this in the same place you define your routes. The code is quite straight
forward:
mongoRest.addResource('user', require('../models/user'));
// Or for irregular plurals:
mongoRest.addResource('hobby', require('../models/user'), 'hobbies');
// Default sorting:
mongoRest.addResource('user', require('../models/user'), null, [ [ "name", 1 ], [ "username", 1 ] ]);
That's it. Now MongoREST nows that it has to use those models whenever the resources users
or hobbies
are accessed.
When you access /resources/users
for example, MongoREST will try to render
this list. To do this it will need a template files.
Two template files are needed for each resource to...
- ...render a list of the resource
- ...render a single resource
To define where the views are located you specify the entityViewTemplate
and the
collectionViewTemplate
options. If you pass resources/{{singularName}}
as
entityViewTemplate
and resources/{{pluralName}}
as collectionViewTemplate
then
MongoREST will use resources/user
as view to render a single entity, and resources/users
to render a collection.
Sometimes some actions need to be taken before or after inserting, updating or deleting records.
You register an interceptor like this:
var eventName = 'post.success'
, handler = function(info, done, req, res, next) { /* Do stuff */ done(); };
mongoRest.addInterceptor('user', eventName, handler);
// You can also provide the same handler for multiple event names:
mongoRest.addInterceptor('users', [ 'post', 'put' ], handler);
The available event names are:
get
Called when a resource is retrieved.post
,post.success
,post.error
Called when a new resource is posted.put
,put.success
,put.error
Called when a resource is updated.delete
,delete.success
,delete.error
Called when a resource is deleted.
If you simply use the event name without .success
or .error
it will be called before
the event will be carried out.
The parameters provided to the handler are:
info
An object containing thedoc
and or thevalues
that will be used to update the recorddone
A callback that has to be called as soon as the interceptor is finished handling the event. (this allows for asynchronous interceptors). If there was an error during the execution of an interceptor, call this function with theerr
object as first parameter. The invokation of the other interceptors will be canceled (if possible).req
res
next
An example of an interceptor could look like this:
/**
* Intercepts posts and puts for guestbook-messages. It compiles the provided textSource with jade, and stores
* the old textSource in a textVersions array to provide a history.
*/
mongoRest.addInterceptor('guestbook-message', [ 'post', 'put' ], function(info, done) {
// Compile the new textSource value with jade, and put the compiled code in textHtml
info.values.textHtml = (jade.compile(info.values.textSource))({});
// Since there is no existing doc when posting a new resource, we test if it exists...
if (info.doc) {
// ...and if it does we add the old textSource to the textVersions array to have a history.
info.doc.textVersions.push(info.doc.textSource);
}
// Tell mongoRest that the interceptor finished intercepting the request.
done();
});
Mongo-REST supports XMLHttpRequest, but since it could be a security risk, they are disabled by default.
If you want to enable them simply pass the option enableXhr
.
The responses from Mongo-REST for XMLHttpRequests are always JSON and look like this:
// If everything went right for entities:
{ doc: doc }
// If everything went right for collections:
{ docs: docs }
// If the server would normally redirect:
{ redirect: "some/url" }
// and if there was an error
{ error: "There was a problem." }
Note that error
and redirect
can be submitted simultaniously.
(The MIT License)
Copyright (c) 2012 Matias Meno <[email protected]>
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.