REST API Tutorial with RESTHeart

Execute on rest ninja doesn’t work with Safari because it requires HTTPS. Since configuring HTTPS requires a valid certificate and takes some time to configure, we suggest to just use Chrome or Firefox for this tutorial.

Watch Practical testing with Rest Ninja

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

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 Documents with filter

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 greater 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.

Watch How to filter data

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 specifying the document identifier at the end of the request, in this case we need to use the query parameter ?wm=upsert since PUT default write mode is update:

PUT /inventory/newDocument?wm=upsert HTTP/1.1

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

PATCH an existing 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