API_TBS

Temporary blob server

mfbus module contains a "Temporary blob server".

With this service, you can store and retrieve various files of any type through a REST api. It's not a storage service because all objects have a lifetime and could be automatically cleaned.

Meta-data can be associated with the data, that will be retrieved when you get the file.

To retrieve a data from this service, you only need to know the namespace and queue names.

Concepts

namespace

A namespace is just a kind of bucket for yours blobs and corresponding queues. It's a plain string (length < 64 characters). Allowed characters are alphanumeric ones [0-9a-zA-Z], . (dot), _ (underscore) and '-' (hyphen).

blob

You can see blob as a binary file. It can be a text file, an image or anything else. The service does not make any assumptions about the content of your blobs. They are never altered.

When you submit your blob to the service, you will get a blob unique id (blob_uid). You have to know your blob_uid to retrieve it. There is no other way (no search service...).

You can provide an indicative (media type)[https://en.wikipedia.org/wiki/Media_type] to your blob. It will be returned as a HTTP Content-Type header during retrieval.

lifetime

All blobs have a lifetime (in seconds). The lifetime can be specific to each blob event there is a default and a maximum value in global configuration.

meta-data

Any key/value pair that will be sent in the header of the post/put/get: X-Custom-Data: key=value

API

POST /tmp_blob_store/{namespace}/blobs

This service add a new blob in the blob store inside the given namespace. The blob is the (raw) body of your POST request.

Note: The namespace is created automatically.

If the operation is successful, the service will respond with a HTTP/201 Created status code and you will get your blob_uid in the JSON reply (or in Location header).

HTTP/1.1 201 Created
Location: http://{...}/tmp_blob_store/{namespace}/blobs/{blob_uid}
Content-Type: application/vnd.api+json

{
    "data": {
        "type": "blob",
        "id": "{blob_uid}",
        "attributes": {
            "lifetime": 3600,
            "content-type": "application/octet-stream"
        },
        "links": {
            "self": "http://{...}/tmp/blob_store/{namespace}/blobs/{blob_uid}
        }
    }
}

If the operation is not successful, the service will respond with a:

• HTTP/413: when your blob is too large (there is a max size in the global configuration)
• HTTP/429: when you hit the number or the size limit of the namespace
• HTTP/400: in other client error cases (bad namespace string for example, too big lifetime...)

You can also set:

• a specific lifetime for your blob by adding (for example) a X-TmpBlobStore-Lifetime: 60 header to your request
• a specific indicative Content-Type for your blob by adding (for example) a X-TmpBlobStore-ContentType: image/png header
• any key/value pair that you want to communicate to the receiver, that will be sent back when he get the blob: X-CustomBlob-Data: key=value

GET /tmp_blob_store/{namespace}/blobs/{blob_uid}[?delete=1]

Get the given blob (the body posted with the previous POST request) or HTTP/404.

If delete=1, the blob is deleted just after the read. So, with this parameter, this is a "single use request". You get the meta-datas associated in the header.

DELETE /tmp_blob_store/{namespace}/blobs/{blob_uid}

Delete the given blob or HTTP/404. (see note above)

POST/tmp_blob_store/{namespace}/blobs/{blob_uid}/clone

Do a clone of the given blob_uid. Note: The PUT verb could be used because it does not create new data, but only new metat-data.

The request body is ignored but you can override headers:

• X-TmpBlobStore-Lifetime
• X-CustomBlob-Data

See POST /tmp_blob_store/{namespace}/blobs API for more details.

note: The data is effectively deleted when the last clone is deleted.