Azure Storage Queue REST API Reference

This document provides a reference for the Azure Storage Queue REST API. The Queue service provides a way to store large numbers of messages that can be accessed from anywhere in the world. A queue message is a unit of information that can be stored in Azure Storage Queue. A queue can contain any number of messages, up to the capacity limit of the storage account.

Authentication

All requests to the Queue service must be authenticated. Azure Storage supports two forms of authentication:

  • Shared Key Authentication: Uses an account key to sign requests.
  • Shared Access Signature (SAS) Authentication: Uses a token with specific permissions and an expiry time.

For more details, refer to the Azure Storage Authentication documentation.

Endpoints

The Queue service exposes the following REST API endpoints:

  • Queue Service Operations: https://{account-name}.queue.core.windows.net/{queue-name}
  • Message Operations: https://{account-name}.queue.core.windows.net/{queue-name}/messages

Core Operations

The following table outlines the primary operations available through the Queue Storage REST API:

Operation HTTP Verb Description URI
Create Queue PUT Creates a new queue within the specified storage account. /{queue-name}
Delete Queue DELETE Deletes the specified queue and all the messages contained within it. /{queue-name}
List Queues GET Enumerates the queues under the specified account. /
Put Message POST Adds a new message to the back of the message queue. /{queue-name}/messages
Get Messages GET Retrieves one or more messages from the front of the message queue. /{queue-name}/messages
Peek Messages GET Retrieves one or more messages from the front of the message queue, without making them invisible. /{queue-name}/messages?peekonly=true
Update Message PUT Updates the visibility of a message in the queue. /{queue-name}/messages/{message-id}
Delete Message DELETE Deletes a specific message from the queue. /{queue-name}/messages/{message-id}
Get Queue Metadata GET Retrieves the user-defined metadata and the last modified time for the queue. /{queue-name}
Set Queue Metadata PUT Sets user-defined metadata for the specified queue. /{queue-name}
Get Queue Properties GET Retrieves the approximate count of messages in the queue. /{queue-name}?comp=metadata

Request Headers

Common request headers include:

  • x-ms-version: Specifies the version of the REST API to use.
  • Authorization: Contains the credentials for authentication.
  • Content-Type: The MIME type of the request body.
  • Accept: The MIME type of the response.

Response Headers

Common response headers include:

  • Content-Type: The MIME type of the response.
  • Server: Indicates the server software.
  • x-ms-request-id: An identifier for the request.
  • x-ms-version: The version of the REST API used.
  • Date: The date and time the request was processed.

Example: Putting a Message onto a Queue

This example demonstrates how to add a message to a queue using curl.


curl -X POST \
  "https://myaccount.queue.core.windows.net/myqueue/messages?popreceipt=abc&visibilitytimeout=60" \
  -H "Authorization: SharedKey myaccount:YOUR_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messageText": "This is a test message."
  }'
Note: Replace myaccount, myqueue, and YOUR_ACCOUNT_KEY with your actual storage account name, queue name, and account key. The popreceipt and visibilitytimeout are typically obtained when retrieving messages, not when putting them. This example is illustrative for the PUT operation for messages, which is technically POST. The correct POST URI is /{queue-name}/messages.
Tip: Always consider using the Azure SDKs for your preferred programming language. They abstract away many of the complexities of direct REST API calls and provide a more robust and maintainable solution.

Further Reading