Search

Chapter 1. Overview of creating your Developer Portal for 3scale-managed APIs

download PDF

Your 3scale Developer Portal is the website that API consumers use to:

  • Sign up for access to your 3scale-managed, upstream API
  • Read documentation about how to use your upstream API

3scale provides a sample Developer Portal with features that most API providers want to implement in their Developer Portal. This native Developer Portal uses the sample Echo API to demonstrate the structure of a typical Developer Portal. After you explore the native Developer Portal, there are instructions for changing it so you can learn how to create your own Developer Portal.

There are no prerequisites for exploring and modifying the native Developer Portal. However, after you modify the native Developer Portal to create your own Developer Portal, you must also implement sign-in workflows and authentication before you open your Developer Portal to API consumers.

1.1. Touring the 3scale editing environment for creating your Developer Portal

Before you start to create your Developer Portal, explore the sample Echo API Developer Portal provided with 3scale. The Echo API Developer Portal is your starting point for creating your own Developer Portal. You do not create a Developer Portal from scratch. Instead, you modify the native Echo API Developer Portal to create a Developer Portal that has the look and feel that you want.

Procedure

  1. In the 3scale Admin Portal, expand the context selector at the top and click Audience.
  2. In the navigation tree on the left, expand Developer Portal and click Content. This displays the main editing environment for creating your Developer Portal:

    Developer Portal main editing environment

    Under Root, 3scale displays the Developer Portal resources hierarchy:

    1. Documentation, Homepage, and Show are the foundation pages for the Developer Portal. For each page, scroll down to see the HTML that defines the page content.
    2. Folders below those pages contain pages that pull your 3scale resources into the Developer Portal. For example, the Account folder contains pages for displaying and editing 3scale accounts that a 3scale administrator created in the Admin Portal. Use these pages as a starting point and modify them as needed.
    3. In the upper right, the New Page drop-down lets you add a page, layout, partial, section, file, or portlet. Select each one to see the information you provide to create one.
  3. With Developer Portal > Content selected, scroll down the resources hierarchy to almost the bottom until you see Layouts and click Main layout.
  4. Scroll back up to the top so that the Layout ‘Main Layout” heading is visible.

    After the internal title and system name, you can see that Liquid is enabled. Liquid is the framework that 3scale uses to display and process most of the data from the 3scale system. The code that defines page content contains Liquid markup as well as HTML. You can see this in the Draft tab, which contains the code for the main layout for Developer Portal pages.

  5. In the navigation tree on the left, below Developer Portal > Content, click each sub-category in turn to explore it: Drafts, Redirects, Groups, Logo, Feature Visibility, and ActiveDocs.
  6. In the navigation tree on the left, below Developer Portal, click Visit Portal, which is the last entry.

    A new browser tab displays the website for the development version of the 3scale-provided Echo API Developer Portal. You use this development version to view the 3scale native Developer Portal. You can then iteratively customize and view changes that you make to the native Developer Portal to create your own Developer Portal.

    You know that this is the development version of the Developer Portal because it has a dark gray panel on the right with Draft|Published at the top. The Draft view supports iterative/incremental improvements. When the Draft version looks and behaves the way you want it to, you can publish it.

    The panel on the right lists the elements that provide the content for the current page:

    1. Page Homepage
    2. Layout Main layout
    3. Partial Submenu
    4. Partial analytics
  7. Click Page Homepage. A new browser tab displays the Developer Portal editing environment with Page 'Homepage' open for editing.
  8. Go back to the development version of the Echo API Developer Portal and in the upper right, click SIGN IN, which displays the SIGN IN page that API consumers use to sign in to your Developer Portal.

    In the gray panel on the right, below the list of templates, is a username and a password that you can use to simulate signing in to your Developer Portal:

    1. In the SIGN IN page, in the USERNAME OR EMAIL field, enter John, which is the username listed in the gray panel on the right.
    2. In the PASSWORD field, enter 123456, which is the password listed in the gray panel.
    3. Click Sign In to display the Developer Portal as your API consumers would see it.

