Sempervirens Plugin: Persistence Endpoints
A set of endpoints to facilitate create, read, update, and delete operations via Express on MongoDB
Contents
Installation
npm i @sempervirens/plugin-persistence-endpoints
Usage
In the Code Example below are some examples of basic usage. After plugging persistenceEndpoints
into the server's endpoints array and configuring it with one or more object(s) containing a modelName
, the endpoints to create, delete, find, and update the model's records become available.
Endpoints
Create records with the request body.
POST http://localhost[:{port}]/{domain}/{api|apiBaseUrl}/{kebab-case-model-name|modelBaseUrl}/create
POST http://{domain}/{api|apiBaseUrl}/{kebab-case-model-name|modelBaseUrl}/create
Delete records with the given ID(s).
DELETE http://localhost[:{port}]/{domain}/{api|apiBaseUrl}/{kebab-case-model-name|modelBaseUrl}/delete/{id1,id2}
DELETE http://{domain}/{api|apiBaseUrl}/{kebab-case-model-name|modelBaseUrl}/delete/{id1,id2}
Find the records matching the given criteria.
GET http://localhost[:{port}]/{domain}/{api|apiBaseUrl}/{kebab-case-model-name|modelBaseUrl}/find[/{ids}[?filters=[&sort=[&page=[&perPage=[&select=[&populate]]]]]]]]
GET http://{domain}/{api|apiBaseUrl}/{kebab-case-model-name|modelBaseUrl}/find[/{ids}[?filters=[&sort=[&page=[&perPage=[&select=[&populate]]]]]]]]
Update the records matching given critiera using the request body.
PATCH http://localhost[:{port}]/{domain}/{api|apiBaseUrl}/{kebab-case-model-name|modelBaseUrl}/update[/{ids}[?filters=[&sort=[&populate]]]]]]]
PATCH http://{domain}/{api|apiBaseUrl}/{kebab-case-model-name|modelBaseUrl}/update[/{ids}[?filters=[&sort=[&populate]]]]]]]
Code Example
import { readFileSync } from 'fs';
import mongoose from 'mongoose';
import authorizer from '@sempervirens/authorizer';
import dao from '@sempervirens/dao';
import Server from '@sempervirens/server';
import persistenceEndpoints from '@sempervirens/plugin-persistence-endpoints';
authorizer.init({
jwtPublicKey: readFileSync('/path/to/public.key', 'utf8'),
jwtPrivateKey: readFileSync('/path/to/private.key', 'utf8')
});
dao.initDb({
host: 'localhost',
port: 27017,
connectionOptions: {
useNewUrlParser: true,
useUnifiedTopology: true
},
name: 'testdb',
models: [
{
name: 'Test1',
schema: new mongoose.Schema({
prop1a: { type: String },
prop1b: { type: String }
})
},
{
name: 'Test2',
schema: new mongoose.Schema({
prop2a: { type: String },
prop2b: { type: String },
test1: { type: mongoose.Types.ObjectId, ref: 'Test1' }
})
}
]
});
new Server({
sites: [
{
domain: 'site-1',
data: { dbName: 'testdb' },
endpoints: [
...persistenceEndpoints([
{
modelName: 'Test1' // Available at /api/test-1/create, delete, find, update
},
{
modelName: 'Test1',
modelBasePath: 'test-1a', // Available at /api-1/test-1a/create, delete, find, update
apiBasePath: 'api-1',
find: { max: 100 } // Only allow 100 records per request
},
{
modelName: 'Test2',
modelBasePath: 'test-2',
create: {
// On /create, take the "_id" from the token data and add it to
// the "test1" property of the created record
bindWithToken: {
tokenKey: '_id',
recordKey: 'test1'
}
},
find: {
bindWithToken: {
// On /find, return only those records where the "_id" from the
// token data matches the "test1" property of the records
tokenKey: '_id',
recordKey: 'test1'
}
}
}
])
]
}
]
}).start();
API
modelName
The name of the model that the endpoints operate on.
modelBasePath
By default the modelBasePath
is kebab-case modelName
. The modelBasePath
property enables a custom definition.
apiBasePath
The base API path is usually /api
. If the apiBasePath
is specified at the site level (same level as domain
, data
, endpoints
, etc.), then it should be specified in the persistenceEndpoints
configuration as well in order for the endpoints to be available at the specified path and for API validation to work.
max
Specified per endpoint. max
records allowed per request.
{
modelName: 'Test1',
create: { max: 100 },
delete: { max: 5 },
find: { max: 200 },
update: { max: 10 }
}
isSecure
Specified per endpoint. If present, isSecure
ensures the endpoint will not process requests when a valid "Authorization": "Bearer {token}"
header is not present. See @sempervirens/authorizer or @sempervirens/plugin-session-endpoints for an explanation of how to generate JWT tokens and pass them to the frontend so the frontend can add them to the request header.
{
modelName: 'Test1',
create: { isSecure: true },
delete: { isSecure: true },
find: { isSecure: true },
update: { isSecure: true }
}
bindWithToken
Specified per endpoint. The purpose of bindWithToken
is to bind requests so that when calling the delete
, find
, and update
endpoints, the value of the given property on the model record must match a property and value in the authroization token. This is useful for example to bind a user's ID to models so that the user can only operate on their own records.
If passed into the create
configuration, rather than checking the value for validity as in the other endpoitns, it sets the value. In the following example, when /test-2/create
is called, it takes the token from the header, decrypts it, gets the _id
property from it, and sets the test1
property of the new Test2
record to the value from the token.
{
modelName: 'Test2',
create: {
bindWithToken: {
tokenKey: '_id',
recordKey: 'test1'
}
},
delete: {
bindWithToken: {
tokenKey: '_id',
recordKey: 'test1'
}
},
find: {
bindWithToken: {
tokenKey: '_id',
recordKey: 'test1'
}
},
update: {
bindWithToken: {
tokenKey: '_id',
recordKey: 'test1'
}
}
}