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.

You upload the extension .zip file to an API Connect Gateway service, and enable the extension, as described in Configuring your Gateway server extensions.

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:

Log in to the DataPower administrative user interface; for the Graphical Interface, select WebGUI rather than Blueprint Console.
Switch to the DataPower application domain for API Connect if necessary.
Under Files and Administration, click File Management.
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:

Uses the top and configure terminal commands to reset CLI processing.
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.
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.
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: