auto-crud
Introduction
auto-crud is an abstraction layer for generating REST routes to perform basic CRUD operations. It glues together express, mongo and json-schema validation. The end goal is to define CRUD APIs in a declarative and uniform way instead of writing route handlers directly.
Also available through NPM: npm install auto-crud
Defining an API
The auto-crud module exports a single function which takes a configuration object as its only input.
;
Configuration object parameters
app
The express application object. This is used to generate REST routes for GET, POST, PUT and DELETE.collection
The mongo collection object. This is where the API will store its data. NOTE: this tool will not ensure indexes.name
The name of this API's objects, this will also be appended to the end of the path param when generating routes.path
The root path for the routes generated by this API.schema
The json-schema that will be used to validate objects given to the API by POST and PUT.
Optional parameters
getCreate
If true a get and get by id method will be registered with express.postCreate
If true a post method will be registered with express.putCreate
If true a put by id method will be registered with express.deleteCreate
If true a delete by id method will be registered with express.
NOTE: The Autocrud object will have all the http methods callable from other objects in the server, regardless of being registered with express.
Input Transformation
It is often that input data from a client application differs from how you want to store data in your database. So, auto-crud allows you to specify transformation functions, which will be called after the input object has been validated, but before a database insert or update.
;
Transform functions take a single parameter, which is the message body after it has been validated.
defaultTransform
If specified, this transform function will be applied to both POST and PUT operations.postTransform
If specified, this function will be used for POST operations, overriding the defaultTransform.putTransform
If specified, this function will be used for PUT operations, overriding the defaultTransform.
Route Authentication
No API would be complete without having an authentication mechanism. This is supported by adding an express middleware function to the configuration object. This allows auto-crud to be agnostic about how users are authenticated. I tend to prefer passport, so that is what is shown in the example.
;
defaultAuthentication
If specified, this middleware will by applied to all HTTP methods on the auto-curd route.getAuthentication
If specified, this middleware will be applied to the GET HTTP method. Overrides default.postAuthentication
If specified, this middleware will be applied to the POST HTTP method. Overrides default.putAuthentication
If specified, this middleware will be applied to the PUT HTTP method. Overrides default.deleteAuthentication
If specified, this middleware will be applied to the DELETE HTTP method. Overrides default.
Object Ownership
Often, the API doesn't need to authenticate users based on any sort of roles, but upon what objects are actually owned by the user. auto-crud provides a facility to automatically tag mongo documents with a value representing the owner. Typically this is the ObjectID of the user in question.
;
It is also possible to tell autocrud that objects own themselves. This is useful for the case in which you have a user object, as a user should be able to edit itself and only itself. When an object owns itself, the POST method does not require authentication to use. This allows new users registering with your site to create an account, then login to modify it. NOTE: You cannot specify ownerSelf and ownerField at the same time. When an object owns itself, its ownerField is always its own "_id" field.
;
NOTE: To enable object ownership the ownerIdFromReq
field and either the ownerField
or ownerSelf
fields must be
provided. You cannot use ownerField
and ownerSelf
at the same time.
ownerIdFromReq
A function that extracts the user id value from the request object. This is passed as the first param.ownerField
The name of the field in each mongo document that holds the owner id.ownerSelf
If true the object uses its own "_id" field as its ownerField.
Schema Additives
There are a few additional tags that Autocrud will read from JSON-Schemas. These allow you to manipulate how Autocrud
will present data to the user as well as how to validate data. These tags will not interfere with the json-schema
library's normal validation process.
;
hidden
If a field is marked hidden it will have normal validation applied to it during POST and PUT calls, but will not be returned to the user during GET calls.
Schema Variants
Autocrud will generate separate validation schemas for POST and PUT calls. Each element in a schema may be suffixed
with either "_post" or "_put". When a suffix is provided, the value of the tag will only be used in the schema that
matches the suffix. For example, if you need a field to be required for POST calls but not for PUT calls, use "required_post"
instead of "required". Additionally, the schemas are parsed separately, this means that a field can be of a different
type in POST calls than in PUT calls (i.e. fieldName: {type_post: 'string', type_put: 'integer'}
).
;
Events
There are a handful of events that will be fired with http calls to the Autocrud object.
get
Called when get by search http route is accessed.documents
The documents that were returned as a result of the search call. Only the current page if limit and skip are provided.count
The total number of documents in the database that matched the search criteria
getId
Called when get by id http route is accessed.id
The id of the resource accessed.document
The document that was returned to the caller.
post
document
The document that was inserted to the database.
putId
id
The id of the resource accessed.document
The changes that were made to the database document.modCount
The number of documents that were updated.
deleteId
id
The id of the resource deleted.modCount
The number of documents that were deleted.
Breaking Changes
>= 0.2.4
The POST function no longer returns a whole document when called. Going forward it will only return a root object that contains the ObjectID of the newly created document.