API_QS

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

mfbus module provides a "queue server".

With this service, you can push and pull queues through a REST api.

All posted messages have a limited (but modificable) lifetime.

Metadata:

• Metadata can be associated with the posted message during POST operations.
• GET operations give access to both data and Metadata.

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

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.

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 /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. A X-BlobStorage_Id header is automatically added to the element that represents the id of the data stored in the blob storage.

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 an 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)

PUT /queue_server/{namespace}/elements/{queue}

Push an element in the queue without data. The body is ignored. If the header contains a reference to an existing blob (for example X-BlobStorage_Id), the data will be sent back to the reader on the GET request.

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}