Skip to content

amsardesai/koa-resource-routes

Repository files navigation

koa-resource-routes

Build Status npm version Dependency Status

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

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

About

RESTful action-based resource routing with Koa

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published