What's the deal with x-ms-version?
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:
- Launch Fiddler
- Go to File menu and uncheck "Capture Traffic". This will ensure no unwanted logs in fiddler.
- 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
- On Fiddler, click "Composer" tab. And copy the URL in the Box.
- 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
- 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