Queue is a logical entity that groups messages. Ideally a queue is created per
work type. For example, if you want to compress files, you would create a queue
dedicated for this job. Any application that reads from this queue would only
compress files.

Nowadays, queue in Zaqar is most like a topic, it’s created lazily. User can
post messages to a queue before creating the queue. Zaqar will create the
queue/topic automatically.

GET

/v2/queues

List queues

Lists queues.

A request to list queues when you have no queues in your account returns 204,
instead of 200, because there was no information to send back.

This operation lists queues for the project. The queues are sorted
alphabetically by name.

Requests a page size of items. Returns a number of items up to a limit
value. Use the limit parameter to make an initial limited request and
use the ID of the last-seen item from the response as the marker
parameter value in a subsequent limited request.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an
initial limited request and use the ID of the last-seen item from the
response as the marker parameter value in a subsequent limited request.

detailed (Optional)

query

boolean

The ‘detailed’ specifies if showing the detailed information when querying
queues, flavors and pools.

The target the message will be moved to when the message can’t processed
successfully after meet the max claim count. It’s not supported to add
queue C as the dead letter queue for queue B where queue B has been set
as a dead letter queue for queue A. There is no default value for this
attribute. If it’s not set explicitly, then that means there is no dead
letter queue for current queue. It is one of the reservedattributes
of Zaqar queues.

_dead_letter_queue_messages_ttl (Optional)

body

integer

The new TTL setting for messages when moved to dead letter queue. If it’s
not set, current TTL will be kept. It is one of the reservedattributes
of Zaqar queues.

_default_message_delay (Optional)

body

string

The delay of messages defined for a queue. When the messages send to
the queue, it will be delayed for some times and means it can not be
claimed until the delay expired. And user can define a queue’s level
value for delay, also can define a message’s level. The latter has
a higher priority. It is one of the reservedattributes of Zaqar
queues.

_default_message_ttl

body

integer

The default TTL of messages defined for a queue, which will effect for
any messages posted to the queue. So when there is no TTL defined for a
message, the queue’s _default_message_ttl will be used. By default, the
value is the same value defined as ‘’max_message_ttl’’ in zaqar.conf. It is
one of the reservedattributes of Zaqar queues. The value will be
reverted to the default value after deleting it explicitly.

_flavor (Optional)

body

string

The flavor name which can tell Zaqar which storage pool will be used to
create the queue. It is one of the reservedattributes of Zaqar
queues.

_max_claim_count (Optional)

body

integer

The max number the message can be claimed. Generally,
it means the message cannot be processed successfully. There is no default
value for this attribute. If it’s not set, then that means this feature
won’t be enabled for current queue. It is one of the
reservedattributes of Zaqar queues.

_max_messages_post_size

body

integer

The max post size of messages defined for a queue, which will effect for
any messages posted to the queue. So user can define a queue’s level
cap for post size which can’t bigger than the max_messages_post_size
defined in zaqar.conf. It is one of the reservedattributes of Zaqar
queues. The value will be reverted to the default value after deleting it
explicitly.

{"_max_messages_post_size":262144,"_default_message_ttl":3600,"_default_message_delay":30,"_dead_letter_queue":"dead_letter","_dead_letter_queue_messages_ttl":3600,"_max_claim_count":10,"description":"Queue for international traffic billing."}

The max post size of messages defined for a queue, which will effect for
any messages posted to the queue. So user can define a queue’s level
cap for post size which can’t bigger than the max_messages_post_size
defined in zaqar.conf. It is one of the reservedattributes of Zaqar
queues. The value will be reverted to the default value after deleting it
explicitly.

_default_message_delay (Optional)

body

string

The delay of messages defined for a queue. When the messages send to
the queue, it will be delayed for some times and means it can not be
claimed until the delay expired. And user can define a queue’s level
value for delay, also can define a message’s level. The latter has
a higher priority. It is one of the reservedattributes of Zaqar
queues.

_default_message_ttl

body

integer

