Frequently asked questions about migrating APIs to API Gateway

Answers to some of the most frequently asked questions about migrating APIs to API Gateway.

What is port-to-apigw?
port-to-apigw is a command in the API Connect migration utility that converts all APIs, products, subscriptions, OAuth providers, and custom policies into v10 native API Gateway artifacts. These newly created artifacts live side-by-side with the original v5-compatible artifacts, and have -apigw appended to the end of the filename.

For more information, see Converting APIs to DataPower API Gateway.

When is it necessary to run the port-to-apigw command, and how do I use it?
Run this command if you are migrating to a v10 native API Gateway. Follow the migration steps that are appropriate for your v5 environment. For instructions on running the port-to-apigw command, see Migration steps. For information on configuring migration options, see Configuring migration options for DataPower API Gateway. For other information to help you optimize migration, see Migration considerations.
Why is the port-to-apigw command needed for migrating to v10 API Gateway?
The required fields, properties, settings, and configuration in v10 native API Gateway differs from v5-compatible mode. The port-to-apigw step in the migration process is needed to convert the artifacts to conform to the changes.
What is the difference between these terms: porting to API Gateway, port-to-apigw, and migration?
Porting to API Gateway describes what the port-to-apigw command does in the migration utility. Migration is the overall purpose of the migration utility. The port-to-apigw step is necessary for migrating to a v10 native API Gateway. Migration can be completed without the port-to-apigw step if you are migrating to a v10 deployment that uses only the v5-compatible DataPower Gateway.
What is v5 policy emulation and how does it work?
The v5 policy emulation layer allows both custom policies and the 1.0.x policies to run on the native v10 API Gateway. It is deployed automatically by the API Connect migration utility to the local:///isp folder of the DataPower appliance when a custom policy is found in the v5 backup, or if you specify a 1.0.x policy in the policy option for the port-to-apigw command. The deployment is first staged by the port-to-apigw command, and pushed by the archive:push command. Follow the steps as outlined in Migration steps.

Note that 1.5.x policies do not use v5 policy emulation, and exist only as native wrappers to the 2.0.0 implementation.

What is the purpose of the policy parameter options in port-to-apigw?
Input options allow you to customize your migration. If you want to use the native policies, such as invoke_2.0.0 instead of the default invoke_1.5.0-compatible option, you can select the appropriate option. However, using these options can result in migration errors that require manual changes to get your APIs up and running. If you want to be up and running quickly, it is best to use the default options for the input. The default options convert APIs in a way that is most backwards compatible with v5.

For more information about the migration configuration options, see Configuring migration options for DataPower API GatewayConfiguration parameters for migrating v5 APIs. For explanations of errors and other messages generated during migration and suggestions for manual changes to APIs, see Messages generated during conversion of APIs to DataPower API Gateway.

How do the v5 emulated policies invoke_1.5.0, proxy_1.5.0, xslt_1.0.0, and gatewayscript_1.0.0 work?
When the push step of the migration utility is completed, these policies will exist on the DataPower Gateway as assembly function objects. The 1.0.x policies call the v5 policy emulation layer in order to function as if they were v5 policies. The 1.5.x policies are wrapper policies to the 2.0.0 implementation. They call the 2.0.0 policies and exist only as a compatibility layer between the original v5 policy and the new 2.0.0 policy.
What is the difference between the 1.5.0 and 2.0.0 versions of the invoke and proxy policies, and the 1.0.0 and 2.0.0 versions of the gatewayscript policy? Why isn't the 2.0.0 version the default version?
The 1.5.x policy implementations are native wrappers to the underlying 2.0.0 implementation. They exist only to create a compatibility layer between the v5 policy and the APIGW native policy. The gatewayscript_1.0.0 policy uses v5 policy emulation to run as if it were on a v5 environment. The performance of the 1.0.x v5 emulation layer policies in API Gateway is the same or slightly better than the v5 and v5-compatible versions. The performance of 1.5.x policies is slightly slower than their corresponding 2.0.0 policies. You can inspect the 1.5.x wrapper implementation in Assembly Functions in DataPower Gateway.
Should I rewrite my GatewayScript policies?
Most GatewayScript policies do not require rewriting, as the native v10 API Gateway contains an enhanced compatibility layer that accepts most of the apim functions without modification. In most cases, GatewayScript policies require rewriting when they contain any of the following:
  • inline parameters
  • require(‘service-metadata’) and service variables associated with it
  • require(‘mgmt’)
  • require(‘fs’)
  • OAuth context variables
