document

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:

Method Description
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 /<dbname>/<collname>/<docid>[?doc_type=TYPE]

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:

Type id_type
ObjectId OID or STRING_OID
String STRING* or STRING_OID
Number NUMBER
Date DATE
MinKey MINKEY
MaxKey MAXKEY

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

Examples

create a document

http PUT 127.0.0.01:8080/test/coll/mydoc number:=1 string="whatever" array:='[1,2,3]' object:='{"a":1,"b":2}'
HTTP/1.1 201 CREATED
ETag: 560570e5c2e6b6654c501db7
...

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

http GET 127.0.0.01:8080/test/coll/mydoc
HTTP/1.1 200 OK
ETag: 560570e5c2e6b6654c501db7
...

{
    "_id": "mydoc", 
    "array": [
        1, 
        2, 
        3
    ], 
    "number": 1, 
    "object": {
        "a": 1, 
        "b": 2
    }, 
    "string": "whatever",
    ...
}

web caching

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.

http GET 127.0.0.01:8080/test/coll/mydoc If-None-Match:560570e5c2e6b6654c501db7
HTTP/1.1 304 Not Modified
...

modify a file

http PATCH 127.0.0.01:8080/test/coll/mydoc If-Match:560570e5c2e6b6654c501db7 array.2:=5 object.a:=2
HTTP/1.1 200 OK
...
ETag: 5605736dc2e6b6654c501db9

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

http DELETE 127.0.0.01:8080/test/coll/mydoc If-Match:5605736dc2e6b6654c501db9
HTTP/1.1 204 No Content
...

Documentation references

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.