Configuration Files

The basic configuration defines the minimum settings required to use the API Ops CLI tool. It introduces the core configuration file and explains how the tool locates and reads configuration values during execution.

On this page:

• Environment configuration
• Export configuration
  • Asset-specific configuration parameters
  • Example: Export configuration file
  • Export configuration selectors
• Import configuration
  • JSON interpolation
  • XPath interpolation
  • Example: Import configuration file
  • Import configuration selectors
• Configuration errors

Environment configuration

The environment configuration file (environment-config.yaml) allows you to define and manage multiple API gateway environments by using a centralized, declarative configuration. It eliminates the need to repeatedly specify connection and authentication parameters through CLI flags. It enables:

• Consistent configuration across teams
• Secure handling of credentials
• Easy integration with CI/CD pipelines
• Environment portability

File location

A sample environment-config.yaml file is provided under the INSTALL_DIR/config directory. Modify this file to match your environment and configuration requirements.

Sample YAML structure:

environments:
    dev:
       baseCMAPIURL: "https://<dev-cm-api-host>:<port>"
       basePMAPIURL: "https://<dev-pm-api-host>:<port>/rest"
       tenantName: "<dev-tenant-name>"
       loginType:"ssoLogin"
       ssoDomain: "<ldap-domain-name>"
       tenantUserName: "<ldap-username>"
       tenantPassword: "<password>"
       sslKeystorePath: "/path/to/keystore.p12"
       sslKeystorePassword: "pwd:<keystore-password>"
       sslTruststorePath: "/path/to/truststore.p12"
       sslTruststorePassword: "pwd:<truststore-password>"
       pkiKeystorePath: "/path/to/identity-keystore.jks"
       pkiKeystorePassword: "pwd:<pkikeystore-password>"   
       pkiMode: "<mode>" 
       pmUserName: "<pm-user-name>"
       pmPassword: "<pm-password>"
    test:
       baseCMAPIURL: "https://<test-cm-api-host>:<port>"
                       .
                       .
                       .
    prod:
       baseCMAPIURL: "https://<prod-cm-api-host>:<port>"
                       .
                       .
                       .      

The following table shows the configuration parameter description:

Export configuration

The export configuration file (export-config.yaml) defines what and how resources are exported from a source environment.

File location

A sample export-config.yaml file is provided under INSTALL_DIR/config directory. Modify the file as per your requirements

Sample YAML structure:

environmentName: "<source-environment-name>"
assetDirectory: "/export-directory-path/export"
assets:
   <asset_type1>:
     baseDirectory: "<base-directory-name>"
     selector:
        type: "<selector-type>"
        values:
          - "<asset-name>"
     strategy: "<export-strategy>"
   <asset_type2>:
     baseDirectory: "<base-directory-name>"
     selector:
        type: "<selector-type>"
        values:
          - "<asset-name>"
     strategy: "<export-strategy>"

The following table describes the export configuration parameters:

Asset-specific configuration parameters

Certain asset types support additional configuration parameters. The following table shows how to configure export settings for those asset types.

Example: Export configuration file

See the export-config.yaml file under the INSTALL_DIR/config directory.

Export configuration selectors

Use the selector type to control which assets are exported from the source environment.

You can export:

• Specific assets that you identify by name
• Assets that are associated with selected APIs

Export assets by name

Use the name selector when you want to export individual assets explicitly (for example, a policy or scope), without exporting any related dependencies.

assets:
  <asset-type>:
    baseDirectory: "<base-directory>"
    selector:
      type: "name"
      values:
        - "<asset-name>"
    strategy: "<export-strategy>"

This configuration exports only the assets listed in selector.values.

Export assets related to selected APIs

Use the api-related selector when you want to export assets that are associated with one or more APIs (for example, policies or scopes associated with an API).

To export related assets:

• Specify the required APIs by using the name selector.
• Specify the related asset types by using the api-related selector.

assets:
  <asset_type1>:
    baseDirectory: "<base-directory>"
    selector:
      type: "name"
      values:
        - "<asset-name>"
    strategy: "<export-strategy>"
  <related-asset-type>:
    baseDirectory: "<base-directory>"
    selector:
      type: "api-related"
    strategy: "<export-strategy>"

This configuration exports the specified APIs and all assets of the specified type that are associated with those APIs.

Import configuration

The import configuration file (import-config.yaml) defines how exported API gateway artifacts are applied to a target environment. It provides a declarative mechanism to control import behavior and strategies, handle conflicts and updates, apply environment-specific transformations (interpolation).

