499 lines
13 KiB
YAML
499 lines
13 KiB
YAML
#### variables in header #####################################################
|
||
|
||
client_id:
|
||
type: UUID
|
||
in: header
|
||
description: |
|
||
A UUID for each client instance. The UUID must be submitted in its
|
||
canonical form (for example, 3381af92-2b9e-11e3-b191-71861300734c). 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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
#### variables in request ####################################################
|
||
|
||
_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.
|
||
|
||
_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_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.
|
||
|
||
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.
|
||
|
||
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_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.
|
||
|
||
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: True
|
||
description: |
|
||
The time to indicate when the pre-signed will be expired.
|
||
|
||
pre_signed_queue_methods:
|
||
type: list
|
||
in: body
|
||
required: True
|
||
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: True
|
||
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
|
||
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.
|