Azure Documentation

Get Started with Azure API Management Developer Portal

Updated: October 26, 2023   |   By: Microsoft Azure Docs

The Azure API Management developer portal is a fully managed website that automatically generates and deploys an interactive developer portal for your APIs. It serves as a single entry point for developers to discover, learn, and consume your APIs. This tutorial will guide you through the essential steps to get started with and customize your developer portal.

What is the Developer Portal?

The developer portal offers a rich set of features to enhance the API developer experience:

  • API Discovery: Browse and search for available APIs.
  • API Documentation: Access detailed documentation, including OpenAPI (Swagger) specifications, for each API.
  • Interactive Console: Test API endpoints directly from the portal.
  • Authentication: Developers can acquire subscription keys and manage their applications.
  • Analytics: Track API usage and performance.

Prerequisites

Before you begin, ensure you have:

  • An active Azure subscription.
  • An existing Azure API Management service instance. If you don't have one, you can create it via the Azure portal.

Accessing the Developer Portal

There are two main ways to access your developer portal:

  1. Azure Portal: Navigate to your API Management service instance in the Azure portal. Under the 'Developer portal' section, you'll find links to the 'Developer portal' and 'Management Portal'.
  2. Direct URL: If you have configured a custom domain for your developer portal, you can access it directly via that URL. Otherwise, it will be available at a default URL provided by Azure.

Configuring and Customizing the Portal

The developer portal is highly configurable. You can customize its appearance, content, and behavior to align with your branding and needs.

Basic Customization

From the API Management Management Portal, navigate to 'Developer portal' -> 'Content'. Here you can:

  • Branding: Upload your company logo and choose color schemes to match your brand identity.
  • Pages: Edit existing pages (e.g., Home, APIs, Products) or create new ones to add custom content.
  • Navigation: Customize the menu structure to organize your portal content effectively.

Advanced Customization (for Self-Hosted Portals)

For more granular control, you can self-host the developer portal on your own infrastructure. This involves:

  1. Cloning the Repository: Clone the official Azure API Management Developer Portal GitHub repository.
  2. Development Environment: Set up a local development environment using Node.js and npm.
  3. Configuration: Configure the portal to connect to your API Management instance by providing your service's details and access tokens.
  4. Deployment: Deploy the customized portal to your chosen hosting platform (e.g., Azure App Service, static web hosting).

Key Features to Explore

Once your portal is set up, encourage your developers to explore these key areas:

1
API Catalog

This section lists all APIs that have been published and made available through the developer portal. Developers can filter and search for APIs based on keywords, tags, or categories.

2
API Details Page

Clicking on an API in the catalog leads to its detail page. Here, developers find comprehensive information:

  • A brief description of the API.
  • The OpenAPI (Swagger) specification.
  • Interactive documentation explaining endpoints, parameters, and responses.
  • The ability to try out the API directly using the interactive console.

3
Applications and Subscription Keys

Developers need to create an 'Application' to group APIs and obtain a subscription key. This key is used to authenticate their requests to your APIs. The portal provides a clear interface for managing applications and keys.

4
Custom Pages

Leverage custom pages to provide tutorials, FAQs, support contact information, or links to external resources. This adds value beyond just API documentation.

Best Practices

  • Keep Documentation Updated: Ensure your API documentation is always current with your API changes.
  • Provide Clear Examples: Include practical code examples in various programming languages.
  • Use Clear Navigation: Organize your portal logically so developers can easily find what they need.
  • Gather Feedback: Include a mechanism for developers to provide feedback on the portal and APIs.

By effectively utilizing the Azure API Management developer portal, you can significantly improve the adoption and success of your APIs by providing a seamless and intuitive experience for your developers.