For more information refer to the How API Clients Authenticate section.
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.
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
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.
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.
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.
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.
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 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.
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] |
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
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}
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""}
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}
The id_type allows you to properly identify documents
Allowed values are:
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"
}
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
Life is too short to develop yet another Data API.