Write Requests
Introduction
You will learn how to insert, update and delete documents in a collection.
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.
|
Tip
|
To run RESTHeart refer to Setup section. |
To create the restheart db, run the following:
PUT / HTTP/1.1The examples on this page use the inventory collection. To create the inventory collection, run the following:
PUT /inventory HTTP/1.1To 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" }
]Write Mode
The default write modes for each HTTP verb are:
-
POSTverb has insert write mode -
PUTandPATCHverbs have update write mode
Use POST to create a document, PUT to replace an existing document and PATCH to update selected properties of an existing document.
|
Note
|
Until RESTHeart v5, all write operations have always upsert mode. The new write mode provides more flexibility and simplifies defining security permissions.
|
The query parameter ?wm=insert|update|upsert allows specifying the write mode.
|
Important
|
the qparam ?wm is forbidden by default; to allow it, the following permission must be granted to the client (the default user admin can use it because it has the root role that provides all permissions).
|
{
"_id": "user-can-wse-wm-qparam",
"roles": [ "user" ],
"predicate": "path-prefix(/collection)",
"mongo": {
"allowWriteMode": true
}
}Create a document
To create a document use the POST method.
POST /inventory HTTP/1.1
{ "_id": "newItem", "item": "rubber", "qty": 15, "size": { "h": 2, "w": 1, "uom": "cm" }, "status": "A" }|
Note
|
If _id field is not specified in the request body, it will generated by MongoDB as an ObjectId and returned to the client via the Location response header.
|
Replace a document
To replace a document use the PUT method.
PUT /inventory/newItem?wm=insert HTTP/1.1
{ "item": "pencil", "qty": 55, "size": { "h": 10, "w": 0.5, "uom": "cm" }, "status": "B", "suppliers": ["brand_1", "brand_2", "brand_3"] }Update a document’s property
To update one or more properties of a document use the PATCH method.
PATCH /inventory/newItem HTTP/1.1
{ "status": "A" }|
Note
|
the PATCH verb allows passing update operator expressions; the body can contain update operators.
|
DELETE a document
To delete a document use the DELETE method.
DELETE /inventory/newItem HTTP/1.1Dot Notation
RESTHeart always allows using 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.
Update an array element
PATCH /inventory/newItem HTTP/1.1
{ "suppliers.1": "new_brand" }Update the property of an embedded document
PATCH /inventory/newItem HTTP/1.1
{ "size.h": 20 }Update Operators
Refer to MongoDB Update Operators documentation for more information.
|
Important
|
RESTHeart allows to use all MongoDB update operators on PATCH requests. PUT and POST can only use $currentDate update operator.
|
Apply given update operators to "newItem" document
PATCH /inventory/newItem HTTP/1.1
{
"$inc": { "qty": 1 },
"$push": { "suppliers": "pushed_brand" },
"$unset": { "status": null },
"$currentDate": { "timestamp": true }
}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.
|
Important
|
bulk requests are forbidden by default; to allow them, the following permission must be granted to the client (the default user admin can execute them because it has the root role that provides all permissions):
|
{
"_id": "user-can-execute-bulk-requests",
"roles": [ "user" ],
"predicate": "path-prefix(/collection)",
"mongo": {
"allowBulkPatch": true,
"allowBulkDelete": true,
"allowWriteMode": true
}
}Create an array of documents
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" }
]|
Important
|
Its a POST request, then the default write mode is insert. As usual, you can use the ?wm=insert|update|upsert query parameter to change write mode.
|
Update properties in multiple documents
PATCH /inventory/*?filter={"qty":{"$gte":50}} HTTP/1.1
{
"qty":1000
}DELETE multiple documents
DELETE /inventory/*?filter={"qty":{"$lte":50}} HTTP/1.1MongoDB write operations
The MongoDB write operation depends on the request method and on the write mode as follows:
| write mode | method | URI | MongoDB write operation | write operation argument |
|---|---|---|---|---|
insert |
POST |
|
|
document |
insert |
PUT |
|
|
document |
insert |
PATCH |
|
|
update operator expression |
update |
POST |
|
|
document |
update |
PUT |
|
|
document |
update |
PATCH |
|
|
update operator expression |
upsert |
POST |
|
|
document |
upsert |
PUT |
|
|
document |
upsert |
PATCH |
|
|
update operator expression |
(1) uses a find condition that won’t match any existing document, making sure the operation is an insert