DataPower API
Gateway

Gateway extension guidelines - DataPower API Gateway

Before you develop your extensions to the DataPower® API Gateway, consider these guidelines.

Note: These guidelines apply to the DataPower API Gateway. If you are using the DataPower Gateway (v5 compatible), see Gateway extension guidelines - DataPower Gateway (v5 compatible).

For information on the different types of gateway, see API Connect gateway types.

Introduction

You apply an extension to a DataPower API Gateway by uploading one or more .cfg files that define the required extension behavior. These .cfg files contain DataPower API Gateway CLI commands. For details of the full set of CLI commands that are available, see the DataPower API Gateway CLI command documentation.

You package the .cfg files in a .zip file, together with any additional required files that are referenced from CLI commands; for example, a .json file that contains the OpenAPI definition for an API. The .cfg files are processed in alphanumeric order by file name.
Note: All the .cfg files must be at the root of the .zip file. If you are attempting to use an API Connect Version 2018 gateway extension that has files in sub-directories, see Gateway extensions manifest for information on how to deploy multiple extensions in a single package.

You upload the extension .zip file to an API Connect Gateway service, and enable the extension, as described in Configuring your Gateway server extensions. Gateway server extensions can be deployed without having to restart the DataPower API Gateway.

To control how gateway extensions are applied to the DataPower API Gateway, you can include a Gateway extensions manifest as a manifest.json file. The manifest allows you to deploy multiple extensions of different types in a single package. For more information, see Gateway extensions manifest.

Using CLI commands in a Gateway extension

Although you can use any DataPower API Gateway CLI commands in your extension .cfg files, typically you use commands that modify API Connect objects that have previously been deployed to the DataPower API Gateway.

When API Connect objects are deployed to a DataPower API Gateway, .cfg are created on the Gateway that define the configuration of those objects. By examining those .cfg on the Gateway, you can determine the precise names of API Connect objects that you want to modify, and the current values of the properties of those objects. You can access these .cfg files by completing the following steps:

  1. Log in to the DataPower administrative user interface; for the Graphical Interface, select WebGUI rather than Blueprint Console.
  2. Switch to the DataPower application domain for API Connect if necessary.
  3. Under Files and Administration, click File Management.
  4. Expand the temporary: folder to locate the .cfg files. The files for API Connect objects are named according to their containing provider organization and Catalog, as follows:
    20.provider-org-name_catalog-name_collection.cfg

    The prefix 20 controls the position of the file in the overall processing sequence, which is in alphanumeric order by file name.

    CAUTION:
    • Do not modify these files directly in the DataPower API Gateway file system, use the gateway extension mechanism described on this page.
    • Do not apply gateway extension modifications to configuration in the local:/config-sequence.cfg file.

Example 1 - change the scope of the rate limit for a Plan

Suppose the DataPower API Gateway configuration for a Plan has the following CLI command:
api-plan myorg_sandbox_financial-services_1.0.0_basic
The api-plan command has the following syntax:
api-plan plan_name
and creates a Plan of the specified name, or modifies a Plan of the same name if it already exists. By using the specified name, you can add api-plan commands in your Gateway extension .cfg files to modify the Plan.
Note: The names of API Connect objects in the DataPower API Gateway configuration are derived from their configuration in API Connect. For example, a Plan name has the following structure:
provider-org-name_catalog-name_product-name_product-version_plan-name
where:
  • provider-org-name is the name of the provider organization.
  • catalog-name is the name of the Catalog in that provider organization.
  • product-name is the name of the Product that contains the Plan.
  • product-version is the version of the Product.
  • plan-name is the name of the Plan.
The default scope to which a Plan rate limit applies is per application. To change this setting on the Plan in this example, so that the rate limit scope is per client ID, add the following command to a .cfg in your Gateway extension:
api-plan myorg_sandbox_financial-services_1.0.0_basic
  rate-limit-scope per-client-id
exit
For more information on configuring Plans by using DataPower API Gateway CLI commands, see API Plan commands.

Example 2 - add a path to an API definition

The .cfg file in this example performs the following actions:
  1. Uses the top and configure terminal commands to reset CLI processing.
  2. Uses the api-operation command as follows:
    1. Creates a new operation called bank_branches_get_operation.
    2. Uses the reset command to set all properties to their default values.
    3. Sets the operation method to GET.
  3. Uses the api-path command as follows:
    1. Creates a new path called bank_branches_path.
    2. Uses the reset command to set all properties to their default values.
    3. Sets the path URL segment to /details.
    4. Adds the previously created operation bank_branches_get_operation to the path.
  4. Uses the api-definition command as follows:
    1. Modifies the existing API definition called myorg_sandbox_myapi_1.0.0.
      Note: The name of the API definition was derived from its configuration in API Connect when it was published to the DataPower API Gateway, and has the following structure:
      provider-org-name_catalog-name_api-name_api-version
      where:
      • provider-org-name is the name of the provider organization.
      • catalog-name is the name of the Catalog in that provider organization.
      • api-name is the name of the API definition in API Connect.
      • api-version is the version of the API.
    2. Adds the previously created path bank_branches_path to the API definition.
      Note: The reset command is not used here because that would reset all the current settings on the myorg_sandbox_myapi_1.0.0 API definition, whereas the requirement is to add a new path to the existing configuration of the API definition.
The .cfg file is as follows:
top; configure terminal

api-operation bank_branches_get_operation
  reset
  method GET
exit

api-path bank_branches_path
  reset
  path "/details"
  operation bank_branches_get_operation
exit

api-definition myorg_sandbox_myapi_1.0.0
  path bank_branches_path
exit
For more information on the DataPower API Gateway CLI commands used in this example, see the following pages:

Gateway extension limitations

This section details the limitations of the extensions to the DataPower API Gateway.
  • User-defined policies that use or reference a newly advertised policy require a restart of the API Connect Gateway Service and the deploy type must be set to deferred.
  • Deleting an extension that contains a user-defined-policy-yaml type extension does not delete the reference to the policy in the apic-gw-service object. The DataPower API Gateway leaks the memory used to create the policy objects and does not remove them from the palette until a restart. To work around this, send an apic extensions:update command with an extension that does not contain these extension types, then send the apic extensions:delete command.
  • v5 policies that modify files outside of the /policy directory are not supported. If any v5 policies modify files outside of the /policy directory, API Gateway retains only the first version of the file in the first policy in the database and removes any duplicates.
  • v5 policy object references to the local:// directory are not rewritten correctly. Modify the object references in these policies to use the local:/// directory.
  • If files or objects that are in use and referenced by other objects are removed, errors can be generated that are difficult to troubleshoot.
  • It is possible to delete an extension that is referenced by published APIs.
  • Extra assembly functions may be present in the DataPower configuration, even if they are not specified in the deploy-policies section of the Gateway extension manifest. Using these functions without declaring them in the deploy-policies section is not supported.
  • A policy yaml file is required to advertise the user-defined-policy type to the API Manager.
  • A user-defined-policy-yaml type extension must contain a properties section.