Update: We have extended the time frame for the removal of the specified versions to December 9th, 2015.
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.
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:
The full rules used to determine the version of a request can be found on MSDN.
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.
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.
All versions prior to version 2012-02-12 will be removed on August 1st, 2015. This includes the following versions:
The following versions are unaffected and continue to be fully supported:
The five affected versions will be removed on August 1st, 2015.
The following changes will occur when removal takes effect.
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.
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.
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.
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.
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.
To ensure that your application continues to work properly after removal, you should do the following things.
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;188.8.131.52;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"
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).
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).
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 1st, 2015.