Skip to main content
API docs by Redocly

My Project (1.0.0)

Download OpenAPI specification:Download

Querator V1

Produce an item on a queue

Produce an item on a queue. Calls to the endpoint may provide multiple items to produce. The call will not return until all items provided have been written to storage.

Timeout Semantics

The call will return when the item(s) provided are written to storage or when request_timeout has been reached. If the call returns with a non 200 response code, the client should consider the items provided as not written to the queue. The client should NOT cancel the request before request_timeout has been reached. If the call fails to return after request_timeout is reached the client can safely cancel the request.

Request Body schema: application/json
queue_name
required
string

The name of the queue

request_timeout
required
string
Default: "5m"

The duration this request should block before the client will cancel the request

required
Array of objects (QueueProduceItem) [ 1 .. 1000 ] items

List of items to be queued

Responses

Request samples

Content type
application/json
{
  • "queue_name": "queue-name",
  • "request_timeout": "30s",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 200
}

Reserve messages from the queue

Reserve a message from the requested queue. When a message is reserved by a consumer, that consumer gains exclusive rights to the message. No other consumer will be provided the same message unless the reserve_deadline has expired and the consumer with the reservation has not marked the message via /queue.complete or /queue.defer

If a message is not acknowledge via /queue.complete within the reserve_deadline period it will be offered to another consumer.

Timeout Semantics

The call will return when a reservation is successful or when request_timeout has been reached. If the call returns with a 454 Retry Request response code, this means there were no items in the queue and the request_timeout was reached. In this case the client should retry the reserve request.

The client should NOT cancel the request before request_timeout has been reached. If the call fails to return after request_timeout is reached the client can safely cancel the request.

Request Body schema: application/json
queue_name
required
string

The name of the queue

client_id
required
string

A unique id which identifies this client. Duplicate client id's are not allowed

request_timeout
required
string
Default: "1m"

The duration this request should block before the client will cancel the request.

batch_size
integer [ 1 .. 1000 ]

The maxium number of items to be reserved for this request

Responses

Request samples

Content type
application/json
{
  • "queue_name": "queue-name",
  • "batch_size": 1000,
  • "client_id": "client-01",
  • "request_timeout": "30s"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "queue_name": "webhooks",
  • "partition": 0
}

Defer a message to be retried

Defer an item to be processed again at a later date/time. Once the enqueue_at time is reached, querator will enqueue this item into the specified queue and the attempted counter for this item will increment by 1.

If the item should not be retried, but failed immediately. Set dead: true and the item will be placed in the dead letter queue regardless of the number of attempts left on the message.

If you wish to fail a message such that it is deleted from the queue and never offered to another consumer, nor placed into the dead letter queue, then call /queue.complete instead.

Request Body schema: application/json
queue_name
required
string

The queue name provided when the item was reserved. If the queue_name does not match the original queue_name provided when the item was reserved, then the defer request will return a non 200 status code.

partition
required
integer

The partition provided when the item was reserved. If the partition does not match the original partition provided when the item was reserved, then the defer request will return a non 200 status code.

required
Array of objects (QueueDeferItem)

Responses

Request samples

Content type
application/json
{
  • "queue_name": "queue-name",
  • "partition": 0,
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 200
}

Complete reserved items

Mark reserved items as completed. The item can then be removed from the queue by Querator and will not be offered to any other consumers.

If any of the ids provided cannot be marked as completed then the entire request will be rejected with a code 453 Request Failed. It is the responsibility of the client to remove the offending id and try again.

Timeout Semantics

The call will return when the id(s) provided are completed to storage or when request_timeout has been reached. If the call returns with a non 200 response code, the client should consider the items provided as not completed to the queue. The client should NOT cancel the request before request_timeout has been reached. If the call fails to return after request_timeout is reached the client can safely cancel the request.

Request Body schema: application/json
queue_name
required
string

The name of the queue these ids are from

partition
required
integer

The Partition these ids are from

request_timeout
required
string

The duration this request should block before the client will cancel the request

ids
required
Array of strings

A list of the item ids to mark as complete

Responses

Request samples

Content type
application/json
{
  • "queue_name": "queue-name",
  • "partition": 0,
  • "request_timeout": "30s",
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 200
}

List all available queues

List all the available queues

Request Body schema: application/json
pivot
required
string

The name of the queue to pivot upon when paging through lists of queues

limit
required
integer <= 1000

The maximum number of items to return in a single list response

Responses

Request samples

