Gateway extension guidelines - DataPower Gateway (v5 compatible)

Before you develop your extensions to the DataPower Gateway (v5 compatible), consider these guidelines.

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

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

You can download sample gateway extensions from https://github.com/ibm-apiconnect/dp-extensions.

You can create DataPower Processing Rules that can extend the enforcement behavior of the IBM® API Connect Gateway server at the following locations:

pre-request extension:
- Before the Gateway server begins to use the policies in the assembly to process the request.
post-request extension:
- After the Gateway server processes all of the policies in the assembly up to the proxy policy, if a proxy policy is used.
- After the Gateway server processes all policies in the assembly, but before any catch logic is processed, if a proxy policy is not used.
post-response extension:
- After the Gateway server processes all of the remaining policies in the assembly after the proxy policy (including catch logic), but before the response is returned to the client application, if a proxy policy is used.
- After the Gateway server processes the catch logic, but before the response is returned to the client application, if a proxy policy is not used.
post-error extension:
- If an error occurs, then before the Gateway server returns the error response to the client application.

To configure the Gateway server to call your extension Processing Rule, you must create an XML file that indicates the extension location and Processing Rule name. For example,

<extensions>
<extension location="pre-request">CustomRule1</extension>
<extension location="post-request">CustomRule2</extension>
<extension location="post-response">CustomRule3</extension>
<extension location="post-error">CustomRule4</extension>
</extensions>

The <extension> element entries are optional for any of the locations. Refer to the Gateway server Extension schema for the XML file syntax.

An extension Processing Rule can be applied to a specific organization or to all of the organizations and Catalogs. If the <extension> element does not have a tenant attribute, then the <extension> element is applied to all of the organizations. The following example shows an <extension> element without a tenant attribute.

<extension location="post-error">gen_error_handling</extension>

To apply an extension Processing Rule to a specific organization, enter the organization name as the value for the tenant attribute in the

<extension>

element. The following example shows an <extension> element with a tenant attribute value of organization1.

<extension location="post-error" tenant="organization1">organization1_error_handling</extension>

If you want to exclude a specific organization in an extension Processing Rule, enter the organization name as the value for the tenant attribute in an empty <extension> element. Add the empty <extension> element immediately after the custom rule <extension> element that you want to exclude the organization from. The following example shows an empty <extension> element with a tenant attribute value of organization1.

<extension location="pre-request">a_specified_CustomRule</extension>
<extension location="pre-request" tenant="organization1"></extension>

Important: An extension Processing Rule with a specified tenant attribute takes precedence over an <extension> element that applies to all of the organizations. Also, only one extension Processing Rule is applied to each extension location.

This XML file must be saved to the following location and included in your DataPower exported configuration .zip file:

local:///ext/extensions.xml

There can be only one DataPower exported configuration .zip file added to a Gateway server in API Connect.

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.
Do not use Gateway server extensions to modify objects that cause the apic-gw-service object to restart, such as TLS Profiles, and Gateway Peering. Extensions that cause the apic-gw-service object to restart, lead to unpredictable behavior in the Gateway service.

DataPower configuration restrictions

All Processing Rules have read access to the INPUT context.

Processing Rules must not rely on context variables that are created by the IBM Gateway server enforcement configuration, because those configuration variables might change in the future.

All Processing Rules except Before Request can transform or alter the message flowing through the Gateway server. Ensure that the Processing Rule returns the desired message output context back to the Gateway server at the end of processing.

To avoid name conflicts, all DataPower configuration object names prefixed with webapi are reserved for IBM use.

The following folders cannot be modified:

local:///isp/*
local:///gwapi/*

As a best practice, avoid adding asynchronous actions in your custom Processing Rules because they increase the use of memory per transaction.