API_QS

This is a place to collaborate on Queue Server API for mfbus

mfbus module contains a "queue server".

With this service, you can push and pull queues through a REST api. It's not a storage service because all objects have a lifetime and could be automatically cleaned.

Concepts

namespace

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

queue

A queue is just a queue name for your elements. It's a plain string (length < 64 characters). Allowed characters are alphanumeric ones [0-9a-zA-Z], . (dot), _ (underscore) and '-' (hyphen).

element

You can see element as a binary file of any size. It can be a text file, an image, a JSON or anything else. The service does not make any assumptions about the content of your elements. They are never altered. If the size of the element is small (<100kb), it can be stored in memory. If it bigger, it can be stored on disk. So the only limitation is file-system dependent.

lifetime

All elements have a lifetime (in seconds). The lifetime can be specific to each element even there is a default and a maximum value in global configuration.

API

POST /queue_server/{namespace}/elements/{queue}

This service push a new element at the end of given queue in the given namespace. The element is the (raw) body of your POST request.

Note: namespace and queue are created automatically.

If the operation is successful, the service will respond with a HTTP/202 Accepted status code.

You can also set:

• a specific lifetime for your blob by adding (for example) a X-QueueServer-Lifetime: 60 header to your request
• a specific indicative Content-Type for your blob by adding (for example) a X-QueueServer-ContentType: image/png header
• any key/value pair that you want to communicate to the receiver, that will be put into the message: X-Custom-Data: key=value

GET /queue_server/{namespace}/elements/{queue}[?timeout=60]

This service pulls an existing element at the head of the given queue in the given namespace. The element is the (raw) body of the POST request used to add it.

The element is served with the Content-Type header you set during the POST request. The header contains all custom-data you gave.

If the queue is empty:

• if timeout=0 (default), the service reply with HTTP/204 No Content
• if timeout>0, the service blocks until an element is available on the queue HTTP/200 OK or until the timeout HTTP/204 No Content

HEAD `/queue_server/{namespace}/elements/{queue}

Pop a element header from the queue, but doesn't have data associated. The data associated is still accessible with its Blob_Id. (useful for cloning a Blob to multiple clients see API_TBS)

HEAD /queue_server/{namespace}/elements/{queue}/stats

This service returns statistics about this queue (number of elements...)

HEAD /queue_server/{namespace}/stats

This service returns statistics about the namespace (list of queues ?)

HEAD /queue_server/{namespace}/messages/{queue}