Partilhar via

What's the deal with x-ms-version?

  • Artigo

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:

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

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

Comments

  • Anonymous
    March 05, 2015
    Hi Ravi,Nice article ths one!!. However, I have got few questions. When you say Copy the Management Certificate to C:Users<user>DocumentsFiddler2 , do I need to export from Azure and install it in the folder. From where do I get the certificate.?Also I guess the URL posted on this post is not complete?Can you please post the entire URL ?
  • Anonymous
    February 24, 2017
    "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."Uhmmm... WRONG!!! The exact reason I found this article is because my code is broke and I have no idea why. The only thing I understand right is now is the version did indeed change and now my software is non-functioning. I am starring at yet another Microsoft exception that a.) makes no sense, b.) doesn't tell me what is really causing the error, and c.) provides absolutely no information how to fix it.
  • Anonymous
    March 08, 2017
    But how do we find out these dates? Where do they come from and how do we know if we're using the latest?Thanks.
  • Anonymous
    March 08, 2017
    Is this it? : https://msdn.microsoft.com/en-us/library/azure/gg592580.aspxSeems a little old to me.