Resource URI

Introduction

This page explains the resource URI format, i.e. how the resources are identified.

Resources URIs

resource	URI	notes
Root	/	The root resource is the API entry point.
Database	/<db>	`<db>` is the database name.
Collection	/<db>/<coll>	`<coll>` is the collection name.
Document	/<db>/<coll>/<doc_id>[?id_type=TYPE]	`<doc_id>` is the `_id` of the document and the optional `id_type` query parameter is its type (default is "STRING_OID").
Bulk Documents	/<db>/<coll>/*?filter=[filter expression]	The wildcard can be used for bulk updates; in this case the `filter` query parameter is mandatory, see Write Requests.
Indexes	/<db>/<coll>/_indexes
Index	/<db>/<coll>/_indexes/<idx_id>	`idx_id` is the _id of the index and must be a string (other types of index _id are not supported).
File bucket	/<db>/<bucket>/.files	`<bucket>` is the file bucket name and it is a string (suffix .files is mandatory).
File	/<db>/<bucket>.files/<file_id>[?id_type=TYPE]	`<file_id>` is the value of the _id the file and the optional `id_type` query parameter is its type (default is "STRING_OID").
Schema Store	/<db>/<coll>/_schemas
Schema	/<db>/<coll>/_schemas/<schema_id>	`<schema_id>` is the `_id` of the schema.
Aggregation	/<db>/<coll>/_aggrs/<aggr_name>	`<aggr_name>` is the `name` of the aggregation (specified in it declaration, see Aggregations).

Document id

In MongoDB, the _id can be of any type. For instance, it can be an ObjectId, a String or even a JSON object, as in the following document:

{ "_id": {"a":1,"b":2} }

RESTHeart needs to be able to assign a unique URI to each document. For this reason, only a subset of _id types are supported.

The following table shows the supported types:

type	id_type
ObjectId	OID or STRING_OID*
String	STRING** or STRING_OID*
Number	NUMBER
Date	DATE
MinKey	MINKEY
MaxKey	MAXKEY
Boolean	BOOLEAN
null	NULL

* The default value of the id_type query parameter is STRING_OID. In this case, the value of the <doc_id> is interpreted either as an ObjectId or a String. The former applies if the value is a valid ObjectId.

** STRING is useful if the _id value would be a valid ObjectId and it is actually a String.

Some examples


/db/coll/1	{ ”_id”: ”1” }
/db/coll/1?id_type=NUMBER	{ ”_id”: 1 }
/db/coll/1?id_type=DATE	{ ”_id”: { ”$date”: 1} }
/db/coll/54f77f0fc2e6ea386c0752a5	{ ”_id”: { ”$oid”: ”54f77f0fc2e6ea386c0752a5”} }
/db/coll/54f77f0fc2e6ea386c0752a5?id_type=STRING	{ ”_id”: ”54f77f0fc2e6ea386c0752a5” }

mongo-mounts

The mongo-mounts configuration options allows to bind MongoDB resources to URIs. The default configuration binds all MongoDB resource below the root URI:

mongo-mounts:
    - what: "*"
      where: /

In this case the URI /db/coll/doc identifies the document with id doc of the collection coll of the database db.

Different mongo-mounts settings result in different resource URIs. Examples:

mongo-mounts:
    - what: "*"
      where: /api

In this case the URI of the document is /api/db/coll/doc

mongo-mounts:
    - what: "/db/coll"
      where: /

In this case the URI of the document is /doc

URL encoding

If a resource URL contains one or more RFC 3986 reserved characters, they must be percent encoded. However most of the HTTP client will encode the URL for you, including all the browsers. For instance, the URL of the database my database is actually https://whatever.org/my%20database.

Special attention must be paid with + (plus sign). The + sign in the query string is URL-decoded to a space! %2B in the query string is URL-decoded to a + sign. So the request

GET /db/coll/a+b will actually find the document with id “a b”. GET /db/coll/a%2Bb finds the document with id “a+b”

Have a look at this issue https://github.com/SoftInstigate/restheart/issues/116

Installation and Configuration

API

Advanced Topics

Misc