v8 v7 v6 v5 v4 v3
Edit Page

Resource URIs in RESTHeart

This page explains how RESTHeart identifies resources through URLs, helping you understand the API structure and how to access different MongoDB resources.

API Structure Overview

RESTHeart organizes MongoDB resources in a hierarchical structure following REST principles:

/                            # Root (list of databases)
├── /<db>                    # Database
│   ├── /<db>/_meta          # Database metadata
│   ├── /<db>/<coll>         # Collection
│   │   ├── /<db>/<coll>/_meta           # Collection metadata
│   │   ├── /<db>/<coll>/<docid>         # Document
│   │   ├── /<db>/<coll>/*               # Bulk documents
│   │   ├── /<db>/<coll>/_indexes        # Collection indexes
│   │   │   └── /<db>/<coll>/_indexes/<indexid>  # Specific index
│   │   ├── /<db>/<coll>/_schemas        # Schema store
│   │   │   └── /<db>/<coll>/_schemas/<schemaid> # Specific schema
│   │   └── /<db>/<coll>/_aggrs/<aggrname>       # Aggregation
│   └── /<db>/<bucket>.files              # File bucket
│       ├── /<db>/<bucket>.files/<fileid> # File metadata
│       └── /<db>/<bucket>.files/<fileid>/binary # File binary content
Note

The default RESTHeart configuration binds the root URI / to the database restheart. This documentation uses the most general case where all MongoDB resources are exposed (mongo.mongo-mounts[0].what: "*").

Resource URI Reference

Resource URI Description

Root

/

API entry point, lists available databases

Database

/<db>

Lists collections in the database

Database Metadata

/<db>/_meta

Metadata for the database

Collection

/<db>/<coll>

Lists documents in the collection

Collection Metadata

/<db>/<coll>/_meta

Metadata for the collection

Document

/<db>/<coll>/<doc_id>[?id_type=TYPE]

Individual document with specified ID

Bulk Documents

/<db>/<coll>/*?filter=<query>

Operates on multiple documents matching a filter

Indexes

/<db>/<coll>/_indexes

Lists all indexes for the collection

Index

/<db>/<coll>/_indexes/<idx_id>

Individual index

File Bucket

/<db>/<bucket>.files

Storage for binary files using GridFS

File

/<db>/<bucket>.files/<file_id>[?id_type=TYPE]

File metadata

File Binary

/<db>/<bucket>.files/<file_id>/binary

File binary content

Schema Store

/<db>/_schemas

Collection of JSON schemas

Schema

/<db>/_schemas/<schema_id>

Individual JSON schema

Aggregation

/<db>/<coll>/_aggrs/<aggr_name>

Named aggregation pipeline

Change Stream

/<db>/<coll>/_streams/<stream_name>

WebSocket endpoint for real-time updates

Document ID Types

In MongoDB, the _id field can be of various types (ObjectId, String, Number, etc.). When accessing documents via REST, RESTHeart needs to interpret the ID portion of the URL correctly.

Supported ID Types

MongoDB Type id_type Parameter Value

ObjectId

OID or STRING_OID*

String

STRING or STRING_OID*

Number

NUMBER

Date

DATE

MinKey

MINKEY

MaxKey

MAXKEY

Boolean

BOOLEAN

null

NULL

Important notes:

  • STRING_OID is the default if no id_type parameter is specified

  • With STRING_OID, the ID is interpreted as an ObjectId if it’s a valid 24-character hex string, otherwise as a String

  • Use STRING explicitly when you have a String ID that looks like a valid ObjectId but should be treated as a String

Document ID Examples

Request URI Document ID in MongoDB

/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 Considerations

When resource URLs contain special characters, they must be properly percent-encoded according to RFC 3986.

Special Characters in IDs:

  • Space: Use %20 (e.g., /db/my%20collection)

  • Forward slash: Use %2F (e.g., /db/coll/path%2Fto%2Ffile)

  • Plus sign: Use %2B (e.g., /db/coll/A%2BB)

Important

The plus sign (+) requires special attention:

  • In query strings, a + is automatically decoded to a space

  • To represent an actual plus sign in an ID, you must use %2B

For example: * /db/coll/A+B accesses a document with ID "A B" * /db/coll/A%2BB accesses a document with ID "A+B"

Most HTTP clients and browsers handle URL encoding automatically, but you should be aware of these rules when constructing requests programmatically.

Mounting Strategies

RESTHeart offers flexibility in how MongoDB resources are exposed through the API:

Default Mount

By default, RESTHeart mounts a single database at the root path:

mongo-mounts:
  - what: /restheart
    where: /

With this configuration, collections in the restheart database are accessed directly at the root level: * /collection1 → restheart.collection1

Exposing All Databases

To expose all MongoDB databases:

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

With this configuration, all databases are visible at the root level: * /dbname/collection1 → dbname.collection1

Custom Mounts

You can create custom URL mappings:

mongo-mounts:
  - what: /inventory
    where: /products
  - what: /users
    where: /accounts

With this configuration: * /products/items → inventory.items * /accounts/admins → users.admins