Quick Reference


This quick reference assumes the default configuration with the database restheart bound to / and the STANDARD representation format.

Reading Documents

Read multiple documents

GET /coll?page=1&pagesize=5&filter={query} HTTP/1.1
[ ... ]

Read a single document

GET /coll/docid HTTP/1.1
{ "_id": "docid",  }

Writing Documents

Write a document with POST

POST /coll HTTP/1.1
{ "_id": "docid", }

Write multiple documents with POST

POST /coll HTTP/1.1
[ ... ]

Modify a document with PUT

PUT /coll/docid HTTP/1.1
{ doc }

The whole document is replaced with the request body.

Modify a document with PATCH

PATCH /coll/docid HTTP/1.1
{ ... }

Only the parameters in the request body are updated.

Update multiple documents

PATCH /coll/*?filter={query} HTTP/1.1
{ ... }

query parameter filter is mandatory

Delete a document

DELETE /coll/docid HTTP/1.1

Delete multiple documents

DELETE /coll/*?filter={query} HTTP/1.1

query parameter filter is mandatory

Reading Files

Read multiple file properties

GET /bucket.files?page=1&pagesize=5&filter={query} HTTP/1.1
[ {file#1 }, { file#2 }, ... , { file#5 } ]

Read a file properties

GET /bucket.files/fileid HTTP/1.1
{ "_id": "fileid", "fileType": "application/pdf", ... }

Read a file content

GET /bucket.files/fileid/binary HTTP/1.1
(file content)

Writing Files

Create a file

POST  /db/bucket.files properties={"a": 1} file=<binary> HTTP/1.1

This is a multipart request

Delete a file

DELETE /bucket.files/fileid HTTP/1.1

Collections and File Buckets

List Collections and Files Buckets

GET / HTTP/1.1
[ "coll1", "coll2", "bucket1.files", "bucket2.files", ... ]

Read metadata of a Collection or Files Bucket

GET /coll/_meta HTTP/1.1
{ "aggrs": [...], "streams": [...] }

Create a Collection

PUT /coll HTTP/1.1
{ metadata }

Create a File Bucket

PUT /bucket.files HTTP/1.1
{ metadata }

Update the metadata of a Collection or a File Bucket

PUT /bucket.files HTTP/1.1
{ metadata }
PATCH /bucket.files HTTP/1.1
{ metadata }

Delete a collection or a File Bucket

DELETE /coll HTTP/1.1
If-Match: <ETag>

If-Match is a request header

Create an index

PUT /coll/_indexes/idxid HTTP/1.1
{ "keys": { ... }, "ops": { ... } }

Delete an index

DELETE /coll/_indexes/idxid HTTP/1.1

Important Query Parameters

qparam description example
page and pagesize control pagination ?page=1&pagesize=5
sort control sorting ?sort={"n":-1}
filter apply a query ?filter={"n":{"$gt":5}}
keys controls projection, i.e. the properties to return ?keys={"a":1, "obj.prop":1}
id_type specifies the type of the _id /coll/1{"_id":"1"} vs /coll/1?id_type=number{"_id":1}

Write requests facts

  • All write requests have upsert semantic: the document is updated if existing or created.
  • POST request whose body does not include the _id property, creates a document with _id generated as a new ObjectId.
  • PATCH modifies only properties in the request body; PUT and POST replace the whole existing document.
  • All write operation can use the dot notation and all mongodb update operators