API Endpoints¶

List Resources GET¶

This entrypoint returns a set of resources.

GET /{base_url}

Parameters¶

Name	Type	In	Description
`limit`	number	query	The maximum number of documents
`page`	number	query	The page number of documents; starts from 1
`include_permissions`	boolean	query	Whether to include document permissions in each document
`include_count`	boolean	query	Whether to include total results count
`lean`	boolean	query	Whether to pass plain objects, not Mongoose Documents, in middleware

Example¶

request¶

curl \
  -H "Accept: application/json" \
  https://example.com/users?limit=100&page=5&include_permissions=false&include_count=false&lean=true

response¶

Status: 200

[
  {
    "name": "Andrew",
    "address": "5d6ede6a0ba62570afcedd3a",
    "roles": ["user"],
    "creditBalance": 100,
    "loginDate": "2022-02-22T02:02:22.679Z"
  }
]

List Resources POST¶

This entrypoint returns a set of resources.

POST /{base_url}/__query

Parameters¶

Name	Type	In	Description
`query`	object	body	Mongoose Query object
`select`	object \| array<string>	body	Document fields to include or exclude
`populate`	array<string> \| array<object>	body	Document fields to populate
`sort`	object	body	Document sort order
`limit`	number	body	The maximum number of documents
`page`	number	body	The page number of documents; starts from 1
`options.includePermissions`	boolean	body	Whether to include document permissions in each document
`options.includeCount`	boolean	body	Whether to include total results count
`options.populateAccess`	'list' \| 'read'	body	The access level to use in `populate` method
`options.lean`	boolean	body	Whether to pass plain objects, not Mongoose Documents, in middleware

Example¶

request¶

curl \
  -X POST \
  -H "Accept: application/json" \
  https://example.com/users/__query \
  -d '{
    "query": { "loginDate": { "$gte": "2022-02-22T02:02:22.679Z" } },
    "select": ["name", "address"],
    "populate": ["address"],
    "sort": { "createdAt": -1 },
    "limit": 100,
    "page": 5,
    "options": {
      "includePermissions": true,
      "includeCount": true,
      "populateAccess": "list",
      "lean": true
    }
  }'

response¶

Status: 200

{
  "count": 2,
  "rows": [
    {
      "_id": "5d6ede6a0ba62570afcedd3a",
      "name": "Mike",
      "address": {
        "city": "Seattle",
        "country": "USA"
      },
      "_permissions": {
        "edit": true
      }
    },
    {
      "_id": "5d6ede6a0ba62570afcedd3b",
      "name": "Jennifer",
      "address": {
        "city": "Vancouver",
        "country": "Canada"
      },
      "_permissions": {
        "edit": false
      }
    }
  ]
}

Create Resource POST¶

This entrypoint creates a resource.

POST /{base_url}

Example¶

request¶

curl \
  -X POST \
  -H "Accept: application/json" \
  https://example.com/users \
  -d '{ "name": "Jane" }'

response¶

Status: 201

{
  "_id": "5d6ede6a0ba62570afcedd3b",
  "name": "Jane",
  "address": null,
  "roles": ["user"],
  "creditBalance": 0,
  "loginDate": null
}

New Resource GET¶

This entrypoint returns an empty resource and is used to retrieve sample data as a placeholder.

GET /{base_url}/new

Example¶

request¶

curl \
  -H "Accept: application/json" \
  https://example.com/users/new

response¶

Status: 200

{
  "_id": "5d6ede6a0ba62570afcedd3b",
  "name": null,
  "address": null,
  "roles": ["user"],
  "creditBalance": 0,
  "loginDate": null
}

Read Resource GET¶

This entrypoint returns a target resource.

GET /{base_url}/:id

Parameters¶

Name	Type	In	Description
`id`	string	param	Resource identifier; defaults to Mongoose document ID
`include_permissions`	boolean	query	Whether to include document permissions in each document
`try_list`	boolean	query	Whether to attempt to retrieve the resource if not allowed
`lean`	boolean	query	Whether to pass plain objects, not Mongoose Documents, in middleware

Example¶

request¶

curl \
  -H "Accept: application/json" \
  https://example.com/users/5d6ede6a0ba62570afcedd3b?try_list=true&include_permissions=false&lean=true

response¶

Status: 200

