Configuring migration options for DataPower API Gateway

If you are converting APIs to DataPower API Gateway, you can accept the default migration configuration or specify configuration parameters.

You can specify migration configuration parameters using either a YAML configuration file or from the command line, but not both. The config.yml file must be located in the same directory as the migration utility. You can specify to use this file when the migration utility is invoked using the apicm command with the port-to-apigw option, as in the following example.
 ./apicm archive:port-to-apigw <path> --use-config-file=true
If use of the configuration file is not specified, the migration utility uses parameters specified on the command line. If no parameters are specified, then the default parameters are used.

Some of these port-to-apigw configuration parameters depend upon a specific DataPower implementation to function. See the information in the following table to ensure that you have the correct version of DataPower for the parameters you want to use.

Table 1. Migration configuration options
Parameter Valid values DataPower version required Description
activity-log-policy activity-log_1.5.0, set-variable_2.0.0 DP 10.0.4.0+ Defines how to process the v5 activity-log policy when the migration utility rewrites the API assembly. The default value is activity-log_1.5.0, which changes the activity-log version to 1.5.0. When set to set-variable_2.0.0, the migration utility sets context variables based upon the value of the activity-log content and error-content configuration values.
chunked-uploads true / false

The default value is false.

For invoke_1.5.0: 10.0.1.1+, 10.0.2.0+

For invoke_2.0.0: 10.0.0.0+

If an invoke_1.5.0 or proxy_1.5.0 policy exists in an assembly in the API, then set chunked-uploads to true to enable chunked encoding for HTTP 1.1 requests to the target server.

If an invoke_2.0.0 policy exists in an assembly after the migration, then set chunked-uploads to false explicitly for the policy, as the default value for chunked-uploads in API Gateway is true.
client-id-header-override String. The string cannot contain spaces. Follow the guidelines for apiKey name:.

No default value.

 10.0.0.0+

Override the existing X-IBM-Client_Id name value with the new value. In API Gateway, x-key-type makes it possible to define custom naming for client_id and client_secret.

Example:
--client-id-header-override="acme-foo"
In this example, the securityDefinitions property is changed from:
foo:
    type: apiKey
    name: X-IBM-Client-Id
    in: header
to the following:
foo:
    type: apiKey
    name: acme-foo
    in: header
    x-key-type: client_id
Calls to this API must supply acme-foo: <client-id> in the request header instead of the original X-IBM-Client-Id: <client-id>.
client-id-query-override String. The string cannot contain spaces. Follow the guidelines for apiKey name:.

No default value.

 10.0.0.0+

Override the existing client_id name value with the new value. In API Gateway, x-key-type makes it possible to define custom naming for client_id and client_secret.

Example: 
--client-id-query-override="acme-foo"
In this example, the securityDefinitions property is changed from: 
foo:
    type: apiKey
    name: client_id
    in: query
to the following:
foo:
    type: apiKey
    name: acme-foo
    in: query
    x-key-type: client_id
Calls to this API must supply ?acme-foo=<client-id> in the query parameter instead of the original ?client_id=<client-id>.
client-secret-header-override String. The string cannot contain spaces. Follow the guidelines for apiKey name:.

No default value.

 10.0.0.0+

Override the existing X-IBM-Client-Secret name value with the new value. In API Gateway, x-key-type makes it possible to define custom naming for client_id and client_secret.

Example:
--client-secret-header-override="acme-foo"
In this example, the securityDefinitions property is changed from:
foo:
    type: apiKey
    name: X-IBM-Client-Secret
    in: header
to the following:
 foo:
    type: apiKey
    name: acme-foo
    in: header
    x-key-type: client_secret
Calls to this API must supply acme-foo: <client-secret> in the request header instead of the original X-IBM-Client-Secret: <client-secret>.
client-secret-query-override String. The string cannot contain spaces. Follow the guidelines for apiKey name:.

No default value.

 10.0.0.0+

Override the existing client_secret name value with the new value. In API Gateway, x-key-type makes it possible to define custom naming for client_id and client_secret.

Example: 
--client-secret-query-override="acme-foo"
In this example, the securityDefinitions property is changed from:
foo:
    type: apiKey
    name: client_secret
    in: query
