Using the REST API (part 1) - Listing BLOBs in a public container using REST

The StorageClient library is useful but it’s only a wrapper implementation of the REST API (which is the only official API). So although you’ll mainly be working against the StorageClient library, there are some instances when you might need to use the REST API directly.

Windows Azure is an evolving platform and the Windows Azure team typically releases new features exposed via the REST API first. At a later date, they might provide an update to the SDK. If there’s a new feature that you badly need to use, you might not have the luxury of waiting for the SDK update.

Another reason that you might need to use the REST API directly is that not all features are implemented (or implemented in the way you might expect) in the SDK; you might need to drop down to the REST API to use that feature. Rather than showing you every single feature with the REST API, we’ll try to show you the important parts: how to list BLOBs in a public container and how to authenticate private requests using the REST API.

1. Listing BLOBs in a public container using REST

In this example, you’re going create a small console application that’ll return a list of all the BLOBs in a public container using the REST API. To do that, let’s return to the funky little podcasting conversion sample . In that application, let’s assume that you’ve converted a bunch of MP3s to WMA, and now you want to list all the converted podcasts. In the console application that you’re going to develop, all the BLOBs stored in the ChrisConverted public container (which holds the WMA files) are going to be returned from the silverlightsukstorage BLOB service account in the live production system. Figure 1 shows the information that’s returned from the request within your console application. This XML output shows that this container contains a single .wma file called mi2limpbiskit.wma.

Figure 1. Console application that returns a list of BLOBs from a public container, using REST

To create the code that returns this output, create a new console application in Visual Studio and replace the existing static main method with the code in the following listing.

Listing 1. Listing the BLOBs in a container via REST

Wow, that’s quite a bit of code. All it really does is list the BLOBs in a public container and output the result to the console (as shown in figure 1). Unfortunately, whenever you use the REST API directly, your code will get more complex. (I guess you can see why we prefer to use the StorageClient library.)

Remember that the HTTP requests that were generated by the code in listing 1 are the same requests that the StorageClient library generates on your behalf.

In listing 1, the GET request is created at . This verb indicates that you want some data returned from the server rather than have an action performed that’ll update the data (such as a create, update, or delete). The request is executed at .

Let’s now take a deeper look at the rest of the code in listing 1; doing so will give you a better understanding of the communication between your clients and the storage accounts.

The URI

Look at the URI that you’re calling at . There’s some interesting information about the request that’s being made.

From the domain, you can determine that you’re using the live BLOB storage service (blob.core.windows.net) and that the request is being made against the storage account silverlightukstorage. Looking at the request, you can also derive that you want a list of whatever is in the container ChrisConverted (chrisconverted?comp=list), which we know are BLOBs (in fact, they’re the WMA files that were converted from MP3).

Windows Azure follows a standard naming convention for performing requests; as soon as you’re familiar with some of the API calls it’s easy to infer what other calls might look like. For example, if you required a list of whatever resides in a storage account (containers), you could use the following URI:

http://silverlightukstorage.blob.core.windows.net/?comp=list

You would need to sign the request with your access key because it isn’t a public operation. Listing BLOBs in a public container can be performed without an authorization key because an authorization key is required only for private containers.

The Request Headers

In the code for the standard CreateHttpRequest in listing 1, two headers are set: x-ms-version and x-ms-date.

The x-ms-version header is an optional header that should be treated as a required header. The storage service versioning policy is that when a new version of an API is released, any existing APIs will continue to be supported. By providing the correct x-ms-version header, you’re stating which API you want your request to work against. Using this policy, Microsoft can release new functionality and change existing APIs but allow your existing services to continue to work against the previous API.

The x-ms-date header is a required header that states the time of the client request. We set this value at in listing 1. The value set in the request header is a representation of the current time in UTC; for example, “Sat, 27 Jun 2009 23:37:31 GMT”. This request header serves two purposes:

• It allows the server to generate the same authorization hash as the client

• It prevents replay attacks by denying old requests

We’ve looked at how to make non-authenticated requests against a public container and how to make requests to the storage accounts via the SDK. We’ll now look at how to make authenticated requests via the REST API and give you an understanding of how the REST API calls are authenticated.