An important feature of apiman is the ability to create plugins that can easily be added to the system in order to provide additional functionality.
Currently the only functionality that can be contributed through the plugin framework is new policies. Fortunately policies are also the most important aspect of apiman, as they are responsible for doing all of the important work at runtime.
An apiman plugin is simply a maven artifact, typically a WAR, with some plugin resources included.
When contributing a policy through a plugin, you will need to include at least a policy definition and policy implementation. It is also recommended, though optional, to include a policy configuration schema file, which will allow the user interface to generate a form when configuring an instance of the policy.
Since examples are always best, let’s take a look at the anatomy of an apiman plugin.
Anatomy of a plugin
The easiest way to create an apiman plugin is by creating a standard WAR maven project.
The layout of the project is very simple, with only the addition of an “apiman” directory under src/main. The “apiman” directory contains all of the plugin’s configuration files, and must get included in the artifact’s META-INF directory. To accomplish this, you can configure the project’s POM to include the directory appropriately. We recommend enabling filtering, so that maven property expansion occurs during packaging.
Within the apiman directory there are a number of configuration files. The most important file is the “plugin.json” file, which is required for all apiman plugins and contains meta-data that describes the plugin. This includes information such as the plugin name and description.
In order to contribute a policy, the plugin must contain a policy definition json file. These files are placed in the apiman/policyDefs folder. The policy definition file includes the following fields:
id - which uniquely identifies the policy
name - a friendly name for the policy, often displayed in the UI
description - a description of the policy
policyImpl - the Java class that implements the policy. This value must be properly formatted to include information about the plugin, and the fully qualified classname of the policy implementation.
icon - which is the name of a Font Awesome icon used when displaying the policy in the UI.
formType - the type of policy configuration UI form. You’ll most likely want to use JsonSchema as the value for this.
form - which is a relative path to the policy configuration UI form (in this case the JSON Schema that defines the configuration data format).
When using JsonSchema s the form type, you will need to include a JSON Schema formatted file. This file defines the format for the Policy’s configuration data, and allows the UI to generate a useful form to configure the policy in the UI. See the JSON Schema specification for more details about its capabilities. In the case of our demo policy, you can see that the JSON Schema is very simple - it just defines two top level properties called propertyOne and propertyTwo.
Finally, you will need some Java code for the policy implementation itself. The policy java class must implement the apiman IPolicy interface. In this demo you can see that the DemoPolicy class actually extends a class called AbstractMappedPolicy, which is a useful base class that uses Jackson to parse the configuration data into a java bean. This is a convenience - your policy can of course simply implement the IPolicy interface. In that case you will need to implement parsing of the configuration data into a Java object of some kind however you choose. However, we definitely recommend using the AbstractMappedPolicy because it makes it very easy to consume the configuration data at runtime.
Once all of these files are in place, simply use maven to build the project and install it into your local maven repository. Now let’s have a look at how to add the plugin to apiman and use it in one of our services.
Using the plugin in apiman
Let’s go ahead and log into the API Manager as an admin user. Once logged in, we can use the admin-only plugin UI to manage our plugins. Currently we don’t have any installed, so let’s go ahead and add the plugin we just built by clicking on Add Plugin.
Now we can fill out the relevant information on the form, which for an apiman plugin means identifying its maven groupId, artifactId, and version. That will allow apiman to find the plugin (either locally or in a remote maven repository) and install it.
Once installed, you will notice in the Policy Definitions page that our demo policy has been automatically added.
Next, let’s navigate over to a service that is waiting for us to add the demo policy. This is done the same as always, by clicking Add Policy and choosing the type of policy we wish to add.