The Bucket resource

The Bucket resource represents a containers for binary files (GridFS). Requests to Bucket URI allow to manage the file buckets, create files and get the list of existing files.

Allowed methods are:

Method Description
GET Returns the files bucket properties and the paginated list of its files
PUT Creates or updates the files bucket
POST Creates a file in the bucket
DELETE Deletes the files bucket

The resource URI format is /<dbname>/<bucketname>.files

The name of the bucket must end with the .files suffix. This is how a bucket resource URI is distinguished from a collection resource URI.

The following options influence the files returned as embedded resources to a GET bucket request: pagination, sorting, filtering and projecting.

Updating an existing file in not yet possibile. These are immutable resources.


create the file bucket /test/mybucket.files with the property descr

$ http PUT descr="my first bucket"
HTTP/1.1 201 Created
ETag: 5516731ec2e6e922cf58d6af

update the bucket /test</mybucket.files adding the property creator

$ http PUT creator="ujibang" If-Match:5516731ec2e6e922cf58d6af

Note the If-Match request header. This needs to be added to modify an existing resource. See ETag documentation section for more information.

create a file in the bucket /test/mybucket.files.

http -f POST file@image.png properties='{"filename":"image.png"}'

Creating a file requires a multi-part request: parts are file and properties, the former is the data, the latter a json string with properties to attach to the file.

create a file in the bucket /test/mybucket.files with curl.

curl -v -u user:password -X POST -F 'properties={"filename":"image.png"}' -F "file=@image.png"

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

get the bucket /test/mybucket.files which includes its files as _embedded resources.

$ http GET
HTTP/1.1 200 OK

  "_embedded": {
    "rh:file": [
        "_embedded": {},
        "_links": {
          "self": {
            "href": "/test/mybucket.files/5516d178c2e657ee55badc8c"
          "rh:data": {
            "href": "/test/mybucket.files/5516d178c2e657ee55badc8c/binary"
          "rh:bucket": {
            "href": "/test/mybucket.files"
        "_type": "FILE",
        "filename": "image.png",
        "length": 3225,
        "contentType": "image/png",
        "_id": {
          "$oid": "5516d178c2e657ee55badc8c"
  "_type": "FILES_BUCKET",
  "_id": "checksize.files",
  "descr": "my first bucket",
  "_returned": 1

Note the contentType. This property is automatically detected and stored by RESTHeart.

Note the file representation and its rh:data link:
GET /test/mybucket.files/5516d178c2e657ee55badc8c returns the file properties.
GET /test/mybucket.files/5516d178c2e657ee55badc8c/binary downloads the binary data.

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.