Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/dicearr/koa-rester

Koa library for deploying RESTful APIs easily
https://github.com/dicearr/koa-rester
koa koa-rester koa2 koajs productivity productivity-booster rest rester restful restful-api
Last synced: about 2 months ago
JSON representation
Koa library for deploying RESTful APIs easily
Host: GitHub
URL: https://github.com/dicearr/koa-rester
Owner: dicearr
License: mit
Archived: true
Created: 2017-03-13T22:27:35.000Z (over 7 years ago)
Default Branch: master
Last Pushed: 2017-10-12T14:01:45.000Z (about 7 years ago)
Last Synced: 2024-09-26T16:40:21.077Z (about 2 months ago)
Topics: koa, koa-rester, koa2, koajs, productivity, productivity-booster, rest, rester, restful, restful-api
Language: JavaScript
Homepage:
Size: 112 KB
Stars: 5
Watchers: 3
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project

README

        # koa-rester

[![Build Status](https://travis-ci.org/dicearr/koa-rester.svg?branch=master)](https://travis-ci.org/dicearr/koa-rester)

[![Coverage Status](https://coveralls.io/repos/github/dicearr/koa-rester/badge.svg?branch=master)](https://coveralls.io/github/dicearr/koa-rester?branch=master)

[![dependencies Status](https://david-dm.org/dicearr/koa-rester/status.svg)](https://david-dm.org/dicearr/koa-rester)

[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1307/badge)](https://bestpractices.coreinfrastructure.org/projects/1307)

![Downloads](https://img.shields.io/npm/dm/koa-rester.png)

> [Koa](https://github.com/koajs/koa) based framework for deploying RESTful APIs easily. Inspired by [travist/resourcejs](https://github.com/travist/resourcejs).

* One line to deploy a REST API from a Model

* Persistence packages (see [wiki](https://github.com/dicearr/koa-rester/wiki) if you want to create your own)

  * In memory [dicearr/kr-persistence-inmemory](https://github.com/dicearr/kr-persistence-inmemory)

  * Mongoose [dicearr/kr-persistence-mongoose](https://github.com/dicearr/kr-persistence-mongoose)

    * Working examples [dicearr/kr-example-mongoose](https://github.com/dicearr/kr-example-mongoose)

  * ~~Sequelize [dicearr/kr-persistence-sequelize](https://github.com/dicearr/kr-persistence-sequelize)~~

* [koa-router](https://github.com/alexmingoia/koa-router/tree/master/) is used internally.

* Tested with [koa-bodyparser](https://github.com/koajs/bodyparser), other parsers could work.

* Todo features are listed in [\#1](https://github.com/dicearr/koa-rester/issues/1)

## Installation

```

$ npm install koa-rester

```

## Usage

```javascript

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](https://github.com/dicearr/koa-rester/wiki).

## API Reference

## Classes



Rester



Resource







## Rester

**Kind**: global class  

* [Rester](#Rester)

    * [new Rester(options)](#new_Rester_new)

    * [.swagger(options)](#Rester+swagger)

    * [.add(model, name)](#Rester+add) ⇒ [Resource](#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](https://github.com/alexmingoia/koa-router#new_module_koa-router--Router_new) 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](https://github.com/dicearr/kr-presistence-sequelize), [kr-persistence-inmemory](https://github.com/dicearr/kr-persistence-inmemory) or [kr-presistence-mongoose](https://github.com/dicearr/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](#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](#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](#Rester)  

**Returns**: [Resource](#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](#Resource)

    * [new Resource(options)](#new_Resource_new)

    * [.list(options)](#Resource+list) ⇒ [Resource](#Resource)

    * [.get(options)](#Resource+get) ⇒ [Resource](#Resource)

    * [.post(options)](#Resource+post) ⇒ [Resource](#Resource)

    * [.patch(options)](#Resource+patch) ⇒ [Resource](#Resource)

    * [.put(options)](#Resource+put) ⇒ [Resource](#Resource)

    * [.delete(options)](#Resource+delete) ⇒ [Resource](#Resource)

    * [.rest(options)](#Resource+rest) ⇒ [Resource](#Resource)

    * [.routes()](#Resource+routes) ⇒ function

    * [.allowedMethods()](#Resource+allowedMethods) ⇒ function



### new Resource(options)

Should not be used directly. Build Resource through [Rester.add](#Rester+add).

| Param | Type | Description |

| --- | --- | --- |

| options | Object | Configuration options |



### resource.list(options) ⇒ [Resource](#Resource)

Create the GET /resource endpoint in the Resource router.

**Kind**: instance method of [Resource](#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](#Resource)

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

**Kind**: instance method of [Resource](#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](#Resource)

Create the POST /resource endpoint in the Resource router.

**Kind**: instance method of [Resource](#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](#Resource)

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

**Kind**: instance method of [Resource](#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](#Resource)

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

**Kind**: instance method of [Resource](#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](#Resource)

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

**Kind**: instance method of [Resource](#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](#Resource)

Create all the endpoints

**Kind**: instance method of [Resource](#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)  



### resource.allowedMethods() ⇒ function

Sugar syntax that returns resource.router.allowedMethods()

**Kind**: instance method of [Resource](#Resource)