Messaging Service API v2 (CURRENT)

Messaging Service API v2 (CURRENT)

API Versions

The Zaqar API only supports ‘’major versions’’ expressed in request URLs.

GET
/

List major versions

Gets the home document.

This operation gets the home document.

The entire API is discoverable from a single starting point, the home document. To explore the entire API, you need to know only this one URI. This document is cacheable.

The home document lets you write clients by using relational links, so clients do not have to construct their own URLs. You can click through and view the JSON doc in your browser.

For more information about home documents, see http://tools.ietf.org/html/draft-nottingham-json-home-02.

Normal response codes: 300 Error response codes: serviceUnavailable (503)

Response Parameters

Name In Type Description
versions body list A list of supported major API versions.

Response Example

{
   "versions":[
      {
         "status":"DEPRECATED",
         "updated":"2014-9-11T17:47:05Z",
         "media-types":[
            {
               "base":"application/json",
               "type":"application/vnd.openstack.messaging-v1+json"
            }
         ],
         "id":"1",
         "links":[
            {
               "href":"/v1/",
               "rel":"self"
            }
         ]
      },
      {
         "status":"SUPPORTED",
         "updated":"2014-9-24T04:06:47Z",
         "media-types":[
            {
               "base":"application/json",
               "type":"application/vnd.openstack.messaging-v1_1+json"
            }
         ],
         "id":"1.1",
         "links":[
            {
               "href":"/v1.1/",
               "rel":"self"
            }
         ]
      },
      {
         "status":"CURRENT",
         "updated":"2014-9-24T04:06:47Z",
         "media-types":[
            {
               "base":"application/json",
               "type":"application/vnd.openstack.messaging-v2+json"
            }
         ],
         "id":"2",
         "links":[
            {
               "href":"/v2/",
               "rel":"self"
            }
         ]
      }
   ]
}

Queues (queues)

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.

Normal response codes: 200

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
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.
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.

Response Parameters

Name In Type Description
queues (Optional) body list A list of the queues.
links body array Links related to the queues. This is a list of dictionaries, each including keys href and rel.

Response Example

{
   "queues":[
      {
         "href":"/v2/queues/beijing",
         "name":"beijing"
      },
      {
         "href":"/v2/queues/london",
         "name":"london"
      },
      {
         "href":"/v2/queues/wellington",
         "name":"wellington"
      }
   ],
   "links":[
      {
         "href":"/v2/queues?marker=wellington",
         "rel":"next"
      }
   ]
}
PUT
/v2/queues/{queue_name}

Create queue

Creates a queue.

This operation creates a new queue.

The body of the request is empty.

queue_name is the name that you give to the queue. The name must not exceed 64 bytes in length, and it is limited to US-ASCII letters, digits, underscores, and hyphens.

Normal response codes: 201, 204

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.

Request Example

{
    "_max_messages_post_size": 262144,
    "_default_message_ttl": 3600,
    "description": "Queue for international traffic billing."
}

This operation does not return a response body.

PATCH
/v2/queues/{queue_name}

Update queue

Updates a queue.

Normal response codes: 200

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • Not Found (404)
  • Conflict (409)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.

When setting the request body of updating queue, the body must be a list which contains a series of json object which follows https://tools.ietf.org/html/draft-ietf-appsawg-json-patch-10.

Note

  • The “Content-Type” header should be “application/openstack-messaging-v2.0-json-patch”
  • The ‘’path’’ must start with /metadata, for example, if the key is ‘’ttl’‘, then the path should be /metadata/ttl

Request Example

[
    {
        "op": "replace",
        "path": "/metadata/max_timeout",
        "value": 100
    }
]

Response Example

{
    "max_timeout": 100
}
GET
/v2/queues/{queue_name}

Show queue details

Shows details for a queue.

Normal response codes: 200

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.

Response Parameters

Name In Type Description
_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 reserved attributes of Zaqar queues. The value will be reverted to the default value after deleting it explicitly.
_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 reserved attributes of Zaqar queues. The value will be reverted to the default value after deleting it explicitly.

