StarQueue


How StarQueue works:


  • StarQueue is a message queue accessed via HTTPS.

Accessing the API.
  • 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:
  • https://api.starqueue.org/messagesend/ba4b1fb8-b230-4a3a-8760f1960b6a42f8/examplequeuename
  • 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.

About queues.
  • 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.

Sending messages.
  • Send a message by POSTing json data with a MessageBody field to the messagesend endpoint.
  • When sending, the MessageBody field must be base64 encoded.

Message priority.
  • 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.

Message VisibilityTimeout.
  • 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 endpoint.

Preventing duplicate messages.
  • 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.

Receiving messages
  • 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 request.
  • When a message has been received, it is no longer visible to be received again for a period of time.

Deleting messages.
  • 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 queue.
  • The queue automatically deletes messages that exceed their MessageRetentionPeriod.