koa-resource-routes

A lightweight middleware for Koa for declarative action-based routing.

• Encourages modular RESTful routing scheme
• Actions are similar to established Rails routing conventions
• Supports routing for nested resources

Action-based Routing

| Action | Route | Aliases | |------------|-----------------------|-------------------| | index | GET /item | default, main | | create | POST /item | | | show | GET /item/:param | | | update | PUT /item/:param | | | destroy | DELETE /item/:param | |

Usage

This plugin is a very lightweight layer on top of koa-route that allows you to organize your routes based on resources that contain actions. Five fundamental resource actions are supported:

• index: Returns a list of the resources.
• create: Creates a resource.
• show: Shows a specific resource.
• update: Updates a specific resource.
• destroy: Destroys a specific resource.

It all works by passing in an object that contains a structured representation of your resources and actions. Resources can be nested within other resources.

var koa = require('koa');
var mount = require('koa-mount');
var resourceRoutes = require('koa-resource-routes');

var resources = {
  users: {
    index: function* (next) {
      // GET /v1/users
    },
    create: function* (next) {
      // POST /v1/users
    },
    show: function* (next) {
      // GET /v1/users/:usersParam
    },
    photos: {
      index: function* (next) {
        // GET /v1/users/:usersParam/photos
      },
      destroy: function* (next) {
        // DELETE /v1/users/:usersParam/photos/:photosParam
      }
    }
  },
  items: {
    index: function* (next) {
      // GET /v1/items
    }
  }
};

var app = koa();

// Other middleware should go here; resourceRoutes should be last

// Pass resources into middleware, and set URL prefix to '/v1'
app.use(mount('/v1', resourceRoutes(resources)));

app.listen(3000);

URL Parameters

URL parameters for a given route will be in this.params.<resourceName>Param. Here's an example for a resource called someResource.

{
  someResource: {
    show: function* (next) {
      this.body = 'Currently showing some resource with param = ' + this.params.someResourceParam;
    }
  }
}

Parameters are designed to be completely flexible. You have the choice of putting a numerical identifier or a slug.

ES6 Module Syntax

For an example of how to use this plugin with the ES6 Module Syntax, check out the Users and Events example.

Examples

• Users and Events

Installation

Run the command:

$ npm install --save koa-resource-routes

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new pull request