# 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.

_enable_encrypt_messages:
  type: boolean
  in: body
  required: False
  description: |
    The switch of encrypting messages for a queue, which will effect for
    any messages posted to the queue. By default, the value is False. It is
    one of the ``reserved attributes`` of Zaqar queues.

_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.

confirmed:
  type: boolean
  in: body
  required: true
  description: |
    The ``confirmed`` attribute specifies whether to confirm a subscription.

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.