The Collection resource

The Collection resource represents a collection. Requests to Collection URI allow to manage the collections, create documents and get the list of existing documents.

The resource URI format is /<dbname>/<collname>

Allowed methods

Method Description
GET Returns the collection properties and the list of its documents
PUT Creates or updates the collection
PATCH Updates the collection properties
POST Creates or updates one document (passing an object) or several documents (passing an array of objects) in the collection
DELETE Deletes the collection

Useful query parameters

qparam Description applies to
page Data page to return (default 1) GET
pagesize Data page size (default 100, maximum 1000; If equals to 0 only returns the db properties) GET
np Don’t return collection properties, i.e. only embedded documents GET
filter Filter query GET
keys Documents keys to return (projection) GET
sort Sort to apply to returned documents GET
shardkey In case of shared server, the shard keys Any verb


create the collection /test/coll with the property descr

$ http PUT descr="my first collection"
HTTP/1.1 201 Created

update the collection /test</coll adding the property creator

$ http PUT creator="ujibang"

create a document in the collection /test/coll.

http POST number:=1 string="whatever" array:='[1,2,3]' object:='{"a":1,"b":2}'

A document can also be created via a PUT to a document URI. POSTing the collection has the advantage that the _id will be automatically generated (of type ObjectId) and returned in the Location response header.

Note the Location response header. This is the URL of the created document.

get the collection /test/coll which includes its documents as _embedded resources.

$ http GET
HTTP/1.1 200 OK

    "_embedded": {
        "rh:doc": [
                "_id": { "$oid": "55f15fc5c2e65448b566d18d" }
                "array": [ 1, 2, 3 ], 
                "number": 1, 
                "object": { "a": 1, "b": 2 }, 
                "string": "whatever",
                "_etag": { "$oid": "5516731ec2e6e922cf58d6af" }
    "_returned": 1, 
    "descr": "a collection for testing",
    "_etag": { "$oid": "55e84b95c2e66d1e0a8e46b2" },

Note the _etag property. It enables web caching and can be used to avoid ghost writes.
By default it is mandatory to specify it via the If-Match header to delete a collection. See ETag documentation section for more information.

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.