The Document resource
The Document resource represents a document in a collection. Requests to Document URI allow to create, delete, update files and get their properties.
Allowed methods are:
|GET||Return the document|
|PUT||Creates or updates the document|
|PATCH||Updates the document (only passed data)|
|DELETE||Deletes the document|
The resource URI format is
The query parameter
doc_type is optional; its default value is STRING_OID: by default RESTHeart treats the
docid as an ObjectId, if the value is a valid ObjectId, or a String.
The following table shows the supported types:
|ObjectId||OID or STRING_OID|
|String||STRING* or STRING_OID|
* doc_type=STRING is useful if the _id value would be a valid ObjectId but it is actually stored as a String.
Refer to URI Format for more information.
create a document
A document can also be created via a POST to the collection URI. POSTing the collection has the advantage that the _id will be automatically generated (of type ObjectId) and returned in the Location response header.
get the document properties
Browsers use the ETAG response header for web caching. Further requests to the resource including the If-None-Match header, gets 304 Not Modified as response. This effectively save bandwidth.
modify a file
This example shows two important of the PATCH operation:
- It is allowed to use the dot notation in PATCH request to access nested properties.
- Arrays can be manipulated directly. In the example we updated the third element of the array.
Note the If-Match request header. This needs to be added to modify an existing resource. See ETag documentation section for more information.
Note that the ETag has been updated and the new value passed back is ETag response header.
delete a file
How to use the examples
The examples make use of the brilliant httpie CLI HTTP client and are ment to be used with RESTHeart stareted on the localhost without the authentication enabled.
Eventually pass username and password with the
-a username:password option.