Lessons learnt while using Azure REST API

I recently got the chance to work with Azure Rest APIs, when we were building Logic Apps monitoring capabilities in our BizTalk360 product. To know more about BizTalk360 Logic Apps Monitoring capabilities, read this article. Whenever Microsoft adds a new Azure Service they usually make a REST API available. Most of these REST APIs have a corresponding client SDK library, which handles much of the client code for you. This is excellent news for developers who are looking to build tools in the Azure platform! Developers can pretty much use all these available capabilities for their own tools. In our case, we needed to use the Insights APIs to get some insights on Logic Apps using the Logic Apps Metrics that are available in the Azure.

Choosing Library or REST API

When it comes to calling the Azure API, the standard approach is to reference the relevant NuGet packages to get the right client API. Specifically, in our case we had to use Microsoft.Azure.Insights, but some developers may prefer to be close to the wire and call the REST API directly, without using specific libraries. Doing this with the Azure API is easy, once we get passed the authentication part.

There is nothing wrong with either of these approaches; it all comes down to personal preference. For example, the SDK for Insights API is still in preview but as the SDK have all the things that we required from the API we decided to go ahead with the SDK instead of calling REST API directly.

Beware of dependencies inconsistency

When we started out using the Client SDK, one of the first roadblocks we faced was the Newtonsoft.Json dependency of the Insights SDK. The latest 0.15.0-preview version of the Microsoft.Azure.Insights NuGet package has a dependency on Newtonsoft.Json with a maximum version of 7.0.0 for the .NET Framework target, which means it cannot be installed along with other libraries in our project which depend on Newtonsoft.Json 8.0.2 or higher. Even though we could get around this problem by altering our projects dependency structure, still this would be a huge issue for many developers. I have also raised a Github issue in the Azure SDK Github page and it looks like this issue is faced by several others as well. Hopefully that this would be resolved soon by the Azure SDK team.

API Documentation

Microsoft has done a great job when it comes to the documentation. You can visit docs.microsoft.com to find the REST APIs documentation, along with all other Microsoft products. From the look of it, you could see that a lot of thoughts went into the site. The API documentation is grouped based on each Azure Service like Analysis, Logic Apps, Cognitive Services, etc. Developers can click into each of the services to view the list of sub services and the request and response format of the each of those services.

Let’s see some code

The first step is to obtain an authentication token for your service principal. The first line in the code below uses a helper function to do this, I won’t go into the details of the helper function(which is really just a REST call)

 
// this is a custom helper class
var tokenManager = new AzureAccessTokenManager(request, 
handler, tenantId);
 _insightsClient = new InsightsClient(tokenManager.GetTokenCredentials(),
 handler)
 {
 SubscriptionId = subscriptionId
 };

Note: In this sample we have added Microsoft.Azure.Insights package. Similarly we would need to add the respective Azure SDK package based on our need Once you obtain the Token Credentials you have to pass that to the InsightsClient along with the SubscriptionId. This is a common step for any clients that are available in the SDK. Now once the InsightsClient object created successfully we are ready to call the Insights API. Below is the sample code snippet of how you would do that.

_insightsClient.Metrics.List(logicAppResourceId, query)
 .SelectMany(q => q.Data)
 .Where(d => d.Total != null)
 .Sum(s => s.Total);

This would return IEnumerable<Metric> and can be iterated and used in the application or it can store in a database.

Gotchas!!

Azure collects metrics data depending on the service. For example, Logic Apps will have only last 30 days metric data available. In Azure there may be a delay between an event and when the corresponding hourly or minute metrics data are recorded. In the case of minute metrics, several minutes of data may be written at once. This can lead to transactions from earlier minutes being aggregated into the transaction for the current minute. When this happens, the alert service may not have all available metrics data for the configured alert interval, which may lead to alerts firing unexpectedly. For Logic Apps Metrics, the chart shown in the monitor section may mislead the user. In the below diagram the ActionLatency metric data is displayed for Logic App with a 15-minute time interval. The Logic App has run only on 10.06 AM and 10.09 AM. In the Y axis, you can see that both minutes have more than 1 second latency, but the portal displays the average latency as 237.43 ms, which is wrong. The Azure portal displays the average for the entire period considering each minute, even if there are no Actions performed in that minute. So the ideal calculation to determine Average Action Latency would be Sum(avg. ActionLatency)/No.Of Actions Started. Note: It looks like Azure portal team has made some changes after this blog was written. But still the calculation seems buggy. It looks they are dividing the latency related metrics by triggers started count. But Ideally the calculation should differ for each latency. For example to calculate ActionSuccessLatency we need to divide the total latency by ActionSucceeded Count not the TriggerStarted count.

Conclusion

One of the main benefits of Azure REST API is we’re not relying on any specific language or libraries. All the user need to know is how to make basic HTTP requests and they’re pretty much covered. To learn Azure REST API in an interactive way please visit Azure Resource Explorer(https://resources.azure.com/).