Introduction to Azure Storage Blobs REST API

The Azure Storage Blobs REST API allows you to interact with Azure Blob Storage programmatically. Blob Storage is a cloud object storage solution designed for storing massive amounts of unstructured data. This API provides operations for managing containers, blobs, and their properties.

Each request to Azure Storage is authenticated, and operations are performed within the context of an Azure subscription and a storage account.

Authentication

All requests to Azure Storage must be authenticated. The primary methods for authentication are:

  • Shared Key Authentication: Uses the storage account's access keys.
  • Shared Access Signatures (SAS): Provides delegated access to resources with defined permissions and expiry times.
  • Azure Active Directory (Azure AD): For more robust and managed access control.

The following examples assume Shared Key authentication for simplicity, but the same endpoints can be used with other authentication mechanisms.

Container Operations

Manage containers within your Azure Blob Storage account.

Create Container

PUT /\{accountName\}/\{containerName\}

Creates a new container in the specified storage account.

Query Parameters

timeoutinteger[Optional]
restypestring[Required]=container
compstring[Optional]=public_access

Request Headers

x-ms-versionstringSpecifies the version of the REST API used to process the request.
AuthorizationstringSpecifies the authorization information for the request.
x-ms-blob-public-accessstring[Optional] Specifies whether data in the container may be accessed publicly and the level of access. Possible values: 'container', 'blob', 'off'.

Success Response (201 Created)

Indicates that the container was successfully created.

Error Responses

400 Bad Request: The request was malformed.

403 Forbidden: The caller does not have permission to perform this operation.

404 Not Found: The storage account or container does not exist.

Get Container Properties

GET /\{accountName\}/\{containerName\}

Retrieves system properties for the specified container.

Query Parameters

restypestring[Required]=container
compstring[Optional]=metadata
timeoutinteger[Optional]

Request Headers

x-ms-versionstringSpecifies the version of the REST API used to process the request.
AuthorizationstringSpecifies the authorization information for the request.

Success Response (200 OK)

Returns container properties such as ETag, Last-Modified, Lease Status, Public Access, and Container Name.

Error Responses

403 Forbidden: The caller does not have permission to perform this operation.

404 Not Found: The storage account or container does not exist.

List Containers

GET /\{accountName\}/

Lists all containers in the specified storage account.

Query Parameters

compstring[Required]=list
prefixstring[Optional]Filters the results to return only containers whose names begin with the specified prefix.
includestring[Optional]Specifies that container metadata or uncommitted blobs should be returned. Possible values: 'metadata'.
maxresultsinteger[Optional]Specifies the maximum number of containers to return.
markerstring[Optional]A string value that identifies the position in the list of containers at which to begin the listing operation.
timeoutinteger[Optional]

Request Headers

x-ms-versionstringSpecifies the version of the REST API used to process the request.
AuthorizationstringSpecifies the authorization information for the request.

Success Response (200 OK)

Returns a list of containers with their properties. Includes a NextMarker if there are more results.

Error Responses

403 Forbidden: The caller does not have permission to perform this operation.

404 Not Found: The storage account does not exist.

Blob Operations

Manage blobs (block blobs, append blobs, page blobs) within containers.

Put Blob (Block Blob)

PUT /\{accountName\}/\{containerName\}/\{blobName\}

Uploads a new block blob or replaces an existing block blob.

Query Parameters

timeoutinteger[Optional]
compstring[Optional]=appendblock
blockidstring[Optional]Specifies the ID of the block to be committed. Used with comp=block.

Request Headers

x-ms-versionstringSpecifies the version of the REST API used to process the request.
AuthorizationstringSpecifies the authorization information for the request.
x-ms-blob-typestringRequired. Specifies the type of blob. Possible values: 'BlockBlob', 'AppendBlob', 'PageBlob'.
x-ms-lease-idstring[Optional] If the blob is locked, this header is required to perform the operation.
x-ms-blob-condition-appendposinteger[Optional] Condition for appending to an append blob.
x-ms-blob-condition-maxsizeinteger[Optional] Condition for max size of an append blob.

Success Response (201 Created)

Indicates that the blob was successfully created or updated.

Error Responses

400 Bad Request: Invalid request parameters or body.

403 Forbidden: Access denied.

404 Not Found: Container or blob not found.

Get Blob

GET /\{accountName\}/\{containerName\}/\{blobName\}

Retrieves a blob from the specified container.

Query Parameters

snapshotstring[Optional]Specifies a snapshot timestamp for the blob to retrieve.
timeoutinteger[Optional]
compstring[Optional]=metadata
rangestring[Optional]Specifies the byte range to retrieve, e.g., 'bytes=0-1023'.