Next steps

Continue to explore the native Developer Portal as much as you want. When you are comfortable navigating the editing environment and the development version of the Echo API Developer Portal, follow the procedure for Modifying the 3scale native Developer Portal.

1.2. Modifying the 3scale native Developer Portal

After exploring the Echo API Developer Portal, make some changes to it before you start to create your own Developer Portal. These practice steps are helpful preparation for creating your Developer Portal.

This procedure replaces the sample 3scale Echo API landing page heading with a heading for the common Swagger Petstore API. It also shows you how to update your Developer Portal to display documentation for the Petstore API.

Procedure

  1. In the 3scale Admin Portal, expand the context selector at the top and click Audience.
  2. In the navigation tree on the left, expand Developer Portal and click Content.
  3. Under Root, click Homepage, which is the internal title of the Developer Portal landing page, and change the landing page heading that appears in the development version of your Developer Portal:

    1. In Page 'Homepage', scroll down to see the code that renders the landing page.
    2. In line 5, change

      <h1>Echo API</h1>

      to

      <h1>Petstore API</h1>
    3. At the bottom of the page, click Publish.
    4. In the navigation tree on the left, below Developer Portal, click Visit Portal to display the development version of your Developer Portal and see that the landing page heading is now Petstore API.
  4. Remain in the development version of your Developer Portal and click Documentation, which is in the top menu bar. The Developer Portal displays ActiveDocs for the Echo API.
  5. Return to the 3scale Admin Portal and select Developer Portal > ActiveDocs to see an entry for the Echo API. 3scale provides an OpenAPI document that defines the Echo API. 3scale uses this OpenAPI document to display ActiveDocs for the Echo API.
  6. Import an OpenAPI document that defines the Swagger Petstore API:

    1. Go to https://petstore.swagger.io/v2/swagger.json and copy the JSON content to your clipboard.
    2. Return to the 3scale Admin Portal with Developer Portal > ActiveDocs selected.
    3. On the ActiveDocs page, click Create a new spec.
    4. In the Name field, enter Petstore.
    5. Select Publish?.
    6. Click in the API JSON Spec window and paste the Swagger Petstore JSON content from your clipboard.
    7. Click Create Spec at the bottom of the page. 3scale displays ActiveDocs for the Petstore API.
    8. In the navigation tree on the left, under Developer Portal, click ActiveDocs. After Echo API, there is a second entry for Petstore.
  7. Display documentation for the Petstore API in your Developer Portal:

    1. In the navigation tree on the left, under Developer Portal, click Content.
    2. Under Root, click Documentation, which is the internal title of the Developer Portal documentation page.
    3. In Page 'Documentation', scroll down to see the code that renders the documentation landing page. Line 5 identifies the OpenAPI document for which your Developer Portal displays ActiveDocs. The default value of line 5 is:

      {% assign spec = provider.api_specs.first %}

      Default behavior is that your Developer Portal displays ActiveDocs for the first entry in the Developer Portal > ActiveDocs page, which is initially the Echo API. This figure highlights line 5:

      Developer Portal code for displaying ActiveDocs
    4. Modify line 5 to change provider.api_specs.first to have an index that identifies the second entry in the ActiveDocs page:

      {% assign spec = provider.api_specs[1] %}

      Default behavior is that your Developer Portal displays ActiveDocs for only one OpenAPI document. To display ActiveDocs for more than one OpenAPI document, you must modify the Documentation page beyond this simple change.

    5. At the bottom of the page, click Publish.
  8. In the navigation tree on the left, below Developer Portal, click Visit Portal to display the development version of your Developer Portal.
  9. In the top menu bar, click Documentation to see documentation for Swagger Petstore.

Next steps

Start creating your Developer Portal by changing the native Developer Portal pages so they display information about access to your 3scale-managed API and documentation for your API.

1.3. Descriptions of additional 3scale features for modifying the native Developer Portal

