Quick Reference

Introduction

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

Reading Documents

Read multiple documents

Request
GET /coll?page=1&pagesize=5&filter={query} HTTP/1.1
Response
[ {doc#1 }, { doc#2 }, ... , { doc#5 } ]

Read a single document

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

Writing Documents

Write a document with POST

Request
POST /coll HTTP/1.1

{ "_id": "docid", ... }

Write multiple documents with POST

Request
POST /coll HTTP/1.1

[ { doc#1 }, { doc#2 }, ... , { doc#n} ]

Modify a document with PUT

Request
PUT /coll/docid HTTP/1.1

{ doc }

The whole document is replaced with the request body.

Modify a document with PATCH

Request
PATCH /coll/docid HTTP/1.1

{ ... }

Only the parameters in the request body are updated.

Update multiple documents

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

{ ... }

query parameter filter is mandatory

Delete a document

Request
DELETE /coll/docid HTTP/1.1

Delete multiple documents

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

query parameter filter is mandatory

Reading Files

Read multiple file properties

Request
GET /bucket.files?page=1&pagesize=5&filter={query} HTTP/1.1

[ {file#1 }, { file#2 }, ... , { file#5 } ]

Read a file properties

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

Read a file content

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

Writing Files

Create a file

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

This is a multipart request

Delete a file

Request
DELETE /bucket.files/fileid HTTP/1.1

Collections and File Buckets

List Collections and Files Buckets

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

Read metadata of a Collection or Files Bucket

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

Create a Collection

Request
PUT /coll HTTP/1.1

{ metadata }

Create a File Bucket

Request
PUT /bucket.files HTTP/1.1

{ metadata }

Update the metadata of a Collection or a File Bucket

Request
PUT /bucket.files HTTP/1.1

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

{ metadata }

Delete a collection or a File Bucket

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

If-Match is a request header

Create an index

Request
PUT /coll/_indexes/idxid HTTP/1.1

{ "keys": { ... }, "ops": { ... } }

Delete an index

Request
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