| title | description | services | documentationcenter | author | manager | editor | ms.service | ms.workload | ms.tgt_pltfrm | ms.topic | ms.date | ms.author |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
Access and customize the managed developer portal - Azure API Management | Microsoft Docs |
Learn how to use the managed version of the developer portal in API Management. |
api-management |
API Management |
mikebudzynski |
cfowler |
api-management |
mobile |
na |
article |
03/05/2020 |
apimpm |
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, and request access.
In this tutorial, you learn how to:
[!div class="checklist"]
- Access the managed version of the developer portal
- Navigate its administrative interface
- Customize the content
- Publish the changes
- View the published portal
You can find more details on the developer portal in the Azure API Management developer portal overview.
- Complete the following quickstart: Create an Azure API Management instance
- Import and publish an Azure API Management instance. For more information, see Import and publish
[!INCLUDE premium-dev-standard-basic.md]
Follow the steps below to access the managed version of the portal.
- Go to your API Management service instance in the Azure portal.
- Click on the Developer portal button in the top navigation bar. A new browser tab with an administrative version of the portal will open.
If you're accessing the portal for the first time, the default content will be automatically provisioned in the background. Default content has been designed to showcase portal's capabilities and minimize the amount of customizations needed to personalize your portal. You can learn more about what is included in the portal content in the Azure API Management developer portal overview.
You can customize the content of the portal with the visual editor. The menu sections on the left let you create or modify pages, media, layouts, menus, styles, or website settings. The menu items on the bottom let you switch between viewports (for example, mobile or desktop), view the elements of the portal visible to authenticated or anonymous users, or save or undo actions.
You can add rows to a page by clicking on a blue icon with a plus sign. Widgets (for example, text, images, or APIs list) can be added by pressing a grey icon with a plus sign. You can rearrange items in a page with the drag-and-drop interaction.
Layouts define how pages are displayed. For example, in the default content, there are two layouts - one applies to the home page, and the other to all remaining pages.
A layout gets applied to a page by matching its URL template to the page's URL. For example, layout with a URL template of /wiki/* will be applied to every page with the /wiki/ segment in the URL: /wiki/getting-started, /wiki/styles, etc.
In the image above, content belonging to the layout is marked in blue, while the page is marked in red. The menu sections are marked respectively.
Styling guide is a panel created with designers in mind. It allows for overseeing and styling all the visual elements in your portal. The styling is hierarchical - many elements inherit properties from other elements. For example, button elements use colors for text and background. To change a button's color, you need to change the original color variant.
To edit a variant, click on it and select the pencil icon that appears on top of it. Once you make the changes in the pop-up window, close it.
Whenever you make a change in the portal, you need to save it manually by pressing the Save button in the menu at the bottom. When you save your changes, the modified content is automatically uploaded to your API Management service.
Before you make your portal available to the visitors, you should personalize the automatically generated content. Recommended changes include the layouts, styles, and the content of the home page.
Note
Due to integration considerations, the following pages can't be removed or moved under a different URL: /404, /500, /captcha, /change-password, /config.json, /confirm/invitation, /confirm-v2/identities/basic/signup, /confirm-v2/password, /internal-status-0123456789abcdef, /publish, /signin, /signin-sso, /signup.
The default Home page is filled with dummy content. You can either remove the whole sections with the content or keep the structure and adjust the elements one by one. Replace the generated text and images with your own and make sure the links point to desired locations.
Replace the automatically generated logo in the navigation bar with your own image.
Although you don't need to adjust any styles, you may consider adjusting particular elements. For example, change the primary color to match your brand's color.
In the video below we demonstrate how to edit the content of the portal, customize the website's look, and publish the changes.
To make your portal and its latest changes available to visitors, you need to publish it.
- Make sure you saved your changes by clicking on the Save icon.
- Click on Publish website in the Operations section of the menu. This operation may take a few minutes.
Note
The portal needs to be republished after API Management service configuration changes, such as assigning a custom domain, updating the identity providers, setting delegation, specifying sign-in and product terms, and more.
After you publish the portal, you can access it at the same URL as the administrative panel, for example https://contoso-api.developer.azure-api.net. View it in a separate browser session (incognito / private browsing mode) as an external visitor.
You need to enable CORS (cross-origin resource sharing) on your APIs to let the visitors of your portal test the APIs through the built-in interactive console. Refer to this documentation article for more details.
Learn more about the developer portal: