v8 v7 v6 v5 v4 v3
Edit Page

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.
Database Metadata /<db>/_meta Metadata associated to the database named <db>.
Collection /<db>/<coll> <coll> is the collection name.
Collection Metadata /<db>/<coll>/_meta Metadata associated to the collection named <coll>.
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).
Change Stream /<db>/<coll>/_streams/<stream_name> <stream_name> is the name of the change stream (specified in it declaration, see Change Streams).

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.

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" }

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