koa-mongo-router
Version:
KOA REST API Router for MongoDB
225 lines (177 loc) • 9.44 kB
Markdown
# KOA REST API Router for MongoDB
A router that exposes a standard REST API for a MongoDB
## Status: BETA
[](https://travis-ci.com/jamestalton/koa-mongo-router)
1. [Usage](#Usage)
1. [Mongo Routes](#Mongo-Routes)
1. [Query String](#Query-String)
## Usage
```bash
npm install koa-mongo-router
```
```TypeScript
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](#Get-Items) | [Query String](#Query-String) |
| POST | /:database/:collection | [Create a collection item](#Create-An-Item) |
| PUT | /:database/:collection | [Create or replace collection items](#Create-Or-Replace-Items) | [Query String Filtering](#Query-String-Filtering) |
| PATCH | /:database/:collection | [Update collection items](#Update-Items) | [Query String Filtering](#Query-String-Filtering) |
| DELETE | /:database/:collection | [Delete collection items](#Delete-Items) | [Query String Filtering](#Query-String-Filtering) |
| GET | /:database/:collection/:id | [Get a collection item](#Get-An-Item) |
| PUT | /:database/:collection/:id | [Create or replace a collection item](#Get-Or-Replace-An-Item) |
| PATCH | /:database/:collection/:id | [Update a collection item](#Update-An-Item) |
| DELETE | /:database/:collection/:id | [Delete a collection item](#Delete-An-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](#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 | ?! |