Response Example

{
    "_max_messages_post_size": 262144,
    "_default_message_ttl": 3600,
    "description": "Queue used for billing."
}
DELETE
/v2/queues/{queue_name}

Delete queue

Deletes the specified queue.

This operation immediately deletes a queue and all of its existing messages.

queue_name is the name that you give to the queue. The name must not exceed 64 bytes in length, and it is limited to US-ASCII letters, digits, underscores, and hyphens.

Normal response codes: 204

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.

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

GET
/v2/queues/{queue_name}/stats

Get queue stats

Returns statistics for the specified queue.

This operation returns queue statistics, including how many messages are in the queue, categorized by status.

If the value of the total attribute is 0, then oldest and newest message statistics are not included in the response.

Normal response codes: 200

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.

Response Example

{
    "messages":{
         "claimed": 10,
         "total": 20,
         "free": 10
    }
}
POST
/v2/queues/{queue_name}/share

Pre-signed queue

Create a pre-signed URL for a given queue.

Note

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.

Normal response codes: 200

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • Not Found (404)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.
paths body list A list of paths the pre-signed queue can support. It could be a set of messages, subscriptions, claims.
methods body list 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.
expires body string The time to indicate when the pre-signed will be expired.

Request Example

{
  "paths": ["messages", "claims", "subscriptions"],
  "methods": ["GET", "POST", "PUT", "PATCH"],
  "expires": "2016-09-01T00:00:00"
}

Response Parameters

Name In Type Description
project body string The ID of current project/tenant.
paths body list A list of paths the pre-signed queue can support. It could be a set of messages, subscriptions, claims.
methods body list 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.
expires body string The time to indicate when the pre-signed will be expired.
signature body list

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

Response Example

{
    "project": "2887aabf368046a3bb0070f1c0413470",
    "paths": [
        "/v2/queues/test/messages",
        "/v2/queues/test/claims"
        "/v2/queues/test/subscriptions"
    ],
    "expires": "2016-09-01T00:00:00",
    "methods": [
        "GET",
        "PATCH",
        "POST",
        "PUT"
    ],
    "signature": "6a63d63242ebd18c3518871dda6fdcb6273db2672c599bf985469241e9a1c799"
}
POST
/v2/queues/{queue_name}/purge

Purge queue

Purge particular resource of the queue.

Note

Now Zaqar supports to purge “messages” and “subscriptions” resource from a queue.

Normal response codes: 204

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.
resource_types (Optional) body list The resource_types attribute allows user to purge particular resource of the queue.

Request Example

{
    "resource_types": ["messages", "subscriptions"]
}

Messages (messages)

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 503 Service Unavailable 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.

Normal response codes: 201

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • Not Found (404)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.

Request Example

{
  "messages": [
    {
      "ttl": 300,
      "body": {
        "event": "BackupStarted",
        "backup_id": "c378813c-3f0b-11e2-ad92-7823d2b0f3ce"
      }
    },
    {
      "body": {
        "event": "BackupProgress",
        "current_bytes": "0",
        "total_bytes": "99614720"
      }
    }
  ]
}

Response Parameters

Name In Type Description
resources (Optional) body list A list of the URL to messages.

Response Example

{
  "resources": [
    "/v2/queues/demoqueue/messages/51db6f78c508f17ddc924357",
    "/v2/queues/demoqueue/messages/51db6f78c508f17ddc924358"
  ]
}
GET
/v2/queues/{queue_name}/messages

List Messages

List the messages in the specified queue.

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.

Results are ordered by age, oldest message first.

Normal response codes: 200

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • Not Found (404)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.
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.
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.
include_claimed (Optional) query boolean Indicate if the messages list should include the claimed messages.

Response Parameters

Name In Type Description
messages body list A list of the messages.
links body array Links related to the queues. This is a list of dictionaries, each including keys href and rel.

Response Example