to the following:
foo:
    type: apiKey
    name: acme-foo
    in: query
    x-key-type: client_secret
Calls to this API must supply ?acme-foo=<client-secret> in the query parameter instead of the original ?client_secret=<client-secret>.
copy-id-headers-to-message true / false

The default value is false.

 10.0.1.1+, 10.0.2.0+

When set to true, the client-id header is copied from request.headers to message.headers to be passed to the backend server. Set this parameter to true if your invoke backend services expect the client-id to be passed through.
custom-policies-scope catalog / global

The default value is catalog.

 10.0.0.0+

When set to catalog, the original v5 or v5-compatible catalog that contains the custom policy is staged for pushing to the target catalog and organization in API Gateway.

When set to global, the custom policy is staged for pushing to API Gateway and is visible to all organizations and catalogs within that gateway.

archive:port-to-apigw sets up the custom policies for pushing to API Gateway, but does not do the pushing. If global scope is used, archive:push of the admin organization will push all custom policies associated with the configured gateways. If catalog scope is used, then the archive:push of the admin organization will initialize the custom policies on the gateway. A subsequent archive:push of the provider organization is needed to advertise the custom policies in the catalogs contained within the provider organization.

Note: Potential conflicts between custom policies of the same name and version are resolved according to the following rules:
  • When set to global and two policies under the same gateway service have the same name, version, and md5 hash value, then the duplicates are discarded and a message is generated.
  • When set to global and two policies under the same gateway service have the same name, version, and a differing md5 hash value, then global scope cannot be applied. Catalog scope is used and a warning is generated.
  • When set to catalog, <orgname>_<catname>_ is appended to the zip filename to maintain uniqueness.
deploy-policies Any combination of the following values: gatewayscript_1.0.0,if_1.5.0, invoke_1.5.0, proxy_1.5.0,redact_1.5.0, switch_1.5.0, validate-usernametoken_1.0.0, xslt_1.0.0

The default values are: if_1.5.0, invoke_1.5.0, proxy_1.5.0, redact_1.5.0, switch_1.5.0, validate-usernametoken_1.0.0, xslt_1.0.0

For invoke_1.5.0, proxy_1.5.0, gatewayscript_1.0.0, and xslt_1.0.0: 10.0.0.0+

For if_1.5.0 and switch_1.5.0: 10.0.1.1+, 10.0.2.0+

For redact_1.5.0: 10.0.3.0+

For validate-usernametoken_1.0.0: 10.0.1.3+, 10.0.2.0+

Defines which backwards-compatible policies should be advertised by DataPower to API Manager.

Note: Any legacy policies that are specified in the config.yml file or by using the apicm command must also be specified by using deploy-policies. If these policies are not specified by using deploy-policies, an error is returned.
emulate-v4-plan-rate-limit true / false

The default value is false.

 10.0.1.2+, 10.0.2.0+

Determines whether all APIs emulate the v4 plan rate limit. If set to true, then API operations do not share the rate limit. This setting matches the behavior of the x-ibm-gateway-emulate-v4-plan-rate-limit v5 option.
enable-api-logging true / false

The default value is true.

 10.0.0.0+

Log all changes that the migration utility makes when rewriting APIs. These changes are logged as comments in the API YAML file.
enforce-required-params true / false

The default value is false.

 10.0.1.1+, 10.0.2.0+

When set to true, required parameters are enforced, which is the default behavior in API Gateway. When set to false, required parameters are not enforced, even if the required parameter checkbox selected.
gatewayscript-policy One of the following values: gatewayscript_1.0.0, gatewayscript_2.0.0

The default value is gatewayscript_2.0.0.

 10.0.0.0+

Defines which gatewayscript policy the migration utility uses when rewriting the API assembly.

gatewayscript_1.0.0: A user-defined policy created by the migration utility. This policy uses the v5 MPGW processing rule. Use gatewayscript_1.0.0 if the gatewayscript policy is dependent on v5 MPGW capabilities, such as load balancer groups or XML Manager settings.

gatewayscript_2.0.0: The migration utility rewrites the existing API to gatewayscript 2.0.0. This policy supports the header-metadata module for compatibility with the DataPower® Gateway (v5 compatible).

