Unlocking the Power of Custom Widgets in Azure API Management

[srinipadala]

Introduction

In the ever-evolving landscape of API management, Azure API Management stands out as a robust and versatile solution. Its rich set of features enables organizations to secure, publish, and manage APIs at scale. API Management Developer portal is an automatically generated, fully customizable website with the documentation of your APIs. It is where API consumers can discover APIs, learn how to use them, request access, and try them out. Depending on the organizational needs, the developer portal needs to be customized and styled. One such powerful feature is the ability to create and use custom widgets, which further enhances the flexibility and customization options available in Azure API Management. In this blog post, we will explore the potential of custom widgets and how they can elevate your API management experience.

Understanding Custom Widgets

Custom widgets in Azure API Management allow you to extend the functionality of the developer portal, enabling you to present information, interact with users, and integrate third-party services seamlessly. These widgets are essentially reusable components that can be added to various pages within the developer portal.

At a high level, widget developers need to understand the below:

1.  Widgets will be scaffolded from Widget templates using the node package azure/api-management-custom-widgets-scaffolder
2. Widgets can be created in TypeScript, React and Vue technologies.
3. An app view and editor view needs to be created.

1. app - Code for the widget component that visitors to the published developer portal see and interact with
2. editor - Code for the widget component that you use in the administrative interface of the developer portal to edit widget settings

4. The npm package azure/api-management-custom-widgets-tools provides functions to develop the widget
5. azure/api-management-custom-widgets-tools/askForSecrets provides the SAS token to authenticate with the API Management Endpoint. Along with the token, it also provides userId, managementApiUrl and apiVersion
6. The Azure API Management Rest API reference can be used to refer the API that can be invoked but with the url part https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName} changed to the value of apiManagementUrl provided by the askForSecrets call.

When developing custom widgets, it is often required to interact with external APIs / Data Sources depending on the requirement. The sample in the GitHub repo, provides one such implementation as outlined below:

1. Custom Widget retrieves the SAS token, userId, apiManagementUrl and apiVersion
2. Invokes an Azure function with the details retrieved above as headers
3. Azure Function implements a custom binding which
   1. Reads the headers
   2. Validates the token
   3. Retrieves the user and group details using the apiManagementUrl and apiVersion
   4. Injects the User Object with the validation status into the function
4. Once the user is authenticated, and the optional authorization checks are performed, the function can implement/provide the required information back to the widget.

Best Practices for Custom Widgets

To ensure optimal usage of custom widgets in Azure API Management, consider the following best practices:

1. Keep it Simple: Strive for simplicity in your custom widgets. A cluttered and complex interface may confuse developers and hinder their experience. Focus on providing the most relevant information and functionality in a clear and concise manner.
2. Test and Validate: Thoroughly test your custom widgets across different browsers and devices to ensure they function correctly and offer consistent experience. Validate the responsiveness and performance of your widgets to accommodate a diverse developer audience.
3. Secure External Integrations: When integrating external services into your custom widgets, pay attention to security considerations. Follow best practices for secure communication, handle authentication securely, and protect sensitive data.

Conclusion

Custom widgets in Azure API Management offer a powerful way to enhance developer experience, streamline workflows, and integrate third-party services seamlessly. By leveraging custom widgets, you can provide a highly tailored and engaging developer portal that drives API adoption and supports the growth of your API ecosystem. So, embrace the potential of custom widgets in Azure API Management and unlock a new level of customization and flexibility in your API management journey.