{
    "messages": [
        {
            "body": {
                "current_bytes": "0",
                "event": "BackupProgress",
                "total_bytes": "99614720"
            },
            "age": 482,
            "href": "/v2/queues/beijing/messages/578edfe6508f153f256f717b",
            "id": "578edfe6508f153f256f717b",
            "ttl": 3600
        },
        {
            "body": {
                "current_bytes": "0",
                "event": "BackupProgress",
                "total_bytes": "99614720"
            },
            "age": 456,
            "href": "/v2/queues/beijing/messages/578ee000508f153f256f717d",
            "id": "578ee000508f153f256f717d",
            "ttl": 3600
        }
    ],
    "links": [
        {
            "href": "/v2/queues/beijing/messages?marker=17&echo=true",
            "rel": "next"
        }
    ]
}
GET
/v2/queues/{queue_name}/messages?ids={ids}

Get A Set Of Messages By Id

Gets a specified set of messages from the specified queue.

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.

Normal response codes: 200

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • Not Found (404)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.
ids (Optional) query list

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

Response Parameters

Name In Type Description
messages body list A list of the messages.

Response Example

{
    "messages": [
        {
            "body": {
                "current_bytes": "0",
                "event": "BackupProgress",
                "total_bytes": "99614720"
            },
            "age": 443,
            "href": "/v2/queues/beijing/messages/578f0055508f153f256f717f",
            "id": "578f0055508f153f256f717f",
            "ttl": 3600
        }
    ]
}
DELETE
/v2/queues/{queue_name}/messages?ids={ids}

Delete A Set Of Messages By Id

Provides a bulk delete for messages.

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.

Normal response codes: 204

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • Not Found (404)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.
ids (Optional) query list

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.

Normal response codes: 200

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • Not Found (404)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.
message_id path string The ID of the message.

Response Example

{
    "body": {
        "current_bytes": "0",
        "event": "BackupProgress",
        "total_bytes": "99614720"
    },
    "age": 1110,
    "href": "/v2/queues/beijing/messages/578f0055508f153f256f717f",
    "id": "578f0055508f153f256f717f",
    "ttl": 3600
}
DELETE
/v2/queues/{queue_name}/messages/{message_id}

Delete A Specific Message

Deletes the specified message from the specified queue.

This operation immediately deletes the specified message.

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.

Normal response codes: 204

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • Not Found (404)
  • ServiceUnavailable (503)

Request

Name In Type Description
queue_name path string The name of the queue.
message_id path string The ID of the message.

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

Claims (claims)

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 204 No Content 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.

Normal response codes: 201

