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

  1. 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.

    1. 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/.

    2. 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.

  2. 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).

    Example config.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 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-v10 sets up the custom policies for pushing to API Gateway, but does not do the pushing. If global scope is used, archive:push-v10 of the admin organization will push all custom policies associated with the configured gateways. If catalog scope is used, then the archive:push-v10 of the admin organization will initialize the custom policies on the gateway. A subsequent archive: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, 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 v5-compatible gateway.

    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-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 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.

    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.
    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 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.

  3. 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 (the archive: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 the port command on any subdirectory within the unpacked /cloud-v10 directory could leave the directory in an inconsistent state, and cause the subsequent archive: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 the archive:push-v10 command to push them all to the DataPower API Gateway in a second operation.

    Table 2. Parameters for the port command
    Parameter 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.
  4. 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.