3scale provides many features for customizing the native Developer Portal to create your own Developer Portal.

During development of your Developer Portal, anyone who needs to view your Developer Portal must specify an access code. Keep this access code in place while API providers are performing the required tasks for opening your Developer Portal to access by API consumers The access code ensures that only you or anyone with this code can view your Developer Portal. The access code is in the Domains & Access page, which is available in the Admin Portal by selecting Audience > Developer Portal > Domains & Access.

The following list introduces some of the features for modifying the native Developer Portal:

  • In the Developer Portal > Content environment, the New Page drop-down in the upper right lets you add the following elements to your Developer Portal:

    • Page - basic unit of Developer Portal content.
    • Layout - a template that multiple pages can use.
    • Partial - content that can be reused in other partials, in layouts, and in pages.
    • Section - functionally equivalent to a directory. Create sections to organize Developer Portal content.
    • File - a resource that you want your Developer Portal to use such as a stylesheet, an image, or a script.
    • Portlet - external RSS feed, table of contents, or latest forum posts.
  • You can input code in HTML, Markdown, or Textile. The code editor supports code highlighting, tabulations, line numbers, and other features.
  • You can preview the draft or published version of a page. Below a page’s text editor, clicking Preview displays the development version of the Developer Portal.

    The preview has a dark gray vertical bar on the right side. At the top of the dark gray bar, one of Draft | Published is highlighted to indicate which version you are viewing. This bar contains links to the editing environment for the following:

    • The page.
    • The layout that the page uses.
    • Any partials that the page uses. A partial is code that can be reused in many places on different pages.

    The Draft view of the development version of the Developer Portal supports iterative/incremental improvements. When the Draft version looks and behaves correctly, you can publish it. When the access code is in place, publishing a page means that you can view what an API consumer would see if your Developer Portal was live. When the access code is no longer in place, publishing a page updates that page in your live Developer Portal.

  • The filter field lets you search for resources in your Developer Portal environment. 3scale displays only the elements that you are searching for, which makes it easier to find just what you want to work on. The filter field is just below the icons:

    Developer Portal filter field
  • The Developer Portal > Redirects page lets you set up redirects from one Developer Portal URL to another. For example, if you deprecate a page that you created, you can redirect requests to the new page.
  • Placeholders are editable fields. For example, the Developer Portal > Content > Login > New page has several placeholders:

    <input id="session_username" name="username" tabindex="1"
      autofocus="autofocus" type="text"
      placeholder="Authenticate with your email"
      class="form-control">
    ...
    <input id="session_password" name="password" tabindex="2"
      type="password"
      placeholder="…and password"
      class="form-control">

    This code generates the following fields in your Developer Portal:

    Developer Portal placeholder field

    You can update the placeholder text and publish it to see the update in your Developer Portal. For example, you can change Authenticate with your email to Authenticate email. After you publish the page, you can see the updated prompt in your Developer Portal, for example:

    Developer Portal updated placeholder field

1.4. How 3scale layouts and partials reuse Developer Portal content

In the Developer Portal > Content environment, when you scroll down in the resource hierarchy you can see headings for Layouts and Partials. Layouts and partials let you reuse content in your Developer Portal:

  • A layout defines the basic structure for a page and functions as a page template. Every page that uses a particular layout contains the content that the layout defines. As you can see in the resource hierarchy under Layouts, your native Developer Portal provides an Error layout and a Main layout. You can modify the code for these layouts and you can create layouts.
  • A partial defines code that you use in more than one place in your Developer Portal. For example, a partial can define the footer in all layouts or the sidebar on multiple pages. You can use a partial in a page, a layout, another partial, or an email template. In the resource hierarchy, under Partials, you can see the partials that the native Developer Portal provides. There are partials for gathering analytics, subscribing to application plans, displaying submenus, and more. Again, you can modify these partials and you can create partials.

    In a page, layout, partial, or email template, to use a partial, you specify an include command with the name of the partial. For example, to use the submenu partial, you would specify

    {% include “submenu” %}

