koa-mongo-router

KOA REST API Router for MongoDB

A router that exposes a standard REST API for a MongoDB

Status: BETA

1. Usage
2. Mongo Routes
3. Query String

Usage

npm install koa-mongo-router

import { getDatabaseRouter } from 'koa-mongo-router'
import { IDatabaseRouterOptions } from 'koa-mongo-router/lib/database-router-options'

const databaseRouterOptions: IDatabaseRouterOptions = {
    permissionCheck: async (
        ctx: Koa.Context,
        next: () => Promise<any>,
        database: string,
        collection: string
    ) => {
        // Assumes you have middleware that already adds a user
        if (ctx.state.user == undefined) {
            ctx.status = 401
            return
        }

        // Example of validating if a user has read or write permissions
        switch (ctx.Method) {
            case "GET":
                if (!ctx.state.user.canRead(database, collection)) {
                    ctx.status = 403
                    return
                }
                break

            case "PUT":
            case "POST":
            case "PATCH":
            case "DELETE":
                if (!ctx.state.user.canWrite(database, collection)) {
                    ctx.status = 403
                    return
                }
                break
        }

        // If user haas permission for method, then continue on
        await next()
    }
};

const mongoRouter = getDatabaseRouter(databaseRouterOptions)

const app = new Koa()
    .use(mongoRouter.routes())
    .use(mongoRouter.allowedMethods())

Mongo Routes

Method	Route	Description	Notes
GET	/	Get databases
GET	/:database	Get database collections
DELETE	/:database	Delete database
GET	/:database/:collection	Get collection items	Query String
POST	/:database/:collection	Create a collection item
PUT	/:database/:collection	Create or replace collection items	Query String Filtering
PATCH	/:database/:collection	Update collection items	Query String Filtering
DELETE	/:database/:collection	Delete collection items	Query String Filtering
GET	/:database/:collection/:id	Get a collection item
PUT	/:database/:collection/:id	Create or replace a collection item
PATCH	/:database/:collection/:id	Update a collection item
DELETE	/:database/:collection/:id	Delete a collection item
GET	/:database/:collection/schema	Get collection schema
PUT	/:database/:collection/schema	Put collection schema
DELETE	/:database/:collection/schema	Delete collection schema
GET	/:database/:collection/indices	Get collection indices
POST	/:database/:collection/indices	Create collection index
DELETE	/:database/:collection/indices/:name	Delete collection index

Get Items

Get items from a collection. Items can be filtered, paged, sorted, and counted using query string parameters.

Request	Parameters	Notes
Method	GET
Path	/:database/:collection
Returns	An array of items
Codes	200 Success
	304 Not Modified	Conditional GET

Create An Item

Create a new item. This creates a new _id and assigns it to the item.

Request	Parameters
Method	POST
Path	/:database/:collection
Body	The item to create
Returns	The id of the created item
Status Codes	201 Created

Create Or Replace Items

Create or replace items.

Request	Parameters
Method	PUT
Path	/:database/:collection
Body	An array of items
Status Codes	200 OK

Update Items

Update items.

Request	Parameters
Method	UPDATE
Path	/:database/:collection
Body	The patch for the items
Status Codes	200 OK

Delete Items

Delete items.

Request	Parameters
Method	DELETE
Path	/:database/:collection
Status Codes	200 OK

Get An Item

Get an item.

Request	Parameters
Method	GET
Path	/:database/:collection/:id
Status Codes	200 OK
	404 Not Found

Get Or Replace An Item

Get or replace an item.

Request	Parameters
Method	PUT
Path	/:database/:collection/:id
Body	The item
Status Codes	200 OK
	201 Created

Update An Item

Update an item.

Request	Parameters
Method	PATCH
Path	/:database/:collection/:id
Body	The patch for the item
Status Codes	200 OK
	404 Not Found

Delete An Item

Delete an item.

Request	Parameters
Method	DELETE
Path	/:database/:collection/:id
Status Codes	200 OK
	404 Not Found

Query String

Query String Options

Option	Description	Example
$limit	Limit the number of items	?$limit=10
$skip	Skip the given number of items	?$skip=20
$fields	Return only specified fields	?$fields=name,description
$sort	Sort on specified fields	?$sort=name,-description
$count	Return the total count header	?$count
$paginate	Return pagination header	?$paginate

Query String Filtering

Operation	Query String
field exists	?foo
field does not exist	?!foo
field equals	?foo=bar
field equals a string (don't cast)	?foo:=bar
field does not equal	?foo!=bar
field greater than	?foo>10
field less than	?foo<10
field greater than or equal to	?foo>=10
field less than or equal to	?foo<=10
field equals any of	?foo=bar&foo=baz
field does not equal any of	?foo!=bar&foo!=baz
field contains case-insensitive string	?foo~=bar
field starts with case-insensitive string	?foo^=bar
field ends with case-insensitive string	?foo$=bar
record exists	?!