Defaulting API Settings using Runtime Configurations

Learn how to use the Runtime Configurations feature to establish templates so that API implementation properties can be established and selectively applied based on custom property filters.

Note: As of the 2018.0.0 release, the behavior in this document can now be defined as part of the Promotion feature within the topology directly, using the Environment Configuration element. See Environment Configuration (Promotion Guide).

Lifecycle Coordinator Installation Sample Topologies

API Platform Version: 8.4.17 and later

Table of Contents

  1. Overview
  2. Creating a Runtime Configuration Asset
  3. Publishing a Runtime Configuration Asset
  4. Runtime Configuration: Example

Overview

The behavior described in this document is not part of Lifecycle Coordinator, but can be used to augment the capabilities of Lifecycle Coordinator to further tailor the configuration of APIs within each environment of a topology.

The intent of the Runtime Configuration feature is to allow templates for API implementation properties to be established and selectively applied based on custom property filters. This is accomplished through customization of the Lifecycle Manager library in which custom properties for a tenant are configured. This configuration requires a working knowledge of the Lifecycle Manager application and the Configuration Designer Tool.

As with the topology definition, it's best if Runtime Configuration assets are set up during the initial configuration of the environment. Changes to a Runtime Configuration do not retroactively affect pre-existing APIs unless those APIs are updated through the API Platform UI or subsequent promotions.

There are two ways to define runtime configuration:

Back to top

Creating a Runtime Configuration Asset

You can use the Lifecycle Manager user interface to create assets of type Runtime Configuration. The following image shows the Lifecycle Manager edit page for a Runtime Configuration asset:

Creating a Runtime Configuration asset

The following aspects of a Runtime Configuration asset determine its behavior when applied to an API implementation:

Owning Group

Groups within the Lifecycle Manager library reflect the Organizations of the associated tenant. The Owning Group chosen when creating a Runtime Configuration asset determines the organizational scope that the Runtime Configuration applies to.

For example, if the tenant organization has two child organizations A and B, a Runtime Configuration asset assigned to Group A is applicable to APIs in organization A but not to APIs in organization B. If you choose the tenant organization as the owning group, the Runtime Configuration is applicable to all APIs within the tenant.

Asset Filters

You can further scope the applicability of Runtime Configuration assets by using asset filters. Asset filters are defined in the Library Process Configuration document (LPC) for the library, and specify criteria for the custom properties of the API (known as classifiers within Lifecycle Manager). For example, the filter below selects APIs with the PII custom property set to true:

<asset-filter name="PII APIs">
  <classifier-criteria classifier-category="asset-type">
    <value-set>
      <value>API</value>
    </value-set>
  </classifier-criteria>
  <classifier-criteria classifier-category="pii">
    <value-set>
      <value>true</value>
    </value-set>
  </classifier-criteria>
</asset-filter>

When selecting a value for the Asset Filter classifier, a list of asset filters defined in the LPC as well as implicit filters for the defined asset types in the library will be shown. The filter in the example above would appear as LPC:PII APIs. Selecting the implicit filter asset-type:API indicates that the Runtime Configuration is applicable to all APIs within its owning group.

Note that any filter chosen for a Runtime Configuration should include criteria specifying API as the asset-type.

Implementation Type

This classifier specifies the type of API implementation the Runtime Configuration applies to. The choices are Live and Sandbox.

Policies

A Runtime Configuration asset provides three classifiers that you can use to select policies to be applied to applicable API implementations. These classifiers are:

  • Operational Policy
  • Compliance Policy
  • Service Level Policy

When choosing values for these classifiers, the application will present a list of policies available for the associated tenant with the specified policy type. You can choose one or more policies for each classifier.

Additionally, there are three classifiers that allow you to select policies for the physical service supporting an API implementation using the proxy pattern. These classifiers are:

  • Operational Policy (Physical Service)
  • Compliance Policy (Physical Service)
  • Service Level Policy (Physical Service)

Policy Replacement Behavior

The default behavior for setting policies on an API implementation or physical service is additive, meaning that policies specified in the Runtime Configuration are added to any existing policies on the implementation or physical service. However, you can customize the default behavior to control policy replacement behavior.

