Azure: Calling the Azure Management Rest API

The Azure Management REST API exposes a series of endpoints that allow you to perform various operations against your Azure subscription. This is documented at https://msdn.microsoft.com/en-us/library/windowsazure/ee460799.aspx. You can do many things with the REST API – the majority of Azure management operations can be initiated via this (Note: the Azure PowerShell commandlets wrap calls to the REST API).

To provide a useful example, this article will focus on obtaining the list of Virtual Networks available on a given Azure subscription. In this example, we will call the “Virtual Network” endpoint, as documented at https://msdn.microsoft.com/en-us/library/windowsazure/jj157185.aspx. [Note: this pattern can be applied to any of the REST API endpoints].

As per all management API scenarios, you must first create a management certificate, install it on the machine where you want to run your code from, and upload it to your Azure subscription. A guide for this can be found at https://msdn.microsoft.com/en-us/library/windowsazure/gg551722.aspx.

Once your management certificate is set up on your machine and registered against your Azure subscription, you can call the REST service (in code) by…

1. Obtaining the management certificate from the local certificate store (in the code below, this is the personal “my” store).
2. Form the HTTP request to call the relevant management service (including the above public certificate in the request headers)
3. Call the relevant management service and obtain the response
4. Deserialize the response

The code sample below illustrates this. Note this uses two DataContract classes “VirtualNetworkSites” and “VirtualNetworkSite” that match the name of the appropriate elements in the XML response. These DataContract classes were manually created for this example.

 namespace AzureCallManagementAPI
 {
     using System;
     using System.Collections.ObjectModel;
     using System.Globalization;
     using System.IO;
     using System.Net;
     using System.Runtime.Serialization;
     using System.Security.Cryptography.X509Certificates;
  
     internal class Program
     {
         private static void Main(string[] args)
         {
             VirtualNetworkSites vNets = AzureHelper.QueryAvailableVirtualNetworks("YOUR-AZURE-SUBSCRIPTION-ID", "YOURMANAGEMENTCERTIFICATETHUMBPRINT");
  
             foreach (VirtualNetworkSite virtualNetwork in vNets)
             {
                 Console.WriteLine(virtualNetwork.Name);
             }
         }
     }
  
     public class AzureHelper
     {
         public static VirtualNetworkSites QueryAvailableVirtualNetworks(string subscriptionId, string managementCertThumbprint)
         {
             X509Certificate2 certificate = GetManagementCertificate(managementCertThumbprint);
  
             string requestUri = string.Format(
                 CultureInfo.InvariantCulture,
                 "https://management.core.windows.net/{0}/services/networking/virtualnetwork",
                 subscriptionId);
  
             HttpWebRequest request = (HttpWebRequest)WebRequest.Create(requestUri);
             request.Headers.Add("x-ms-version", "2012-03-01");
             request.Method = "GET";
             request.ContentType = "application/xml";
             request.ClientCertificates.Add(certificate);
  
             using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())
             {
                 using (Stream responseStream = response.GetResponseStream())
                 {
                     if (responseStream != null)
                     {
                         DataContractSerializer serializer = new DataContractSerializer(typeof(VirtualNetworkSites));
                         return (VirtualNetworkSites)serializer.ReadObject(responseStream);
                     }
                 }
             }
  
             return null;
         }
  
         private static X509Certificate2 GetManagementCertificate(string managementCertThumbprint)
         {
             X509Store store = new X509Store(StoreName.My, StoreLocation.CurrentUser);
             store.Open(OpenFlags.ReadOnly);
             X509Certificate2Collection certificates = store.Certificates.Find(X509FindType.FindByThumbprint, managementCertThumbprint, false);
  
             if (certificates.Count == 0)
             {
                 throw new Exception(string.Format("Could not find certificate with thumbprint {0}", managementCertThumbprint));
             }
  
             return certificates[0];
         }
     }
  
     [CollectionDataContract(Name = "VirtualNetworkSites", Namespace = "https://schemas.microsoft.com/windowsazure")]
     [KnownType(typeof(VirtualNetworkSite))]
     public class VirtualNetworkSites : Collection<VirtualNetworkSite>
     {
     }
  
     [DataContract(Name = "VirtualNetworkSite", Namespace = "https://schemas.microsoft.com/windowsazure")]
     public class VirtualNetworkSite
     {
         [DataMember(Order = 1)]
         public string Name { get; set; }
  
         public ExtensionDataObject ExtensionData { get; set; }
     }
 }

Written by Rob Nowik.

Thanks to Christopher Owczarek for his help investigating the Azure REST API.