Cloud-native API Administration with Red Hat 3scale API Management
Abstract
| Goal | Configure Developer Portals for external consumption and documentation of your APIs. |
| Objectives |
|
| Sections |
|
After completing this section, you should be able to create and configure a developer portal for API consumption.
The Developer Portal aims to engage API users, and turn developers into customers. Developer Portal is a configurable portal where API developers can create application credentials, subscribe to application plans, read about billing plans, and read the documentation for your APIs. This means that your users can self-provision access to APIs managed by 3scale API Management.
You can create new content and change the look and feel of the Developer Portal by using the 3scale API Manager Admin Portal. This means that you can tailor the Developer Portal to use your branding and content.
 |
To access the Developer Portal customization options, select from the drop-down menu, and then click . The following list describes sections in the Developer Portal menu:
- Content
Contains Developer Portal content that you can create and manage, such as HTML, CSS, and JavaScript files.
- Drafts
Lists the content with the
Draftstatus.- Redirects
Create and manage redirects from one portal URL to another, for example when you deprecate a page on your Developer Portal.
- Groups
Create and manage user groups. You can use groups to limit access to content sections.
- Logo
Upload a Developer Portal logo.
- Feature Visibility
Toggle advanced features of your Developer Portal, such as webhooks, or identity and access management (IAM) tools.
- ActiveDocs
Contains the OpenAPI documentation for your APIs.
In the section, you can create and edit the following elements:
- Page
A page typically contains liquid-templated HTML content to be shown when the users access a given URL. You can also create pages in Markdown or Textile.
- Section
A section is a logical grouping of pages that you can use to create hierarchical page structures. For example, you can group all pages accessible by users that belong to a particular group under a common URL subpath.
- Layout
Layouts define a common structure that is often used by multiple pages. For example, you might reference common CSS and JavaScript files in one layout and use the layout for all your pages.
- Partial
Partials are reusable elements that you can embed in pages. Layouts and partials are distinct elements. Typically, layouts define the structure of pages whereas partials are contained in Pages.
For example, a layout defines a common header and footer for your pages, while a partial defines a disclaimer which you add to a subset of your pages.
- File
Files are content uploaded to the Developer Portal that you want to reference or display, such as an image later referenced in a page.
- Portlets
Portlets gather and show information from external sources. You can use the following portlets:
- External RSS Feed
Fetches the RSS feed from an external source. For example, you might decouple announcing changes to the API by moving it to an RSS feed. This means that you can add this feed to a page such that there is no need to update the page every time an announcement is made.
- Table of Contents
Generates a list of links for the pages in a given section.
- Latest Forum Posts
Displays the latest posts in the Community Forum.
You can create new content by selecting the option in the section.
To add content to the portal, click . To create another kind of content, use the drop-down menu of that button to select the desired content type.
For example in the editor, provide the following data:
- Title
Name of the page.
- Section
Section to file the page under.
- Path
URL path relative to the Developer Portal that shows the page.
Note
The page called Homepage has a special path (/) that does not include the file name.
This is because homepage is implemented as an index.html file, which is automatically served if no file name is provided.
- Layout
Layout to define the general structure of the page.
After you provide the details, use the content box below to write the content of the page. 3scale API Management supports content written in HTML, Markdown and Textile.
Use the button to validate the results and view how this new content is presented to the client. You can view the content in a preview page with a preview toolbar. This toolbar shows information about the page and the templates used to render the page. You can also switch between publishing modes.
You can limit access to some parts of the Developer Portal by creating restricted sections. These sections can contain content that is specific for logical groups of users. Users that are associated with that logical group can access the restricted section.
For example, consider that there is a group of developers called partners. You can create a new section with the following details:
Then, you create a page in the private section, for example with the following parameters:
Table 5.2. Page data
| Field | Value |
|---|---|
| Title |
How it works
|
| Section |
Partner Pages
|
| Path |
/howitworks
|
| Layout |
Main
|
| Content |
<h1>How restricted sections work</h1>
|
After you create a restricted section, create a group and give it access to that section.
Navigate to and click .
Set the name of the group to Partner's Group, mark the Partner pages section as allowed, and click .
Finally, add users to this group to grant access to pages that belong to the Partner pages section.
Navigate to , then click , and select a user.
In the account page, click and select the Partner's Group.
This means that the user has access to the PORTAL-URL/howitworks
References
For more information, refer to the Creating the Developer Portal guide at https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.11/html-single/creating_the_developer_portal/index
