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.
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.
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.
- 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.
- 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
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.
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.
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.
- 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)
- And then click Save.
- Do the same for the other two operations.
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?.
I hope you are enjoying and stay tuned for the next blog post where we will address Tags and Headers!