What is the optimize-gws option?
The optimize-gws migration option converts certain v5 gatewayscript functions to the native API Gateway implementation. This setting is optional because the compatibility layer already handles processing of original v5 gatewayscript functions. If set to true, the migration utility makes the following conversions:
  • apim.getvariable() is converted to context.get()
  • apim.setvariable() is converted to context.set()
  • hm.current.remove() is converted to context.clear()
What is the gateway-extension.zip file and how does it work?
After running the port-to-apigw command, a gateway-extension.zip file is located in the cloud/admin-org/availability-zones/default-availability-zone/gateway-services/<gateway-service> folder. This file is automatically generated by the migration utility during the processing of the port-to-apigw command. It contains a manifest.json file, and every custom policy under the gateway service that came from the v5 backup. The manifest.json file contains a list of custom policies to push, and backwards-compatible policies to advertise and make available for use by APIs. These backwards-compatible policies include invoke_1.5.0, proxy_1.5.0, xslt_1.0.0, and gatewayscript_1.0.0. During the archive:push steps of the migration process, this zip file is pushed to the API Manager as a gateway extension.

For more information, see Gateway extensions manifest.

How does the migration utility migrate custom policies?

Custom policies are migrated in multiple steps, depending on whether the custom-policies-scope option is set to global or catalog. Once custom policies are pushed to the DataPower Gateway, they use the v5 policy emulation layer that was unpacked into the local:///isp folder in order to run on the native v10 API Gateway.

When port-to-apigw is run, the following steps are performed depending on the custom-policies-scope setting.

  • If custom-policies-scope is set to global, and there are no duplicate custom policies with differing implementations, the custom policies under each gateway service are bundled in a gateway-extension.zip file. This zip file contains a manifest.json file that describes the contents. The gateway-extension.zip file is copied to the admin-org gateway-service folder. These steps are performed automatically when port-to-apigw is run. Next, you must push the admin-org during the archive:push step, which pushes the gateway-extension.zip bundles (one per gateway) to the API Manager using an internal APIC Toolkit gateway-extensions:create call. The custom policies within the bundle are advertised on the API Manager. The custom policies and compatible legacy policies are shown in the policy pallet in the API Manager Assemble UI. These custom policies are also in the DataPower filesystem in the local:/// folder. Note that if duplicate custom policies with the same name, version, and differing underlying implementation are found, the migration utility logs a message and automatically falls back to catalog scope to prevent the migration from failing.

  • If custom-policies-scope is set to catalog, the custom policies under each gateway service are bundled in a gateway-extension.zip zip file. This zip file contains a manifest.json file that describes the contents. The gateway-extension.zip file is then copied to the admin-org gateway-service folder. The custom policy definition files under each catalog are copied into the catalog-scoped-staging folder, where their gateway type is set to datapower-api-gateway. Next, you must push the admin-org during the archive:push step, which pushes the gateway-extension.zip bundles (one per gateway) to the API Manager using an internal APIC Toolkit gateway-extensions:create call. Note that the custom policies and compatible legacy policies are not visible in the policy pallet in the UI. You can see the custom policies in the DataPower filesystem in the local:/// folder. Before you can publish APIs that use these policies, you must push your provider-orgs during the archive:push step. The custom policy definitions as described earlier from the catalog-scoped-staging folder are then pushed to the API Manager automatically using an internal APIC Toolkit policies:create call. The APIs containing the newly migrated catalog-scoped custom policies are then published.
Note: The folders and zip files are created automatically, and you should not need to modify them. For instructions on the tasks you must perform, see Migration steps.
Should I set the custom-policies-scope option to global or catalog?
Global scope custom policies are visible to every catalog and org on the gateway. Catalog scope custom policies are visible only to the catalog that they were migrated from. If you plan to migrate to v10 with the intention of custom policy availability the same as it is on v5, then use the default catalog setting.
Why are my custom policies not showing up in the Assembly Editor policy palette?
See the following troubleshooting information: Custom policies not appearing in the policy palette after migration