#### variables in header #####################################################

client_id:
  type: UUID
  in: header
  description: |
    A unique ID for indicating where the request come from.

#### variables in path #######################################################

queue_name:
  type: string
  in: path
  required: True
  description: |
    The name of the queue.

claim_id:
  type: string
  in: path
  required: True
  description: |
    The id of the claim.

subscription_id_path:
  type: string
  in: path
  required: True
  description: |
    The id of the subscription.

#### variables in query ######################################################

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.

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.

#### variables in request ####################################################

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.

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 grace period, its expiration is not adjusted.

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

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.

#### variables in response ###################################################

versions:
  type: list
  in: body
  required: True
  description: |
    A list of supported major API versions.

queues:
  type: list
  in: body
  description: |
    A list of the queues.

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

queue_metadata:
  type: dict
  in: body
  description: |
    Metadata of queue.

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

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

subscriptions:
  type: list
  in: body
  description: |
    A list of the subscriptions.

subscription_id:
  type: string
  in: body
  description: |
    The id of the subscription.

subscription_age:
  type: integer
  in: body
  description: |
    How long the subscription has be existed.

subscription_source:
  type: string
  in: body
  description: |
    The queue name which the subscription is registered on.