StarQueue



Are you planning on using StarQueue in a project? Let us know first!


You must first create an account.


Read this in conjunction with the How it works page.



StarQueue API Reference



Available endpoints:


authtokenget
messagechangevisibility
messagedelete
messagereceive
messagesend
queueclear
queueslist


Making requests to the StarQueue API:





Structure of endpoint URLs:



https://api.starqueue.org/authtokenget/{accountid}
https://api.starqueue.org/messagechangevisibility/{accountid}/{queuename}
https://api.starqueue.org/messagedelete/{accountid}/{queuename}
https://api.starqueue.org/messagereceive/{accountid}/{queuename}
https://api.starqueue.org/messagesend/{accountid}/{queuename}
https://api.starqueue.org/queueclear/{accountid}/{queuename}
https://api.starqueue.org/queueslist/{accountid}




AuthTokenGet



Description:
When you create a StarQueue account, you will be given a password and an accountid.

To access the endpoints of StarQueue, you do not submit your password, but instead you submit an auth token.

You get an authtoken by submitting your password to this endpoint.

You include an AuthToken field in the JSON body of most API requests.

JSON request body example:
{
   "Version": 1,
   "AccountPassword": "SuperSecret01"
}

JSON response example:
{
   "AuthToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiBIUzI1NiJ9.eyJhY2NvdW50aWQiOiI4Y2ZiZmJmNi02YzJkLTQxN2UtYjUzNS05YjM3MWY2NzVkZTgiLCJ0aW1lIjoxNjIzODA1OTI3Ljk2ODYzNjV9.zHGGKUgbJUY2ktlij14OAsoklG7SpNwKaCLOLgD4Ssw"
}
    
JSON request body fields:
AccountPassword
Description:
The password for your StarQueue account.
JSON Type: strings
Required: true

JSON response fields:
AuthToken
Description: see above
JSON Type: string





MessageChangeVisibility



Description:
Changes the amount of time that a message remains hidden from MessageReceive.

Note: MessageChangeVisibility returns successful but has no effect in cases where the message
has a MessageDeduplicationId.

Note: a success response is always returned, as long as the params are valid

JSON request body example:
{
   "Version": 1
}

JSON response example:
{
    "MessageChangeVisibilityResult": {}
}
JSON request body fields:
ReceiptHandles
Description:
An array of one or more (maximum 10) receipt handles.
See above for an explanation of ReceiptHandle
JSON Type: array of strings
Required: true

VisibilityTimeout
Description: see above
JSON Type: number
Required: true
Default: 30
Range: 0 - 43200 (12 hours max)





MessageDelete


Description:
To delete a message from the queue you must provide the ReceiptHandle that was returned from MessageReceive.

Note that a success response is always returned, as long as the ReceiptHandle is a valid UUID.

JSON request body example:
{
   "Version": 1
}

JSON response example:
        {"MessageDeleteResult": {}}

JSON request body fields:
ReceiptHandles
Description:
A JSON array of one or more (maximum 10) receipt handles
See above for an explanation of ReceiptHandle.
JSON Type: string
Required: true

MessageReceive


Description:
Receives one or more messages from a queue.

JSON request body example:
{
   "Version": 1
}

JSON response example:
{
   "MessageReceiveResult":[
      {
         "AccountId":"d9e0c791-cb03-44a7-b793-fe8c637e05ca",
         "ApproximateFirstReceiveTimestamp":"2021-06-15T23:46:22.269736+00:00",
         "ApproximateReceiveCount":1,
         "MD5OfMessageBody":"6507848bd3c9b03f21825829ec8a97a8",
         "MessageBody":"aGVsbG8ga2l0dHk=",
         "MessageDeduplicationId":null,
         "MessageId":"16ad9d2c-778c-452d-a085-7e7fc6f51fec",
         "Priority":100,
         "QueueName":"myexamplequeue",
         "ReceiptHandle":"a286c9eb-0656-4228-b00c-e14f0aa0cb17",
         "SentTimestamp":"2021-06-15T23:46:00.906373+00:00"
      }
   ]
}

JSON request body fields:

MaxReceives
Maximum number of times a message can be received.
If a message is present in the queue, and has already been received MaxReceives times or more,
then the message is deleted by the server and no message is returned, unless DeadLetterQueueName
is supplied in the request, in which case the message is moved to the specified DeadLetterQueueName
(see DeadLetterQueueName description below for more detail).

So for example if MaxReceives is 4, then a message may be received up to 4 times in total.
Behind the scenes (invisible to the client), the server deletes any message the 5th time it is received.
i.e. if the value in the ApproximateReceiveCount column in the database is 4 then server deletes the
message instead of returning it to the client, and the server continues to wait for a message.

Default: 4
Range: 1-10
JSON Type: number
Required: false

DeadLetterQueueName
Description:
The DeadLetterQueueName is used by the server when MaxReceives is exceeded (see MaxReceives above).
If the DeadLetterQueueName request param is supplied, then instead of being deleted, the server:
1: changes the queue name of the message to match the DeadLetterQueueName
2: resets the message's ApproximateReceiveCount to 0
3: clears the message's MessageDeduplicationId
The DeadLetterQueueName cannot be the same as the current QueueName.

Default: 4
Valid: see definition above for valid structure of a queuename
JSON Type: string
Required: false


MaxNumberOfMessages
Maximum number of messages to receive. Fewer messages may be received.
As soon as a single message becomes available, the queue server will grab and return as many
messages as are available up to the maximum defined here. So it is possible that fewer messages
may be returned than the specified MaxNumberOfMessages.
Default: 1
Range: 1-10
JSON Type: number
Required: false