The default TTL of messages defined for a queue, which will effect for
any messages posted to the queue. So when there is no TTL defined for a
message, the queue’s _default_message_ttl will be used. By default, the
value is the same value defined as ‘’max_message_ttl’’ in zaqar.conf. It is
one of the reservedattributes of Zaqar queues. The value will be
reverted to the default value after deleting it explicitly.

In the case of pre-signed URLs, the queue cannot be created lazily. This
is to prevent cases where queues are deleted and users still have a valid
URL. This is not a big issues in cases where there’s just 1 pool. However,
if there’s a deployment using more than 1 type of pool, the lazily created
queue may end up in an undesired pool and it’d be possible for an attacker
to try a DoS on that pool. Therefore, whenever a pre-signed URL is created,
if a pool doesn’t exist, it needs to be created.

Message is sent through a queue and exists until it is deleted by a recipient
or automatically by the system based on a TTL (time-to-live) value.

All message-related operations require Client-Id to be included in the headers.
This is to ensure that messages are not echoed back to the client that posted
them unless the client explicitly requests this.

POST

/v2/queues/{queue_name}/messages

Post Message

Posts the message or messages for the specified queue.

This operation posts the specified message or messages.

You can submit up to 10 messages in a single request, but you must always
encapsulate the messages in a collection container (an array in JSON, even
for a single message - without the JSON array, you receive the “Invalid request
body” message). The resulting value of the Location header or response body
might be used to retrieve the created messages for further processing.

The client specifies only the body and TTL for the message. The server inserts
metadata, such as ID and age.

The response body contains a list of resource paths that correspond to each
message submitted in the request, in the order of the messages. If a
server-side error occurs during the processing of the submitted messages, a
partial list is returned, the partial attribute is set to true, and the client
tries to post the remaining messages again. If the server cannot enqueue any
messages, the server returns a 503ServiceUnavailable error message.

The body attribute specifies an arbitrary document that constitutes the
body of the message being sent.

.The following rules apply for the maximum size:

The maximum size of posted messages is the maximum size of the entire request
document (rather than the sum of the individual message body field values as
it was in earlier releases). On error, the client will now be notified of how
much it exceeded the limit.

The size is limited to 256 KB, including whitespace.

The document must be valid JSON. (The Message Queuing service validates it.)

The ttl attribute specifies how long the server waits before marking the
message as expired and removing it from the queue. The value of ttl must
be between 60 and 1209600 seconds (14 days). Note that the server might not
actually delete the message until its age has reached up to (ttl + 60) seconds,
to allow for flexibility in storage implementations.

The delay attribute specifies how long the message can be claimed.
The value of delay must be between 0 and 900 seconds (15 mins).

A request to list messages when the queue is not found or when messages are
not found returns 204, instead of 200, because there was no information to
send back. Messages with malformed IDs or messages that are not found by ID
are ignored.

This operation gets the message or messages in the specified queue.

Message IDs and markers are opaque strings. Clients should make no assumptions
about their format or length. Furthermore, clients should assume that there is
no relationship between markers and message IDs (that is, one cannot be derived
from the other). This allows for a wide variety of storage driver
implementations.

The ID of the last-seen item. Use the limit parameter to make an
initial limited request and use the ID of the last-seen item from the
response as the marker parameter value in a subsequent limited request.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit
value. Use the limit parameter to make an initial limited request and
use the ID of the last-seen item from the response as the marker
parameter value in a subsequent limited request.

echo (Optional)

query

boolean

Indicate if the messages can be echoed back to the client that posted them.

This operation provides a more efficient way to query multiple messages
compared to using a series of individual GET s. Note that the list of IDs
cannot exceed 20. If a malformed ID or a nonexistent message ID is provided,
it is ignored, and the remaining messages are returned.

Unlike the Get Messages operation, a client’s own messages are always returned
in this operation. If you use the ids parameter, the echo parameter is not used
and is ignored if it is specified.

