610 lines
17 KiB
YAML
610 lines
17 KiB
YAML
# variables in header
|
|
|
|
client_id:
|
|
type: string
|
|
in: header
|
|
description: |
|
|
The identification for each client instance. The format of client id is
|
|
UUID by default, but Zaqar also supports a Non-UUID string by setting
|
|
configuration "client_id_uuid_safe=off". The UUID must be submitted in its
|
|
canonical form (for example, 3381af92-2b9e-11e3-b191-71861300734c). The
|
|
string must be longer than "min_length_client_id=20" and smaller than
|
|
"max_length_client_id=300" by default. User can control the length of
|
|
client id by using those two options. The client generates the Client-ID
|
|
once. Client-ID persists between restarts of the client so the client
|
|
should reuse that same Client-ID. Note: All message-related operations
|
|
require the use of ``Client-ID`` in the headers to ensure that messages
|
|
are not echoed back to the client that posted them, unless the client
|
|
explicitly requests this.
|
|
|
|
# variables in path
|
|
|
|
claim_id:
|
|
type: string
|
|
in: path
|
|
required: True
|
|
description: |
|
|
The id of the claim.
|
|
|
|
flavor_name_path:
|
|
type: string
|
|
in: path
|
|
required: True
|
|
description:
|
|
The name of the flavor.
|
|
|
|
message_id:
|
|
type: string
|
|
in: path
|
|
required: True
|
|
description: |
|
|
The ID of the message.
|
|
|
|
pool_name_path:
|
|
type: string
|
|
in: path
|
|
required: True
|
|
description:
|
|
The name of the pool.
|
|
|
|
queue_name:
|
|
type: string
|
|
in: path
|
|
required: True
|
|
description: |
|
|
The name of the queue.
|
|
|
|
subscription_id_path:
|
|
type: string
|
|
in: path
|
|
required: True
|
|
description: |
|
|
The id of the subscription.
|
|
|
|
# variables in query
|
|
|
|
claim_limit:
|
|
type: integer
|
|
in: query
|
|
required: false
|
|
description: |
|
|
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.
|
|
|
|
detailed:
|
|
type: boolean
|
|
in: query
|
|
required: false
|
|
description: |
|
|
The 'detailed' specifies if showing the detailed information when querying
|
|
queues, flavors and pools.
|
|
|
|
echo:
|
|
type: boolean
|
|
in: query
|
|
required: false
|
|
description:
|
|
Indicate if the messages can be echoed back to the client that posted
|
|
them.
|
|
|
|
ids:
|
|
type: list
|
|
in: query
|
|
required: false
|
|
description: |
|
|
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
|
|
|
|
include_claimed:
|
|
type: boolean
|
|
in: query
|
|
required: false
|
|
description:
|
|
Indicate if the messages list should include the claimed messages.
|
|
|
|
include_delayed:
|
|
type: boolean
|
|
in: query
|
|
required: false
|
|
description:
|
|
Indicate if the messages list should include the delayed messages.
|
|
|
|
limit:
|
|
type: integer
|
|
in: query
|
|
required: false
|
|
description: |
|
|
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:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
description: |
|
|
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.
|
|
|
|
name:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
description: |
|
|
The 'name' specifies if filter the queues by queue's name when querying
|
|
queues.
|
|
|
|
pop:
|
|
type: integer
|
|
in: query
|
|
required: false
|
|
description: |
|
|
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.
|
|
|
|
with_count:
|
|
type: boolean
|
|
in: query
|
|
required: false
|
|
description: |
|
|
The 'with_count' specifies if showing the amount of queues when querying
|
|
them.
|
|
|
|
# variables in body
|
|
|
|
_dead_letter_queue:
|
|
type: string
|
|
in: body
|
|
required: False
|
|
description: |
|
|
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 ``reserved attributes``
|
|
of Zaqar queues.
|
|
|
|
_dead_letter_queue_messages_ttl:
|
|
type: integer
|
|
in: body
|
|
required: False
|
|
description: |
|
|
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 ``reserved attributes``
|
|
of Zaqar queues.
|
|
|
|
_dead_letter_queue_messages_ttl_response:
|
|
type: integer
|
|
in: body
|
|
required: True
|
|
description: |
|
|
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 ``reserved attributes``
|
|
of Zaqar queues.
|
|
|
|
_dead_letter_queue_response:
|
|
type: string
|
|
in: body
|
|
required: True
|
|
description: |
|
|
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 ``reserved attributes``
|
|
|
|
_default_message_delay:
|
|
type: string
|
|
in: body
|
|
required: False
|
|
description: |
|
|
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 ``reserved attributes`` of Zaqar
|
|
queues.
|
|
|
|
_default_message_delay_response:
|
|
type: string
|
|
in: body
|
|
required: True
|
|
description: |
|
|
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 ``reserved attributes`` of Zaqar
|
|
|
|
_default_message_ttl:
|
|
type: integer
|
|
in: body
|
|
required: True
|
|
description: |
|
|
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 ``reserved attributes`` of Zaqar queues. The value will be
|
|
reverted to the default value after deleting it explicitly.
|
|
|
|
_flavor:
|
|
type: string
|
|
in: body
|
|
required: False
|
|
description: |
|
|
The flavor name which can tell Zaqar which storage pool will be used to
|
|
create the queue. It is one of the ``reserved attributes`` of Zaqar
|
|
queues.
|
|
|
|
_max_claim_count:
|
|
type: integer
|
|
in: body
|
|
required: False
|
|
description: |
|
|
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
|
|
``reserved attributes`` of Zaqar queues.
|
|
|
|
_max_claim_count_response:
|
|
type: integer
|
|
in: body
|
|
required: True
|
|
description: |
|
|
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
|
|
``reserved attributes`` of Zaqar queues.
|
|
|
|
_max_messages_post_size:
|
|
type: integer
|
|
in: body
|
|
required: True
|
|
description: |
|
|
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 ``reserved attributes`` of Zaqar
|
|
queues. The value will be reverted to the default value after deleting it
|
|
explicitly.
|
|
|
|
capabilities:
|
|
type: list
|
|
in: body
|
|
description: |
|
|
Capabilities describe what this flavor is capable of base on the storage
|
|
capabilities. They are used to inform the final user such capabilities.
|
|
|
|
catalog_reachable:
|
|
type: boolean
|
|
in: body
|
|
required: True
|
|
description: |
|
|
A boolean value to indicate if the management(catalog) datatabse is
|
|
reachable or not.
|
|
|
|
claim_grace:
|
|
type: integer
|
|
in: body
|
|
required: false
|
|
description: |
|
|
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.
|
|
|
|
claim_ttl:
|
|
type: integer
|
|
in: body
|
|
required: false
|
|
description: |
|
|
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.
|
|
|
|
count:
|
|
type: integer
|
|
in: body
|
|
required: false
|
|
description: |
|
|
The ``count`` attribute specifies how many queus in current project.
|
|
|
|
flavor_href:
|
|
type: string
|
|
in: body
|
|
description: |
|
|
The url of the flavor.
|
|
|
|
flavor_links:
|
|
type: array
|
|
in: body
|
|
required: true
|
|
description: |
|
|
Links related to the flavors. This is a list of dictionaries, each including
|
|
keys ``href`` and ``rel``.
|
|
|
|
flavor_name:
|
|
type: string
|
|
in: body
|
|
required: true
|
|
description: |
|
|
The name of the flavor.
|
|
|
|
flavor_pool_group:
|
|
type: string
|
|
in: body
|
|
required: true
|
|
description: |
|
|
The ``pool_group`` attribute specifies the name of the pool group
|
|
this flavor sits on top of.
|
|
NOTE: Remove pool_group in Rocky release and use pool_list instead
|
|
for flavor.
|
|
|
|
flavor_pool_list:
|
|
type: list
|
|
in: body
|
|
description: |
|
|
A list of pools in the flavor.
|
|
NOTE: Suggest config pool_list in stead of pool_group from the
|
|
beginning of Queens.
|
|
|
|
flavors:
|
|
type: list
|
|
in: body
|
|
description: |
|
|
A list of the flaovrs.
|
|
|
|
links:
|
|
type: array
|
|
in: body
|
|
required: true
|
|
description: |
|
|
Links related to the queues. This is a list of dictionaries, each including
|
|
keys ``href`` and ``rel``.
|
|
|
|
messages:
|
|
type: list
|
|
in: body
|
|
required: True
|
|
description: |
|
|
A list of the messages.
|
|
|
|
messages_resources:
|
|
type: list
|
|
in: body
|
|
description: |
|
|
A list of the URL to messages.
|
|
|
|
operation_status:
|
|
type: dict
|
|
in: body
|
|
required: False
|
|
description: |
|
|
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.
|
|
|
|
pool_flavor:
|
|
type: string
|
|
in: body
|
|
required: false
|
|
description: |
|
|
The ``flavor`` attribute specifies a tag to given to more than one pool
|
|
so that it keeps user remind the purpose/capabilities of all pools that
|
|
falls under that flavor.
|
|
NOTE: Suggest config flavor in stead of group from the beginning of queen.
|
|
|
|
pool_group:
|
|
type: string
|
|
in: body
|
|
required: false
|
|
description: |
|
|
The ``group`` attribute specifies a tag to given to more than one pool
|
|
so that it keeps user remind the purpose/capabilities of all pools that
|
|
falls under that group.
|
|
NOTE: Remove group in Rocky release and use flavor instead for pool.
|
|
|
|
pool_href:
|
|
type: string
|
|
in: body
|
|
description: |
|
|
The url of the pool.
|
|
|
|
pool_links:
|
|
type: array
|
|
in: body
|
|
required: true
|
|
description: |
|
|
Links related to the pools. This is a list of dictionaries, each including
|
|
keys ``href`` and ``rel``.
|
|
|
|
pool_name:
|
|
type: string
|
|
in: body
|
|
description: |
|
|
The name of the pool.
|
|
|
|
pool_options:
|
|
type: dict
|
|
in: body
|
|
required: false
|
|
description: |
|
|
The ``options`` attribute gives storage-specific options used by storage
|
|
driver implementations. The value must be a dict and valid key-value come
|
|
from the registered options for a given storage backend.
|
|
|
|
pool_uri:
|
|
type: string
|
|
in: body
|
|
required: true
|
|
description: |
|
|
The ``uri`` attribute specifies a connection string compatible with a
|
|
storage client (e.g., pymongo) attempting to connect to that pool.
|
|
|
|
pool_weight:
|
|
type: integer
|
|
in: body
|
|
required: true
|
|
description: |
|
|
The ``weight`` attribute specifies the likelihood that this pool will be
|
|
selected for the next queue allocation. The value must be an integer
|
|
greater than -1.
|
|
|
|
pools:
|
|
type: list
|
|
in: body
|
|
description: |
|
|
A list of the pools.
|
|
|
|
pre_signed_queue_expires:
|
|
type: string
|
|
in: body
|
|
required: False
|
|
description: |
|
|
The time to indicate when the pre-signed will be expired.
|
|
|
|
pre_signed_queue_methods:
|
|
type: list
|
|
in: body
|
|
required: False
|
|
description: |
|
|
A list of HTTP methods. The HTTP method(s) this URL was created for. By
|
|
selecting the HTTP method, it's possible to give either read or read/write
|
|
access to a specific resource.
|
|
|
|
pre_signed_queue_paths:
|
|
type: list
|
|
in: body
|
|
required: False
|
|
description: |
|
|
A list of paths the pre-signed queue can support. It could be a set of
|
|
``messages``, ``subscriptions``, ``claims``.
|
|
|
|
pre_signed_queue_signature:
|
|
type: list
|
|
in: body
|
|
required: True
|
|
description: |
|
|
The signature is generated after create the pre-signed URL. It can be
|
|
consumed by adding below to HTTP headers:
|
|
|
|
URL-Signature: 6a63d63242ebd18c3518871dda6fdcb6273db2672c599bf985469241e9a1c799
|
|
URL-Expires: 2015-05-31T19:00:17Z
|
|
|
|
project_id:
|
|
type: string
|
|
in: body
|
|
required: True
|
|
description: |
|
|
The ID of current project/tenant.
|
|
|
|
queue_metadata:
|
|
type: dict
|
|
in: body
|
|
description: |
|
|
Metadata of queue.
|
|
|
|
queues:
|
|
type: list
|
|
in: body
|
|
required: true
|
|
description: |
|
|
A list of the queues.
|
|
|
|
resource_types:
|
|
type: list
|
|
in: body
|
|
required: false
|
|
description: |
|
|
The ``resource_types`` attribute allows user to purge particular resource
|
|
of the queue.
|
|
|
|
storage_reachable:
|
|
type: boolean
|
|
in: body
|
|
required: False
|
|
description: |
|
|
A boolean value to indicate if the messages(pool) datatabse is
|
|
reachable or not.
|
|
|
|
subscriber:
|
|
type: string
|
|
in: body
|
|
required: True
|
|
description: |
|
|
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``.
|
|
|
|
subscription_age:
|
|
type: integer
|
|
in: body
|
|
description: |
|
|
How long the subscription has be existed.
|
|
|
|
subscription_id:
|
|
type: string
|
|
in: body
|
|
description: |
|
|
The id of the subscription.
|
|
|
|
subscription_options:
|
|
type: dict
|
|
in: body
|
|
required: false
|
|
description: |
|
|
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.
|
|
|
|
subscription_source:
|
|
type: string
|
|
in: body
|
|
description: |
|
|
The queue name which the subscription is registered on.
|
|
|
|
subscription_ttl:
|
|
type: integer
|
|
in: body
|
|
required: false
|
|
description: |
|
|
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.
|
|
|
|
subscriptions:
|
|
type: list
|
|
in: body
|
|
description: |
|
|
A list of the subscriptions.
|
|
|
|
versions:
|
|
type: list
|
|
in: body
|
|
required: True
|
|
description: |
|
|
A list of supported major API versions.
|