Plugins overview

Overview

Plugins can be installed to expand the capabilities of DSAPI APIM Gateway, APIM Management API (mAPI), AM, or Alert Engine (AE). They can customize the component’s behavior to satisfy needs and technical constraints.

Types of Plugins

The table below lists the different types of plugins you can use with APIM and the component(s) they can be plugged into, respectively:

Deploying Plugins

Deployment

Deploying a plugin is as easy as copying the plugin archive (zip) into the dedicated directory. By default, you need to deploy the archives in ${DSAPI_HOME/plugins}. Refer to APIM Gateway Configuration for more information on modifying the directory structure.

Discovery and Loading

Plugin discovery and loading occurs regardless of APIM license type. If a plugin is not included with your license, then it will be loaded but it will not be functional.

Phase 1: Discover Plugins

When APIM starts, all plugin zip files are read from the list of plugin directories set in the dsapi.yaml configuration file.

If duplicates are found (same type and ID), the most recent file is kept regardless of the plugin's version. This allows for easily overriding plugins.

Plugin override circumvents the need to remove plugins to use a newer version, which is a huge benefit for Kubernetes deployments via DSAPI's Helm Chart. This also benefits plugin developers, as they can pack and copy an updated plugin without having to script the removal of the old version.

Phase 2: Load Plugins

After APIM finishes traversing the plugin directories, the plugins are loaded.

Plugins are immediately initialized by a specialized handler. If an error occurs while unpacking a plugin zip file, the faulty plugin is ignored. An error will be reported in the logs and the loading of the remaining plugins will resume.

The loading process is sequential and adheres to the following order based on plugin type:

1. Cluster
2. Cache
3. Repository
4. Alert
5. Cockpit
6. Any other types

The rest of the plugins are loaded in no particular order, except if they have dependencies. If a plugin depends on another plugin, that takes precedence over type ordering.

For example, if plugin1 (type:cluster) depends on plugin2 (type:cache) which depends on plugin3 (type:alert), then the plugins are loaded in the following order:

• plugin3 (because plugin 2 depends on it, even if it is #4 in the type priority list)
• plugin2 (because plugin 1 depends on it, even if it is #2 in the type priority list)
• plugin1

Custom Plugins

Overview

DSAPI API Management (APIM) plugins extend and customize component behavior to meet your strategic needs. Each APIM distribution includes a default set of plugins. You can also deploy additional DSAPI-maintained and third-party plugins from the plugin marketplace.

Common Structure

Plugins follow a common structure:

                        -----------------
                        .
                        ├── pom.xml
                        ├── README.md
                        └── src
                            ├── assembly
                            │   └── <plugin>-assembly.xml
                            ├── main
                            │   ├── java
                            │   │   └── <main java files>
                            │   └── resources
                            │       └── plugin.properties
                            └── test
                                └── java
                                    └── <test java files>
                        -----------------
                            

Below are the different key files:

pom.xml

DSAPI projects are Maven-managed. A plugin project is described via the Maven Project Object Model file.

README.md

Each plugin should be documented by a dedicated README.md file that contains comprehensive information related to the use of your plugin.

<plugin>-assembly.xml

To integrate with the DSAPI ecosystem, a plugin needs to be deployed with a given file structure. The <plugin>-assembly.xml file is the Maven Assembly descriptor used to build the distribution file, which has the following structure:

                        -----------------
                        .
                        ├── <main Jar file>.jar
                        └── lib
                        -----------------
                            

The different files/folders are described below:

.jar

The main .jar file of each plugin contains information on the business behavior and the plugin descriptor file.

lib/

This directory contains all of the plugin's external dependencies (non-provided-scope Maven dependencies).

plugin.properties

The plugin.properties file is the plugin descriptor, which acts as an ID card and is read by APIM Gateway during the plugin loading process. The descriptor includes the following parameters: