API

This section lists the requests to read and write data and provide you with a quick reference about the API.

For more step-by-step guides you should refer to the Tutorials.

Resource URLs

Your Datalet has an URL. You find it in the Datalet Info page of the Manager.

In this example the Datalet URL is https://beta.mrest.io/demo

The Resources of the Datalet such as Collections, Documents, Files, etc. are uniquely identified by the following URIs:

URI	Resource
`/`	The Datalet.
`/coll`	The Collection coll.
`/coll/docid`	The Document with _id equal to docid in the Collection coll.
`/bucket.files`	The File Bucket bucket.files. The name of file buckets must end with .files.
`/bucket.files/fileid`	The File with equal to fileid in the File Bucket bucket.files.

The URL of a resources is simply the Datalet URL plus its URI.

For instance, given the demo Datalet, the URI of the collection messages is /messages and its URL is https://beta.mrest.io/demo/messages

The API key

All requests must specify the Datalet API key via the key header.

You find your API key in the Datalet Info page of the Manager. By default the key is hidden as a security precaution, but you can show and copy it to the clipboard.

The following is an example request done using httpie, a modern HTTP cli command that allows specifying a request header with the simple header:value notation and passing the authentication credentials with the -a id:password option.

$ http GET -a root:<password> https://beta.mrest.io/<datalet>/<collection> key:<your-API-key>

HTTP/1.1 200 OK
(other headers omitted)

[
    {
        "_id": {
            "$oid": "5bbf63a09c5d125a2b98ca39"
        },
        (other properties omitted)
    },
    (other documents omitted)
]

For more information refer to the How API Clients Authenticate section.

Read Requests

The HTTP verb for reading data is GET.

Request	Effect	Params
`GET /`	Returns the names of Collections and File Buckets as a JSON array of strings.	[page] [pagesize]
`GET /coll`	Returns the Documents in the Collection as a JSON array of objects.	[page] [pagesize] [keys] [filter] [sort]
`GET /coll/docid`	Returns the Document in the Collection as a JSON object.	[id_type] [keys]
`GET /bucket.files`	Returns the properties of the Files in the File Bucket as a JSON array of objects.	[page] (pagesize) [keys] [filter] [sort]
`GET /bucket.files/fileid`	Returns the properties of the File as a JSON object.	[keys] [filter] [id_type]
`GET /db/bucket.files/fileid/binary`	Returns the binary content of the File.	[filter] [id_type]

For more information refer to the Query Documents section of the RESTHeart Documentation.

Representation

All resources are represented as JSON.

Nevertheless Documents can have properties of BSON types, such as ObjectId, Date and others.

BSON is the format used by MongoDB for data and it is a super set of JSON.

Complex types are represented with the so called extended json.

For instance the _id of a Document of type ObjectId is represented using $oid:

{"_id": {"$oid":"568106e67d3126b74dc5f9af"}}.

For more information refer to the Strict mode representations of BSON section of the RESTHeart Documentation.

Write Requests

The HTTP verbs for writing are POST, PUT and PATCH.

The verb Upsert means that the resource is Updated if exiting or Inserted.

Request	Effect	Params
`POST /coll {..}`	Upserts one Document in the collection replacing the whole document with the request body. To update a document, include the _id property in the body.	[filter] [checkEtag]
`POST /coll [{..}, .. ,{..}]`	Upserts several documents in the collection, for existing documents indentified by the _id property, it modifies only the properties included in the request body.	[filter] [checkEtag]
`PUT /coll/docid {..}`	Upserts the Document replacing the whole document with the request body.	[filter] [id_type] [checkEtag]
`PATCH /coll/docid {..}`	Upsert the Document modifying only the properties included in the request body	[filter] [id_type] [checkEtag]
`PATCH /coll/*?filter={..} {..}`	Modifies all the Documents that match the filter condition	filter
`POST /bucket.files properties={...} file=<binary>`	Creates an immutable file in bucket. Note that this must be a multipart request	[checkEtag]
`PUT /bucket.files/fileid properties={...} file=<binary>`	Creates an immutable file in bucket. Note that this must be a multipart request	[checkEtag]

