Promoting an API to the Next Environment

Learn about promoting an API to the next environment.

API Platform Version: 8.4 and later

Table of Contents

  1. What is the promotion feature?
  2. How do I know if the promotion feature is available for my API?
  3. How do I promote my API?
  4. Related Topics

What is the promotion feature?

The platform includes an add-on feature, Lifecycle Coordinator, which allows the Administrator to define a one-way topology that includes a chain of environments reflecting the development lifecycle. For example, the topology chain could be from Development to Testing to Staging to Production. Each environment is a separate installation of the developer portal.

Lifecycle Coordinator is a standalone user interface that's installed separately. The new feature also includes modifications to the developer portal user interface to allow the API Admin to promote an API to the next environment.

Lifecycle Coordinator

Within the Lifecycle Coordinator, the authorized user can:

  • Define and manage the environment topology (two or more environments in a unidirectional chain).
  • Set up processing rules that are executed when an API is promoted from one specific environment to the next. For example:
    • A rule might change the target URL host for the physical services when an API is promoted from Staging to Production.
    • A rule might deploy an API to different deployment zones in the Production environment depending on the PCI compatibility of the API.
    • A rule might define an approval required for the resource to be promoted to the next environment. If approval is required, the resource will be in a Promotion Pending state until the promotion is approved.

This feature includes a user permission specifically for the user who manages the Lifecycle Coordinator.

For more detailed information about the Lifecycle Coordinator feature, refer to the Lifecycle Coordinator Promotion Guide.

Developer Portal

Within the developer portal user interface, the new feature allows the API Admin or Business Admin to promote an API from the current environment to the next step in the environment topology.

When the user in the developer portal promotes the API, the API is passed to the Lifecycle Coordinator. The next steps are governed by the process set up in the Lifecycle Coordinator. For example, if a manual approval is required, approval is requested. If processing rules are in place, the rules are applied to the data before it is promoted to the next environment. The status of the promotion request is reflected in the developer portal user interface; for example, Promoted or Promotion Pending.

Iterations

A resource can be promoted to the next lifecycle stage multiple times, each time being an iteration of the resource, to accommodate a development scenario where multiple changes are made before the API is fully mature and ready to move to the next stage.

For example, an API might be promoted from Development to Testing, and some errors found in Testing. It can then be updated in the Development environment and promoted to Testing again, possibly multiple times until it fully passes Testing and is ready to be promoted to the next lifecycle stage in the next environment.

In the Lifecycle Coordinator, each of these iterations is stored, for historical tracking and non-repudiation.

Deployment

In terms of deployment, the Lifecycle Coordinator can be co-located with any one of the tenants, or it can stand alone and communicate remotely with any of them.

Back to top

How do I know if the promotion feature is available for my API?

If the promotion feature is available for your API, you'll see extra sections in the developer portal, showing the current state of the API, as shown in the examples below.

API Overview page

You'll see an extra section to the right of your API Overview page, as shown below.

Note: In the example below, the Promotion feature is enabled for API Admins, so the Promote button is available. If you see the right pane, but you don't see the Promote button, the feature is available but disabled in the developer portal settings. See How do I promote my API?

Promotion feature for an API; Overview page

The extra section shows:

  • Current environment / status in current environment
  • Environment chain / status in each environment
  • Promote button
API Designer

You'll see additional information at the bottom of the API Designer page, as shown below.

Promotion feature for an API; API Designer page

Back to top

How do I promote my API?

When your API is ready to be promoted, just click the Promote button, as shown below.

Promotion feature with Promote button enabled

Notes:

  • If you promote the API, and then find you need to make further changes, you can just make the changes and then promote it again. You can promote your API from one environment to the next as many times as you need to. See Iterations above.
  • What happens to the API after you click the Promote button is determined by the workflow in place in the Promotion Coordinator. For example, if approval is required, the resource isn't actually promoted until approval is granted.

In some cases, you might see the promotion feature in the right pane, but there is no Promote button, as shown below:

Promotion feature with Promote button disabled

In this scenario, the promotion feature is available, but the API Admin cannot control the promotion process. This is controlled by the Site Admin in the site settings; see General API Settings: API Promotion. If you need help or have questions about your API promotion, contact a Site Admin for assistance.

Back to top