Here are a couple of examples of how this could be used:

  • Adding a policy: Let's say there is a two-environment topology, dev and prod, and the topology is configured so that policies from dev are preserved when promoting, but you also want to make sure that the production-level security policy is in place for all APIs that are PCI-compliant. You could set up a Runtime Configuration with a pci = true filter that specifies the production-level security policy, but you probably wouldn't want to remove other policies the API may have. In this scenario, you could set the preserve-existing-policies property to true. The new policy is in addition to any existing policies.
  • Replacing existing policies: Let's say you want to completely automate the assignment of policies to APIs, managing it entirely based on properties set on the API. In this case, you could set the preserve-existing-policies property to false. The Runtime Configuration would then overwrite any policies that were manually set or were in the promotion from an earlier environment. The policies in the Runtime Configuration would replace all existing policies.

There are two ways that you can customize policy replacement behavior:

In any case, if a policy classifier has no value in the Runtime Configuration, no action will be taken with the policies associated with the implementation or physical service.

Setting the preserve-existing-policies property

You can customize the Apply Runtime Configuration API post-processing task using the Configuration Designer by setting the preserve-existing-policies property to false. This indicates that any existing policies on the implementation or physical service that are not specified in the Runtime Configuration will be removed, and replaced by those in the Runtime Configuration.

When the preserve-existing-policies property is set to false, you can specify the value of NONE for any of the policy classifiers. This indicates that all policies should be removed from the implementation or physical service.

In the example below, the preserve-existing-policies property is set to false in an environment configuration of a topology.

"configuration": {
  "properties" : [
    {"name":"preserve-existing-policies","value":"false"}
  ],
  "apiImplementationProfiles": [ 
  ...
  ]
}

Setting the ENV:preserve-existing-policies property in the repository library (2018.0.0 and later)

In the example below, the ENV:preserve-existing-policies library property is set directly in the LPC document of the repository library.

<library-properties>
  <property name="ENV:preserve-existing-policies">
    <value>false</value>
  </property>
</library-properties>

Virtual Host

This classifier is used to set the vanity host name for every endpoint in the implementation. Leaving this classifier unset indicates that the host name of the endpoints should not be modified.

Path Classifier

The path classifier supports the Lifecycle Manager concept of context parameters. It is used to set the context path for every endpoint in the implementation. This allows aspects of the API, such as the API name or the values of custom properties, to be used within the path.

If you leave the path classifier unset, the default API context path, assigned by the API portal, applies to the API created by the runtime configuration. However, you can use one or more of the path classifiers to control the context path for the API created using the configuration.

In this section:

Path classifier parameters

The following parameters are available to be used for the path classifier:

  • {catalog_asset.id}

    Indicates that the path should include the asset ID (APIID, App ID, or UserID, depending on the asset that the Runtime Configuration is applied to).

  • {catalog_asset.name}

    Indicates that the path should include the asset name (for example, App03). If you're not sure what the asset name is, check in the Lifecycle Coordinator, as shown below. In this example, the asset name is Training-1.

    Path classifier example -- input

  • {catalog_asset.name_normalized}

    Indicates that the path should include the API's name, with normalization applied for any spaces or other characters that are not URL-safe. For normalization rules, see Normalization in classifiers below.

  • {catalog_asset.version}

    Indicates that the asset path should include the version.

  • {catalog_asset.version_normalized}

    Indicates that the asset path should include the version, with normalization applied for any spaces or other characters that are not URL-safe. For example, version 1 becomes version_1. For normalization rules, see Normalization in classifiers below.

  • {catalog_asset.property.<property name>}

    Indicates that the value of a specific property defined for the API should be used in the context path.

  • {catalog_asset.classifier.<classifier name>}

    Indicates that the value of a specific classifier defined for the API should be used in the context path. For example, if an API had a custom classifier called visibility set to a value external, using a value of /rest/{catalog_asset.classifier.visibility} for the path would result in endpoint paths set to /rest/external.

  • {catalog_asset.group.name}

    The group name, as defined in the Lifecycle Coordinator user interface, corresponds to the organization name as defined in the developer portal. If this classifier is used, the group/organization name is included in the API context path. See example below.

    Note: You could also use modifiers with your path classifiers to normalize the copy. For more information, see Modifiers with path classifiers below.