{
  "_id": "5d6ede6a0ba62570afcedd3b",
  "name": "Andrew",
  "address": "5d6ede6a0ba62570afcedd3a",
  "roles": ["user"],
  "creditBalance": 100,
  "loginDate": "2022-02-22T02:02:22.679Z"
}

Read Resource POST¶

This entrypoint returns a target resource.

POST /{base_url}/:id

Parameters¶

Name	Type	In	Description
`id`	string	param	Resource identifier; defaults to Mongoose document ID
`select`	object \| array<string>	body	Document fields to include or exclude
`populate`	array<string> \| array<object>	body	Document fields to populate
`options.includePermissions`	boolean	body	Whether to include document permissions in each document
`options.tryList`	boolean	body	Whether to attempt to retrieve the resource if not allowed
`options.populateAccess`	'list' \| 'read'	body	The access level to use in `populate` method
`options.lean`	boolean	body	Whether to pass plain objects, not Mongoose Documents, in middleware

Example¶

request¶

curl \
  -X POST \
  -H "Accept: application/json" \
  https://example.com/users/5d6ede6a0ba62570afcedd3b \
  -d '{
    "select": ["name", "address"],
    "populate": ["address"],
    "options": {
      "includePermissions": true,
      "tryList": true,
      "populateAccess": "list",
      "lean": true
    }
  }'

response¶

Status: 200

{
  "_id": "5d6ede6a0ba62570afcedd3b",
  "name": "Andrew",
  "address": {
    "city": "Seattle",
    "country": "USA"
  }
}

Update Resource PUT¶

This entrypoint updates a target resource.

PUT /{base_url}/:id

Parameters¶

Name	Type	In	Description
`id`	string	param	Resource identifier; defaults to Mongoose document ID
`returning_all`	boolean	query	Whether to return entire document or partial document

Example¶

request¶

curl \
  -X PUT \
  -H "Accept: application/json" \
  https://example.com/users/5d6ede6a0ba62570afcedd3b?returning_all=false \
  -d '{ "name": "Andrew-2nd" }'

response¶

Status: 200

{
  "name": "Andrew-2nd"
}

Delete Resource DELETE¶

This entrypoint deletes a target resource.

DELETE /{base_url}/:id

Parameters¶

Name	Type	In	Description
`id`	string	param	Resource identifier; defaults to Mongoose document ID

Example¶

request¶

curl \
  -X DELETE \
  -H "Accept: application/json" \
  https://example.com/users/5d6ede6a0ba62570afcedd3b

response¶

Status: 200

"5d6ede6a0ba62570afcedd3b"

Distinct Field Values GET¶

This entrypoint finds the distinct values for a specified field across a target collection and returns the results in an array.

GET /{base_url}/distinct/:field

Parameters¶

Name	Type	In	Description
`field`	string	param	The field for which to return distinct values

Example¶

request¶

curl \
  -X GET \
  -H "Accept: application/json" \
  https://example.com/users/name

response¶

Status: 200

["Andrew", "Andrew-2nd", "Mike"]

Distinct Field Values POST¶

This entrypoint finds the distinct values for a specified field across a target collection and returns the results in an array.

POST /{base_url}/distinct/:field

Parameters¶

Name	Type	In	Description
`field`	string	param	The field for which to return distinct values
`query`	string	body	Mongose query that specifies the match rules to retrieve the distinct values

Example¶

request¶

curl \
  -X POST \
  -H "Accept: application/json" \
  https://example.com/users/name \
  -d '{
    "query": {
      "name": { "$regex": "drew", "$options": "i" }
    }
  }'

response¶

Status: 200

["Andrew", "Andrew-2nd"]

Count Documents GET¶

This entrypoint returns the count of documents that would match a query for the collection.

GET /{base_url}/count

Example¶

request¶

curl \
  -X GET \
  -H "Accept: application/json" \
  https://example.com/count

response¶

Status: 200

Count Documents POST¶

This entrypoint returns the count of documents that would match a query for the collection.

POST /{base_url}/distinct/:field

Parameters¶

Name	Type	In	Description
`query`	string	body	Mongose query that specifies the match rules to retrieve the distinct values
`access`	'list' \| 'read'	body	The access level to use in `find` method

Example¶

request¶

curl \
  -X POST \
  -H "Accept: application/json" \
  https://example.com/count \
  -d '{
    "query": {
      "name": { "$regex": "drew", "$options": "i" }
    },
    "access": "list"
  }'

response¶

Status: 200