Specifying gatewayscript_2.0.0 can cause migration errors or run-time errors. Use gatewayscript_2.0.0 if you are able to review and verify all changes made by the migration utility in the API YAML file.
if-policy One of the following values: if_1.5.0, switch_2.0.0

The default value is if_1.5.0.

For if_1.5.0: 10.0.1.1+, 10.0.2.0+

For switch_2.0.0: 10.0.0.0+

Defines which if policy the migration utility uses when rewriting the API assembly.

if_1.5.0: The migration utility rewrites the existing API to if 1.5.0.

switch_2.0.0: The migration utility rewrites the existing API to switch 2.0.0. Specifying switch_2.0.0 can cause migration errors or run-time errors. Use switch_2.0.0 if you are able to review and verify all changes made by the migration utility in the API YAML file.
invoke-policy One of the following values: invoke_1.5.0, invoke_2.0.0

The default value is invoke_1.5.0.

 10.0.0.0+

Defines which invoke policy the migration utility uses when rewriting the API assembly.

invoke_1.5.0: The migration utility rewrites the existing API to invoke 1.5.0.

invoke_2.0.0: The migration utility rewrites the existing API to invoke 2.0.0. Specifying invoke_2.0.0 can cause migration errors or run-time errors. Use invoke_2.0.0 if you are able to review and verify all changes made by the migration utility in the API YAML file.
no-rename true / false

The default value is false.

 10.0.0.0+

Defines whether to append the -apigw suffix to artifact file names or within artifacts. When set to false, the files are renamed using the -apigw suffix and the original unpacked v5c files are also overwritten with the ported API Gateway artifacts.

A y/n prompt appears when using this option. To bypass this prompt, use the --accept-no-rename-deletion option.
no-retitle true / false

The default value is false.

 10.0.0.0+

Defines whether to append the -apigw suffix to the title of the migrated API, product, or OAuth provider. Set this option to true if you want the title of the migrated API, product, or OAuth provider to match the original title in the v5-compatible YAML file.

Note that the x-ibm-name of API Gateway APIs and products always includes the -apigw suffix. The no-retitle option applies only to the title.
optimize-gws true / false

The default value is false.

 10.0.0.0+

When set to true, gatewayscript policies are modified to map v5 functions to API Gateway functions.

Setting optimize-gws to true is valid only for the gatewayscript_2.0.0 policy. If it is set to true for gatewayscript_1.0.0, an error is generated.

Note: Setting optimize-gws to true can result in performance enhancements. However, the modifications to gatewayscript policies by the migration utility can cause problems. When using this setting, review all gatewayscript policy modifications after migration.
proxy-policy One of the following values: proxy_1.5.0, invoke_2.0.0

The default value is proxy_1.5.0.

 10.0.0.0+

Defines which proxy policy the migration utility uses when rewriting the API assembly.

proxy_1.5.0: The migration utility rewrites the existing API to proxy 1.5.0.

invoke_2.0.0: The migration utility converts the proxy policy to invoke 2.0.0. Specifying invoke_2.0.0 can cause migration errors or run-time errors. Use invoke_2.0.0 if you are able to review and verify all changes made by the migration utility in the API YAML file.
redact-policy One of the following values: redact_1.5.0, redact_2.0.0

The default value is redact_1.5.0.

 10.0.3.0+

Defines which redact policy the migration utility uses when rewriting the API assembly.

redact_1.5.0: The migration utility rewrites the existing API to redact 1.5.0.

redact_2.0.0: The migration utility rewrites the existing API to redact 2.0.0. Specifying redact_2.0.0 can cause migration errors or run-time errors, including changes to what is redacted, particularly with redactions meant for JSON payloads. Use redact_2.0.0 if you are able to review and verify all changes made by the migration utility in the API YAML file.
repair-wsdl-apis true / false

The default value is true.

 10.0.1.1+, 10.0.2.0+

If an API ported from V5 is created from WSDL, the WSDL is read and checked for accuracy. If repair-wsdl-apis is set to true, then the API and WSDL are automatically repaired. For example, if the WSDL ZIP file contains unnecessary files, they are automatically removed if repair-wsdl-apis is true.
return-v5-responses true / false

