The Storage Service was initially introduced in 2008, and since then we have released seven version updates, each refining the protocol and adding new features. We are announcing the upcoming removal and removal of some earlier versions of our REST API. This post will outline all you need to know to ensure that your application continues to run well after these versions have been removed.

Background: Storage Service Versioning

What is versioning?

Azure Storage is accessed using REST API’s. These APIs were first released in 2008. As we have improved the service through additions and changes, we have used versioning to avoid breaking existing applications. Any time we make a change that could break an existing application, we introduce a new version, which applications must explicitly opt-in to use. Existing applications will be unaffected by the new version’s existence. Calls to storage generally specify the version to be used in one of the following ways:

1. api-version query parameter: this can be specified for any call made to storage as long as sv and x-ms-version are not specified, or if specified are using version 2014 or greater. This api-version parameter will dictate the service version used.
2. x-ms-version request header: this is required for calls made using Shared Key authentication. The x-ms-version header specifies a version, which informs the service how to interpret the request, and how to form the response for a client using that version of the REST API.
3. SAS version header: in versions 2012 and 2013, the version specified in the “sv” parameter of a Shared Access Signature (SAS) token would specify the protocol version. In version 2014, the “sv” parameter only specifies the protocol version if the api-version query parameter is not specified.
4. DefaultServiceVersion: The user can set this using SetServiceProperties on the Blob Service to set the version of the API which will be used for requests with no version specified (namely, requests for public blobs).
5. Default: If a request is made for a public blob and the DefaultServiceVersion has not been set, the service default will be used. This was our initial, 2008 version, unless SetContainerACL had been set, in which case version 2009 is used (regardless of the version that was used for SetContainerACL).

The full rules used to determine the version of a request can be found on MSDN.

What about Client Libraries and tools?

Many of our users use the Storage Client Libraries provided by Microsoft for developing their applications. Each of these client libraries is essentially bound to a specific version of the REST API. This also applies to our PowerShell cmdlets and AzCopy. The Storage Emulator supports all versions of the REST API that have been released when that version of the Storage Emulator is released.

What’s changing?

Our approach to versioning is unchanged – we will continue to introduce new versions of our REST API whenever we make changes that might break an existing application. However, we will now be removing several of our earlier service versions which were released early in the lifetime of the storage service.

Removal Details

What versions are being removed?

All versions prior to version 2012-02-12 will be removed on August 1^st, 2015. This includes the following versions:

• 2008 (released prior to GA)
• Version 2009-04-14 (released prior to GA)
• Version 2009-07-17 (released prior to GA)
• Version 2009-09-19 (released prior to GA)
• Version 2011-08-18

The following versions are unaffected and continue to be fully supported:

• Version 2012-02-12
• Version 2013-08-15
• Version 2014-02-14

When will these versions be removed?

The five affected versions will be removed on August 1^st, 2015.

What will happen when these versions are removed?

The following changes will occur when removal takes effect.

Explicitly Versioned Requests

Requests which are explicitly versioned using x-ms-version request header (set to one of the removed versions) will fail, receiving an HTTP 400 (Bad Request) status code, similar to any request made with an invalid version header.

SAS Requests with no “sv” parameter

Prior to version 2012-02-12, a SAS request did not specify a version in the “sv” parameter of the SAS token. The SAS token parameters of these requests were interpreted using the rules for the 2009-07-17 REST version. When the versions prior to 2012-02-12 are removed, these requests will fail, receiving an HTTP 400 (Bad Request) status code, regardless of whether x-ms-version is specified as a supported version. For SAS requests to continue working, they must specify the “sv” parameter. Using at least version 2014-02-14 is recommended.

Default Service Version and Anonymous Requests with no explicit version

If Set Blob Service Properties (REST API) has been used to set the default version of requests to version 2012-02-12 or higher, the version set will be used. If the default version was unset, then it assumed that the request is version agnostic, and going forward we will start to respond with version 2014-02-14. Note that we make no guarantees about whether or not there will be breaking changes when unversioned requests start to get the new service version, so best practice continues to be that providing a version is always best.

If default service version was set to a version that is now removed, that request is considered to be explicitly versioned, and will fail with “400 Bad Request”. If default service version was set to a version that is still supported, that version will continue to be used.

SharedKey/SharedKeyLite Requests with no explicit version

For requests that were signed using the account’s shared key, if no explicit version is specified using x-ms-version header or api-version query parameter (supported in version 2014-02-14 and above), the requests will fail with 400 Bad Request.

Note: It is considered best practice to ensure that all requests made to the storage service are explicitly versioned. Beginning in version 2014-02-14, requests can be explicitly versioned using the api-version query string parameter, so that even clients that cannot specify custom headers can specify a version by including this parameter in their query string. See MSDN for a discussion of versioning in Azure Storage and best practices to follow.

Minimum Supported Versions/Libraries/SDK’s

Users should upgrade to the latest version whenever possible. The below table is provided to allow users to quickly see if they are using any components that target the versions to be removed.

What should I do?

To ensure that your application continues to work properly after removal, you should do the following things.

Check your application to find what versions it is using

The first thing to do is to determine what REST versions your application is using. If your application is under your control and you have confidence you are aware of all of all of the components of it which make calls to Azure Storage, then you can verify this by checking the components used against the above list, or by inspecting your code if you have written your own code to make calls to storage.

As a stronger check, or if you are unsure which versions of the components have been deployed, you can enable logging, which will log the requests being made to your storage account. The logs have the request version used included, which can be used to find if any requests are being made using versions with planned removal. Here is a sample log entry, with the version used highlighted – in this case the request was an anonymous GetBlob request which implicitly used the 2009-09-19 version:

1.0;2011-08-09T18:52:40.9241789Z;GetBlob;AnonymousSuccess;200;18;10;anonymous;;myaccount;blob;"https:// myaccount.blob.core.windows.net/thumbnails/lake.jpg?timeout=30000";"/myaccount/thumbnails/lake.jpg";a84aa705-8a85-48c5-b064-b43bd22979c3;0;123.100.2.10;2009-09-19;252;0;265;100;0;;;"0x8CE1B6EA95033D5";Friday, 09-Aug-11 18:52:40 GMT;;;;"8/9/2011 6:52:40 PM ba98eb12-700b-4d53-9230-33a3330571fc"

What to change

If you find any log entries which show that version to be removed is being used, you will need to find that component and either validate that it will continue to work (unversioned requests may continue to work as their implicit version will simply increase – see above), or take appropriate steps to change the version being used. Most commonly, one of the following two steps will be used:

1) Change the version specified in the request, typically by migrating to a later version of the libraries/tools. When possible, migrate to the latest version to get the most improvements and fixes.

2) Set the default service version to one of the supported versions now so that the behavior can be verified prior to removal. This only applies to anonymous requests with no explicit version.

When migrating your applications to newer versions, you should review the above linked change lists for each service version and test thoroughly to ensure that your application is working properly after you’ve updated it. Please note that the service version updates included both included syntactic breaks (the request will receive a response that either is a failure or formed very differently) and semantic breaks (the request will receive a similar response that means something different).

Post migration validation

After the migration, you should validate in the logs that you do not find any of the earlier versions anymore. This is the surest way to know that your application is not using any of the versions to be removed. Make sure to check the logs over long enough durations of time to be sure that there are no tasks/workloads running rarely that would still use the older versions (scheduled tasks that run once per day, for example).

Conclusion

It is recommended that users begin their application upgrades now in order to avoid being impacted when the earlier service versions are removed on August 1^st, 2015.

Jeff Irwin