v8 v7 v6 v5 v4 v3
Edit Page

Intoduction

Getting Started

Upgrade to v4

Roadmap

Content API

Management API

Securing Requests

Plugins

Develop Plugins

Other Features

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