koa-rester

Koa based framework for deploying RESTful APIs easily

• One line to deploy a REST API from a Model
• Tested with mongoose and ORM models
• Tested with koa-router but it should work with almost any router that provides get|post|put|delete operations.
• Tested with koa-bodyparser
• Todo features are listed in #1

Installation

$ npm install koa-rester

Usage

const router = new Router();
const base = 'test';
 
router.use(bodyParser());
rester = new Rester({ router, base });
 
// Expose GET, POST /test/resource 
//        GET, PATCH, DELETE /test/resource/:id
rester.add(model, 'resource').rest({
  after: async (ctx, next) => {},
  // afterPost overwrites after for POST requests
  afterPost: async (ctx, next) => {},
});
 
// Expose GET /test/resource1 
//        GET /test/resource1/:id
rester.add(model1, 'resource1').list({
  before: async (ctx, next) => {},
}).get();
 
new Koa()
  .use(r.routes())
  .use(r.allowedMethods())
  .listen(30001);

More complex examples, with model definitions included, are located in the wiki.

API Reference

koa-rester

• koa-rester
  • Rester ⏏
    • new Rester(options)
    • instance
      • .add(model, name) ⇒ Rester
      • .rest(options) ⇒ Rester
      • .list(options) ⇒ Rester
      • .post(options) ⇒ Rester
      • .get(options) ⇒ Rester
      • .patch(options) ⇒ Rester
      • .delete(options) ⇒ Rester
    • static
      • .errorHandler(error) ⇒ Object

Rester ⏏

Kind: Exported class

new Rester(options)

Create a new Rester.

Param	Type	Description
options	Object	Configuration object. Property router is compulsory.
options.errorHandler	function	A function that receive the DB error and returns an JSON object with at least two properties status and message. Status will be the HTTP response status and the whole object will be sent as body.
options.router	Object	The koa express style router. Any router that supports get, post, put, patch and delete operations.
options.model	Object	The persistence layer model. It can be included here or by using the add() function. Use add function if the rester itself is going to be used to export multiple resources.
options.base	String	The resource base url. It can be included here or by using the add() function. Use add function if the rester itself is going to be used to export multiple resources.
options.before	function	A koa middleware to be executed before each single rest request. It can be added in get, post, put, delete, list and rest options.
options.after	function	A koa middleware to be executed after each single rest request. It can be added in get, post, put, delete, list and rest options.

rester.add(model, name) ⇒ Rester

Kind: instance method of Rester
Returns: Rester - A new Rester instance configured with the given model and base.

Param	Type	Description
model	Object	The persistence layer Model object.
name	String	The resource name used to build the resource URI

rester.rest(options) ⇒ Rester

Build the endpoints /resource and /resource/:id with the methods GET, POST PUT, PATCH and DELETE.

Kind: instance method of Rester
Returns: Rester - The Rester itself.

Param	Type	Description
options	Object	The resource specific options.
options.before	function	beforeList, beforePost, beforeGet, beforePut and/or beforeDelte: A koa middleware to be executed before the selected operation.
options.after	function	afterList, afterPost, afterGet, afterPut and/or afterDelte: A koa middleware to be executed after the selected operation.

rester.list(options) ⇒ Rester

Build the endpoint /resource allowing GET requests. It will respond with all the resources available in the persistence layer.

Kind: instance method of Rester
Returns: Rester - The Rester itself.

Param	Type	Description
options	Object	The endpoint specific options.

rester.post(options) ⇒ Rester

Build the endpoint /resource allowing POST requests. It will save the resource received in the persistence layer.

Kind: instance method of Rester
Returns: Rester - The Rester itself.

Param	Type	Description
options	Object	The endpoint specific options.

rester.get(options) ⇒ Rester

Build the endpoint /resource/:id allowing GET requests. It will return the resource with the id given in the url.

Kind: instance method of Rester
Returns: Rester - The Rester itself.

Param	Type	Description
options	Object	The endpoint specific options.

rester.patch(options) ⇒ Rester

Build the endpoint /resource/:id allowing PATCH requests. It will modify the resource with the id given in the url.

Kind: instance method of Rester
Returns: Rester - The Rester itself.

Param	Type	Description
options	Object	The endpoint specific options.

rester.delete(options) ⇒ Rester

Build the endpoint /resource/:id allowing DELETE requests. It will remove the resource with the id given in the url.

Kind: instance method of Rester
Returns: Rester - The Rester itself.

Param	Type	Description
options	Object	The endpoint specific options.

Rester.errorHandler(error) ⇒ Object

Converts a persistence layer error into a JSON error. JSON errors must have at least 2 properties 'status' and 'message'. Status will be the http status code of the response so it must be a valid one. This handler supports only mongoose and orm2 errors. If any other DBMS is required it can be overwritten via Rester's option errorHandler.

Kind: static method of Rester
Returns: Object - The JSON that should be returned via http.

Param	Type	Description
error	Object	The error object thrown from the persistence layer.