The DB resource

The DB resource represent a database. Request to DB URIs allow to manage the databases and get the list of their collections and file buckets.

The resource URI format is /<dbname>

Allowed methods

Method Description
GET Returns the database properties and the paginated list of its collections and file buckets
PUT Creates or updates the database
PATCH Updates the database (only passed data)
DELETE Deletes the database

Useful query parameters

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 db properties, i.e. only embedded collections and file buckets GET


create the database /test with the property descr

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

update the database /test adding the property creator

$ http PATCH creator="ujibang"

get the database /test which includes its collections and file buckets as _embedded resources.

$ http GET
HTTP/1.1 200 OK

    "_embedded": {
        "rh:bucket": [
                "_id": "mybucket.files", 
                "descr": "my first bucket",
                "_etag": { "$oid": "5516731ec2e6e922cf58d6af" }
        "rh:coll": [
                "_id": "mycollection", 
                "descr": "my first collection",
                "_etag": { "$oid": "55f15fc5c2e65448b566d18d" }
    "descr: "my first db",
    "creator": "ujibang",
    "_etag": { "$oid": "55e84b95c2e66d1e0a8e46b2" },
    "_returned": 2, 
    "_size": 2, 
    "_total_pages": 1, 

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