The message attributes are defined as follows: href is an opaque relative
URI that the client can use to uniquely identify a message resource and
interact with it. ttl is the TTL that was set on the message when it was
posted. The message expires after (ttl - age) seconds. age is the number
of seconds relative to the server’s clock. body is the arbitrary document
that was submitted with the original request to post the message. checksum
is the hash digest of the body, default algorithm is MD5.

This operation immediately deletes the specified messages. If any of the
message IDs are malformed or non-existent, they are ignored. The remaining
valid messages IDs are deleted. Please note that users should input either
ids or pop parameter, otherwise this API will delete nothing. If
pop is provided, the value must be at least 1 and may not be greater than
max_messages_per_claim_or_pop in conf. If ids is provided, it should
contain at least one id and not greater than max_messages_per_page in conf.

A list of the messages ids. pop & ids parameters are mutually
exclusive. Using them together in a request will result in HTTP 400.

NOTE: Actually, it’s not a real list, it’s string combined with many
message ids separated with comma, for example:
/messages?ids=578f0055508f153f256f717e,578f0055508f153f256f717f

pop (Optional)

query

integer

The pop specifies how many messages will be popped up from the queue.
pop & ids parameters are mutually exclusive. Using them together
in a request will result in HTTP 400.

This operation does not accept a request body and does not return a response
body.

GET

/v2/queues/{queue_name}/messages/{message_id}

Get A Specific Message

Gets the specified message from the specified queue.

This operation gets the specified message from the specified queue.

If either the message ID is malformed or nonexistent, no message is returned.

Message fields are defined as follows: href is an opaque relative URI that
the client can use to uniquely identify a message resource and interact with
it. ttl is the TTL that was set on the message when it was posted. The
message expires after (ttl - age) seconds. age is the number of seconds
relative to the server’s clock. body is the arbitrary document that was
submitted with the original request to post the message. checksum is the
hash digest of the body, default algorithm is MD5.

The claim_id parameter specifies that the message is deleted only if it
has the specified claim ID and that claim has not expired. This specification
is useful for ensuring only one worker processes any given message. When a
worker’s claim expires before it can delete a message that it has processed,
the worker must roll back any actions it took based on that message because
another worker can now claim and process the same message.

If you do not specify claim_id, but the message is claimed, the operation
fails. You can only delete claimed messages by providing an appropriate
claim_id.

Claim is a mechanism to mark messages so that other workers will not process
the same message.

POST

/v2/queues/{queue_name}/claims

Claim messages

Claims a set of messages from the specified queue.

This operation claims a set of messages (up to the value of the limit
parameter) from oldest to newest and skips any messages that are already
claimed. If no unclaimed messages are available, the API returns a
204NoContent message.

When a client (worker) finishes processing a message, it should delete the
message before the claim expires to ensure that the message is processed only
once. As part of the delete operation, workers should specify the claim ID
(which is best done by simply using the provided href). If workers perform
these actions, then if a claim simply expires, the server can return an error
and notify the worker of the race condition. This action gives the worker a
chance to roll back its own processing of the given message because another
worker can claim the message and process it.

The age given for a claim is relative to the server’s clock. The claim’s age
is useful for determining how quickly messages are getting processed and
whether a given message’s claim is about to expire.

When a claim expires, it is released. If the original worker failed to process
the message, another client worker can then claim the message.

Note that claim creation is best-effort, meaning the worker may claim and
return less than the requested number of messages.

The ttl attribute specifies how long the server waits before releasing
the claim. The ttl value must be between 60 and 43200 seconds (12 hours).
You must include a value for this attribute in your request.

The grace attribute specifies the message grace period in seconds. The
value of grace value must be between 60 and 43200 seconds (12 hours).
You must include a value for this attribute in your request. To deal with
workers that have stopped responding (for up to 1209600 seconds or 14 days,
including claim lifetime), the server extends the lifetime of claimed messages
to be at least as long as the lifetime of the claim itself, plus the specified
grace period. If a claimed message would normally live longer than the claim’s
live period, its expiration is not adjusted.

The limit specifies up to 20 messages (configurable) to claim. If not
specified, limit defaults to 10. Note that claim creation is best-effort,
meaning the server may claim and return less than the requested number of
messages.

