Tutorial

Before running the example requests

The following step by step tutorial assumes that RESTHeart is running on localhost with the default configuration: the database restheart is bound to / and the user admin exists with default password secret.

To run RESTHeart please first read the setup section.

To create the restheart db, run the following:

PUT / HTTP/1.1

The examples on this page use the inventory collection. To create the inventory collection, run the following:

PUT /inventory HTTP/1.1

To populate the inventory collection, run the following:

POST /inventory HTTP/1.1

[
   { "item": "journal", "qty": 25, "size": { "h": 14, "w": 21, "uom": "cm" }, "status": "A" },
   { "item": "notebook", "qty": 50, "size": { "h": 8.5, "w": 11, "uom": "in" }, "status": "A" },
   { "item": "paper", "qty": 100, "size": { "h": 8.5, "w": 11, "uom": "in" }, "status": "D" },
   { "item": "planner", "qty": 75, "size": { "h": 22.85, "w": 30, "uom": "cm" }, "status": "D" },
   { "item": "postcard", "qty": 45, "size": { "h": 10, "w": 15.25, "uom": "cm" }, "status": "A" }
]

GET Documents from the Collection

Now let’s get all documents in a row. For this, we send a GET request to the whole collection:

GET /inventory HTTP/1.1

[
  {
    "_id": {
      "$oid": "5d0b3dbc2ec9ff0d92ddc2aa"
    },
    "_etag": {
      "$oid": "5d0b3dbc2ec9ff0d92ddc2a5"
    },
    "item": "postcard",
    "qty": 45,
    "size": {
      "h": 10,
      "w": 15.25,
      "uom": "cm"
    },
    "status": "A"
  },
  {
    "_id": {
      "$oid": "5d0b3dbc2ec9ff0d92ddc2a9"
    },
    "_etag": {
      "$oid": "5d0b3dbc2ec9ff0d92ddc2a5"
    },
    "item": "planner",
    "qty": 75,
    "size": {
      "h": 22.85,
      "w": 30,
      "uom": "cm"
    },
    "status": "D"
  },

  ...

]

GET filtered Documents from the Collection

It’s possible to apply a filter at the end of the request to reduce the number of output documents. The following request asks for all documents with a “qty” property greather than 75:

GET /inventory?filter={"qty":{"$gt":75}} HTTP/1.1

[
    {
        "_id": {
            "$oid": "5d0b3dbc2ec9ff0d92ddc2a8"
        },
        "_etag": {
            "$oid": "5d0b3dbc2ec9ff0d92ddc2a5"
        },
        "item": "paper",
        "qty": 100,
        "size": {
            "h": 8.5,
            "w": 11,
            "uom": "in"
        },
        "status": "D"
    }
]

Note that only the retrieved document meets the filter’s condition.

POST a new document

Now we are going to insert a new document to the collection.

POST /inventory HTTP/1.1

{"item": "newItem", "qty": 10, "size": { "h": 2, "w": 4, "uom": "cm" }, "status": "C"}

ETag: 5d0b47422ec9ff0d92ddc2ad
X-Powered-By: restheart.org
Content-Type: application/json
Location: http://localhost:8080/inventory/5d0b47425beb2029a8d1bc72

Note the Location header in the response, as it contains a link to the newly created document! To get the document you can directly copy that link and use it in a subsequent query.

PUT a new document

It’s possible to PUT a document into the collection by specifing the document identifier at the end of the request:

PUT /inventory/newDocument HTTP/1.1

{ "item": "yetAnotherItem", "qty": 90, "size": { "h": 3, "w": 4, "uom": "cm" }, "status": "C" }

PATCH a document

PATCH /inventory/newDocument HTTP/1.1

{ "qty": 40, "status": "A", "newProperty": "value" }

{
    "_id": "newDocument",
    "item": "yetAnotherItem",
    "qty": 40,
    "size": {
        "h": 3,
        "w": 4,
        "uom": "cm"
    },
    "status": "A",
    "_etag": {
        "$oid": "5d0b4b9e2ec9ff0d92ddc2af"
    },
    "newProperty": "value"
}

The previous request changes the document created in the previous example as indicated in the request body.

DELETE a document

DELETE /inventory/newDocument HTTP/1.1