File location

A sample import-config.yaml file is provided under INSTALL_DIR/config directory. Modify the file as per your requirements.

Sample YAML structure:

environmentName: "<target-environment-name>"
assetDirectory: "/path-to-exported-assets/export"
assets:
   <asset_type>:
     baseDirectory: "<base-directory-name>"
     selector:
        type: "<selector-type>"
        values:
        - "<asset-name-to-import>"
     strategy : "<import-strategy>"
     jsonInterpolations:
        - filterValue: "<filter_value>"
          jsonPath: "<json_path>"
          value: "<new_value>"

The following table describes the import configuration parameters:

JSON interpolation

When you import APIs into a new environment, update the environment‑specific values such as hostnames, tenant/organization identifiers, or endpoint URIs. Rather than editing several configuration files manually, you can use JSON interpolation rules in import-config.yaml to automate these updates.

The following table describes the parameters:

JSON interpolation scenarios

The following configuration applies JSON path–based interpolations to selected API assets. These rules locate fields in API configuration files through JSON path expressions and update values either by replacing them fully or by using partial string replacements.

The following are common interpolation scenarios:

• Set the tenant organization by updating the organization field.
• Standardize gateway and endpoint hostnames for the target environment.
• Perform a partial string replacement to update endpoint URIs.
• Replace BasicAuditing with DetailedAuditing in API‑level and operation‑level policy definitions.
• Update the status parameter description and set the required field to false.
• Set the actual password for a static user identity during import by using JSON interpolation in import-config.yaml to replace the CHANGE_ME placeholder.
• For HSM environments, set the alias and password values under pki_mapping for the API by updating the endpoint alias fields during import.

The following are standalone examples for each interpolation rule.

Example: Set the tenant organization

jsonInterpolations:
  - filterValue: ".*api_configuration.yaml"
    jsonPath: "$.organization"
    value: "Tenant - automation2022-1"

Example: Update endpoint hostnames

jsonInterpolations:
  - filterValue: ".*api_configuration.yaml"
    jsonPath: "$.implementationConfig.*.deploymentZonesHostingInfo[*].deploymentZoneEndpoints[*].endPointHostName"
    value: "automation2022-1-mysql80.aws.akana.roguewave.com"

  - filterValue: ".*api_configuration.yaml"
    jsonPath: "$.implementationConfig.*.deploymentZonesHostingInfo[*].deploymentZoneEndpoints[*].gatewayHostName"
    value: "automation2022-1-mysql80.aws.akana.roguewave.com"

Example: Partially replace text in endpoint URIs

jsonInterpolations:
  - filterValue: ".*api_configuration.yaml"
    jsonPath: "$.implementationConfig.*.targetEndpoints[*].uri"
    partialReplaceString: "petstore.swagger.io"
    value: "pet.petstore.swagger.io"

Example: Replace Basic Auditing at the API‑level

jsonInterpolations:
  - filterValue: ".*api_configuration.yaml"
    jsonPath: "$.implementationConfig.*.endpointPolicies.apiPolicyDetails[?(@.name=='BasicAuditing')].test"
    value: "DetailedAuditing

Example: Replace Basic Auditing at the operation‑level

jsonInterpolations:
  - filterValue: ".*api_configuration.yaml"
    jsonPath: "$.implementationConfig.*.endpointPolicies.operationPolicyDetails[*].policy[?(@.name=='BasicAuditing')].name"
    value: "DetailedAuditing"

Example: Update the status parameter description

jsonInterpolations:
  - filterValue: ".*.json"
    jsonPath: "$.paths['/pet/findByStatus'].get.parameters[?(@.name=='status')].description"
    partialReplaceString: "Status values"
    value: "Value"

Example: Set the status parameter to false

jsonInterpolations:
  - filterValue: ".*.json"
    jsonPath: "$.paths['/pet/findByStatus'].get.parameters[?(@.name=='status')].required"
    value: "false"

Example: Set a static user identity password for an outbound identity

jsonInterpolations:
  - filterValue: ".*api_configuration.yaml"
    jsonPath: "$.implementationConfig.Live.identity_config.IdentityMap.OutboundIdentity[0].SourceUserPassword"
    value: "pwd:plaintextpassword" # other option enc:encryptedpassword

Example: Set alias and password for pki_mapping in an API

