x-ms-version is a HTTP header which is used in Service Management API calls to specify the version of operation. You could also specify x-ms-version in Azure Storage Services APIs.  In other words users can specify which version of an operation they want to use by setting the x-ms-version request header. The benefits of x-ms-version is that if there is a new version of the API is available, it will not break the functionality of your existing code. Users can modify the code to call a newer version of API by specifying the x-ms-version HTTP Headers.

The x-ms-version request header value must be specified in the format YYYY-MM-DD. For example: 

x-ms-version: 2011-08-18

 

To understand it better, here is an example for you. I will call List Hosted Services Service Management API from Fiddler to get a list of the cloud services available under the specified subscription. This is what we need to do:  

  • Grab the Subscription ID from Azure Portal.
  • Download and Install Fiddler
  • Copy the Management Certificate to C:\Users\<user>\Documents\Fiddler2

 

Here are the detailed steps:

  1. Launch Fiddler
  2. Go to File menu and uncheck "Capture Traffic". This will ensure no unwanted logs in fiddler.
  3. Now you need to prepare the URL for Rest API. Just replace your existing subscription id and you are good to go. Your URL should look like this

https://management.core.windows.net/<subscriptionid>/services/hostedservices 

  1. On Fiddler, click "Composer" tab. And copy the URL in the Box.
  2. Now define the x-ms-version HTTP header. Let's use 2009-10-01 as value for x-ms-version.

 x-ms-version: 2009-10-01 

 

  1. Now hit the Execute button and wait for a response. You should have a HTTP 200 response (Fiddler left pane)if everything goes well. If so, double click on the log and click XML tab in right pane. And you should see something like this:


7.   As you could see, this has returned a list of Cloud services. And if you expand the tree, you could see several  fields. So this was the response when we use 2009-10-01 to define the version for the operations. Now let's try again with a different x-ms-version value. This time we will use  2013-03-01 as value of x-ms-version.

x-ms-version: 2013-03-01

 8.  After executing the request, I got the following response:

 

Now as you could see, for 2013-03-01 version of operation, I got a bit different response. This time I got 6 more fields in response. So now as you could see that we got different response because we passed different version number for x-ms-version.

 

Reference:

http://msdn.microsoft.com/en-us/library/windowsazure/gg592580.aspx

http://msdn.microsoft.com/en-us/library/windowsazure/dd894041.aspx