Content type
application/json
{
  • "pivot": "queue-302",
  • "limit": 500
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a queue

Create a new queue with the provided characteristics

Request Body schema: application/json
name
required
string

The name of the queue

created_at
required
string <date-time>

The timestamp the queue was created

updated_at
required
string <date-time>

The timestamp the queue was last updated

dead_queue
required
string

The name of the dead letter queue for this queue. If this is a dead letter queue then this field will be empty when retrieved via /queue.list

reference
required
string

This is a user supplied field which could contain metadata or specify who owns this queue

reserve_timeout
required
string

The default reservation timeout for this queue

dead_timeout
required
string

How long an item can wait in the queue regardless of attempts before it is moved to the dead letter queue

max_attempts
required
integer

The maximum number of times an item can be defered by a consumer before it is placed in the dead letter queue. This includes cases where the 'deadline' was exceeded and the item was retried.

requested_partitions
required
integer

The number of partitions this queue hasrequested. This might be different than the number of currently active partitionsas the system grows or contracts the number of partitions.

Responses

Request samples

Content type
application/json
{
  • "name": "queue-name",
  • "dead_queue": "queue-name-dead",
  • "reference": "jake@statefarm.com",
  • "reserve_timeout": "60m",
  • "dead_timeout": "24h",
  • "max_attempts": 10,
  • "requested_partitions": 25
}

Response samples

Content type
application/json
"{\n \"code\": 200,\n\n}"

Update a queue

Update the details of a queue.

Request Body schema: application/json
name
required
string

The name of the queue

created_at
required
string <date-time>

The timestamp the queue was created

updated_at
required
string <date-time>

The timestamp the queue was last updated

dead_queue
required
string

The name of the dead letter queue for this queue. If this is a dead letter queue then this field will be empty when retrieved via /queue.list

reference
required
string

This is a user supplied field which could contain metadata or specify who owns this queue

reserve_timeout
required
string

The default reservation timeout for this queue

dead_timeout
required
string

How long an item can wait in the queue regardless of attempts before it is moved to the dead letter queue

max_attempts
required
integer

The maximum number of times an item can be defered by a consumer before it is placed in the dead letter queue. This includes cases where the 'deadline' was exceeded and the item was retried.

requested_partitions
required
integer

The number of partitions this queue hasrequested. This might be different than the number of currently active partitionsas the system grows or contracts the number of partitions.

Responses

Request samples

Content type
application/json
{
  • "name": "queue-name",
  • "dead_queue": "queue-name-dead",
  • "reference": "account-12345",
  • "reserve_timeout": "60m",
  • "dead_timeout": "24h",
  • "max_attempts": 35
}

Response samples

Content type
application/json
{
  • "code": 200
}

Get Info about a queue

Request Body schema: application/json
name
required
string

The name of the queue to retrieve info about

Responses

Request samples

Content type
application/json
{
  • "name": "queue-name"
}

Response samples

Content type
application/json
{
  • "name": "queue-name",
  • "created_at": "2024-01-01 12:00:00.0000",
  • "updated_at": "2024-01-01 12:00:00.0000",
  • "dead_queue": "queue-name-dead",
  • "reference": "jake@statefarm.com",
  • "reserve_timeout": "60m",
  • "dead_timeout": "24h",
  • "max_attempts": 50,
  • "requested_partitions": 456
}

Fetch stats for a queue

Retrieve statistics about a queue. Queue stats provide information on the health of a partition in a queue

Request Body schema: application/json
queue_name
required
string

Responses

Request samples

Content type
application/json
{
  • "queue_name": "queue-name"
}

Response samples

Content type
application/json
{
  • "queue_name": "queue-name",
  • "logical_queues": [
    ]
}

Clear a queue

Clears all data from a queue, optionally clears all defer and scheduled items

Request Body schema: application/json
queue_name
required
string

The name of the queue to clear

defer
required
boolean

Indicates the 'defer' queue will be cleared. If true, any items scheduled to be retried at a future date will be removed.

scheduled
required
boolean

Indicates any 'scheduled' items in the queue will be cleared. If true, any items scheduled to be enqueued at a future date will be removed.

queue
required
boolean

Indicates any items currently waiting in the FIFO queue will clear. If true, any items in the queue which have NOT been reserved will be removed.

destructive
required
boolean

Indicates the Defer,Scheduled,Queue operations should be destructive in that all data regardless of status will be removed.

For example, if used with ClearRequest.Queue = true, then ALL items in the queue regardless of reserve status will be removed. This means that clients who currently have ownership of those items will not be able to "complete" those items, as querator will have no knowledge of those items.

Responses

Request samples

Content type
application/json
{
  • "queue_name": "queue-name",
  • "defer": false,
  • "scheduled": false,
  • "queue": true,
  • "destructive": true
}

Response samples

Content type
application/json
{
  • "code": 200
}

List Items in a Partition

List items in a queue partition

Request Body schema: application/json
queue_name
required
string
partition
required
integer
pivot
required
string
limit
required
integer

Responses

Request samples

Content type
application/json
{
  • "queue_name": "string",
  • "partition": 0,
  • "pivot": "string",
  • "limit": 0
}

Response samples

Content type
application/json
[
  • {
    }
]

Import Items to a Partition

Import items into a partition

Request Body schema: application/json
queue_name
required
string
partition
required
integer
required
Array of objects (StorageItem)

Responses

Request samples

Content type
application/json
{
  • "queue_name": "string",
  • "partition": 0,
  • "items": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Delete items from a partition

Request Body schema: application/json
queue_name
required
string
ids
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "queue_name": "string",
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 200
}