API management Developer portal Customization | API Management custom developer portal | Paperbits api management developer portal

Sanjeevi SubramaniSanjeevi Subramani -
0
{tocify} $title={Table of Contents}

Overview of the developer portal

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.

As introduced in this article, you can customize and extend the developer portal for your specific scenarios.

Customization and styling of the managed portal

Your API Management service includes a built-in, always up-to-date, managed developer portal. You can access it from the Azure portal interface.

  • Customize and style the managed portal through the built-in, drag-and-drop visual editor:
  • Use the visual editor to modify pages, media, layouts, menus, styles, or website settings.
  • Take advantage of built-in widgets to add text, images, buttons, and other objects that the portal supports out-of-the-box.

Options to extend portal functionality

In some cases, you might need functionality beyond the customization and styling options provided in the managed developer portal. If you need to implement custom logic, which isn't supported out-of-the-box, you have several options:

  • Add custom HTML directly through a developer portal widget designed for small customizations - for example, add HTML for a form or to embed a video player. The custom code is rendered in an inline frame (iframe).
  • Create and upload a custom widget to develop and add more complex custom portal features.
  • Self-host the portal, only if you need to make modifications to the core of the developer portal codebase. This option requires advanced configuration. Azure Support's assistance is limited only to the basic setup of self-hosted portals.

Tutorial: Access and customize the developer portal

The 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:

  • 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.


Access the portal as an administrator


Follow the steps below to access the managed version of the portal.

  • In the Azure portal, navigate to your API Management instance.
  • Select the Developer portal button in the top navigation bar. A new browser tab with an administrative version of the portal will open.

Developer portal architectural concepts

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

Code

Code is maintained in the API Management developer portal GitHub repository and includes:

  • Widgets - 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 - specify how widgets can be styled
  • Engine - which generates static webpages from portal content and is written in JavaScript
  • Visual editor - allows for in-browser customization and authoring experience

Content

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, such as fonts, colors, borders
  • Settings - configurations such as favicon, website metadata
  • Portal content, except for media, is expressed as JSON documents.
  • API Management content includes entities such as APIs, Operations, Products, Subscriptions.

Understand the portal's administrative interface

Default content

If you're accessing the portal for the first time, the default content is automatically provisioned in the background. Default content has been designed to showcase the portal's capabilities and minimize the 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.

Visual editor

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.
    • 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.
    • Rearrange items in a page with the drag-and-drop interaction.

Layouts and pages

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, a 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 preceding image, content belonging to the layout is marked in blue, while the page is marked in red. The menu sections are marked respectively.

Styling guide

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, select it and select the pencil icon that appears on top of it. After you make the changes in the pop-up window, close it.

Save button

Whenever you make a change in the portal, you need to save it manually by selecting the Save button in the menu at the bottom, or press [Ctrl]+[S]. When you save your changes, the modified content is automatically uploaded to your API Management service.

Customize the portal's content

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.

Home page

The default Home page is filled with placeholder content. You can either remove entire sections containing this 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. You can edit the structure and content of the home page by:

  • Dragging and dropping page elements to the desired placement on the site.
  • Selecting text and heading elements to edit and format content.
  • Verifying your buttons point to the right locations.
  • Layouts
  • Replace the automatically generated logo in the navigation bar with your own image.

  • In the developer portal, select the default Contoso logo in the top left of the navigation bar.
  • Select the Edit icon.
  • Under the Main section, select Source.
  • In the Media pop-up, either select:
  • An image already uploaded in your library, or
  • Upload file to upload a new image file to use, or
  • Select None to forego using a logo.
  • The logo updates in real-time.
  • Select outside the pop-up windows to exit the media library.
  • Click Save.

Styling

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. You can do this in two ways:

Overall site style

  • In the developer portal, select the Styles icon from the left tool bar.
  • Under the Colors section, select the color style item you want to edit.
  • Click the Edit icon for that style item.
  • Select the color from the color-picker, or enter the hex color code.
  • Add and name another color item by clicking Add color.
  • Click Save.
  • Container style
  • On the main page of the developer portal, select the container background.
  • Click the Edit icon.
  • In the pop-up, set:
  • The background to clear, an image, a specific color, or a gradient.
  • The container size, margin, and padding.
  • Container position and height.
  • Select outside the pop-up windows to exit the container settings.
  • Click Save.

Customization example

In the following video, we demonstrate how to edit the content of the portal, customize the website's look, and publish the changes.


Publish the portal

To make your portal and its latest changes available to visitors, you need to publish it. You can publish the portal within the portal's administrative interface or from the Azure portal.

Publish from the administrative interface

  • Make sure you saved your changes by selecting the Save icon.
  • In the Operations section of the menu, select Publish website. This operation may take a few minutes.
  • Publish portal

Publish from the Azure portal

  • In the Azure portal, navigate to your API Management instance.
  • In the left menu, under Developer portal, select Portal overview.
  • In the Portal overview window, select Publish.


 Note

The portal needs to be republished after API Management service configuration changes. For example, republish the portal after assigning a custom domain, updating the identity providers, setting delegation, or specifying sign-in and product terms.


Visit the published portal

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 (using incognito or private browsing mode) as an external visitor.


Apply the CORS policy on APIs

To let the visitors of your portal test the APIs through the built-in interactive console, enable CORS (cross-origin resource sharing) on your APIs. For details, see the Azure API Management developer portal FAQ.

For Detailed article


You can go through this video tutorial:




Tags:

إرسال تعليق

أحدث أقدم

postad

post ad 2