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

Write Requests

Introduction

This document shows how RESTHeart can use the PUT, POST, PATCH and DELETE verbs to create, modify and delete resources within a MongoDB database, using only the HTTP protocol.

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:

Request Execute with restninja 
PUT / HTTP/1.1

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

Request Execute with restninja 
PUT /inventory HTTP/1.1

To populate the inventory collection, run the following:

Request Execute with restninja 
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" }
]

Write Verbs

The following table summarizes the semantic of the write verbs:

verb semantic
PUT

Upserts the resource identified by the request URL:

  • if the resource does not already exist, the PUT request creates it setting its state as specified in the request JSON body;
  • if the resource alreadyn exists, the PUT request sets the resource state as specified in the request JSON body.
  • $currentDate update operator is supported. Using any other update operator (such as $min) is not allowed and would result in BAD REQUEST response.
  • Properties keys can use the dot notation (such as foo.bar).
POST

Upserts a resource under the resource identified by the request URL:

  • if the resource does not already exist, the POST request creates it setting its state as specified in the request JSON body;
  • if the resource exists, the POST sets the resource properties as specified in the request JSON body.

The resource to upsert is identified by the _id property of the request JSON body. If the request body does not include it, the _id it is auto generated as a new ObjectId and the URL of the new document is returned in the response via the Location header.

  • $currentDate update operator is supported. Using any other update operator (such as $min) is not allowed and would result in BAD REQUEST response.
  • Properties keys can use the dot notation (such as foo.bar).
PATCH

While PUT and POST verbs replace the whole state of the resource identified by the request URL, PATCH verb only modifies the properties passed with the request JSON body. All write requests, including PATCH, have upsert semantic.

  • All update operators are allowed.
  • Properties keys can use the dot notation (such as foo.bar).
DELETE Deletes the resource identified by the request URL.

Upsert

The term upsert means either to create a resource, if it does not already exist or to update it, if it does. It comes from joining the terms update and insert.

Basic Examples

Create a document with a given “newItem” Id

Request Execute with restninja 
PUT /inventory/newItem HTTP/1.1

{ "item": "pencil", "qty": 55, "size": { "h": 10, "w": 0.5, "uom": "cm" }, "status": "B", "suppliers": ["brand_1", "brand_2", "brand_3"] }

Create a document without a given Id

Request Execute with restninja 
POST /inventory HTTP/1.1

{ "item": "rubber", "qty": 15, "size": { "h": 2, "w": 1, "uom": "cm" }, "status": "A" }

Edit “newItem” document’s property “status”

Request Execute with restninja 
PATCH /inventory/newItem HTTP/1.1

{ "status": "A" }

Dot Notation

RESTHeart uses the dot notation to access the elements of an array and to access the fields of an embedded document.

The dot notation can be used in PUT, PATCH and POST verbs.

Dot Notation Examples

Edit “newItem” document’s array element “supplier[1]”

Request Execute with restninja 
PATCH /inventory/newItem HTTP/1.1

{"suppliers.1": "new_brand" }

Edit “newItem.size” embedded document’s “h” property

Request Execute with restninja 
PATCH /inventory/newItem HTTP/1.1

{"size.h": 20 }

Update Operators

Refer to MongoDB Update Operators documentation for more information.

RESTHeart allows to use all MongoDB update operators on PATCH requests. PUT and POST can only use $currentDate update operator.

Update Operators Examples

Apply given update operators to “newItem” document

Request Execute with restninja 
PATCH /inventory/newItem HTTP/1.1

{
  "$inc": { "qty": 1 },
  "$push": { "suppliers": "pushed_brand" },
  "$unset": { "status": null },
  "$currentDate": { "timestamp": true }
}

The request above will:

  • increment the properties qty using the $inc field operator
  • add a new item to the suppliers using the $push array operator
  • remove the property status using the $unset field operator
  • update the timestamp with the current date using the $currentDate operator

Bulk Write Requests

Bulk write requests create, update or delete multiple documents with a single request.

A bulk request response contains the URIs of the created documents.

All the upserted documents have the same _etag property value as reported in the ETag response header. To retrieve the upserted documents with a single request GET the collection filtering on the _etag property.

Bulk Write Requests Examples

POST an array of documents

Request Execute with restninja 
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" }
]

The bulk POST has the same behavior of PATCH: only the properties in the request data will be updated. POSTing documents containing existing _ids will update the them (and not replace the existing onces at all).

PATCH multiple documents with “qty” property greater than (or that equals) 50 using the wildcard document id

Request Execute with restninja 
PATCH /inventory/*?filter={"qty":{"$gte":50}} HTTP/1.1

{
  "qty":1000
}

DELETE multiple documents with “qty” property less than (or that equals) 50 using the wildcard document id

Request Execute with restninja 
DELETE /inventory/*?filter={"qty":{"$lte":50}} HTTP/1.1