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