Azure Storage REST API

The Azure Storage REST API provides a robust and scalable way to interact with Azure Storage services programmatically. It allows you to manage and access your data from anywhere in the world over HTTP or HTTPS.

Introduction

Azure Storage offers several services, including Blob Storage, File Storage, Queue Storage, and Table Storage. Each service has its own set of REST operations that enable fine-grained control over your data.

This document serves as an introduction to using the Azure Storage REST API, covering fundamental concepts, authentication, common operations, and best practices.

Authentication

All requests to Azure Storage services must be authenticated. Azure Storage supports several authentication methods:

• Shared Key Authentication: Uses account access keys to sign requests. This is the simplest method for development and testing.
• Shared Access Signature (SAS): Provides delegated access to resources for a limited time with specific permissions. Ideal for granting temporary access to clients.
• Azure Active Directory (Azure AD): Integrates with Azure AD for enterprise-grade authentication and authorization, using OAuth 2.0 tokens.

For detailed information on each authentication method, refer to the Azure Storage authentication overview.

Shared Key Signing

A common way to authenticate using Shared Key is to construct a canonicalized string and then generate a signature using your account's access key. The signing process is as follows:

1. Construct the canonicalized string.
2. Sign the canonicalized string using HMAC-SHA256.
3. Include the signature in the Authorization header.

The Authorization header format is:

Authorization: SharedKey <account-name>:<signature>

Endpoints

Each Azure Storage service has a base endpoint. The format of the endpoint depends on the service and your region:

• Blob Storage: https://<storage-account-name>.blob.core.windows.net
• File Storage: https://<storage-account-name>.file.core.windows.net
• Queue Storage: https://<storage-account-name>.queue.core.windows.net
• Table Storage: https://<storage-account-name>.table.core.windows.net

For example, to list blobs in a container, you would send a request to:

GET https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list HTTP/1.1
Authorization: SharedKey myaccount:V4UqMzk2h7BGLmPz8Xg7mD3J/6rR8iQ/y5Q3J7M/3Q==
Date: Mon, 27 Jul 2024 18:30:00 GMT

Common Operations

The REST API supports a wide range of operations for managing your storage resources. Here are some common examples:

Blob Storage

• Creating a Container: PUT https://<account-name>.blob.core.windows.net/<container-name>
• Uploading a Blob: PUT https://<account-name>.blob.core.windows.net/<container-name>/<blob-name>
• Downloading a Blob: GET https://<account-name>.blob.core.windows.net/<container-name>/<blob-name>
• Listing Blobs: GET https://<account-name>.blob.core.windows.net/<container-name>?restype=container&comp=list

Queue Storage

• Creating a Queue: PUT https://<account-name>.queue.core.windows.net/<queue-name>
• Adding a Message: POST https://<account-name>.queue.core.windows.net/<queue-name>/messages
• Getting Messages: GET https://<account-name>.queue.core.windows.net/<queue-name>/messages?numofmessages=5

For a comprehensive list of operations, please consult the Azure Storage REST API documentation.

Error Handling

Azure Storage returns standard HTTP status codes to indicate the success or failure of a request. In case of errors, the response body will typically contain an XML document detailing the error code, message, and other relevant information.

Common error codes include:

• 400 (Bad Request): The request was malformed.
• 403 (Forbidden): Authentication failed or authorization denied.
• 404 (Not Found): The requested resource does not exist.
• 500 (Internal Server Error): An error occurred on the server.

A typical error response body looks like this:

<?xml version="1.0" encoding="utf-8"?><Error>
    <Code>InvalidHeaderValue</Code>
    <Message>The value for one of the HTTP headers is invalid.
    RequestId:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    Time:2024-07-27T18:30:00.1234567Z</Message>
</Error>

Best Practices

To ensure efficient and secure use of the Azure Storage REST API:

• Use HTTPS: Always use HTTPS to encrypt data in transit.
• Manage Keys Securely: Protect your account access keys and consider using Azure AD or SAS for more granular and temporary access.
• Implement Retries: Transient errors can occur. Implement a robust retry mechanism with exponential backoff.
• Use Compression: For large data transfers, consider enabling compression on the client or server side.
• Monitor Performance: Utilize Azure Monitor to track performance metrics and identify bottlenecks.