ttl (Optional)

body

integer

The ttl attribute specifies how long the server waits before releasing
the claim. The ttl value must be between 60 and 43200 seconds (12 hours).
You must include a value for this attribute in your request.

grace (Optional)

body

integer

The grace attribute specifies the message grace period in seconds. The
value of grace value must be between 60 and 43200 seconds (12 hours).
You must include a value for this attribute in your request. To deal with
workers that have stopped responding (for up to 1209600 seconds or 14 days,
including claim lifetime), the server extends the lifetime of claimed
messages to be at least as long as the lifetime of the claim itself, plus
the specified grace period. If a claimed message would normally live longer
than the claim’s live period, its expiration is not adjusted.

This operation updates the specified claim for the specified queue. Claims
with malformed IDs or claims that are not found by ID are ignored.

Clients should periodically renew claims during long-running batches of work
to avoid losing a claim while processing a message. The client can renew a
claim by issuing a PATCH command to a specific claim resource and
including a new TTL for the claim (which can be different from the original
TTL). The server resets the age of the claim and applies the new TTL.

The ttl attribute specifies how long the server waits before releasing
the claim. The ttl value must be between 60 and 43200 seconds (12 hours).
You must include a value for this attribute in your request.

grace (Optional)

body

integer

The grace attribute specifies the message grace period in seconds. The
value of grace value must be between 60 and 43200 seconds (12 hours).
You must include a value for this attribute in your request. To deal with
workers that have stopped responding (for up to 1209600 seconds or 14 days,
including claim lifetime), the server extends the lifetime of claimed
messages to be at least as long as the lifetime of the claim itself, plus
the specified grace period. If a claimed message would normally live longer
than the claim’s live period, its expiration is not adjusted.

Example Update Claim: JSON request

{"ttl":300,"grace":300}

This operation does not return a response body.

DELETE

/v2/queues/{queue_name}/claims/{claim_id}

Delete(Release) Claim

Releases the specified claim for the specified queue.

This operation immediately releases a claim, making any remaining, undeleted)
messages that are associated with the claim available to other workers. Claims
with malformed IDs or claims that are not found by ID are ignored.

This operation is useful when a worker is performing a graceful shutdown,
fails to process one or more messages, or is taking longer than expected to
process messages, and wants to make the remainder of the messages available
to other workers.

Subscriptions are relationships between queue/topic and the targeted
subscribers. After created subscriptions for a particular subscriber, like an
email or a webhook, then when new messages posted to the queue, the subscriber
will be notified automatically.

GET

/v2/queues/{queue_name}/subscriptions

List Subscriptions

Lists a queue’s subscriptions.

This operation lists subscriptions for a queue. The subscriptions are sorted
alphabetically by name.

Requests a page size of items. Returns a number of items up to a limit
value. Use the limit parameter to make an initial limited request and
use the ID of the last-seen item from the response as the marker
parameter value in a subsequent limited request.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an
initial limited request and use the ID of the last-seen item from the
response as the marker parameter value in a subsequent limited request.

The subscriber attribute specifies the destination where the message
notify to. It has been designed to match the Internet RFC on Relative
Uniform Resource Locators. Zaqar now support two kinds of subscribers:
http/https and email. The http/https subscriber should start with
http/https. The email subscriber should start with mailto.

ttl (Optional)

body

integer

The ttl attribute specifies how long the subscription be alive. The ttl
value must be great than 60 seconds. The default value is 3600 seconds.

options (Optional)

body

dict

The options attribute specifies the extra metadata for the subscription
. The value must be a dict and could contain any key-value. If the
subscriber is “mailto”. The options can contain from and
subject to indicate the email’s author and title.

The subscriber attribute specifies the destination where the message
notify to. It has been designed to match the Internet RFC on Relative
Uniform Resource Locators. Zaqar now support two kinds of subscribers:
http/https and email. The http/https subscriber should start with
http/https. The email subscriber should start with mailto.

ttl (Optional)

body

integer

