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.

1
2// Create the model ... We use mongoose/mongodb model here
3// But you can also implment your own model if you want
4var userSchema = new require('mongoose').Schema({... Your schema definition here...});
5var userModel = mongoose.model("user", userSchema);
6
7// Create the crud router
8var RouterFactory = require('node-express-crud-router').RouterFactory;
9var userRouter = RouterFactory.create({
10  path: "users",
11  model: userModel
12});
13
14// Add router to your express app
15var app = require('express')();
16app.use("/api", userRouter);
17// Now http://server:port/api/users is available

RouterFactory.create(opts);

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

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

1http://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:

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

limit=<int>

Limits the amount of returning models to .

Example:

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

criteria=<JSON>

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

Example:

1http://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:

1http://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

1GET http://server:port/modelName
2
3// Returns
4[
5  {your model 1},
6  {your model 2},
7  // ...
8]

POST /modelName

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

Example

1POST http://server:port/modelName
2{'name':'test'}
3
4// Returns
5{
6  _id: ..., // in case of mongodb usage
7  name: 'test'
8}

PUT /modelName?criteria=<JSON>

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

Example

1PUT http://server:port/modelName?criteria=<JSON>
2{'name':'test'}
3
4// Returns
5{
6  numberAffected: ...
7}

DELETE /model

• Deletes all available models
• Returns number of affected entities

Example

1DELETE http://server:port/modelName
2
3// Returns
4{
5  numberAffected: ...
6}

DELETE /model?criteria=<JSON>

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

Example

1DELETE http://server:port/modelName
2
3// Returns
4{
5  numberAffected: ...
6}

---

GET /modelName/modelId

• Returns single model JSON object referenced by the modelId

Example

1GET http://server:port/modelName/modelId
2
3// Returns
4{your model referenced by id}

DELETE /modelName/modelId

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

Example

1DELETE http://server:port/modelName/modelId
2
3// Returns
4{
5  delete: true,
6  model: {deleted model object}
7}

PUT,POST /modelName/modelId

• Updates the referenced model
• Returns the updated model

Example:

1POST http://server:port/api/modelName/modelId
2{'name':'test123'}
3
4// Returns
5{
6  // ...,
7  name: 'test123'
8}

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:

1
2// Find single model by id
3model
4  .findById(id)
5  .exec(function (err, result) {
6
7  })
8
9// Find models by criteria with limit and skip options
10model
11  .find({...})
12  .sort({...})
13  .skip(int)
14  .limit(int)
15  .exec(function (err, result) {
16
17  })
18
19// Create new model object and persist
20model
21  .create({data},function (err, result) {
22
23 })
24
25// Update single model data
26model
27  .findByIdAndUpdate(id,{update data})
28    .exec(function(err, result) {
29
30    })
31
32// Update bulk data
33model
34  .update({criteria},{update data}, {options}) // options: {multi: true}
35    .exec(function(err, result) {
36
37    })
38
39// Remove all models or by selection criteria (bulk delete)
40model
41  .remove(null || <JSON criteria>)
42  .exec(function(err) {
43
44  })
45
46// Remove single model found by id
47model.findByIdAndRemove(id)
48    .exec(function (err, removedDoc) {
49
50    })

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