Promoting an API to the Next Environment

Learn about promoting an API to the next environment.

Table of Contents

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 Community Manager developer portal.

Lifecycle Coordinator is a standalone user interface that's installed separately. This feature also includes modifications to the Community Manager 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 app or 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 app or API is promoted from Staging to Production.
    • A rule might deploy an app or API to different deployment zones in the Production environment depending on the PCI compatibility of the resource.
    • 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.

Community Manager developer portal

Within the Community Manager 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 Community Manager developer portal promotes the app or API, it 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 Community Manager 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 it is fully mature and ready to move to the next stage.

For example, an app or 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.

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 Community Manager 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 Community Manager 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 (Hermosa theme).

Promotion feature for an API; API Designer page, Hermosa Theme

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.

I promoted my API to the next environment. What else do I need to do?

Once you've promoted your API to the next environment, there are a few steps you'll need to take to make sure that the API is fully set up in the new environment. If the deployment zone wasn't assigned automatically, you'll need to specify it, and make sure that the Community Manager developer portal's endpoint for the API is set up correctly.

To get your API ready for promotion, in the target environment

  1. Go to API > Implementations > choose implementation > in the Deployment section, click Edit.
  2. Make sure the correct deployment zone is enabled. If it isn't, choose the deployment zone and click Enable Zone.
  3. Edit the context path as needed. The Calculated Endpoint for the API is displayed.
  4. Click Save.

What are the different promotion states?

The basic lifecycle of an API goes from Not Promoted to Promoted in each environment. In some cases, approval of a promotion request might be required.

For details of the promotion states and their sequence, see What are the valid statuses and lifecycle for a promotion request? (Site Admin help).

What is promotion fanout?

The basic structure of an environment topology is linear; for example, from development to testing to production. However, in some cases a topology might include two or more environments at the same level. Perhaps there are two testing environments, for testing under different criteria sets; or there might be three production environments, each at a different global location.

When the topology includes more than one environment at the same level, this is called fanout. When an app or API is promoted from one environment to the next level, which includes two or more environments, the fanout behavior can be either of the following:

  • It is promoted simultaneously to all environments that are at the next level.
  • It is promoted to multiple target environments based on custom properties of the app or API. For example, asset-filters might be set up based on one or more custom properties

The fanout behavior is determined by the topology definition in Akana Lifecycle Manager.

In the Community Manager developer portal user interface, fanout is shown by indentation. In the example below, there is one development environment and one staging environment, and there are two production environments.

Promotion fanout

An example of promotion based on custom properties:

  1. In the topology definition, you could set up asset-filters based on a Boolean property called external, with external and internal filters defined based on that property.
  2. Different production environments for internal and external APIs.
  3. Assuming the environment prior to production is acceptance, you could define two promotion profiles on the acceptance environment: one that specifies the internal filter and points to the internal production environment, while the other specified the external filter and points to the external production environment.

With the above configuration, the APIs are effectively routed based on the value of the external property.