Note: The above is a list of key path classifiers. For a complete list, refer to the Lifecycle Manager Configuration guide.

Example #1: No path classifier set

If no path is specified in the Runtime Configuration, the default path is assigned when the API is created in the developer portal. An example is shown below.

Path classifier example -- unset

Example #2: Three classifier values

In the example below, three values are concatenated: {catalog_asset.group.name}, {catalog_asset.version_normalized}, and {catalog_asset.name_normalized}.

In the Runtime Configuration:

Path classifier example -- concatenated with three

The resulting API path, as displayed on the API Details page in the developer portal, is shown below.

Path classifier example -- concatenated with three: result

Example #3: Four classifier values

In the example below, four values are concatenated: {catalog_asset.group.name}, {catalog_asset.classifier.<classifier name>}, {catalog_asset.version_normalized}, and {catalog_asset.name_normalized}.

Path classifier example -- concatenated with three

The resulting API path, as displayed on the API Details page in the developer portal, is shown below.

Path classifier example -- concatenated with three

Normalization in classifiers

If you use a path classifier that includes normalization, the following rules are applied.

  • Uppercase is changed to lowercase, so all letters are lowercase.
  • Any characters other than the below are removed:
    • letters
    • numbers
    • Period (.)
    • Dash (-)
    • Underscore (_)
    • Colon (:)

For example, a space in an API name or API version name would be removed.

Modifiers with path classifiers

API Platform Version: 8.4.30 and later, 2018.0.3 and later

You can also use the context_path_safe modifier, with path classifiers such as catalog_asset.group.name, to transform the resolved parameter value as follows:

  • Removes characters that aren't letters or numbers
  • Strips accents from accented characters (for example, é becomes e)
  • Changes remaining characters to lowercase

For example, if you have a group name Nuestra Compañía #1, the following path classifier, with the modifier added, would result in a URL-safe group name value of nuestracompania1:

{catalog_asset.group.name.context_path_safe}

Deployment Zones

A Runtime Configuration asset can include a Deployment Zones classifier. This allows deployment zones to be designated for deployment of API implementations that match the filter of the Runtime Configuration asset. This section includes:

Basic Deployment Zone Configuration

API Platform Version: 8.4.18 and later

When the Deployment Zones classifier is edited, a list of Deployment Zones defined in the associated tenant is displayed. Any number of these deployment zones can be selected. Then, matching API implementations are deployed in the selected deployment zones.

If the Deployment Zones classifier is left empty, the deployment zones of a matching API implementation will not be affected. However, setting the classifier to a value of NONE will result in matching API implementations having no deployment zones enabled.

Settings designated in the Path and Virtual Host classifiers are applied to the endpoints in the designated deployment zones.

Advanced Deployment Zone Configuration

API Platform Version: 2018.0.0 and later

While the Deployment Zones classifier mentioned above can specify deployment zones for an API to be deployed to, it is sometimes necessary to also specify listeners within a deployment zone as well as specific settings for each listener. If this level of granularity is needed, the Deployment Zones classifier should be left unset and instead the Deployment Zone Configuration artifact in the Runtime Configuration asset should be used. This artifact should be a JSON document containing a JSON array of deploymentZone properties in the same format as shown for the deploymentZones property of an Environment Configuration (see Environment Configuration). Here is a sample Deployment Zones Configuration document:

[
  {
    "name": "DZ9921"
  },
  {
    "name": "DZ9941",
    "listeners": [
      {
        "name": "default-http0",
        "public": "false",
        "virtualHost": "{api.property.internal}",
        "path": "{api.name_normalized}_{api.version_normalized}"
      },
      {
        "name": "default-https",
        "useImplementationKeyforSSL": "true"
      }
    ]
  }
]

Note that only the deployment zone name is required in each deploymentZone property. Also be aware that there is no configuration-time validation of the information specified in the Deployment Zones Configuration document, so care must be taken to ensure that it is in sync with the actual deployment zones and listeners defined in the API platform instance.

Deployment Zone Replacement Behavior