jsonInterpolations:
  - filterValue: ".*api_configuration.yaml"
    jsonPath: "$.pki_mapping.Live.endpointAliasPassword"
    value: "aliasName1"

  - filterValue: ".*api_configuration.yaml"
    jsonPath: "$.pki_mapping.Live.targetEndpointAlias"
    value: "aliasName2"

  - filterValue: ".*api_configuration.yaml"
    jsonPath: "$.pki_mapping.Live.targetEndpointAliasPassword"
    value: "pwd:aliasPassword"

  - filterValue: ".*api_configuration.yaml"
    jsonPath: "$.pki_mapping.Live.targetEndpointAliasPassword"
    value: "pwd:alaisPassword"  

XPath interpolation

XPath interpolation modifies values in XML‑based configuration or specification files during asset processing.

The following table shows the parameter description.

XPath interpolation scenarios

You can use XPath interpolation to update XML‑based policy configuration files during asset processing. These rules locate XML nodes by using XPath expressions and modify values by replacing, removing, adding, or partially updating element content.

The following are common interpolation scenarios:

• Set the OpenBankingVersion value in the policy configuration file.
• Update a specific Expression element when multiple instances are present.
• Remove the AuditInputMessage field from the BasicAuditing policy configuration.
• Add the AuditOutputMessage field under the AuditContract hierarchy.
• Perform a partial string replacement to update version values in the OpenBankingDocUrl element.

The following are standalone examples for each interpolation rule.

Example: Set the OpenBankingVersion value to 3.1

xmlInterpolations:
     - filterValue: ".*JOSE-OB-1-IN_AutoTent/policy_configuration.yaml"
       xPath: "//*[local-name()='OpenBankingVersion']"
       value: "3.1" 

Example: Update the first Expression element value

xmlInterpolations:
  - filterValue: ".*HttpJavaScriptInjectionSQLInjectionPolicy/policy_configuration.yaml"
    xPath: "//*[local-name()='Expression'][1]"
    value: "new-regex-pattern-1-30"

Example: Remove the AuditInputMessage field

xmlInterpolations:
  - filterValue: ".*BasicAuditing/policy_configuration.yaml"
    xPath: "//*[local-name()='AuditInputMessage']"
    action: "remove"

Example: Add the AuditOutputMessage field

xmlInterpolations:
  - filterValue: ".*BasicAuditing/policy_configuration.yaml"
    xPath: "//*[local-name()='AuditContract']"
    value: "AuditOutputMessage"
    action: "add"

Example: Partially replace version in URL

xmlInterpolations: 
   - filterValue: ".*JOSE-OB-1-IN_AutoTent/policy_configuration.yaml"
     xPath: "//*[local-name()='OpenBankingDocUrl']"
     partialReplaceString: "v3.1"
     value: "v4.0"

Example: Import configuration file

See the import-config.yaml file under the INSTALL_DIR/config directory.

Import configuration selectors

Use selector types to specify which assets are imported into the target environment.

You can import:

• Specific assets by name
• Assets that are associated with selected APIs

Import assets by name

Use a name‑based selector to import specific assets (for example, a license) from the exported asset directory into a target environment.

assets:
  <asset-type>:
    baseDirectory: "<base-directory>"
    selector:
      type: "name"
      values:
        - "<asset-name>"
    strategy: "<import-strategy>" 

This configuration imports only the assets listed in selector.values into the specified target environment.

Import assets related to selected APIs

Use an API‑related selector to import assets that are associated with one or more APIs into a target environment.

To import related assets:

• Specify the required APIs by using the name selector.
• Specify the related asset types by using the api-related selector.

assets:
  <asset_type>:
    baseDirectory: "<base-directory>"
    selector:
      type: "name"
      values:
        - "<asset-name>"
    strategy: "<import-strategy>"
  <related-asset-type>:
    baseDirectory: "<base-directory>"
    selector:
      type: "api-related"
    strategy: "<import-strategy>"

This configuration imports the specified APIs and the related assets that are associated with those APIs into the target environment.

Configuration errors

The configuration errors in YAML or JSON files can cause import or export operations to fail when using the CLI tool.

The following are the common configuration issues:

• Ensure that the YAML file uses correct indentation. Validate the file by using a YAML syntax validator before running the CLI tool.
• Verify that the base directory specified for import is correct.
• Ensure that the asset directory paths in the export and import configuration files match.
• Verify that the JSONPath configuration for list fields is valid.