Layouts and partials have draft and published states as well as a version history. For example, you can save a draft, publish it, and revert to the last published version.

To learn about editing and writing code for layouts and partials, see the 3scale Liquid Reference.

1.5. Adding images and other assets to your Developer Portal for 3scale-managed APIs

Typically, you want to use your own images, files, or other assets to customize the native Developer Portal. To do this, add the file to the Developer Portal content library, make a note of its path in this environment, and then in code you add a link to the location of the file in the content library.

Prerequisites

  • Access to the image, file, or other asset that you want to use in your Developer Portal

Procedure

  1. Add your asset to the Developer Portal content library:

    1. In the Developer Portal > Content environment, in the upper right, expand New Page and select New File.
    2. Under Upload File, click in the Section field to display a list of the directories in which you can store the asset you are adding and click the appropriate directory to select it. For example, you might select |- images.
    3. Optional. In the Path field, enter any additional path levels that are useful for you.
    4. Select Downloadable.
    5. Click Choose File, navigate to the file you want to add, select it and click Open.
    6. Optional. In the Tag list field, enter a Liquid tag that you want to use to include this new content in code, for example, you might enter my-logo.
    7. Click Create File to add your asset to the Developer Portal content library.
  2. Make a note of the path to the asset you added. For example, if you added the MyLogo.png image to the images section, the path would be /images/MyLogo.png.
  3. To use the asset in code, insert an HTML <a> element. For example:

    <a href="/images/MyLogo.png"/>

    Alternatively, if you added a Liquid tag to your asset, you can use the asset in code by specifying the tag, for example:

    {% my-logo %}

1.6. Considerations for customizing the native Developer Portal for 3scale-managed APIs

Before you start customizing the native Developer Portal to create your own Developer Portal, you should have a plan for its basic elements, reusable content, page hierarchy, page headers and footers, and branding.

  • Basic Developer Portal elements - The plan for your Developer Portal should include:

    • Site map: Skeleton of how your portal is organized.
    • Top menu bar: Navigation that is repeated on each page.
    • Side menu bars: Access to individual pages in each section.
    • Page layout guidelines: For a consistent look and feel.
    • Reusable content - Layouts and partials ensure consistency in your Developer Portal. Create them before you start creating pages.
  • Page hierarchy - Beginning at the root level in your site map, create a section for each of your top menu items.

    Next, create the pages needed for each top menu item. When you create a page, be sure to associate it with the correct section. This creates a consistent structure for URL paths in your Developer Portal. To code a page with a markup language such as Textile or Markdown, expand the page’s ADVANCED OPTIONS. The Handler field identifies the markup language.

  • Page headers and footers - Repetitive page elements are typically defined in partials. When you have only a few layouts, you might prefer to define headers and footers directly in your layouts rather than in partials.
  • Branding - The default native Developer Portal stylesheet, default.css, is large and complex. Rather than extending this stylesheet, create your own stylesheet with customizations that overwrite the defaults.

    You can create a new stylesheet in the same way you create a page. Choose the css section and an appropriate MIME content type in the advanced page settings. Then in your layouts, after the link to default.css, add a link to your custom stylesheet. For example, if you create my-custom.css, you would insert:

    <link rel="stylesheet" href="/css/my-custom.css" />
  • Built-in features that you cannot modify include:

    • Pagination
    • Message menu
    • Forums - You can change only the layout.
    • Payment - Only a few text fields in these pages are editable.

1.7. Requirements for allowing access to your Developer Portal for 3scale-managed APIs

