Azure API Management developer portal overview

Developer portal is an automatically generated, fully customizable website with the documentation of your APIs. It is where API consumers can discover your APIs, learn how to use them, request access, and try them out.

This article describes the differences between self-hosted and managed versions of the developer portal in API Management. It also explains its architecture and provides answers to frequently asked questions.

Warning

The new developer portal is currently being rolled out to API Management services. If your service is newly created or is a Developer tier service, you should already have the latest version. Otherwise, you might experience problems (for example, with the publishing functionality). The feature rollout is expected to complete by Friday November 22nd, 2019.

Learn how to migrate from the preview version to the generally available version of the developer portal.

API Management developer portal

Availability

Important

This feature is available in the Premium, Standard, Basic and Developer tiers of API Management.

Managed and self-hosted versions

You can build your developer portal in two ways:

  • Managed version - by editing and customizing the portal, which is built into your API Management instance and is accessible through the URL <your-api-management-instance-name>.developer.azure-api.net. Refer to this documentation article to learn how to access and customize the managed portal.
  • Self-hosted version - by deploying and self-hosting your portal outside of an API Management instance. This approach allows you to edit the portal's codebase and extend the provided core functionality. You also need to upgrade the portal to the latest version yourself. For details and instructions, refer to the GitHub repository with the source code of the portal. The tutorial for the managed version walks through the portal's administrative panel, which is also featured in the self-hosted version.

Portal architectural concepts

The portal components can be logically divided into two categories: code and content.

Code is maintained in the GitHub repository and includes:

  • Widgets - which represent visual elements and combine HTML, JavaScript, styling ability, settings, and content mapping. Examples are an image, a text paragraph, a form, a list of APIs etc.
  • Styling definitions - which specify how widgets can be styled
  • Engine - which generates static webpages from portal content and is written in JavaScript
  • Visual editor - which allows for in-browser customization and authoring experience

Content is divided into two subcategories: portal content and API Management content.

Portal content is specific to the portal and includes:

  • Pages - for example, landing page, API tutorials, blog posts
  • Media - images, animations, and other file-based content
  • Layouts - templates, which are matched against a URL and define how pages are displayed
  • Styles - values for styling definitions, e.g. fonts, colors, borders
  • Settings - configuration, e.g. favicon, website metadata

Portal content, except for media, is expressed as JSON documents.

API Management content includes entities such as APIs, Operations, Products, Subscriptions.

The portal is based on an adapted fork of the Paperbits framework. The original Paperbits functionality has been extended to provide API Management-specific widgets (e.g., a list of APIs, a list of Products) and a connector to API Management service for saving and retrieving content.

Frequently asked questions

In this section, we answer common questions about the new developer portal, which are of general nature. For questions specific to the self-hosted version, refer to the wiki section of the GitHub repository.

How can I migrate from the preview version of the portal?

By using the preview version of the developer portal, you provisioned the preview content in your API Management service. The default content has been significantly modified in the generally available version for better user experience. It also includes new widgets.

If you're using the managed version, reset the content of the portal by clicking Reset content in the Operations menu section. Confirming this operation will remove all the content of the portal and provision the new default content. The portal's engine has been automatically updated in your API Management service.

Reset portal content

If you're using the self-hosted version, use the scripts/cleanup.bat and scripts/generate.bat from the GitHub repository to remove existing content and provision new content. Make sure you upgrade your portal's code to the latest release from the GitHub repository beforehand.

If you don't want to reset the content of the portal, you may consider using newly available widgets throughout your pages. Existing widgets have been automatically updated to the latest versions.

If your portal was provisioned after the general availability announcement, it should already feature the new default content. No action is required from your side.

How can I migrate from the old developer portal to the new developer portal?

Portals are incompatible and you need to migrate the content manually.

Does the new portal have all the features of the old portal?

The new developer portal doesn't support Applications and Issues. If you have used Issues in the old portal and need them in the new one, post a comment in a dedicated GitHub issue.

Has the old portal been deprecated?

The old developer and publisher portals are now legacy features - they will be receiving security updates only. New features will be implemented in the new developer portal only.

Deprecation of the legacy portals will be announced separately. If you have questions, concerns, or comments, raise them in a dedicated GitHub issue.

How can I automate portal deployments?

You can programmatically access and manage the developer portal's content through the REST API, regardless if you're using a managed or a self-hosted version.

The API is documented in the GitHub repository's wiki section. It can also be used for automating migrations of portal content between environments - for example from a test environment to the production environment. You can learn more about this process in this documentation article on GitHub.

Does the portal support Azure Resource Manager templates and/or is it compatible with API Management DevOps Resource Kit?

No.

Do I need to enable additional VNET connectivity for the managed portal dependencies?

No.

I'm getting a CORS error when using the interactive console. What should I do?

The interactive console makes a client-side API request from the browser. You can resolve the CORS problem by adding a CORS policy on your API(s). You can specify all the parameters manually or use wildcard * values. For example:

<cors>
    <allowed-origins>
        <origin>*</origin>
    </allowed-origins>
    <allowed-methods>
        <method>GET</method>
        <method>POST</method>
        <method>PUT</method>
        <method>DELETE</method>
        <method>HEAD</method>
        <method>OPTIONS</method>
        <method>PATCH</method>
        <method>TRACE</method>
    </allowed-methods>
    <allowed-headers>
        <header>*</header>
    </allowed-headers>
    <expose-headers>
        <header>*</header>
    </expose-headers>
</cors>

Note

If you apply the CORS policy in the Product scope, instead of the API(s) scope, and your API uses subscription key authentication through a header, your console won't work.

The browser automatically issues an OPTIONS HTTP request, which doesn’t contain a header with the subscription key. Because of the missing subscription key, API Management can't associate the OPTIONS call with a Product, so it can’t apply the CORS policy.

As a workaround you can pass the subscription key in a query parameter.

Next steps

Learn more about the new developer portal:

Browse other resources: