How StarQueue works:
Accessing the API.
- StarQueue is a message queue accessed via HTTPS.
- To start, you need to create an accountid and password.
- You must submit an "AuthToken" as a header within every API request.
- You get an "AuthToken" by submitting your password to the authtokenget endpoint.
- All API requests must be POSTs of json with content type application/json.
- The endpoint URLs of the API look like this example:
- The final part of the URL path is the queuename, which is a string.
- Prior to the queuename is the accountid, which you got when you created your account.
- To create a queue, simply send a message to a queuename - you do not need to explicitly create a queue.
- You may use any string for the queuename - just make one up.
- Queues are virtual - they exist only because there are messages in that queue.
- The QueuesList endpoint lists the queue names for a given accountid.
- QueuesList will not list a queue that contains no messages, because queues do not exist without
messages in them.
- The queueclear endpoint unconditionally deletes all messages in the specified queue.
- Send a message by POSTing json data with a MessageBody field to the messagesend endpoint.
- When sending, the MessageBody field must be base64 encoded.
- A Priority may be specified when sending a message.
- A message with a numerically higher Priority will always be returned before a message with a
numerically lower priority. For example, messages with Priority 100 are returned before priority 1.
Preventing duplicate messages.
- A message may be sent with a VisibilityTimeout.
- The VisibilityTimeout defines how long in seconds the message is hidden from queue receivers.
- The VisibilityTimeout may be changed for messages already in the queue via the messagechangevisibility
- A MessageDeduplicationId may be specified when sending a message.
- If a message is sent and is has the same MessageDeduplicationId as an existing message then it will
be accepted by the queue but no message will be created.
- A MessageDeduplicationTimePeriod may be specified when sending a message.
- The MessageDeduplicationTimePeriod defines how long in seconds a message should prevent duplicates for.
- You can receive a message by POSTing to the messagereceive endpoint.
- If a message is available, messagereceive will return it immediately.
- If no message is available, messagereceive uses long polling, and waits for up to 20 seconds.
- messagereceive will return up to 10 messages from a single request.
- You can specify the maximum number of messages (1-10) that messagereceive may return from a single
- When a message has been received, it is no longer visible to be received again for a period of time.
- You delete a message by passing the ReceiptHandle (which comes from messagereceive) to messagedelete.
- If you do not delete a received message, then it will, after its VisibilityTimeout expires, appear again
in the queue.
- If a message is received 4 times without being deleted, then the system deletes that message.
- If a message is received 4 times without being deleted, AND the message was created with a
"DeadLetterQueueName", then instead of deleting that message, the message is moved to the specified
- The queue automatically deletes messages that exceed their MessageRetentionPeriod.