A node.js express generic crud router / controller

Install

npm install node-express-crud-router

Issues and enhancements

Please open an issue for bugs and/or enhancement requests here https://github.com/DennisAhaus/node-express-crud-router/issues.

As much issues we get as much we can improve this implementation.

Roadmap

Please have a look at https://github.com/DennisAhaus/node-express-crud-router/milestones to see the upcoming roadmap/milestones

Getting started

Create a crud router

We use mongoose schema as model but you can also use another model definition as well. We will refer to that later on.

// Create the model ... We use mongoose/mongodb model here
// But you can also implment your own model if you want
var userSchema = new require('mongoose').Schema({... Your schema definition here...});
var userModel = mongoose.model("user", userSchema);

// Create the crud router
var RouterFactory = require('node-express-crud-router').RouterFactory;
var userRouter = RouterFactory.create({
  path: "users",
  model: userModel
});

// Add router to your express app
var app = require('express')();
app.use("/api", userRouter);
// Now http://server:port/api/users is available

RouterFactory.create(opts);

var opts = {
  path: //The http url routing path valid for this router
  model: // Model used by the controller to execute the request
  before: // function((path, controller, router){...}
  after: // function(path, controller, router){...}
}

The before and after options are called before creating the router and after creating the router. Here you can intercept the router/controller creation process;

The default router is expecting a defined api on the model. This api is derived from mongoose model api.

REST API

Url schema

http://yourServer:port/api/<YourModelName>/<ModelId>?skip=<int>&limit=<int>&criteria=<JSON>&sort=<JSON>

Url query parameters

skip=<int>

Skips models from the top of the result list.

Example:

http://yourServer:port/api/yourModelName?skip=5

limit=<int>

Limits the amount of returning models to .

Example:

http://yourServer:port/api/yourModelName?limit=5

criteria=<JSON>

Provide a json object which will be used as selection condition (like where clause).

Example:

http://yourServer:port/api/yourModelName?criteria={price:{'$gt':25}}

sort=<JSON>

Provide a json object which will be used as projection like sql-where clause).

Example:

http://yourServer:port/api/yourModelName?sort={price:'desc'}

Please beware of the syntax. The criteria and sort syntax depends an the persistance layer / controller / model combination you use. The syntax used hereis the default for mongodb usage.

HTTP Verbs

All operations will return http status 200 on success. If there is any error we return http status 4XX / 5XX and an error message body with error explanation.

GET /modelName

• Criteria, sort, limit and skip parameters can be used
• Returns an array of available models

Example

GET http://server:port/modelName

// Returns
[
  {your model 1},
  {your model 2},
  // ...
]

POST /modelName

• Creates (persists) the provided http body
• Returns the persisted model object with new id property assigned

Example

POST http://server:port/modelName
{'name':'test'}

// Returns
{
  _id: ..., // in case of mongodb usage
  name: 'test'
}

PUT /modelName?criteria=<JSON>

• Updates all entities found by criteria (bulk update)
• Returns the number of affected entities

Example

PUT http://server:port/modelName?criteria=<JSON>
{'name':'test'}

// Returns
{
  numberAffected: ...
}

DELETE /model

• Deletes all available models
• Returns number of affected entities

Example

DELETE http://server:port/modelName

// Returns
{
  numberAffected: ...
}

DELETE /model?criteria=<JSON>

• Deletes all available models selected by criteria (bulk delete)
• Returns number of affected entities

Example

DELETE http://server:port/modelName

// Returns
{
  numberAffected: ...
}

GET /modelName/modelId

• Returns single model JSON object referenced by the modelId

Example

GET http://server:port/modelName/modelId

// Returns
{your model referenced by id}

DELETE /modelName/modelId

• Deletes single model referenced by modelId
• Returns following json object

Example

DELETE http://server:port/modelName/modelId

// Returns
{
  delete: true,
  model: {deleted model object}
}

PUT,POST /modelName/modelId

• Updates the referenced model
• Returns the updated model

Example:

POST http://server:port/api/modelName/modelId
{'name':'test123'}

// Returns
{
  // ...,
  name: 'test123'
}

Additional usage examples

GET http://server:port/modelName?skip=10&limit=5

• Returns JSON [{}, {}, ...]. The first 10 items will be skipped (not part of the result) and only 5 items will be returned. This also depends on the amount of available data. If there are only 3 items in database [] will be returned because of skip parameter which will skip the first 10 items.

Implement your own model

Since this implementation is heaviliy influenced by mongoose project (and was intended to be used with mongodb at first time) we use that api as default. But you welcome to implement your own model api where you can delegate the operations to another persistence api. here is the api your model have to implement:

// Find single model by id
model
  .findById(id)
  .exec(function (err, result) {

  })

// Find models by criteria with limit and skip options
model
  .find({...})
  .sort({...})
  .skip(int)
  .limit(int)
  .exec(function (err, result) {

  })

// Create new model object and persist
model
  .create({data},function (err, result) {

 })

// Update single model data
model
  .findByIdAndUpdate(id,{update data})
    .exec(function(err, result) {

    })

// Update bulk data
model
  .update({criteria},{update data}, {options}) // options: {multi: true}
    .exec(function(err, result) {

    })

// Remove all models or by selection criteria (bulk delete)
model
  .remove(null || <JSON criteria>)
  .exec(function(err) {

  })

// Remove single model found by id
model.findByIdAndRemove(id)
    .exec(function (err, removedDoc) {

    })

If you provide such a model you can use your own operations on crud requests to the router.

Testing

npm test

Before running the test you have to start a mongodb on standard port. This will fixed in future releases

Contributing

New contributors are welcome. If you have any further requests, bugs or ideas please put that on github project issues. Pull requests are welcome.

Maintainers

Dennis Ahaus (dennisahaus.github.io)

License

Copyright (c) 2015 Licensed under the MIT license. Other dependency modules may have other licenses. See license file