VisibilityTimeout
Description: Time in seconds that a message is hidden from MessageReceive requests.
Note that the default value for VisibilityTimeout is different for MessageSend.
VisibilityTimeout -300 is 5 minutes in the past, which means the message is immediately visible.
JSON Type: number
Required: false
Default: 30 (30 seconds, which means the message is hidden from other receivers for 30 seconds)
Valid range: -43200 to 43200 (12 hours in the past to 12 hours in the future)

WaitTimeSeconds
Description:
If a message is not immediately available, the server will wait for up to this number of seconds for a
message to appear in the queue, after which the server returns success with an empty list of messages.
WaitTimeSeconds is ignored if a message is immediately available.
Default: 20
Range: 0-20
JSON Type: number
Required: false

JSON response fields:
accountid
(see description above)

ApproximateFirstReceiveTimestamp
Description: time that the message was first received

ApproximateReceiveCount
Description: number of times a message has been received but not deleted

MD5OfMessageBody
Description: MD5 hash of the MessageBody

MessageBody
Description: see description above

MessageId
Description: see above

MessageDeduplicationId
Description: see above

Priority
Description: see above

QueueName
Description: see above

ReceiptHandle
Description:
A receipt handle is a UUID string returned from the server in response to a successful MessageReceive.
You must use the ReceiptHandle to identify a message when you want to perform a MessageDelete
or MessageChangeVisibility.
Length: 36 characters (bytes)
JSON Type: string

SentTimestamp
Description: time that the message was sent


MessageSend


Description:
Puts a message onto a queue.

JSON request body example:
{
   "Version": 1,
   "MessageBody":"44OP44Ot44O844Kt44OG44KjSGVsbG9LaXR0eQ=="
}

JSON response example:
{
   "MessageSendResult":{
      "MessageId":"42d9c717-d004-4efe-ba92-142e7fef4339",
      "MD5OfMessageBody":"66919d2f1234aab92fce29a0508134dd"
   }
}
JSON request fields:

MessageBody
JSON Type: string
Max length: 256K
Min length: 1 byte
Required: true
Validation: The MessageBody must be base64 encoded.

VisibilityTimeout
Description: Time in seconds that a message is hidden from MessageReceive requests.
Note that the default value for VisibilityTimeout is different in MessageReceive.
JSON Type: number
Required: false
Default: -300 (5 minutes in the past, which means the message is immediately visible)
Valid range: -43200 to 43200 (12 hours in the past to 12 hours in the future)

Priority
Description:
Messages with a higher numeric priority are received before messages with lower numeric priority
a message with a higher priority number will always be returned before a message with a lower
priority number, regardless of which message entered the queue first.
JSON Type: number
Default: 100
Range: 0 to 1000
Required: false

MessageDeduplicationId
Description:
If a message has a MessageDeduplicationId, then any message added to the queue with the same
deduplicationid, within the MessageDeduplicationTimePeriod, is accepted successfully, but is actually dropped.

When a "normal" message is deleted - i.e. a message without a MessageDeduplicationId, it is deleted
from the queue immediately. When a message with a MessageDeduplicationId is deleted, it remains in the
queue, but cannot be accessed, thus later messages sent to the queue with the same MessageDeduplicationId
will continue to be identified as duplicates and not added to the queue.

When the amount of time (in seconds) specified in the MessageDeduplicationTimePeriod has elasped, the
message is deleted from the queue, after which time it is possible to send messages with the same
MessageDeduplicationId.

Important: MessageDeduplicationId is set to NULL when a message is moved to a dead letter queue

Note that if a message is sent with a MessageDeduplicationId, then the VisibilityTimeout is
always 0 or less.

JSON Type: string
Max length: 128 characters(bytes)
Required: false
Valid characters: 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz

MessageDeduplicationTimePeriod
Description:
Time in seconds during which to discard any message sent to the queue with the same MessageDeduplicationId.
Note this time period continues even after the message is deleted.
Note that if a message is sent with a MessageDeduplicationId, then the VisibilityTimeout is always 0.

See description of MessageDeduplicationId for more information.

JSON Type: number
Required: false
Default: if there is a MessageDeduplicationId then the default is 300
Range: 0 - 43200 (12 hours max)

MessageRetentionPeriod
Description:
Approximate time in seconds after which the server will delete the message from queue.
JSON Type: number
Required: false

Default: 14400 (4 hours)
Max: 14400
Min: 14400


JSON response fields:
MessageId
Description: system assigned MessageId
JSON Type: string/UUID

MD5OfMessageBody
Description: an MD5 hash of the MessageBody field
JSON Type: string/UUID


QueueClear


Description:
Unconditionally deletes all messages in queue.

JSON request body example:
{
   "Version": 1
}

JSON response example:
{
   "QueueClearResult":{}
}


QueuesList


Description:
Lists the queues for a given accountid plus the approximate number of messages in the queue.
Note that queues are virtual - they exist only when there are messages in that queue.

JSON request body example:
{
   "Version": 1
}

JSON response example:
        {
            "QueuesListResult": [
                {
                    "Count": 5,
                    "QueueName": "anotherqueuename",
                    "accountid": "4b849fef-2a42-45ac-acc6-19f4fcf385bf"
                },
                {
                    "Count": 4,
                    "QueueName": "examplequeuename",
                    "accountid": "4b849fef-2a42-45ac-acc6-19f4fcf385bf"
                }
            ]
        }