koa-rester

Koa based framework for deploying RESTful APIs easily. Inspired by travist/resourcejs.

• One line to deploy a REST API from a Model
• Persistence packages (see wiki if you want to create your own)
  • In memory dicearr/kr-persistence-inmemory
  • Mongoose dicearr/kr-persistence-mongoose
    • Working examples dicearr/kr-example-mongoose
  • Sequelize dicearr/kr-persistence-sequelize
• koa-router is used internally.
• Tested with koa-bodyparser, other parsers could work.
• Todo features are listed in #1

Installation

$ npm install koa-rester

Usage

const koa = new Koa()
const rester = new Rester({
  persistence: require('kr-persistence-inmemory'),
})

koa.use(bodyParser())
/*
 * GET /name
 * GET /name/:id
 * POST /name
 * PUT /name/:id
 * PATCH /name/:id
 * DELETE /name/:id
 */
const nameResource = rester.add(model, 'name').rest()
/*
 * GET /otherName
 * GET /otherName/:id
 * POST /otherName
 */
const otherResource = rester.add(otherModel, 'otherName').get().list().post()

koa
  .use(nameResource.routes())
  .use(nameResource.allowedMethods())
  .use(otherResource.routes())
  .use(otherResource.allowedMethods())

More examples can be found in the wiki.

API Reference

Classes

Rester

Resource

Rester

Kind: global class

• Rester
  • new Rester(options)
  • .swagger(options)
  • .add(model, name) ⇒ Resource

new Rester(options)

Create a rester.

Param	Type	Description
options	Object	Configuration object.
options.router	Router	The router to be used, by default koa-router, change this property can break the package.
options.routerOptions	Object	The options that will be passed to koa-router constructor. If options.router is overwritten with any other router this options must be changed according to the new router.
options.logger	function	The logger that will be used
options.persistence	KoaResterPersistence	An instance of KoaResterPersistence, such as kr-presistence-sequelize, kr-persistence-inmemory or kr-presistence-mongoose. This property is compulsory, an error will be thrown if it is not present.

rester.swagger(options)

Adds the required metadata to the Swagger documentation.

Kind: instance method of Rester

Param	Type	Description
options	Object	Swagger metadata
options.info	Object	Global information
options.info.version	String	The API version
options.info.title	String	The API title
options.info.description	String	The API description
options.host	String	The API host

rester.add(model, name) ⇒ Resource

Create a Resource configured on top of the rester, this Resource instance has it own Router and KoaResterPersistence instances.

Kind: instance method of Rester
Returns: Resource - A Resource instance

Param	Type	Description
model	Object	A native instance of the supported ORM. If persitence is kr-presistence-mongoose it should be a Mongoose model.
name	String	The resource name used to build the resource URI without slashes i.e. 'resourceName'.

Resource

Kind: global class

• Resource
  • new Resource(options)
  • .list(options) ⇒ Resource
  • .get(options) ⇒ Resource
  • .post(options) ⇒ Resource
  • .patch(options) ⇒ Resource
  • .put(options) ⇒ Resource
  • .delete(options) ⇒ Resource
  • .rest(options) ⇒ Resource
  • .routes() ⇒ function
  • .allowedMethods() ⇒ function

new Resource(options)

Should not be used directly. Build Resource through Rester.add.

Param	Type	Description
options	Object	Configuration options

resource.list(options) ⇒ Resource

Create the GET /resource endpoint in the Resource router.

Kind: instance method of Resource

Param	Type	Description
options	Object
options.before	function	The middleware or array of middlewares that will be executed before the list method.
options.after	function	The middleware or array of middlewares that will be executed after the list method.

resource.get(options) ⇒ Resource

Create the GET /resource/:id endpoint in the Resource router.

Kind: instance method of Resource

Param	Type	Description
options	Object
options.before	function	The middleware or array of middlewares that will be executed before the list method.
options.after	function	The middleware or array of middlewares that will be executed after the list method.

resource.post(options) ⇒ Resource

Create the POST /resource endpoint in the Resource router.

Kind: instance method of Resource

Param	Type	Description
options	Object
options.before	function	The middleware or array of middlewares that will be executed before the create method.
options.after	function	The middleware or array of middlewares that will be executed after the create method.

resource.patch(options) ⇒ Resource

Create the PATCH /resource/:id endpoint in the Resource router.

Kind: instance method of Resource

Param	Type	Description
options	Object
options.before	function	The middleware or array of middlewares that will be executed before the update method.
options.after	function	The middleware or array of middlewares that will be executed after the update method.

resource.put(options) ⇒ Resource

Create the PUT /resource/:id endpoint in the Resource router.

Kind: instance method of Resource

Param	Type	Description
options	Object
options.before	function	The middleware or array of middlewares that will be executed before the replace method.
options.after	function	The middleware or array of middlewares that will be executed after the replace method.

resource.delete(options) ⇒ Resource

Create the DELETE /resource/:id endpoint in the Resource router.

Kind: instance method of Resource

Param	Type	Description
options	Object
options.before	function	The middleware or array of middlewares that will be executed before the delete method.
options.after	function	The middleware or array of middlewares that will be executed after the delete method.

resource.rest(options) ⇒ Resource

Create all the endpoints

Kind: instance method of Resource

Param	Type	Description
options	Object	The configuration for all the endpoints
options.before	function	The middleware or array of middlewares that will be executed before any method.
options.after	function	The middleware or array of middlewares that will be executed after all the methods.
options.afterList	function	options.after for list()
options.beforeList	function	options.before for list()
options.afterGet	function	options.after for get()
options.beforeGet	function	options.before for get()
options.afterPost	function	options.after for post()
options.beforePost	function	options.before for post()
options.afterPut	function	options.after for put()
options.beforePut	function	options.before for put()
options.afterDelete	function	options.after for delete()
options.beforeDelete	function	options.before for delete()
options.afterPatch	function	options.after for patch()
options.beforePatch	function	options.before for patch()

resource.routes() ⇒ function

Sugar syntax that returns resource.router.routes()

Kind: instance method of Resource

resource.allowedMethods() ⇒ function

Sugar syntax that returns resource.router.allowedMethods()

Kind: instance method of Resource