Migrating v5 APIs to v10 API Gateway format

You can convert API Connect v5 APIs to the format required by the DataPower API Gateway in v10.

About this task

Converting APIs to the API Gateway format is a two-step process: make a first pass with the migration utility, and then resolve any issues with manual modifications.

Note: If you are migrating your APIs to a DataPower v5-compatible Gateway, skip this step because there is no need to convert your APIs.

The migration utility generates an annotated YAML file and logs with information regarding the artifacts that it attempts to convert. Because of differences between the programming models of v5 APIs and v10 API Gateway APIs, the migration utility might not be able to convert all items. In these cases, messages generated by the apicm archive:port-to-apigw command provide links to documentation with more details about changes you must make by manually editing the API definitions.

Procedure

  1. Automatically convert the APIs with the migration utility by running the following command, where cloud is the directory where the unpacked v5 Public Cloud data resides:
    ./apicm archive:port-to-apigw /cloud
    Note: On Windows: open a command window with Administrator privileges, and omit the "./" from the command.

    When you run the command, all artifacts within the cloud folder structure are ported to v10 configuration, including APIs, Products, OAuth providers, custom policies, subscriptions, and so on.

    Usage notes:
    • Specify migration configuration parameters using either a YAML configuration file or with parameters on the command line, but not both. For information about configuration parameters, see Configuration parameters for migrating APIs.
    • By default, all changes that the migration utility makes when rewriting APIs are logged as comments within the API YAML file. You can use the enable-api-logging parameter to disable logging of these changes, as in the following example:
      ./apicm archive:port-to-apigw /cloud --enable-api-logging=false
    • Multiple runs of the command on the same cloud folder will skip artifacts that have already been converted.
    • If you decide to rewrite one API at a time, you can replace cloud with the path to the API definition in the command.

      With this approach, you cannot use the migration utility to push the API to the v10 deployment. Instead, use the toolkit or the API Manager in v10 to manually import the API definition.

    Because of differences between the programming models of v5 APIs and v10 DataPower API Gateway APIs, the migration utility might not be able to convert all items. You might need to port these items to the API Gateway. In these cases, messages generated by the conversion process include links to documentation that provides more details about changes you must make in the next step for these items to be compatible with DataPower API Gateway.

  2. Review the conversion results and make any manual changes to the APIs as needed.

    The conversion produces an output YAML file, which you can review for information on API conformance, performance, and errors. Review the log files for messages about any manual actions that might be needed. For information on reviewing the results and modifying the migrated APIs, see Reviewing and correcting migrated v5 APIs.