By default, the deployment zones specified on the Runtime Configuration asset replace those already enabled for a matching API implementation.

Using Configuration Designer, it is possible to customize the Apply Runtime Configuration API post-processing task by setting the Preserve Existing Deployment Zones property to true. This indicates that any existing deployment zones enabled for a matching API implementation will be merged with those specified on the Runtime Configuration asset.

Allow Anonymous Access

This classifier is used to set the allow anonymous access value of the implementation. Leaving this classifier unset indicates that the allow anonymous access value of the implementation should not be modified.

Approval Required

This classifier is used to set the approval required value of the implementation. It is only applicable when allow anonymous access is set to false. Leaving this classifier unset indicates that the approval required value of the implementation should not be modified.

Debug Mode Enabled

This classifier is used to set the debug mode enabled value of the implementation. Leaving this classifier unset indicates that the debug mode enabled value of the implementation should not be modified.

For an example, see Runtime Configuration: Example, Line 39.

API Visibility

API Platform Version: 2018.0.11 and later

This classifier is used to set the visibility of the API that's created. Defaults to Public, which means that the API can be viewed by anyone.

Valid values: Public, Private, Registered Users.

For an example, see Runtime Configuration: Example, Line 40.

API Group Visibility

API Platform Version: 2019.1.0 and later

This classifier is used to invite user groups to view the API. Below is a configuration example:

{
  "apiImplementationProfiles":[
    {
      "name":"Internal API Profile",
      "type":"Live",
      "apiVisibility":"Registered Users",
      "groupVisibility":[
        "Group 1",
        "Group 3"
      ]
    }
  ]
}

Values that do not match a group are ignored.

OAuth Provider

API Platform Version: 2019.1.0 and later

This classifier allows you to specify the OAuth Provider domain associated with an API. You can specify domain, but not scopes.

The value is the name of a valid domain, already set up in the platform; for example, EOAP_acmepay. The domain must be one of these domain types:

  • External OAuth Provider
  • OAuth/OIDC Provider
  • PingFederate Provider

An example is shown below.

OAuth Domain classifier

Note: The API OAuth domain can only be specified in the Lifecycle Manager portal or Lifecycle Repository client user interface.

API Type (REST or SOAP)

API Platform Version: 2019.1.0 and later

This classifier allows you to filter your selection by API type (api-type). Valid values:

  • REST
  • SOAP

An example of these values shown on the Asset Filter list is shown below.

Edit Classifier drop-down

To implement this filter in an existing library you'll need to modify these files:

  • lpc.lpc: The workflow definition file for the Configuration Designer.
  • gdt.xml
  • Runtime Configuration.ctxml : the capture template for Runtime Configuration

Back to top

Publishing a Runtime Configuration Asset

When edit is complete on a Runtime Configuration asset, it must be submitted. Once any necessary approvals are complete, the Runtime Configuration is published, and is immediately active.

Back to top

Runtime Configuration: Example

The following is an example of an Environment Configuration definition. Line numbers have been added.

01  {
02    "name":"development",
03    "displayName":"Development",
04    "description":"Development environment",
05    "tenant":"DevelopmentTenant",
06    "configuration":{
07      "apiImplementationProfiles":[
08        {
09          "name":"Internal API Profile",
10          "type":"Live",
11          "filterNames":[
12            "internal"
13          ],
14          "deploymentZones":[
15            "DZ9941"
16          ],
17          "virtualServicePolicies":[
18            {
19              "policyName":"DetailedAuditing"
20            }
21          ],
22          "virtualHost":"InternalHost.com",
23          "path":"/{catalog_asset.name_normalized}",
24          "allowAnonymousAccess":"true"
25        },
26        {
27          "name":"External API Profile",
28          "type":"Live",
29          "filterNames":[
30            "external"
31          ],
32          "deploymentZones":[
33            "DZ9942"
34          ],
35          "virtualHost":"ExternalHost.com",
36          "path":"/{catalog_asset.name_normalized}/external",
37          "allowAnonymousAccess":"false",
38          "approvalRequired":"true",
39          "debugModeEnabled":"true",
40          "apiVisibility":"Registered Users"
41        }
42      ]
43    }
44  }

Back to top