Binary Files

RESTHeart offers complete binary files management. It’s possible to create, read and delete even huge files. RESTHeart makes use of MongoDB’s GridFS, a specification for storing and retrieving files that exceed the BSON-document size limit of 16 MB.

You can read more about GridFS here.

Create a File Bucket

File buckets are special collections whose aim is to store binary data and the associated metadata. Start by creating a new one for uploading binaries.

Note	A file bucket name must end with .files (e.g. `mybucket.files` is a valid file bucket name)

Create the default restheart database, if none exists yet:

Create the file bucket.

PUT /mybucket.files HTTP/1.1

HTTP/1.1 201 Created

Upload a file with POST

POST /bucket.files is used to insert a file.

Note	the request body must be encoded as `multipart/form-data`. This is obtained in the following example with the `--form` option in the `http` command

The following example request POSTs the binary image example.jpg with {"author":"SoftInstigate"} metadata into /mybucket.files

With httpie:

$ http -a admin:secret --form POST localhost:8080/mybucket.files @/path/to/my/binary/example.jpg metadata='{"author":"SoftInstigate", "filename": "example.jpg"}'

HTTP/1.1 201 Created
Location: http://localhost:8080/mybucket.files/5e5fcdd8ddfa017301e00331
(other response headers omitted)

With curl:

$ curl -i -X POST -u admin:secret --form metadata='{"author":"SoftInstigate", "filename": "example.jpg"}' --form file= @/path/to/my/binary/example.jpg localhost:8080/mybucket.files

HTTP/1.1 201 Created
Location: http://localhost:8080/mybucket.files/5e5fcdd8ddfa017301e00331
(other response headers omitted)

curl -i -X POST -u admin:secret --form metadata='{"filename":"hello.json"}' --form file=@/tmp/hello2.json localhost:8080/my.files

The Location HTTP header returns the file’s URI. The last part is the _id.

Note	file bucket does not support write mode. The `POST` verb is always an insert. If an `_id` is specified in the request content and a file with this `_id` already exists, the request will fail with status code `409 Conflict`

Upsert a file with PUT

PUT /bucket.files/fileid is used to upsert a file.

Note	the request body must be encoded as `multipart/form-data`. This is obtained in the following example with the `--form` option in the `http` command

With httpie:

$ http -a admin:secret --form PUT localhost:8080/mybucket.files/example  @/path/to/my/binary/example.jpg metadata='{"author": "SoftInstigate", "filename": "example.jgp"}'

HTTP/1.1 201 Created

With curl:

$ curl -i -X PUT -u admin:secret --form metadata='{"author":"SoftInstigate", "filename": "example.jpg"}' --form file=@/path/to/my/binary/example.jpg localhost:8080/mybucket.files/example

HTTP/1.1 201 Created

Note	file bucket does not support write mode. The `PUT` verb is always an upsert. If the file exists, it will be updated (response code `200 Ok`) otherwise it will be created (response code `201 Created`)

GET the file metadata

The file metadata is returned with GET /bucket.files and GET /bucket.files/fileid requests.

GET http://localhost:8080/mybucket.files/example HTTP/1.1

{
    "_id": "example.jpg",
    "chunkSize": 261120,
    "filename": "example.jgp",
    "length": 66273,
    "metadata": {
        "_etag": {
            "$oid": "5e5fcdd8ddfa017301e00330"
        },
        "author": "SoftInstigate",
        "contentType": "image/jpeg",
        "filename": "example.jgp"
    },
    "uploadDate": {
        "$date": 1583336920114
    }
}

Important

the file contentType is automatically detected by RESTHeart and used to define the Content-Type response header.

Note	Uploaded files metadata can be filtered and treated as regular collection documents. For example, `http://localhost:8080/mybucket.files?filter={"metadata.author":"SoftInstigate"}` returns all the file metadata that satisfy the query.

GET the file binary data

The binary content is available by appending /binary to the file URI:

GET http://localhost:8080/mybucket.files/example/binary HTTP/1.1

Update file metadata

PUT /bucket.files/docid and PATCH /bucket.files/docid are used to update the file metadata.

Important

to update the metadata, use a normal requests with Content-Type: application/json. This differ from upserting a file that uses a multi-part request, i.e. Content-Type: multipart/form-data

The following request, adds the two field foo and bar to the file metadata.

PATCH http://localhost:8080/mybucket.files/example HTTP/1.1

{
    "foo": 1,
    "bar": 2
}

The following request replaces the whole file metadata with the given document:

PUT http://localhost:8080/mybucket.files/example HTTP/1.1

{
    "author": "uji"
}

Note	update operators and update aggregation pipelines cannot be used in files updates.