The ttl attribute specifies how long the subscription be alive. The ttl
value must be great than 60 seconds. The default value is 3600 seconds.

options (Optional)

body

dict

The options attribute specifies the extra metadata for the subscription
. The value must be a dict and could contain any key-value. If the
subscriber is “mailto”. The options can contain from and
subject to indicate the email’s author and title.

The subscriber attribute specifies the destination where the message
notify to. It has been designed to match the Internet RFC on Relative
Uniform Resource Locators. Zaqar now support two kinds of subscribers:
http/https and email. The http/https subscriber should start with
http/https. The email subscriber should start with mailto.

source (Optional)

body

string

The queue name which the subscription is registered on.

ttl (Optional)

body

integer

The ttl attribute specifies how long the subscription be alive. The ttl
value must be great than 60 seconds. The default value is 3600 seconds.

options (Optional)

body

dict

The options attribute specifies the extra metadata for the subscription
. The value must be a dict and could contain any key-value. If the
subscriber is “mailto”. The options can contain from and
subject to indicate the email’s author and title.

With health API, user or operator can get a general idea about the status of
Zaqar server. Those information can be used for basic validation, performance
checking, etc.

GET

/v2/ping

Ping

Simple health check for end user.

A request to ping Zaqar server when server is working returns 204, otherwise
returns 503. This can be a handy API for end user to check if the messaging
service is in working status.

Normal response codes: 204

Error response codes:

ServiceUnavailable (503)

This operation does not accept a request body and does not return a response
body.

GET

/v2/health

Health

Detailed health check for cloud operator/admin.

This is an adminonly API. A request to get detailed health information
of Zaqar server.

The response body will depend on the storage setting of Zaqar server. By
default, there is no pool created. Then the response body will only
contain the catalog_reachable. Otherwise, the response body will have
catalog_reachable and the health status for each pool.

A boolean value to indicate if the management(catalog) datatabse is
reachable or not.

storage_reachable (Optional)

body

boolean

A boolean value to indicate if the messages(pool) datatabse is
reachable or not.

operation_status (Optional)

body

dict

A dict which will contain the status for many different actions/operations.
For example, post_messages, delete_messages, delete queue, etc. And each
status is a dict which contains three items: seconds, ref and
succeeded. Seconds means how long the operation took and succeeded will
indicate if the actions was successful or not. Ref may contain the
information if the succeeded is False, otherwise it’s null.

If pooling is enabled, queuing service uses multiple queues databases in order
to scale horizontally. A pool (queues database) can be added any time without
stopping the service. Each pool has a weight that is assigned during the
creation time but can be changed later. Pooling is done by queue which
indicates that all messages for a particular queue can be found in the same
pool (queues database).

GET

/v2/pools

List pools

Lists pools.

This operation lists pools for the project. The pools are sorted
alphabetically by name.

Requests a page size of items. Returns a number of items up to a limit
value. Use the limit parameter to make an initial limited request and
use the ID of the last-seen item from the response as the marker
parameter value in a subsequent limited request.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an
initial limited request and use the ID of the last-seen item from the
response as the marker parameter value in a subsequent limited request.

detailed (Optional)

query

boolean

The ‘detailed’ specifies if showing the detailed information when querying
queues, flavors and pools.

Queue flavors allow users to have different types of queues based on the
storage capabilities. By using flavors, it’s possible to allow consumers of the
service to choose between durable storage, fast storage, etc. Flavors must be
created by service administrators and they rely on the existence of pools.

GET

/v2/flavors

List flavors

Lists flavors.

This operation lists flavors for the project. The flavors are sorted
alphabetically by name.

Requests a page size of items. Returns a number of items up to a limit
value. Use the limit parameter to make an initial limited request and
use the ID of the last-seen item from the response as the marker
parameter value in a subsequent limited request.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an
initial limited request and use the ID of the last-seen item from the
response as the marker parameter value in a subsequent limited request.

detailed (Optional)

query

boolean

The ‘detailed’ specifies if showing the detailed information when querying
queues, flavors and pools.