Before you can give API consumers access to your Developer Portal, API providers must perform the following tasks. These tasks can be performed concurrently:

  • Change the 3scale native Developer Portal to have the look and feel that you want:

    • Liquids: Developer Portal shows how to use Liquid markup to display and process 3scale system data related to your API. Liquid markup is the primary way to add logic to your Developer Portal pages.
    • Customizing the Developer Portal layout describes how to change the native Developer Portal to match your own branding. A standard cascading stylesheet (CSS) is available to provide an easy starting point for your customizations.
    • Change built-in pages explains how to use CSS and JavaScript to modify or hide an element in a system-generated page. All pages provided as part of the native Developer Portal are referred to as system-generated pages.

    A developer who is familiar with HTML, CSS, Liquid, and web sites in general can modify the native Echo API Developer Portal to create your Developer Portal web pages. This developer can create pages and modify code in system-generated pages to create whatever you want API consumers to see in your Developer Portal.

  • Define 3scale API products, backends, and application plans, and assign policies to products.

    A 3scale product is the 3scale resource that exposes your API to consumers. In your Developer Portal, API consumers read the documentation for a product and subscribe to use the API provided by a product. A 3scale product has the following characteristics:

    • Bundles one or more backends, which are internal 3scale APIs that you have created.
    • Has an application plan that defines the rules for using the product with regard to limits, pricing, and available features.
    • Has an APIcast gateway configuration for how the gateway should process API consumer calls before sending them to your API. Policies that you add to a product change the default APIcast gateway behavior.

    See the Admin Portal Guide.

  • Import the OpenAPI document that defines and documents your 3scale-managed API.

    The foundation for your Developer Portal is an OpenAPI document that defines your API. When you import an OpenAPI document into 3scale, 3scale creates or updates ActiveDocs so you immediately have functional documentation for your API. In your Developer Portal, API consumers use this documentation to explore, test, and integrate with your API.

    For each operation defined in an OpenAPI document, importing the document causes 3scale to create a method and a mapping rule. Methods and mapping rules help enforce the limits and rules for API consumer access to your API.

    The 3scale guide, Providing APIs in the Developer Portal contains information and procedures for working with 3scale and OpenAPI documents. In particular, see How to write an OpenAPI document for use as a 3scale specification and Adding ActiveDocs to 3scale.

  • Configure the workflow for how an API consumer signs up for access to your 3scale-managed API.

    Signup workflows are a critical aspect of API consumer experience with your Developer Portal. The workflow can range from self-service to total control over who gains access to what. Accounts, services, and application plans offer multiple levels of granularity. At each level, you control whether there is an approval gate that you operate and whether the API consumer is required to make any choices.

    For maximum automation and self-service, you can remove all approval steps and enable all possible default plans. Immediately after signup, your Developer Portal can issue a key that provides API consumer access to your Developer Portal.

    The native Developer Portal provides commonly used fields for user, account, and application signups. You might need to add custom fields to these typically used fields. For details, see Configuring signup flows and Custom signup form fields. Be sure to configure workflows before you customize email templates.

  • Implement authentication of API consumers.

    Authentication of API consumer access to your Developer Portal secures your Developer Portal resources and your APIs. You can use any of the following methods to authenticate access to your Developer Portal:

    See Developer Portal authentication.

  • Customize 3scale native templates for email communication between your Developer Portal and API consumers.

    Many different events require communication between your Developer Portal and API consumers including providing an account activation link upon signup, password recovery, service charges, change notifications, and many more. 3scale provides templates for each typical email type that a Developer Portal sends to API consumers.

    After you have defined signup workflows, customize the content of email messages. This lets you closely match the workflows that you set up for your Developer Portal.

    See Email templates and Liquids: Email templates.

  • Specify terms, conditions, and policies that API consumers must agree to for access to your 3scale-managed API.

    When you allow API consumers to sign up and call your API, you typically want them to agree to your terms, conditions and policies before you grant access. You can have different versions of terms and conditions, for example, for signup, for using particular applications, or for using particular services, if your Developer Portal provides more than one service.

    If you are charging for use of your API, you probably want agreement to your credit card policies.

    See Setting terms and conditions.

  • Set up API consumer billing and credit card gateways.

    The 3scale billing process runs daily. It creates invoices for each API consumer account that is subscribed to a paid service. An invoice can be in one of the following states: open, finalized, pending, unpaid, paid, failed, canceled. 3scale uses the payment gateway that you configure to process invoices.

    The 3scale billing process can run in a prepaid or postpaid mode. Billing in 3scale is based on the calendar month and there are special events that happen on the first day of the month.

    See Admin Portal Guide, Billing.

