restal

restal

This is a simple restful api generator with express & mongoose.

Install

$ npm i restal -S

Usage

// connect to mongodb and create a mongoose model
const mongoose = require('mongoose')
mongoose.Promise = Promise
mongoose.connect('mongodb://localhost/test', { useMongoClient: true })
const Post = new mongoose.Schema({
    title: String,
    content: { type: String, required: true },
    classification: String
})
const post = mongoose.model('post', Post)

// create a express app
const express = require('express')
const bodyParser = require('body-parser')
const app = express()
app.use(bodyParser.json())

// import restal
const Restal = require('restal')
// create a restal instance with a model, and mount it on a uri
const postApis = new Restal(post, '/post')
// inject the apis into the express app
postApis.inject(app)

// listening
app.listen(8000)

Public Fields & Methods

constructor	remark
Restal(model, uri)	create a restal api instance

field	remark
uri	the uri that restal instance mounted
model	the model that restal instance associated

method	remark
inject(app)	inject the apis into the express app
preHandle(method, handler)	unshift pre-hanlde middleware(s)
postHandle(method, handler)	push post-hanlde middleware(s)

APIs

APIs are generated by restal when the restal instance created. And the APIs support five HTTP methods listed below.

method	query params	json body	remark
GET	id, cond, skip, num	(none)	get document(s)
POST	(none)	document	create document
PUT	id	document	update the whole document
PATCH	id	some document props	update some document props
DELETE	id, cond	(none)	delete document(s)

After injection, APIs are routed by the express app and become active when the app is listening. The request body type of POST, PUT and PATCH is json and all responses are in json. So, the express app need to use body-parser before being injected.

GET

query params	type	requirement	remark
id	ObjectID(_id)	optional	highest priority, ignore other params
cond	json	optional	query object for mongodb, see mongodb manual
skip	number	optional	number of documents skipped, default 0
num	number	optional	number of documents requested, default all

No request body is needed. If all query params are missing, all documents of the collection will be responsed.

POST

No query params needed but request body (the document object to create) is required in json.

PUT

query params	type	requirement	remark
id	ObjectID(_id)	required	locate the document needed to be updated

The request body (the document object to update) is also required in json. The offered document will overwrite the whole original document in mongodb.

PATCH

query params	type	requirement	remark
id	ObjectID(_id)	required	locate the document needed to be updated

The request body (some document props to update) is also required in json. The offered document props will overwrite those of original document in mongodb.

DELETE

query params	type	requirement	remark
id	ObjectID(_id)	required	highest priority, ignore "cond" param
cond	json	optional	query object for mongodb, see mongodb manual

No request body is needed. If all query params are missing, all documents of the collection will be deleted.

Extention

Features of express middleware are fully maintained in restal, and it's convenient to extend the restal instance handlers.

// import restal
const Restal = require('restal')
// create a restal instance with a model, and mount it on a uri
const postApis = new Restal(post, '/post')

//              ----+----+----+---------+----+----+----
// preHandle -> ... | f2 | f1 | handler | f1 | f2 | ... <- postHandle
//              ----+----+----+---------+----+----+----

// add middleware(s) to pre-hanlde or intercept the request
postApis.preHandle('get', (req, res, next) => {
    const postModel = postApis.model
    const postUri = postApis.uri
    // do something here like authorization check
    
    // if next misses, original handler will be blocked
    // and you need to reponse on your own
    next()
})
// add middleware to post-handle the result
postApis.postHandle('get', (result, req, res, next) => {
    const postModel = postApis.model
    const postUri = postApis.uri
    // do somethind here like data processing

    // if you push post handler, the orignal handler won't
    // reponse the request and pass the orignal reponse to
    // post handler with param "result"

    // you need to reponse on your own
    res.status(200).send(result)
})

// inject the apis into the express app
postApis.inject(app)