For more information refer to the Write Requests section of the RESTHeart Documentation.

Dot Notation and Update Operators

All write operations can use the dot notation and the MongoDb update operators.

For example the following request increments the value of the property n of the nested document obj identified by obj.n using the $inc operator.

PATCH /coll/docid {"$inc": {"obj.n":1}}

Files

Files are immutable: they cannot be modified: in order to update a file it must be first deleted and then recreated.

When a file it is created mrest automatically detects its type and sets the fileType property for you. This property is then used to set the Content-Type response header for GET requests.

Delete Requests

The HTTP verb for deleting resources is DELETE.

Request	Effect	Params
`DELETE /coll/docid`	Deletes the document.	[filter] [id_type] [checkEtag]
`DELETE /db/coll/*?filter={..}`	Deletes all the Documents that match the filter condition.	filter
`DELETE /bucket.files/fileid`	Deletes the File	[filter] [id_type] [checkEtag]

Query Parameters

page and pagesize

These query parameters control the pagination.

The default paging options are page=1&pagesize=20 and the maximum value for pagesize is 100.

For more information check Query Documents in RESTHeart documentation.

Examples

The following requests returns up to 100 documents, from the 301th.

GET /coll?page=3&pagesize=100

sort

The sort parameter controls the sorting.

The default sort is sort={"_id":-1}. To disable sorting you can specify sort={}.

For more information check Query Documents in RESTHeart documentation.

Examples

Return documents sort by timestamp ascending and _id descending.

GET /coll?sort={"timestamp":1, "_id": -1}

filter

The filter query parameter specifies a MongoDb query.

For more information check Query Documents in RESTHeart documentation.

Examples

The following request returns documents whose status property is equal to "to be deleted".

GET /coll?filter={"status":"to be deleted"}

The following request deletes the document with _id equal to docid only if its status is "to be deleted".

DELETE /coll/docid?filter={"status":"to be deleted""}

keys

The keys query parameter defines the properties to return (projection)

more information on RESTHeart Query Documents page

Examples

The following request, returns only the properties a and prop of the nested document obj (the dot notation is allowed).

GET /coll?filter?keys={"a":1, "obj.prop":1}

id_type

The id_type allows you to properly identify documents

Allowed values are:

STRING_OID the value of the doc_id is interpreted either as an ObjectId or a String. The former applies if the value is a valid Object.
STRING useful if the docid value would be a valid ObjectId but it is actually a String
NUMBER
DATE
BOOLEAN
MAXKEY
MINKEY
NULL

For more information refer to the Document id section of the RESTHeart Documentation.

Examples

Given the documents:

{
    "_id: "1",
    "type" "string"
},
{
    "_id: 1,
    "type" "number"
}

The following request returns the document with _id of type String.

GET /coll/1

{
    "_id: "1",
    "type" "string"
}

The following request returns the document with _id of type Number.

GET /coll/1?id_type=number

{
    "_id: 1,
    "type" "number"
}

ETag

Each document and file has an ETag property that is returned via the ETag response header.

http GET https://beta.mrest.io/demo/messages/docid key:demo
HTTP/1.1 200 OK

ETag: 5b8eb198c9e77c00052fad75
(other headers omitted)

For read requests, The ETag is used for web caching; all browsers actually use it automatically.

For write requests, it allows avoiding ghost writes, i.e. it can make sure that the client is updating a document that has not been updated by others.

The client can optionally require to check the ETag passing the checkETag query parameter and the If-Match request header.

For more information refer to the ETag section of the RESTHeart Documentation.

Examples

This will only modify the document if its etag matches with the value specified by the If-Match header.

PATCH /coll/docid?checkEtag=true {"$inc": {"a":1}} If-Match:<ETag>

Passing the ETag via the If-None-Match header avoids to transfer data.

GET /coll/docid If-None-Match:<ETag>

HTTP/1.1 304 Not Modified

mrest is the perfect solution for your serverless architecture

Life is too short to develop yet another Data API.

Start Now