Azure API Management Developer Portal

The Azure API Management developer portal can be deployed in two ways, each with different support models:

1. Managed developer portal: Hosted and managed by Microsoft. For bugs, use Azure Support + Troubleshooting in the Azure portal. For feature requests, use the Azure Feedback Forum.

2. Self-hosted developer portal: You host the portal yourself. For bugs, use the GitHub Issues section. For feature requests, use the GitHub Discussions section.

Note on Support: Microsoft Azure Support assistance is limited to managed portals and the initial setup of self-hosted portals. For self-hosted issues like custom widgets or environmental factors (hosting, network, etc.), please use Stack Overflow with the azure-api-management tag. GitHub Issues are not monitored for support requests.

To make the document-details widget functional, you must register its modules in the following three root module files using injector.bindModule():

1. Design-time: src/apim.design.module.ts
2. Publish-time: src/apim.publish.module.ts
3. Run-time: src/apim.runtime.module.ts

// src/apim.design.module.ts
import { DocumentDetailsDesignModule } from "../community/widgets/document-details/documentDetails.design.module";
// ...
injector.bindModule(new DocumentDetailsDesignModule());

// src/apim.publish.module.ts
import { DocumentDetailsPublishModule } from "../community/widgets/document-details/documentDetails.publish.module";
// ...
injector.bindModule(new DocumentDetailsPublishModule());

// src/apim.runtime.module.ts
import { DocumentDetailsRuntimeModule } from "../community/widgets/document-details/documentDetails.runtime.module";
// ...
injector.bindModule(new DocumentDetailsRuntimeModule());

The document-details widget allows you to display long API descriptions (like security, troubleshooting, or best practices) by fetching HTML documents from an Azure Storage account and rendering them dynamically in the developer portal.

Prerequisites

1. Azure Storage: Upload your HTML documents to an Azure storage account. Ensure the access level is set to either Blob (anonymous read access for blobs only) or Container (anonymous read access for containers and blobs).

Installation Steps

1. Copy Widget Files: Copy the document-details folder from /community/widgets into the /api-management-developer-portal directory.
2. Configure Storage URL:
   • Open community/widgets/document-details/ko/runtime/document-details-runtime.ts.
   • Assign your storage account HTML URL to the documentApiUrl constant.
3. Set Default File:
   • Open document-details/constants.ts.
   • Update the defaultFileName constant to the name of the file you want displayed by default.
4. Register Modules: You must register the widget's modules in the portal's root modules to enable design-time, publish-time, and runtime functionality.

Usage

1. Run npm start to launch the portal.
2. In the widget selector, find Document details under the Community category.
3. Place the widget on a page and save (Ctrl+S or ⌘+S).
4. To change the content, select the widget in the editor and enter a different HTML file name in the text-editor block in the corner.

// In community/widgets/document-details/ko/runtime/document-details-runtime.ts
const documentApiUrl = 'YOUR_STORAGE_ACCOUNT_URL';

// In document-details/constants.ts
const defaultFileName = 'your_default_file.html';

To create a workflow where an API description links to a specific documentation page containing unique details, use URL hash parameters.

1. Create the Link

In your API description, use an anchor tag with fileName and api parameters in the hash.

Format: <a href="PAGE_NAME#fileName=FILE_NAME&&api=API_NAME">Link Text</a>

Example: If you have a portal page named documentation and an HTML file named sample_document.html for an API named Echo API:

<a href="documentation#fileName=sample_document.html&&api=Echo API">Click here</a> for the additional details of this API.

2. Implement the Route Helper

Add the getFileName() method to src/routing/routeHelper.ts to allow the widget to extract the fileName from the current route's hash:

/**
 * Returns ARM resource name of the html file specified in hash parameter of the current route, e.g. "sample_document.html".
 */
public getFileName(): string {
    return this.getHashParameter("fileName");
}

3. (Optional) Customize the Page Title

By default, the widget might show the file name. To show the API name as the title instead, update the data-binding in document-details/ko/runtime/document-details-runtime.html:

<h1><span data-bind="text: api"></span></h1>
<p data-bind="html: sessionDescription"></p>

When creating or documenting a new community widget for the Azure API Management developer portal, use the standard scaffold format. This template ensures that essential metadata—such as the contributor's identity, organization, security implications, and a visual preview—is clearly communicated to users.

Note that placeholders like <widget name>, <github-alias>, and <widget description> must be replaced with the actual values for the specific widget being documented.

# Community widget: <widget name>

**Contributor's GitHub alias**: <github-alias>

**Organization name**: <for example, Contoso or individual>

**Privacy and security notes**: <(optional) describe and explain all potentially unsafe operations performed by the widget; for example: this widget forwards the logged-in user token to a service hosted under the `contoso.com` domain>

![Widget screenshot](image.png)

<widget description>

The ListOfApisModel class is used to configure the behavior and appearance of the API list component. It allows you to control the layout, selection capabilities, visibility of API types, and the positioning of filters.

Key configuration properties include:

• layout: A string defining the list layout.
• allowSelection: A boolean indicating if operations can be selected.
• showApiType: A boolean to toggle the visibility of the API type.
• defaultGroupByTagToEnabled: A boolean that, when true, enables grouping by tags by default.
• detailsPageHyperlink: A HyperlinkModel object providing the link to the operation details page.
• filtersPosition: Determines where filters are positioned (using the FiltersPosition type).
• allowViewSwitching: A boolean indicating if the user is allowed to switch between different views.
• styles: An object of LocalStyles for applying widget-specific styling.

import { ListOfApisModel } from './path-to-model';

const model = new ListOfApisModel('grid');
model.allowSelection = true;
model.showApiType = true;
model.filtersPosition = FiltersPosition.Top; // Assuming FiltersPosition enum/type exists

The AccessToken class provides a static parse method to convert raw token strings into structured AccessToken objects. It supports three primary formats:

1. Bearer Tokens: Strings starting with Bearer . The expiration is extracted from the JWT payload.
2. SharedAccessSignature (SAS) Tokens: Strings starting with SharedAccessSignature or raw SAS strings. These include a user ID and an expiration timestamp.
3. Extended SAS Tokens: Strings containing the token="..." pattern.

If the token format is unrecognized or invalid, the method throws an error.

import { AccessToken } from './path-to-file';

// Parsing a Bearer token
const bearerToken = AccessToken.parse('Bearer eyJhbGci...');

// Parsing a SharedAccessSignature token
const sasToken = AccessToken.parse('SharedAccessSignature user123&202512312359&...');

// Parsing an extended SAS token
const extendedSas = AccessToken.parse('token="user123&202512312359&..."');