Error response codes:

  • Unauthorized(401)
  • Forbidden(403)
  • itemNotFound(404)
  • ServiceUnavailable(503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.
limit (Optional) query integer 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.

Example Claim Messages: JSON request

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

Response Parameters

Example Claim Messages: JSON response

{
    "messages": [
        {
            "body": {
                "event": "BackupStarted"
            },
            "age": 239,
            "href": "/v2/queues/demoqueue/messages/51db6f78c508f17ddc924357?claim_id=51db7067821e727dc24df754",
            "ttl": 300
        }
    ]
}
GET
/v2/queues/{queue_name}/claims/{claim_id}

Query Claim

Queries the specified claim for the specified queue.

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

Normal response codes: 200

Error response codes:

  • Unauthorized(401)
  • Forbidden(403)
  • itemNotFound(404)
  • ServiceUnavailable(503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.
claim_id path string The id of the claim.

Response Parameters

Example Query Claim: JSON response

{
  "age": 57,
  "href": "/v2/queues/demoqueue/claims/51db7067821e727dc24df754",
  "messages": [
    {
      "body": {
        "event": "BackupStarted"
      },
      "age": 296,
      "href": "/v2/queues/demoqueue/messages/51db6f78c508f17ddc924357?claim_id=51db7067821e727dc24df754",
      "ttl": 300
    }
  ],
  "ttl": 300
}
PATCH
/v2/queues/{queue_name}/claims/{claim_id}

Update(Renew) Claim

Updates the specified claim for the specified queue.

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.

Normal response codes: 204

Error response codes:

  • Unauthorized(401)
  • Forbidden(403)
  • itemNotFound(404)
  • ServiceUnavailable(503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.
claim_id path string The id of the claim.
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.

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.

Normal response codes: 204

Error response codes:

  • Unauthorized(401)
  • Forbidden(403)
  • itemNotFound(404)
  • ServiceUnavailable(503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.
claim_id path string The id of the claim.

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

Subscriptions(subscriptions)

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.

Normal response codes: 200

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.

Query Parameters

Name In Type Description
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.
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.

Response Parameters

Name In Type Description
subscriptions (Optional) body list A list of the subscriptions.
links body array Links related to the queues. This is a list of dictionaries, each including keys href and rel.

Response Example

{
  "links": [
    {
      "href": "/v2/queues/test/subscriptions?marker=57692ab13990b48c644bb7e6",
      "rel": "next"
    }
  ],
  "subscriptions": [
    {
      "age": 13,
      "id": "57692aa63990b48c644bb7e5",
      "subscriber": "http://10.229.49.117:5678",
      "source": "test",
      "ttl": 360,
      "options": {}
    },
    {
      "age": 2,
      "id": "57692ab13990b48c644bb7e6",
      "subscriber": "http://10.229.49.117:5679",
      "source": "test",
      "ttl": 360,
      "options": {}
    }
  ]
}
POST
/v2/queues/{queue_name}/subscriptions

Create Subscription

Creates a subscription.

This operation creates a new subscription.

Normal response codes: 201

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.
subscriber body string 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.

Request Example

{
    "subscriber":"http://10.229.49.117:5679",
    "ttl":3600,
    "options":{}
}
{
    "subscriber":"mailto://test@gmail.com",
    "ttl":3600,
    "options":{
      "from": "Jack",
      "subject": "Hello"
    }
}

Response Parameters

Name In Type Description
subscription_id (Optional) body string The id of the subscription.

Response Example

{
  "subscription_id": "57692ab13990b48c644bb7e6"
}
PATCH
/v2/queues/{queue_name}/subscriptions/{subscription_id}

Update Subscription

Updates a subscription.

Normal response codes: 204

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • Not Found (404)
  • Conflict (409)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.
subscription_id path string The id of the subscription.
subscriber body string 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.

Request Example

{
    "subscriber":"http://10.229.49.117:1234",
    "ttl":360,
    "options":{
      "name": "test"
    }
}

This operation does not return a response body.

GET
/v2/queues/{queue_name}/subscriptions/{subscription_id}

Show Subscription Details

Shows details for a subscription.

Normal response codes: 200

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.
subscription_id path string The id of the subscription.

Response Parameters

Name In Type Description
age (Optional) body integer How long the subscription has be existed.
id (Optional) body string The id of the subscription.
subscriber body string 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.

Response Example

{
  "age": 1632,
  "id": "576b54963990b48c644bb7e7",
  "subscriber": "http://10.229.49.117:5679",
  "source": "test",
  "ttl": 3600,
  "options": {
    "name": "test"
  }
}
DELETE
/v2/queues/{queue_name}/subscriptions/{subscription_id}

Delete Subscription

Deletes the specified subscription.

Normal response codes: 204

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
queue_name path string The name of the queue.
subscription_id path string The id of the subscription.

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

Health (health)

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 admin only 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.

Normal response codes: 200

Error response codes:

  • Unauthorized (401)
  • Forbidden (403)
  • ServiceUnavailable (503)

Response Parameters

Name In Type Description
catalog_reachable body boolean 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.

Response Example

{
    "catalog_reachable": true,
    "redis": {
        "storage_reachable": true,
        "operation_status": {
            "post_messages": {
                "seconds": 0.027673959732055664,
                "ref": null,
                "succeeded": true
            },
            "delete_messages": {
                "seconds": 0.0028481483459472656,
                "ref": null,
                "succeeded": true
            },
            "delete_queue": {
                "seconds": 0.017709016799926758,
                "ref": null,
                "succeeded": true
            },
            "bulk_delete_messages": {
                "seconds": 0.03959178924560547,
                "ref": null,
                "succeeded": true
            },
            "create_queue": {
                "seconds": 0.021075963973999023,
                "ref": null,
                "succeeded": true
            },
            "list_messages": {
                "seconds": 0.00003504753112792969,
                "ref": null,
                "succeeded": true
            },
            "delete_claim": {
                "seconds": 0.0006170272827148438,
                "ref": null,
                "succeeded": true
            },
            "claim_messages": {
                "seconds": 0.008388042449951172,
                "ref": null,
                "succeeded": true
            }
        }
    }
}

Pools (pools)

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.

Normal response codes: 200

Error response codes:

  • Not Found (404)
  • Unauthorized (401)

Query Parameters

Name In Type Description
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.
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.

Response Parameters

Name In Type Description
pools (Optional) body list A list of the pools.
links body array Links related to the pools. This is a list of dictionaries, each including keys href and rel.

Response Example

{
  "pools": [
    {
      "href": "/v2/pools/test_pool1",
      "group": "poolgroup",
      "name": "test_pool1",
      "weight": 60,
      "uri": "mongodb://192.168.1.10:27017"
    },
    {
      "href": "/v2/pools/test_pool2",
      "group": "poolgroup",
      "name": "test_pool2",
      "weight": 40,
      "uri": "mongodb://192.168.1.20:27017"
    }
  ],
  "links": [
    {
      "href": "/v2/pools?marker=test_pool2",
      "rel": "next"
    }
  ]
}
PUT
/v2/pools/{pool_name}

Create pool

Creates a pool.

This operation creates a new pool.

pool_name is the name that you give to the pool. The name must not exceed 64 bytes in length, and it is limited to US-ASCII letters, digits, underscores, and hyphens.

Normal response codes: 201

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • Conflict (409)

Request Parameters

Name In Type Description
pool_name path string The name of the pool.
weight body integer 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.
uri body string The uri attribute specifies a connection string compatible with a storage client (e.g., pymongo) attempting to connect to that pool.
group (Optional) body string 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.
options (Optional) body dict 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.

Request Example

{
    "weight": 100,
    "uri": "mongodb://127.0.0.1:27017",
    "options":{
        "max_retry_sleep": 1
    },
    "group": "poolgroup"
}

This operation does not return a response body.

PATCH
/v2/pools/{pool_name}

Update pool

Updates a pool.

Normal response codes: 200

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • Not Found (404)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
pool_name path string The name of the pool.
weight body integer 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.
uri body string The uri attribute specifies a connection string compatible with a storage client (e.g., pymongo) attempting to connect to that pool.
group (Optional) body string 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.
options (Optional) body dict 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.

Request Example

{
    "weight": 60,
    "uri": "mongodb://127.0.0.1:27017",
    "options":{
        "max_retry_sleep": 1
    },
    "group": "newpoolgroup"
}

Response Example

{
  "href": "/v2/pools/test_pool",
  "group": "newpoolgroup",
  "name": "test_pool",
  "weight": 60,
  "uri": "mongodb://127.0.0.1:27017"
}
GET
/v2/pools/{pool_name}

Show pool details

Shows details for a pool.

Normal response codes: 200

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
pool_name path string The name of the pool.

Response Parameters

Name In Type Description
name (Optional) body string The name of the pool.
weight body integer 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.
uri body string The uri attribute specifies a connection string compatible with a storage client (e.g., pymongo) attempting to connect to that pool.
group (Optional) body string 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.
href (Optional) body string The url of the pool.

Response Example

{
  "href": "/v2/pools/test_pool",
  "group": "testpoolgroup",
  "name": "test_pool",
  "weight": 100,
  "uri": "mongodb://127.0.0.1:27017"
}
DELETE
/v2/pools/{pool_name}

Delete pool

Deletes the specified pool.

This operation immediately deletes a pool.

pool_name is the name that you give to the pool. The name must not exceed 64 bytes in length, and it is limited to US-ASCII letters, digits, underscores, and hyphens.

Normal response codes: 204

Error response codes:

  • Unauthorized (401)
  • Forbidden (403)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
pool_name path string The name of the pool.

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

Flavors (flavors)

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.

Normal response codes: 200

Error response codes:

  • Unauthorized (401)
  • Forbidden (403)

Query Parameters

Name In Type Description
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.
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.

Response Parameters

Name In Type Description
flavors (Optional) body list A list of the flaovrs.
links body array Links related to the flavors. This is a list of dictionaries, each including keys href and rel.

Response Example

{
  "flavors": [
    {
      "href": "/v2/flavors/test_flavor1",
      "pool_group": "testgroup",
      "name": "test_flavor1",
      "pool": "testgroup"
    },
    {
      "href": "/v2/flavors/test_flavor2",
      "pool_group": "testgroup",
      "name": "test_flavor2",
      "pool": "testgroup"
    }
  ],
  "links": [
    {
      "href": "/v2/flavors?marker=test_flavor2",
      "rel": "next"
    }
  ]
}
PUT
/v2/flavors/{flavor_name}

Create flavor

Creates a flavor.

This operation creates a new flavor.

flaovr_name is the name that you give to the flavor. The name must not exceed 64 bytes in length, and it is limited to US-ASCII letters, digits, underscores, and hyphens.

Normal response codes: 201

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • Forbidden (403)

Request Parameters

Name In Type Description
flavor_name path string The name of the flavor.
pool_group body string The pool_group attribute specifies the name of the pool group this flavor sits on top of.

Request Example

{
    "pool_group": "testgroup"
}

This operation does not return a response body.

PATCH
/v2/flavors/{flavor_name}

Update flavor

Updates a flavor.

Normal response codes: 200

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • Forbidden (403)
  • Not Found (404)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
flavor_name path string The name of the flavor.
pool_group body string The pool_group attribute specifies the name of the pool group this flavor sits on top of.

Request Example

{
    "pool_group": "testgroup"
}

Response Example

{
  "href": "/v2/flavors/testflavor",
  "pool_group": "testgroup",
  "name": "testflavor",
  "capabilities": [
    "FIFO",
    "CLAIMS",
    "DURABILITY",
    "AOD",
    "HIGH_THROUGHPUT"
  ]
}
GET
/v2/flavors/{flavor_name}

Show flavor details

Shows details for a flavor.

Normal response codes: 200

Error response codes:

  • BadRequest (400)
  • Unauthorized (401)
  • Forbidden (403)
  • Not Found (404)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
flavor_name path string The name of the flavor.

Response Parameters

Name In Type Description
name body string The name of the flavor.
capabilities (Optional) body list Capabilities describe what this flavor is capable of base on the storage capabilities. They are used to inform the final user such capabilities.
pool_group body string The pool_group attribute specifies the name of the pool group this flavor sits on top of.
href (Optional) body string The url of the flavor.

Response Example

{
  "href": "/v2/flavors/testflavor",
  "capabilities": [
    "FIFO",
    "CLAIMS",
    "DURABILITY",
    "AOD",
    "HIGH_THROUGHPUT"
  ],
  "pool_group": "testgroup",
  "name": "testflavor"
}
DELETE
/v2/flavors/{flavor_name}

Delete flavor

Deletes the specified flavor.

This operation immediately deletes a flavor.

flavor_name is the name that you give to the flavor. The name must not exceed 64 bytes in length, and it is limited to US-ASCII letters, digits, underscores, and hyphens.

Normal response codes: 204

Error response codes:

  • Unauthorized (401)
  • Forbidden (403)
  • ServiceUnavailable (503)

Request Parameters

Name In Type Description
flavor_name path string The name of the flavor.

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

Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.