Request Headers

x-ms-versionstringSpecifies the version of the REST API used to process the request.
AuthorizationstringSpecifies the authorization information for the request.
x-ms-lease-idstring[Optional] If the blob is locked, this header is required to perform the operation.
If-Matchstring[Optional] Returns the blob only if its ETag matches the value specified in the If-Match header.
If-None-Matchstring[Optional] Returns the blob only if its ETag does not match the value specified in the If-None-Match header.
If-Modified-Sincedatetime[Optional] Returns the blob only if it has been modified since the specified date.
If-Unmodified-Sincedatetime[Optional] Returns the blob only if it has not been modified since the specified date.

Success Response (200 OK)

Returns the blob's content and system properties.

Error Responses

403 Forbidden: Access denied.

404 Not Found: Container or blob not found.

412 Precondition Failed: A specified condition, such as If-Match or If-Modified-Since, was not met.

Delete Blob

DELETE /\{accountName\}/\{containerName\}/\{blobName\}

Deletes a blob from the specified container.

Query Parameters

snapshotstring[Optional]Specifies a snapshot timestamp for the blob to delete.
timeoutinteger[Optional]
compstring[Optional]=snapshot
resourcestring[Optional]=snapshotsIf specified, indicates that the deletion of the blob should include all snapshots associated with the blob.

Request Headers

x-ms-versionstringSpecifies the version of the REST API used to process the request.
AuthorizationstringSpecifies the authorization information for the request.
x-ms-lease-idstring[Optional] If the blob is locked, this header is required to perform the operation.
If-Matchstring[Optional] Condition for ETag.
If-Unmodified-Sincedatetime[Optional] Condition for Last-Modified.

Success Response (200 OK)

Indicates that the blob was successfully deleted.

Error Responses

403 Forbidden: Access denied.

404 Not Found: Container or blob not found.

409 Conflict: The blob is currently leased.

Lease Operations

Manage leases for blobs and containers to provide exclusive write or delete access.

Acquire Lease

PUT /\{accountName\}/\{containerName\}/\{blobName\}

Acquires a new lease on a blob or container.

Query Parameters

timeoutinteger[Optional]
compstring[Required]=lease

Request Headers

x-ms-versionstringSpecifies the version of the REST API used to process the request.
AuthorizationstringSpecifies the authorization information for the request.
x-ms-lease-durationinteger[Optional] Specifies the lease duration in seconds. Must be between 15 and 60 seconds, or -1 for an infinite lease. Default is 60.
x-ms-proposed-lease-idstring[Optional] Specifies the proposed lease ID for the new lease.

Success Response (201 Created)

Indicates that the lease was successfully acquired. Returns the Lease ID.

Error Responses

400 Bad Request: Invalid lease duration or other parameters.

403 Forbidden: Access denied.

404 Not Found: Container or blob not found.

Snapshot Operations

Create read-only snapshots of blobs.

Create Snapshot

PUT /\{accountName\}/\{containerName\}/\{blobName\}

Creates a read-only snapshot of a blob.

Query Parameters

compstring[Required]=snapshot
timeoutinteger[Optional]

Request Headers

x-ms-versionstringSpecifies the version of the REST API used to process the request.
AuthorizationstringSpecifies the authorization information for the request.
x-ms-snapshotdatetimeThe date and time for the snapshot. This is automatically generated if not provided.

Success Response (201 Created)

Indicates that the snapshot was successfully created. Returns the ETag and Last-Modified properties of the snapshot.

Error Responses

400 Bad Request: Invalid parameters.

403 Forbidden: Access denied.

404 Not Found: Container or blob not found.

Access Tier Operations

Manage access tiers for blobs (e.g., Hot, Cool, Archive).

Set Blob Tier

PUT /\{accountName\}/\{containerName\}/\{blobName\}

Sets the access tier for a blob.

Query Parameters

compstring[Required]=tier
timeoutinteger[Optional]
snapshotstring[Optional]Specifies a snapshot timestamp for the blob to modify.

Request Headers

x-ms-versionstringSpecifies the version of the REST API used to process the request.
AuthorizationstringSpecifies the authorization information for the request.
x-ms-access-tierstringRequired. Specifies the access tier. Possible values: 'Hot', 'Cool', 'Archive', 'Cold'.
x-ms-lease-idstring[Optional] If the blob has an active lease, this header is required.
If-Matchstring[Optional] Condition for ETag.

Success Response (200 OK)

Indicates that the tier was successfully set.

Error Responses

400 Bad Request: Invalid tier or other parameters.

403 Forbidden: Access denied.

404 Not Found: Container or blob not found.

409 Conflict: Blob is leased or has snapshots.