API
Currently in development
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/filesGET
Used to GET a collection of files
bucketID, creationTime, method, sigprefix, includeData, startsWith-
/blob/files/{identifier}GET
Used to retrieve file metadata or file base64 encoded data of the file with {identifier}.
bucketID, creationTime, method, sigincludeData (was called binary below v0.1.14)-
/blob/files/{identifier}/downloadGET
Used to retrieve binary file data of the file with {identifier}
bucketID, creationTime, method, sig-
/blob/filesPOST
Used to create a file
bucketID, creationTime, prefix, method, sigfile, fileName, fileHashadditionalMetadata, additionalType, notifyEmail, retentionDuration
/blob/filesDELETE
Used to DELETE the files with given prefix
bucketID, creationTime, prefix, method, sigstartsWith-
/blob/files/{identifier}DELETE
Used to DELETE the file with given
bucketID, creationTime, method, sig-
/blob/files/{identifier}PATCH
Used to change the filename with given
bucketID, creationTime, method, sigat least one of the optional body parameters
file, fileName, additionalMetadata, additionalType, existsUntil, notifyEmail
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
bucketIDID of the bucket in which the file(s) are located.
int
all valid bucket IDs
creationTimeCurrent time (UTC) in seconds
int
all valid integers
prefixprefix which the file(s) have
string
all valid prefixes
startsWithif 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
sigsignature string of the checksums ucs and bcs
string
all valid signature strings
fileNameoriginal filename of the file
string
all valid strings
fileHashthe 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
notifyEmailemail address of a person that wants to be notified before deletion
string
all valid email addresses
retentionDurationdefines the lifespan of the file
int
all non-negative int durations
additionalMetadatasome additional data the uploader wants to add
string / json
all valid json strings
additionalTypea type given to the additionalMetadata. If the type is also defined in the blob bundle config, then the additionalMetadata is also validated against the given schema.
string
all valid strings
existsUntila timestamp in ISO 8601 that defines how long the resource should exist
string
datetime string
filethe 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 are two signed items, one is a SHA-256 checksum ucs that was generated using the url and one is a SHA-256 checksum bcs that was generated using the body. ucs is needed in every request, while bcs is only needed in POST and PATCH requests!
Everything beginning from and including /blob has to be included when generating the url checksum ucs.
Everything in the body except the file formData has to be included when generating the body checksum bcs. POST and PATCH requests should only have multipart/formdata bodys . Everything except the file formData needs to be included in the checksum bcs.
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-sig400
The signature parameter sig is missing
message
blob:get-file-data-collection-missing-bucket-id400
The bucket id parameter bucketID is missing
message
blob:get-file-data-collection-missing-creation-time400
The creation time parameter creationTime is missing
message
blob:get-file-data-collection-missing-method400
The method/action parameter method is missing
message
blob:get-file-data-collection-bucket-id-not-configured400
Bucket with given bucketID is not configured
message['message' => 'Signature cannot checked']
blob:get-file-data-collection-no-bucket-service400
BucketService is not configured
message['message' => 'Signature cannot checked']
blob:check-signature-missing-sig400
The signature in parameter sig is missing
message
blob:check-signature-missing-signature-params400
One or multiple of the required url parameters are missing
message
blob:check-signature-creation-time-too-old403
The parameter creationTime is too old, therefore the request timed out and a new request has to be created, signed and sent
message
blob:check-signature-method-not-suitable405
The method used is not compatible with the method/action specified in the url
message
POST
relay:errorId
Status code
Description
relay:errorDetails
Example
blob:create-file-data-missing-sig400
The signature parameter sig is missing
message['message' => 'Signature cannot checked']
blob:create-file-data-unset-params400
One or multiple of the required url parameters are missing
message
blob:create-file-data-data-upload-failed400
Data upload failed.
message
blob:create-file-data-no-bucket-service400
BucketService is not configured.
message
blob:create-file-data-missing-file400
No file with parameter key "file" was received!
message
blob:create-file-data-upload-error400
File upload pload went wrong.
message
blob:create-file-data-empty-files-not-allowed400
Empty files cannot be added!
message
blob:create-file-data-not-configured-bucket-id400
BucketID is not configured
message
blob:create-file-bad-additional-metadata400
The parameter additionalMetadata is not a valid json
blob:create-file-data-file-hash-change-forbidden403
The parameter fileHash does not match with the hash of the uploaded file
message
blob:create-file-data-creation-time-too-old403
The parameter creationTime is too old, therefore the request timed out and a new request has to be created, signed and sent
message
blob:signature-invalid403
The signature is invalid, e.g. by using a wrong key
message['message' => 'Signature cannot checked']
blob:checksum-invalid403
The checksum sent in the signature is invalid, e.g. by changing some params, using the wrong hash algorithm or forgetting some characters
message
blob:create-file-data-method-not-suitable405
The method used is not compatible with the method/action specified in the url
message
blob:blob-service-invalid-json422
The additional Metadata doesn't contain valid json!
message
blob:file-not-saved500
File could not be saved!
message
blob:create-file-data-bucket-quota-reached507
Bucket quota is reached.
message
DELETE
relay:errorId
Status code
Description
relay:errorDetails
Example
blob:delete-file-data-by-prefix-missing-sig400
The signature in parameter sig is missing
message
blob:delete-file-data-by-prefix-unset-sig-params400
One or multiple of the required url parameters are missing
message['message' => 'Signature cannot checked']
blob:delete-file-data-by-prefix-bucket-id-not-configured400
Bucket is not configured
message['message' => 'Signature cannot checked']
blob:delete-file-data-by-prefix-no-bucket-service400
BucketService is not configured
message['message' => 'Signature cannot checked']
blob:delete-file-data-by-prefix-creation-time-too-old403
The parameter creationTime is too old, therefore the request timed out and a new request has to be created, signed and sent
message
blob:signature-invalid403
The signature is invalid, e.g. by using a wrong key
message['message' => 'Signature cannot checked']
blob:checksum-invalid403
The checksum sent in the signature is invalid, e.g. by changing some params, using the wrong hash algorithm or forgetting some characters
message
blob:file-data-not-found404
No data was found for the specified bucketID and prefix combination
message
blob:delete-file-data-by-prefix-method-not-suitable405
The method used is not compatible with the method/action specified in the url
message
Item operations (by identifier) /blob/files/{identifier}
GET
relay:errorId
Status code
Description
relay:errorDetails
Example
blob:get-file-data-by-id-missing-sig400
The signature in parameter sig is missing
message
blob:get-file-data-by-id-missing-bucket-id400
The parameter bucketID is missing
message
blob:get-file-data-by-id-bucket-not-configured400
The bucket with given bucketID is not configured
message
blob:get-file-data-by-id-missing-bucket-id400
The request has not specified a action/method
blob:check-signature-missing-sig400
The signature in parameter sig is missing
message
blob:check-signature-missing-signature-params400
One or multiple of the required url parameters are missing
message
blob:check-signature-creation-time-too-old403
The parameter creationTime is too old, therefore the request timed out and a new request has to be created, signed and sent
message
blob:get-file-data-by-id-file-data-not-found404
No FileData for the given identifier was not found!
message
blob:get-file-data-by-id-method-not-suitable405
The method used is not compatible with the method/action specified in the url
message
blob:check-signature-method-not-suitable405
The method used is not compatible with the method/action specified in the url
message
PATCH
relay:errorId
Status code
Description
relay:errorDetails
Example
blob:get-file-data-by-id-missing-sig400
The signature in parameter sig is missing
message
blob:get-file-data-by-id-missing-bucket-id400
The parameter bucketID is missing
message
blob:get-file-data-by-id-bucket-not-configured400
The bucket with given bucketID is not configured
message
blob:check-signature-missing-sig400
The signature in parameter sig is missing
message
blob:check-signature-missing-signature-params400
One or multiple of the required url parameters are missing
message
blob:patch-file-data-missing400
At least one parameter has to be provided
message
blob:patch-file-data-bad-additional-type400
The given additionalType is not defined in the config
blob:patch-file-data-bad-additional-metadata400
The given additionalMetadata is no valid JSON
blob:patch-file-data-additional-type-mismatch400
The given additionalMetadta does not match the JSON schema defined in additionalType
blob:patch-file-data-exists-until-bad-format400
The given existsUntil is not a valid DateTime format!
blob:check-signature-creation-time-too-old403
The parameter creationTime is too old, therefore the request timed out and a new request has to be created, signed and sent
message
blob:get-file-data-by-id-file-data-not-found404
No FileData for the given identifier was not found!
message
blob:get-file-data-by-id-method-not-suitable405
The method used is not compatible with the method/action specified in the url
message
blob:check-signature-method-not-suitable405
The method used is not compatible with the method/action specified in the url
message
blob:file-not-saved500
File could not be saved!
message
DELETE
relay:errorId
Status code
Description
relay:errorDetails
Example
blob:get-file-data-by-id-missing-sig400
The signature in parameter sig is missing
message
blob:get-file-data-by-id-missing-bucket-id400
The parameter bucketID is missing
message
blob:get-file-data-by-id-bucket-not-configured400
The bucket with given bucketID is not configured
message
blob:check-signature-missing-sig400
The signature in parameter sig is missing
message
blob:check-signature-missing-signature-params400
One or multiple of the required url parameters are missing
message
blob:check-signature-creation-time-too-old403
The parameter creationTime is too old, therefore the request timed out and a new request has to be created, signed and sent
message
blob:get-file-data-by-id-file-data-not-found404
No FileData for the given identifier was not found!
message
blob:get-file-data-by-id-method-not-suitable405
The method used is not compatible with the method/action specified in the url
message
blob:check-signature-method-not-suitable405
The method used is not compatible with the method/action specified in the url
message
Download operation /blob/files/{identifier}/download
GET
relay:errorId
Status code
Description
relay:errorDetails
Example
blob:download-file-by-id-missing-identifier400
The identifier {identifier} is missing
message
blob:download-file-by-id-missing-bucket-id400
The bucket id parameter bucketID is missing
message
blob:download-file-by-id-missing-method400
The prefix parameter prefix is missing
message
blob:download-file-by-id-missing-creation-time400
The creation time parameter creationTime is missing
message
blob:download-file-by-id-bucket-not-configured400
The bucket with given bucketID is not configured
message
blob:download-file-by-id-invalid-method400
The action/method combination is not valid
message
blob:download-file-by-id-missing-sig400
The signature parameter sig is missing
message
blob:download-file-by-id-creation-time-too-old403
The creation time parameter creationTime is too old
message
blob:checksum-invalid403
The checksum ucs or bcs inside the signature is not valid
message
blob:signature-invalid403
The signature in parameter sig is invalid
message