Locking Down the "api version" Strings

The Basics

Every HTTP request made to Azure includes an "api-version" string at the end of it. For example, a GET request to return a list all virtual machines might look like this:

https://management.azure.com/subscriptions/xxx/providers/Microsoft.Compute/virtualMachines?api-version=2017-03-30

In that example, the api-version string is "2017-03-30". The YYYY-MM-DD format is significant. Attempting to use a date in another format will cause an error.

What are the available api-version strings?

If you want to see all of the possible api-version strings for a given provider, you can use the ResourceProviderService. For example, this will list all of the resource types and api-version strings for the "Microsoft.Compute" provider:

provs = Azure::Armrest::ResourceProviderService.new(conf)
compute = provs.get("Microsoft.Compute")

puts compute.namespace

compute.resource_types.each do |resource|
  puts "#{resource.resource_type} => " + resource.api_versions.join(', ')
end

In the output you will see something like this:

availabilitySets => 2017-03-30, 2016-08-30, 2016-04-30-preview, 2016-03-30, 2015-06-15, 2015-05-01-preview
virtualMachines => 2017-03-30, 2016-08-30, 2016-04-30-preview, 2016-03-30, 2015-06-15, 2015-05-01-preview
virtualMachines/extensions => 2017-03-30, 2016-08-30, 2016-04-30-preview, 2016-03-30, 2015-06-15, 2015-05-01-preview
... # and so on

What the azure-armrest gem does

Internally the azure-armrest gem automatically looks for and sets the relevant :api_version attribute for each service class to the most recent non-preview date. If it cannot find a non-preview date, it uses the most recent preview date.

Normally this is fine. However, from time to time Microsoft updates the API to generate different output. Sometimes it changes the format, sometimes it adds data, and sometimes it removes data. Typically, removed data must then be acquired via a different type of request.

This can be problematic for you because we autogenerate models and methods based on the JSON output. If the JSON output changes, the resulting autogenerated methods change. You could suddenly find yourself getting a NoMethodError because Microsoft removed or rearranged various JSON properties.

What you should do

For larger applications we recommend locking down your api-version strings internally. Typically you will want to store these in an external configuration file that you can then load. If you ever want to update the api-version string, you would just alter your configuration file.

You can set the api_version attribute on any service class like so:

vms = Azure::Armrest::VirtualMachineService.new(conf)
vms.api_version = "2017-04-01"