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 | ?! |