Converting v5-compatible API definitions
To convert v5-compatible APIs to the format required by the DataPower API Gateway, you must map all v5-compatible gateway services to DataPower API Gateway services, optionally specify any configuration settings to be used in the conversion, and use the AMU to port the API definitions.
Procedure
-
Map your v5-compatible Gateway Services to DataPower API Gateway services.
You must map your v5-compatible Gateway Services (the v5c gateway) to DataPower API Gateway services so that the AMU command has a target for migrating custom policies and gateway extensions, and can migrate the configured gateway services for each catalog and space.
- In the unpacked data, locate the gateway services.
Each of the gateway services in stored in cloud-v10/admin-org/availability-zones/<az_name>/gateway-services/.
- For each v5-compatible gateway service, create a mapping.yml file
that contains the name of the DataPower API Gateway Service you want to map to. Create the mapping.yml file directly in the directory containing the v5-compatible gateway service. The file must contain 3 statements:
- The artifact type, which is always
gateway-service:
- The name of the DataPower API Gateway service (not the Title or ID)
- The gateway type for that gateway service, which is always
datapower-api-gateway
for converting to DataPower API Gateway service
For example, the following mapping.yml file maps the v5-compatible gateway service to the DataPower API Gateway service named "gateway-10-1" and specifies a target gateway of type
datapower-api-gateway
:gateway-service: name: gateway-10-1 gateway-type: datapower-api-gateway
If you have several v5-compatible gateway services and you want to map each of them to the same DataPower API Gateway service, copy the mapping.yml file into the directory for each of those v5-compatible gateway services.
Make sure to map all of the v5-compatible gateway services to DataPower API Gateway services before attempting to port the APIs in the next step.
- The artifact type, which is always
- In the unpacked data, locate the gateway services.
- Optional: Create a configuration file that defines settings for migrating the
v5-compatible APIs.
In the directory where the AMU is stored, create a file called
config.yml
and use it to specify configuration settings (see Table 1 for the configuration settings).Exampleconfig.yml
file: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
If you omit the config.yml file, you can optionally specify configuration settings as parameters on the command line when you port the APIs in the next step.
Table 1. Migration configuration settings 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 toset-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
orproxy_1.5.0
policy exists in an assembly in the API, then setchunked-uploads
totrue
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 setchunked-uploads
tofalse
explicitly for the policy, as the default value forchunked-uploads
in API Gateway istrue
.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 forclient_id
andclient_secret
.Example:
In this example, the--client-id-header-override="acme-foo"
securityDefinitions
property is changed from:
to the following:foo: type: apiKey name: X-IBM-Client-Id in: header
Calls to this API must supplyfoo: type: apiKey name: acme-foo in: header x-key-type: client_id
acme-foo: <client-id>
in the request header instead of the originalX-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 forclient_id
andclient_secret
.Example:
In this example, the--client-id-query-override="acme-foo"
securityDefinitions
property is changed from:
to the following:foo: type: apiKey name: client_id in: query
Calls to this API must supplyfoo: type: apiKey name: acme-foo in: query x-key-type: client_id
?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 forclient_id
andclient_secret
.Example:
In this example, the--client-secret-header-override="acme-foo"
securityDefinitions
property is changed from:
to the following:foo: type: apiKey name: X-IBM-Client-Secret in: header
Calls to this API must supplyfoo: type: apiKey name: acme-foo in: header x-key-type: client_secret
acme-foo: <client-secret>
in the request header instead of the originalX-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 forclient_id
andclient_secret
.Example:
In this example, the--client-secret-query-override="acme-foo"
securityDefinitions
property is changed from:
to the following:foo: type: apiKey name: client_secret in: query
Calls to this API must supplyfoo: type: apiKey name: acme-foo in: query x-key-type: client_secret
?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
, theclient-id
header is copied fromrequest.headers
tomessage.headers
to be passed to the backend server. Set this parameter totrue
if your invoke backend services expect theclient-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-v10
sets up the custom policies for pushing to API Gateway, but does not do the pushing. Ifglobal
scope is used,archive:push-v10
of the admin organization will push all custom policies associated with the configured gateways. Ifcatalog
scope is used, then thearchive:push-v10
of the admin organization will initialize the custom policies on the gateway. A subsequentarchive:push-v10
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
, andxslt_1.0.0
: 10.0.0.0+For
if_1.5.0
andswitch_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 theconfig.yml
file or by using theapicm
command must also be specified by usingdeploy-policies
. If these policies are not specified by usingdeploy-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 thex-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 tofalse
, 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. Usegatewayscript_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 theheader-metadata
module for compatibility with the v5-compatible gateway.Specifying
gatewayscript_2.0.0
can cause migration errors or run-time errors. Usegatewayscript_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. Specifyingswitch_2.0.0
can cause migration errors or run-time errors. Useswitch_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. Specifyinginvoke_2.0.0
can cause migration errors or run-time errors. Useinvoke_2.0.0
if you are able to review and verify all changes made by the migration utility in the API YAML file.no-retitle
true / false
The default value is
false
.10.0.0.0+ Defines whether to append the porting suffix to the
title
of the migrated API, product, or OAuth provider. Set this option totrue
if you want thetitle
of the migrated API, product, or OAuth provider to match the originaltitle
in the v5-compatible YAML file.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
totrue
is valid only for thegatewayscript_2.0.0
policy. If it is set totrue
for gatewayscript_1.0.0, an error is generated.Note: Settingoptimize-gws
totrue
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.porting-suffix
A string containing alphanumeric, dash, underscore and dot characters. The default value is
-apigw
.10.0.0.0+ Defines the suffix to be used when renaming APIs, Products, OAuth Providers, and other ported artifacts. The suffix is appended to the version on APIs, Products and other ported artifacts that have versions, and onto the name for OAuth Providers and other ported artifacts that do not have versions. If porting-suffix
is not specified then a value of-apigw
will be used. The porting suffix can contain alphanumeric, dash, underscore and dot characters. Prior to AMU 10.0.5.4 the porting suffix could not be overridden and-apigw
was appended to the name for all ported artifacts.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 toproxy 1.5.0
.invoke_2.0.0
: The migration utility converts the proxy policy to invoke 2.0.0. Specifyinginvoke_2.0.0
can cause migration errors or run-time errors. Useinvoke_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 toredact 1.5.0
.redact_2.0.0
: The migration utility rewrites the existing API toredact 2.0.0
. Specifyingredact_2.0.0
can cause migration errors or run-time errors, including changes to what is redacted, particularly with redactions meant for JSON payloads. Useredact_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 totrue
, then the API and WSDL are automatically repaired. For example, if the WSDL ZIP file contains unnecessary files, they are automatically removed ifrepair-wsdl-apis
istrue
.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 tofalse
, 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. Specifyingswitch_2.0.0
can cause migration errors or run-time errors. Useswitch_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 theapicm
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 tofalse
, 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. Usexslt_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. Specifyingxslt_2.0.0
can cause migration errors or run-time errors. Usexslt_2.0.0
if you are able to review and verify all changes made by the migration utility in the API YAML file. - When set to
- Use the AMU
port
command to convert the v5-compatible APIs to the DataPower API Gateway format.When you run the
port
command with the AMU, there are 3 options for specifying configuration settings for your APIs:- Store the settings in the config.yml migration configuration file.
You must name the configuration file config.yml. Specify the
--use-config-file=true
parameter on the command line when you port the APIs. - Include the configuration settings on the command line (see Table 2 for the configuration
settings).
Specify the settings as parameters on the command line. If you also specify a configuration file, any configuration settings specified as parameters directly on the command line are ignored.
- Accept the default configuration settings.
If you don't specify a configuration file and also don't specify any configuration parameters on the command line, the AMU uses the default configuration when porting the APIs.
Before you port the APIs, back up your /cloud-v10 directory. If you need to rerun the
archive:port-to-apigw-v10
command, first restore the un-ported /cloud-v10 directory (thearchive:port-to-apigw-v10
command does not overwrite DataPower API Gateway artifacts that were previously created).To port the APIs, run the following command:
On Windows: open a command window with Administrator privileges, and omit the "./" from the command.
./apicm archive:port-to-apigw-v10 <path_to_APIs> --enable-api-logging=false --use-config-file=true
where<path_to_APIs>
represents one of the following locations:- The top-level /cloud-v10 directory containing all of the extracted
archive:The AMU ports all artifacts within the directory, including APIs, Products, OAuth providers, and custom policies. Running a subsequent
archive:push-v10
command pushes all of the converted artifacts to the DataPower API Gateway. Custom policies and OAuth providers are not migrated if a directory other than /cloud-v10 is specified.Attention: Running theport
command on any subdirectory within the unpacked /cloud-v10 directory could leave the directory in an inconsistent state, and cause the subsequentarchive:push-v10
command to fail. - A single API file, or a directory that contains only APIs or Products:
When you are testing your migration settings, you might want to convert just a few APIs or Products to verify the settings. When you use this approach, you cannot use the high-level
archive:push-v10
command to push the artifacts to the DataPower API Gateway. Instead, you must push the ported artifacts into API Manager using either the toolkit or the user interface.When testing is complete, you can delete the artifacts from testing and run the
port
command on the top-level /cloud-v10 directory to convert all of the artifacts in one operation, and then use thearchive:push-v10
command to push them all to the DataPower API Gateway in a second operation.
Table 2. Parameters for the port
commandParameter Description --enable-api-logging=false
Optional. Disable logging. By default, logging is enabled for the conversion and all changes that the migration utility makes when rewriting APIs are logged as comments within the API's YAML file. --use-config-file=true
Optional. When converting APIs, apply the configuration settings specified in the config.yml file that is stored in the same directory as the AMU. Parameters from Table 1, Migration configuration settings. Optional. Follow the format shown in Table 1, and prefix each parameter with the -- symbol and leave a blank space before the next parameter as shown in the example command. - Store the settings in the config.yml migration configuration file.
- Review the ported artifacts.
The API conversion process annotates the YAML file and logs with information regarding the artifacts that it attempts to convert. For cases where additional information is available or further action is required, the YAML input file and logs contain links to documentation.
Review the entire draft output YAML file for conformance, performance, and errors. Review the log files for messages about any manual actions that might be needed. For more information, see Reviewing APIs converted to DataPower API Gateway. By default, all changes that the migration utility makes when rewriting APIs are logged as common.
Because of differences between the programming models of v5-compatible APIs and DataPower API Gateway APIs, the command might not be able to convert all items; you might need to manually convert the failed items. In these cases, messages generated by the
apicm archive:port-to-apigw-v10
command provide links to documentation that provides more details about changes you must make for the items to be compatible with DataPower API Gateway.