As you build more with code in Azure, knowing the API versions to lean on is helpful. If you use ARM Snippets in Visual Studio Code or lean on the engineering within Visual Studio outright, you may decide to use different or newer APIs because you need specific or certain features.
Well how do you check what APIs are available to use?
First off, let's take a quick step back. Azure Resource Manger is comprised of REST APIs. REST stands for Representational State Transfer and API stands for application programming interface. Another way it's commonly referred to is a RESTful API. An API is a set of definitions and protocols for building or integrating application software (also for building out infrastructure now that everything is software defined). If you want to interact with systems to retrieve information or to perform a function, an API helps communicate what you want the system to do and it helps you fulfill your original request.
I tend to think of APIs as a mediator between users and the resources or web services they need to interact with. Maybe think of APIs as a translator between you and computer binary code.
APIs are also a way for companies to share resources and information while ensuring security, control, authentication, etc. are met. APIs that companies create or host allow those APIs to simplify development processes, which saves time and money. APIs provide flexibility, simplify design/administration/use, and provide opportunities for innovation.
Pretty cool, aye?
Azure Resource Manager is used to provision resources in each Azure subscription. ARM is generally a way you may see it referenced in various GitHub repos or possibly even in Microsoft documentation.
Each resource in Azure gets created as a result of hitting a REST API in Azure Resource Manager. Additionally, all resources in Azure have what is called a Resource Provider. A Resource Provider is an HTTPS RESTful API contract that's implemented so a trusted Azure endpoint can provision, delete, create, and manage services on a user or service's behalf. Azure uses the resource from a Resource Provider to perform a set of management operations within the Azure Resource Manager portal.
So now that we've squared that way, let's move back to the topic at hand: finding what API versions are available for use. Typically, I handle this 1 of 2 ways.
Way 1:
Head over to the ARM Template reference within Microsoft's documentation. On the left, you see all the Resource Providers underneath Reference. All Resource Providers show up here, so everything from Compute, Network, AAD, Key Vault, etc. On the overview page, you will be able to read up on a number of different topics like how to create templates, the template structure, and how to find resources:
Between the cmdlets I'll share in this post and the ARM Template reference, these are the tools I use for API versions. If you examine Compute, you'll see a number of different resources show up underneath. If you examine something like Virtual Machines, you'll see the following output on the right, where API versions can be examined to understand structure of the ARM Template and what the ARM template engine is expecting to provision resources:
The Template format I find extremely helpful and note that there's a JSON example + a Bicep example now for each API.
Way 2:
I have had times where I'm very into the code I have been working on and don't necessarily want to open up yet another browser window. You're in luck as you can get all available API version alternatives for ARM endpoints via PowerShell!
First off, if you haven't already, ensure you have the Azure cmdlets installed on your machine. If you don't like to install these things locally, you could lean on Cloud Shell as well. If you're using the modules locally, log in to your Azure account Connect-AzAccount. If you use Cloud Shell, you will not have to run the Connect-AzAccount cmdlet. After you are logged in, ensure you set your Azure context to the right subscription you are building resources in. If you're not sure all the subscriptions you have access to, you can also run a quick cmdlet to retrieve that information. The code looks like this:
# Connect to Azure account.
Connect-AzAccount
# Retrieve all Azure subscriptions.
Get-AzSubscription
# After authenticated, set Azure context.
Set-AzContext -Subscription "Name-of-subscription"Here it is in a real shell:
One thing to note is I have quite a number of subscriptions (more than the screen shot indicates). The first subscription is actually the subscription I wish to access and Azure selected the right environment for me without needing to set my Azure context. Many times this is not the case though so administrators, engineers, and even developers may need to set their context. It's helpful knowing the subscription name, which is why I provided the cmdlet that extracts all relevant information so you can set your Azure context correctly. I have also blurred out the sensitive information within my environment.
Setting the right context is as simple as typing in the following cmdlet once you're logged in, either within Cloud Shell or via a remote PowerShell session:
Set-AzContext -Subscription "subscription-name-goes-here"Here's how it looks within a local shell:
Sweet! Now that you're officially logged in, you may find you're unfamiliar with how to query different regions in Azure. You may not know that East US is eastus, for example. The best way is to run the following command:
Get-AzLocation | moreI add the pipe and more so you can see the locations easily, versus scrolling up and examining them one by one. In the screen shot below, you can see the way you get information back from the REST API you're calling. The pipe and more enables an ability to not have to scroll through a lot of text.
If your region shows up in the first screen, great! You can press Control + C, which brings you back to an empty prompt. If you don't see the location you're looking for, press the space bar, which cycles through the next screen of locations to select from. In my use case, I'm wondering what API versions are within East US, so I'll use eastus.
Next, if you're unfamiliar with the different Resource Providers in each region, you could query the region using PowerShell. The easiest way is to run the following cmdlet (I'll use East US as my example):
Get-AzResourceProvider -Location eastus -ListAvailable | Format-Table ` ProviderNameSpace
What you will receive is a formatted list of all Resource Providers in the region. Usually the output is more than your shell prompt may display. You could always add a pipe and then more to see an organized output vs. everything formatted into a table. After you run the cmdlet, you should see results like this:
Let's pick Microsoft.Compute to continue drilling in for more information. Microsoft.Compute is where resources like VMs, VMSS, Availability Sets, etc., live. We'll focus on virtual machines, but the examples below should highlight that you could focus on anything: networking, Log Analytics, Automation, Site Recovery, etc.
Let's say I wasn't sure if it was VM, virtual machine, virtualmachine, virtualMachine, etc. for deeper queries into the API versions (again, we'll use Microsoft.Compute here). You could run a quick query against the ARM Resource Provider to determine the resource type name as it's registered within Azure. The easiest way I've found is to lean on PowerShell by running the following cmdlet:
(Get-AzResourceProvider -ProviderNamespace ` Microsoft.Compute).ResourceTypes | Format-Table ResourceTypeName
Just like with the other cmdlets, you can pipe more at the end if you don't like scrolling up after the cmdlet runs. The output should look like this (and we'll target virtualMachines for the last cmdlet example):
After figuring out we want to query virtualMachines, now we can actually retrieve the API versions for VMs being built with ARM Templates, Bicep, or Terraform templates. Note, if you already know the resource provider type name, you can skip to the last cmdlet. I wanted to showcase that you can incrementally build out queries via PowerShell to retrieve the information you may be looking for related to an ARM API.
The final cmdlet extracts all relevant APIs you could use within your template builds. You will run the following cmdlet:
((Get-AzResourceProvider -ProviderNamespace ` Microsoft.Compute).ResourceTypes | Where-Object ResourceTypeName -eq ` virtualMachines).ApiVersions
The output will look something like this:
Hopefully going through these cmdlets, you realize that you can reference information by querying ARM APIs faster than tracking down the relevant information within the documentation. Ultimately it's up to you on what you feel comfortable with. If you keep pushing yourself to use more and more code, I encourage you to adopt these cmdlets into your regular day-to-day activities.
Cheers!