Gateway extension guidelines - DataPower API Gateway

Use API Gateway extensions to customize and configure the DataPower application domain in ways that are not possible from the API Manager UI.

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.

Some common uses of API Gateway extensions are:
  • Adding other DataPower services to the application domain.
  • Deploying user defined policies.
  • Deploying v5 emulation policies.

The extension structure is a zip file that contains a manifest file and one or more extension implementation files that the manifest file references. See Gateway extensions manifest for details on the manifest file JSON structure as well as the supported implementation types.

  • gateway_extension.zip
    • manifest.json
    • extension_implementation_1.zip
    • extension_implementation_2.zip

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.

Gateway extension limitations

This section details the limitations of the extensions to the DataPower API Gateway.
  • If you use an extension to create a user-defined policy and then delete the extension, the extension is removed from the filesystem, but the configuration sequence is not triggered to clean up related files. For the policy to be cleaned up, you must send a modified extension that explicitly removes the user-defined policy from apic-gw-service, as in the following example.
    apic-gw-service
    no user-defined-policies udp-basic_1.0.0
exit
    Note: This limitation does not apply only to user-defined policies, but any object customization that adds a reference to another object.
  • user-defined-policy-yaml policies that use or reference another policy can be deployed only after the referenced policy has been advertised to API Manager. The deploy type must be set to deferred and the Gateway Service must be restarted.
  • v5 policies that contain files outside of the /policy directory are not supported. If multiple v5 policies reference the same file outside the /policy directory, the last applied policy will overwrite the file and will be used by all policies that reference it. Removing any policy that contains the file will cause the file to be deleted and may cause errors for the remaining policies that use it.
  • If an extension contains or references objects and files that are also referenced by other objects outside of the extension, deleting the extension can cause errors that are difficult to troubleshoot.
  • It is possible to delete an extension that is referenced by published APIs. This may cause those API requests to return errors.
  • For an extension type of user-defined-policy, extra assembly functions may be present in the DataPower import .zip file, even if there is no .yaml file to indicate their presence. Using these functions without declaring them using a .yaml file is not supported. A policy .yaml file is required for each policy you want to advertise to API Manager.
  • Extension type user-defined-policy-yaml may leak generated Gateway script .js files in temporary:/js/ or .xslt files when deleted.
  • Extension types that use SOMA imports must use new objects with no overrides. If you override a singleton or shared object using an extension of this type, then the object will not be restored to its previous state when the extension is deleted, and those objects may be missing after the extension is deleted. You must then restore any needed objects.