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

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

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

  

  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:

  

• 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” %}

Prerequisites

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

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

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

  • Username, email and password
  • GitHub
  • Auth0
  • Red Hat Single Sign-On (RH-SSO)

  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.

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

Prerequisites

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

Additional resources

• Liquid drops, tags, and filters in the 3scale Liquid Reference