Tags :  

How to Expose and protect Logic App using Azure API Management (Part 5) – API operation documentation: Descriptions (Part 1)

Last updated on: January 21, 2021

There is no doubt that organizations have a difficult task to address the current requirements for building and managing APIs, especially if they don’t use tools like Azure API Management. APIs require up-to-date and strong documentation, increased security levels, comprehensive testing, routine versioning, and high-reliability to be appropriately utilized.

Today we will address how you can easily document your API operations without requiring the traditional Word/PDF documents that can quickly become deprecated and obsolete. You will see that it will not require an extreme amount of work, and even people who don’t like to write documentation, will be happy to make this approach instead. What you need are a little discipline and some best practices. But this topic is so massive and so important that I decided to divide this Part 5 into multiple sub-parts to understand better and avoid the blog post to become too extensive and dull.

We will take as a sample the API and operations we exposed in part 3 of this series: How to Expose and protect Logic App using Azure API Management (Part 3) – Exposing multiple Logic Apps in a single API. We will be documenting two of these operations for simplicity.

Free download this blog as a PDF document for offline read.

API Description

So, without making any changes, if we access our developer portal and explore our APIs, the first thing we see is that our API doesn’t have an accurate description. Instead, we have the default value used during our first importation: Azure Logic App.

API description

To fix that, or to improve this we need to:

  • Access to your APIM on the Azure Portal.
  • And on the left menu, under the APIs section, click the APIs option.
  • Select the API, in this case, BizTalk Alerts API, and click Settings.

API documentation

  • On the Settings panel, change the Description attribute and add a description that can easily define the goal of the API. For example:
    • This API is used to notify the support teams about the alarms triggered on different BizTalk Server platforms.

API's

  • And then click Save.

Anyone who enters on the developer portal, a new partner, a new developer, etc., knows exactly what this API is for. Simple and easy, don’t you think?.

API Operation Description

API Operation Description

The second thing we see is that our operation doesn’t have an accurate description. If we look at the first operation, host-instances-notification, this was the first operation created with the Import Logic App wizard, we see that we have the default value used during our first importation: Trigger a run of the logic app witch is not ideal.

API Documentation

If we look to the other operations, that we add them manually, it is even worse because we don’t have any description at all.

Frontend panel

To fix that, or to improve this we need to:

  • Access to your APIM on the Azure Portal.
  • And on the left menu, under the APIs section, click the APIs option.
  • Select the API, in this case, BizTalk Alerts API, and on the Design panel select your operation, let’s start to select the first one host-instances-notification and then click Open form-based editor to edit the Frontend settings.

API Documentation

  • On the Frontend panel, change the Description attribute and add a description that can easily define the goal of the operation. For example:
    • API that receives a JSON message from the BizTalk Server Monitoring tool with a list of Host Instances that aren’t Started (Stopped, Start pending, Stop pending, Continue pending, Pause pending, Paused or Unknown), and will notify the support team in different channels (email and Teams)

API

  • And then click Save.
  • Do the same for the other two operations.

Free download this blog as a PDF document for offline read.


Once again, anyone who enters on the developer portal, a new partner, a new developer, etc., knows exactly what these operations are for. Simple and easy, don’t you think?.

API Alerts I hope you are enjoying and stay tuned for the next blog post where we will address Tags and Headers!

Author: Sandro Pereira

Sandro Pereira lives in Portugal and works as a consultant at DevScope. In the past years, he has been working on implementing Integration scenarios both on-premises and cloud for various clients, each with different scenarios from a technical point of view, size, and criticality, using Microsoft Azure, Microsoft BizTalk Server and different technologies like AS2, EDI, RosettaNet, SAP, TIBCO etc. He is a regular blogger, international speaker, and technical reviewer of several BizTalk books all focused on Integration. He is also the author of the book “BizTalk Mapping Patterns & Best Practices”. He has been awarded MVP since 2011 for his contributions to the integration community.