This bundle is currently in development, thus not everything may work as explained here.
The bundle provides GET endpoints for retrieving file metadata, file binary data and POST, DELETE endpoints for creating and deleting data.
Endpoints
Endpoint
Method
Description
Required Url Parameters
Optional Url Parameter
Required body parameter (as formData)
Optional body parameter (as formData)
/blob/files
GET
Used to GET a collection of files
bucketIdentifier, creationTime, method, sig
prefix, includeData, startsWith
-
/blob/files/{identifier}
GET
Used to retrieve file metadata or file base64 encoded data of the file with {identifier}.
bucketIdentifier, creationTime, method, sig
includeData (was called binary below v0.1.14)
-
/blob/files/{identifier}/download
GET
Used to retrieve binary file data of the file with {identifier}
bucketIdentifier, creationTime, method, sig
-
/blob/files
POST
Used to create a file
bucketIdentifier, creationTime, prefix, method, sig
notifyEmail, retentionDuration, type
file, fileName,
metadata, fileHash, metadataHash
/blob/files
DELETE
Used to DELETE the files with given prefix
bucketIdentifier, creationTime, prefix, method, sig
startsWith
-
/blob/files/{identifier}
DELETE
Used to DELETE the file with given
bucketIdentifier, creationTime, method, sig
-
/blob/files/{identifier}
PATCH
Used to change the filename with given
bucketIdentifier, creationTime, method, sig
type, existsUntil, notifyEmail
at least one of the optional body parameters
file, fileName, metadata
In general, the parameters have to be given in the specified order while optional parameters can be selectively left out for the computation of the checksum. The only exception is the sig parameter, which always has to be the last parameter.
Parameters
Parameter
Description
Type
Possible values
bucketIdentifier
ID of the bucket in which the file(s) are located.
int
all valid bucket IDs
creationTime
Current time (UTC) in seconds
int
all valid integers
prefix
prefix which the file(s) have
string
all valid prefixes
startsWith
if set, the request operation will affect all prefixes starting with the given prefix
int
1
method (was called action until v0.1.14)
method that is used, e.g. GET to get files
string
GET, POST, DELETE, PATCH
sig
signature string of the checksums ucs
string
all valid signature strings
fileName
original filename of the file
string
all valid strings
fileHash
the fileHash of the binary file
string
all valid hash strings
includeData (was called binary until v0.1.14)
defines whether the base64 encoded binary data should be returned (=1) or a link to the binary data
int
0 or 1
notifyEmail
email address of a person that wants to be notified before deletion
string
all valid email addresses
retentionDuration
defines the lifespan of the file
int
all non-negative int durations
metadata (was called additionalMetadata until v0.1.35)
some additional metadata the uploader wants to add
string / json
all valid json strings
type (was called additionalType until v0.1.35)
a type given to the metadata. If the type is also defined in the blob bundle config, then the metadata is also validated against the given schema.
string
all valid strings
existsUntil
a timestamp in ISO 8601 that defines how long the resource should exist
string
datetime string
file
the file to upload
file
Signature
Key security
The key should be kept confidential and safe and should NOT be leaked into the frontend or the user! The key has to remain secret!
The signatures are JWTs created with the algorithm HS256 and are sent as a string. There is one signed item, a SHA-256 checksum ucs that was generated using the url, and it is needed in every request.
Everything beginning from and including /blob has to be included when generating the url checksum ucs. POST and PATCH requests should only have multipart/formdata bodys.
The signature then has to be appended at the end of the url using the sig parameter.
The key used for signing and verifying the checksum has to be defined in the blob bucket config and the other backend system communicating with blob.
Signature url encoding
By default, blob verifies the url by generating the signature of the urlencoded url using RFC3986. This means that, among other things, space get converted to %20!
This means that systems communicating with blob have to also generate their checksum this way. It is not possible to just urlencode the whole url, since this would mean that valid symbols like / or & would be encoded too. Therefore, it is necessary to urlenode each parameter value separately before appending them in the url.
Error codes and descriptions
Collection operations (by prefix) /blob/files
GET
relay:errorId
Status code
Description
relay:errorDetails
Example
blob:get-file-data-collection-missing-sig
400
The signature parameter sig is missing
message
blob:get-file-data-collection-missing-bucket-id
400
The bucket id parameter bucketIdentifier is missing