v8 v7 v6 v5 v4 v3
Edit Page

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.