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. |