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 |
Resource URI Reference
Resource | URI | Description |
---|---|---|
Root |
|
API entry point, lists available databases |
Database |
|
Lists collections in the database |
Database Metadata |
|
Metadata for the database |
Collection |
|
Lists documents in the collection |
Collection Metadata |
|
Metadata for the collection |
Document |
|
Individual document with specified ID |
Bulk Documents |
|
Operates on multiple documents matching a filter |
Indexes |
|
Lists all indexes for the collection |
Index |
|
Individual index |
File Bucket |
|
Storage for binary files using GridFS |
File |
|
File metadata |
File Binary |
|
File binary content |
Schema Store |
|
Collection of JSON schemas |
Schema |
|
Individual JSON schema |
Aggregation |
|
Named aggregation pipeline |
Change Stream |
|
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 |
|
String |
|
Number |
|
Date |
|
MinKey |
|
MaxKey |
|
Boolean |
|
null |
|
Important notes:
-
STRING_OID
is the default if noid_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 |
---|---|
|
|
|
|
|
|
|
|
|
|
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 (
For example:
* |
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