Tuesday, January 06, 2009

Azure Storage Services - StorageClient Library: Blob Storage API Class Reference

The only “official” interface exposed by the Azure Storage Services is the REST protocol. The StorageClient sample provides “example” .NET wrapper classes for REST API operations for Blob, Queue, and Table Storage. These wrapper classes pack and unpack the URIs for HTTP storage requests and translate HTTP request and response header values to property values of blob storage classes.

Following is the class diagram for the classes contained in the StorageClient library’s BlobStorage.cs class of the October 2008 CTP. The Azure Storage Services - StorageClient Library: REST Blob Storage API Class Reference post of 1/6/2009 contains the diagrams for BlobStorageRest and BlobContainerRest, which inherit from the BlobStorage and BlobContainer abstract classes. See below for the status of the October 2008 CTP of these classes.

Methods that have an IfNotModified suffix use LastModifiedTime and ETag property values to determine if the specified blob has been modified since last accessed by the client (for optimistic concurrency conflict management.)

The Status of the StorageClient APIs

Here’s a quote from Microsoft’s Vikram Dhaneshwar in the What's up with StorageClient in the samples? thread of 10/29/20098 in the Windows Azure forum with the party line for the StorageClient sample:

The official API for Windows Azure storage is the REST API. StorageClient is only a sample .NET client library. As the docs say:

The primary goals of this sample are:

  • To enable users of the Windows Azure SDK to quickly prototype applications and services that interface with storage services using a .NET library, rather than having to implement the underlying REST protocols from scratch.
  • To aid users in building their own client libraries by providing them with a working example of an implementation of the REST APIs.

Aleks Gershaft of the Azure team clarifies its API policy in the same thread:

Please note that the library was explicitly not designed to be THE storage APIs. It was designed as a simple way of communicating to storage and a sample of using different features. As such, it does not expose features like blocks, conditional uploads (based on date), asynchronous calls, etc. It is good for using as a quick-start, prototyping, etc. but shouldn't be considered as comprehensive library.

For example, for best upload performance, you may want to use the parallel block upload and asynchronous calls to maximize the throughput at cost of complexity and higher memory usage.

Subsequently, Aleks stated in the Understanding the Role of StorageClient in Our Application thread of 11/20/2008:

The current version of StorageClient is provided as a sample for the developers and should not be considered an official library. The documentation has the following disclaimer:

The StorageClient sample library is not o  ptimized for performance and is not intended to be used for building robust services, but only as an example of a working client library.

We are not ready to announce any future plans with respect to any official library.

Note: We consider the REST apis to be the official APIs for Windows Azure storage and therefore any changes in those will be done with minimal impact on existing code.

The preceding statements imply that the Azure team doesn’t intend to provide (much less support) a “comprehensive library.”

Note: According to Daniel C. Wang the Azure Team doesn’t plan to provide a lower-level “local” API because of the lack of a “significant performance benefit” from doing so. [From a reply to the Table / Blob / Queue storage - REST APIs the only available ? thread of 12/1/2008 in the Windows Azure forum.