The default value is false.

 10.0.1.1+, 10.0.2.0+

When set to true, OAuth-related messages are printed in the v5 response format. When set to false, OAuth-related response messages are printed in API Gateway response format.
switch-policy switch_1.5.0, switch_2.0.0

The default value is switch_1.5.0.

For switch_1.5.0: 10.0.1.1+, 10.0.2.0+

For switch_2.0.0: 10.0.0.0+

Defines which switch policy the migration utility uses when rewriting the API assembly.

switch_1.5.0: The migration utility rewrites the existing API to switch 1.5.0.

switch_2.0.0: The migration utility rewrites the existing API to switch 2.0.0. Specifying switch_2.0.0 can cause migration errors or run-time errors. Use switch_2.0.0 if you are able to review and verify all changes made by the migration utility in the API YAML file.
use-config-file true / false

The default value is false.

 10.0.0.0+

Use the config.yml file that is in the same directory as the apicm binary file that is being executed. If this file is used, configuration options cannot be set using the command line. The purpose of the config file is to specify the command inputs given on this page, but in an easy-to-read file format (YAML).
v5-request-headers true / false

The default value is true.

 10.0.1.2+, 10.0.2.0+

When set to true, the following v5-compatible request headers are set: Via, X-Global-Transaction-ID, X-Client-IP. When set to false, these request headers are not set.
validate-usernametoken-policy validate-usernametoken_1.0.0

The default value is empty.

 10.0.1.3+, 10.0.2.0+

Defines whether or not to use the validate-usernametoken v5 emulation policy when the migration utility rewrites the API assembly. When empty, the migration utility takes no action on the policy.
xslt-policy One of the following values: xslt_1.0.0, xslt_2.0.0

The default value is xslt_1.0.0.

 10.0.0.0+

Defines which gatewayscript policy the migration utility uses when rewriting the API assembly.

xslt_1.0.0: A user-defined policy created by the migration utility. This policy uses the v5 MPGW processing rule. Use xslt_1.0.0 if the xslt policy is dependent on v5 MPGW capabilities, such as load balancer groups or XML Manager settings.

xslt_2.0.0: The migration utility rewrites the existing API to xslt 2.0.0. Specifying xslt_2.0.0 can cause migration errors or run-time errors. Use xslt_2.0.0 if you are able to review and verify all changes made by the migration utility in the API YAML file.

Example migration configurations

The following examples show configuration options using the config.yml file or the apicm command.

  • The following example uses the config.yml file to specify the migration configuration.
    
custom-policies-scope: global
emulate-v4-plan-rate-limit: false
deploy-policies:
  - proxy_1.5.0
  - redact_1.5.0
  - invoke_1.5.0
  - gatewayscript_1.0.0
rewrite-apis:
  enable-api-logging: false
  proxy-policy: proxy_1.5.0
  redact-policy: redact_1.5.0 
  invoke-policy: invoke_1.5.0
  xslt-policy: xslt_2.0.0
  gatewayscript-policy: gatewayscript_1.0.0
  if-policy: switch_2.0.0
  switch-policy: switch_2.0.0
  optimize-gws: false
  no-retitle: true

    Use the use-config-file parameter when running the apicm command to specify that the config.yml file is used for migration configuration values.

    ./apicm archive:port-to-apigw <path> --use-config-file=true
  • The following example uses the apicm command to specify the same settings as in the previous example.
    ./apicm archive:port-to-apigw <path> --custom-policies-scope: global --emulate-v4-plan-rate-limit: false --deploy-policies="proxy_1.5.0,redact_1.5.0,invoke_1.5.0,xslt_2.0.0,gatewayscript_1.0.0,switch_2.0.0" --enable-api-logging=false --proxy-policy="proxy_1.5.0" --redact-policy="redact_1.5.0" --invoke-policy="invoke_1.5.0" --xslt-policy="xslt_2.0.0" --gatewayscript-policy="gatewayscript_1.0.0" --if-policy="switch_2.0.0" --switch-policy="switch_2.0.0" --optimize-gws=true --no-retitle=true
  • The following example uses the apicm command to specify that the default migration configuration values are used.
    ./apicm archive:port-to-apigw <path>