The last task you must perform before your Developer Portal goes live is to remove the access code. Do this only after authentication for access to your Developer Portal is in place and after you have thoroughly tested your Developer Portal to confirm that it is behaving as you want it to.

To delete the access code, display the Developer Portal > Content environment. In the lower right, click Open your Portal to the world and confirm this action.

1.8. Optional steps for customizing your Developer Portal for 3scale-managed APIs

Beyond the requirements for opening your Developer Portal to API consumers, you might want to do the following:

  • Provide multiple APIs in your Developer Portal.

    Each OpenAPI document that you import into 3scale provides the foundation for a separate API offering, also referred to as a separate service. To configure your Developer Portal to provide multiple services, the main task is to create a page that lets an API consumer choose which service or services to subscribe to.

    For details, see Multi-service signup.

  • Mark Developer Portal pages or portions of pages as visible to only the API consumers you specify.

    You might need to have parts of your Developer Portal accessible to only a specific group of API consumers. You can restrict access to a page, part of a page, or a menu selection, which typically corresponds to a section.

    A handy way to restrict access to a section is to map each section to a logical group of API consumers. For example, suppose there are API consumers who are partners. You can create a group called partners and give only that group access to a particular section.

    You can provide access to restricted content to API consumers based on a change in state. For example, when an API consumer upgrades to a new application plan additional pages might automatically become visible to that API consumer.

    Another way to restrict access is to require an API consumer to log in to view certain content.

    For details, see Restricted content.

  • Implement webhooks.

    Webhooks let you tightly integrate 3scale with your back-office workflow. When specified events happen in the 3scale system, your back-office applications can be notified with a webhook message. Your application can then use that data, for example, information about a new account, to populate your Developer Portal.

    For details, see Webhooks.

1.9. Updating Developer Portals used in 3scale releases earlier than 2.8

In 3scale 2.8, external assets were moved from Content Delivery Networks (CDN) to the 3scale codebase. Consequently, starting with 3scale 2.8, the native Developer Portal is created by using the cdn_asset Liquid tag. If you are upgrading from a 3scale release that is earlier than 2.8, you must update your Developer Portal to use the new assets with the cdn_asset tag. With the use of this tag, there is no longer a dependency for downloading assets from external websites.

Prerequisites

  • An installation of 3scale 2.8 or later
  • A Developer Portal that you created with 3scale 2.7 or earlier

Procedure

  1. In the 3scale Admin Portal, with Audience > Developer Portal > Content selected, at the top of the resource hierarchy, click </> to display only layouts:

    Display only layouts
  2. Under Layouts, click Main layout.
  3. In the code editor for the main layout, on or around line 17, replace this line:

    {{ '//netdna.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.css' | stylesheet_link_tag }}

    with this line:

    {% cdn_asset /font-awesome/4.3.0/css/font-awesome.css %}
  4. On or around line 19, replace this line:

    {{ '//ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js' | javascript_include_tag }}

    with this line:

    {% cdn_asset /jquery/1.7.1/jquery.min.js %}
  5. Scroll down and click Publish.
  6. Go to the top of the resource hierarchy and click Partials to display partials.
  7. Under Partials, click stats/chart.
  8. In the code editor for stats/chart, on or around line 3, replace this line:

    {{ '//ajax.googleapis.com/ajax/libs/jqueryui/1.11.4/themes/ui-lightness/jquery-ui.css' | stylesheet_link_tag }}

    with this line:

    {% cdn_asset /jquery-ui/1.11.4/jquery-ui.css %}
  9. Scroll down and click Publish.
  10. Optional. If you created files based on the main layout or based on the stats/chart partial, you must similarly update those files.

Additional resources

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.