Apiman Plugins

Plugins are identified by their Maven coordinates (groupId, artifactId, version, classifier, type). The classifier and type are optional. If the type is not specified when loading a plugin, Apiman will assume war.

When loading a plugin for use, Apiman will first check for the plugin in the local user’s .m2 directory. This is useful when running Apiman during development, but is unlikely to be available in a production environment. If the plugin cannot be found locally, Apiman will attempt to download it from a remote repository such as Maven Central.

This all means that when testing your plugin locally, you can simply use Maven to install it into your local .m2 directory and then ask Apiman to load it.

Now that you know how to create an Apiman plugin, you might be wondering what you can actually do with it!

The most important purpose of a plugin is to provide additional Policies that can be used when configuring Plans, APIs, and Client Apps in Apiman.

Although Apiman comes with a set of useful built-in policies, it is often necessary for users to provide their own custom policies. The best way to do that is to create a plugin that provides such policies.

In order to provide a custom policy from a plugin, several things are needed:

The next few sections explain each of these elements further, but note that they are all included in the Apiman plugin WAR.

A policy implementation is the Java code that is executed by the API Gateway when a managed API request is made. This is the bread and butter of the API Gateway; its primary purpose.

For each request, the API Gateway creates a chain of policies that must be executed before proxying the request to the back-end API implementation.

Each of the policies in that chain is an implementation of the IPolicy interface.

The policy implementation is what allows the API Gateway to execute the policy at runtime.

But how does the API Manager know about the policy so that users can add it to a Plan, API, or Client App from within the User Interface? The answer is that the plugin must also include a Policy Definition JSON file for each policy it is providing.

A plugin definition is a JSON file that must be located within the plugin archive here:

The plugin definition file takes the following form:

The most important thing to get right in this file is probably the policyImpl. This is the information that the API Manager will use when it tries to instantiate the policy implementation at runtime.

For policies that come from plugins, the format of the policyImpl is:

An example of what this string might look like if you cracked open a valid Apiman plugin and had a peek at one of its policy definition files is:

When building your plugin using the recommended maven configuration documented in the Using Maven to Create a Plugin section, it is extremely convenient to simply let Maven set the values for you:

You may be wondering how the configuration information specific to a Plan, API, or Client App is managed.

Since the same policy implementation instance is used for all requests, unique configuration appropriate to a particular request must be passed to the policy implementation when it is executed. This configuration is created in the API Manager user interface when adding the policy to a Plan, API, or Client App.

Policy configuration takes the form of string data that is ultimately included when publishing an API to the API Gateway. That string data is parsed into a Java object via the parseConfiguration on the IPolicy interface and then passed to the policy during execution.

The string data is created in the API Manager user interface, either by interacting with a Policy Configuration Form contributed by the plugin, or (if no form is included in the plugin) by a default configuration form (a simple text area).

The first thing you will need is to include the appropriate maven dependencies in your project’s pom.xml file. There is a single additional dependency that you will need (make sure to import it using the test maven scope):

Once you have imported the appropriate dependency, you can go ahead and create a JUnit test case. The only additional thing you need is to annotate your test case appropriately and make sure your test case Java class extends the framework’s ApimanPolicyTest base class.

The following annotations can then be added to your test:

The @TestingPolicy annotation is always placed at the class level, but the @Configuration annotation can either be global or specified at the test method level.

These annotations tell the apiman Policy Testing framework what policy you want to test and the policy configuration you want to use when testing, but you still need to actually send requests to an "API". This is done using the send(PolicyTestReqest) method defined by the base class.

The send() method allows you to send a request (that you build) to the mock back-end API governed by your policy. By default, the mock back-end API is a simple "echo" API that responds to all requests with a JSON payload describing the request it received (more on how to override this default functionality later).

The send() method requires that you create and pass to it a valid PolicyTestRequest object. This can be created using the PolicyTestRequest.build() method. You can set the request’s type, resource path, request headers, and body.

If the request is successful, then a PolicyTestResponse object will be returned, and you can perform assertions on it. If there is a policy failure, then the send() method will throw a PolicyFailureError.

Here is a full example of everything working together:

Sometimes the echo API is not sufficient when testing your custom policy. Perhaps the custom policy is more tightly coupled to the API it is protecting.

In this case, you may want to provide your own custom back-end API mock implementation. This can be done by simply annotating either the class or an individual test method with @BackEndApi.

If you use @BackEndApi, then you must supply the annotation with a class that implements the IPolicyTestBackEndApi interface.

Here is an example of what this might look like in a test:

In this example everything works as it did before, but instead of responding with an Echo Response, the send() method will return with a custom response (as created and returned by the provided custom back-end API implementation).

When developing a custom plugin policy, it can be cumbersome to have to uninstall and reinstall the plugin every time you make a change. Hopefully, unit testing will help you quickly iterate your plugin policy implementation, but there are times when testing in a live environment is necessary.

At runtime, the API Gateway installs plugins from the local .m2 directory. If the plugin is not found there, Apiman attempt to find and download the plugin from the configured remote Maven repositories.

Typically, the API Gateway will load and cache the plugin the first time it is used. However, if your plugin version ends with -SNAPSHOT, then Apiman will reload it every time it is used.

As a result, you can quickly iterate changes to your plugin policy using a live apiman environment by doing the following:

Because the version of your plugin ends with -SNAPSHOT, the API Gateway will not cache it, but instead will reload it each time you do step #4. This allows you to quickly make changes, rebuild, and re-test with a minimum of additional steps.

You can use the Plugin Management UI to uninstall a plugin. When you do this, any API that is already configured to use the plugin will continue to work. If you wish for an API to no longer use a plugin policy, you must remove the policy from the API as a separate step.

Often, new versions of a plugin may become available. When this happens you can use the Plugin Management UI to upgrade a plugin to a newer version.

Please note that this will not automatically upgrade any API using the older version of the plugin. Instead, to upgrade an API to use the newer plugin policy, you will need to remove the old policy configuration and re-add it. This will cause the API to pick up the newer version.

Of course, any new APIs will always use the new version.

The procedure for creating a plugin to hold your custom component is exactly the same as already described in the Creating a Plugin section above.

Once you have created your plugin, including a custom implementation of a core component is simply a matter of creating a Java class that implements the appropriate component interface.

Let’s try an example.

By default, Apiman stores API Gateway configuration in Elasticsearch. The component responsible for this is called ESRegistry, and it implements this interface:

Let’s imagine you would rather store the API Gateway configuration information into MongoDB instead of Elasticsearch. Since we don’t support a MongoDB registry, you would need to implement your own and contribute it via a plugin.

Simply create a new plugin and include in it the following Java class:

Now that you have a custom component built and included in a plugin, you will need to make sure that the plugin is available to your server.

You can do this by deploying the plugin artifact to a Maven repository and then making that repository available to Apiman by adding its URL to the following property in apiman.properties:

Simply add your organization’s maven repository to that (the value can be a comma separated list of URLs).

Alternatively, you can make sure your plugin is installed in the ~/.m2 directory on the machine that is running your server. You can use mvn install to accomplish this, or by copying it across as part of your build process.

Next, simply enable the custom component implementation by updating your apiman.properties file like this (for example):

The most important part above is the format for the registry itself. It might look something like this:

Finally, the set of properties prefixed with apiman-gateway.registry will be processed and passed to your MongoDbRegistry class’s Map constructor if one is provided. The map that is passed to the constructor will contain the following:

This section lists all/most of the available customization points available within Apiman. These represent all the core Apiman components that can be replaced by custom implementations provided via plugins.

Apiman allows users to import one or more API (to be managed) from a globally configured API Catalog. This feature makes it easier to manage APIs that are "known" by providing API catalog entries which include information such as the endpoint, endpoint type, etc. Importing an API from the catalog brings those fields into Apiman, so that users don’t have to manually set them.

When installing Apiman, a custom API Catalog can be easily configured by creating a properly formatted JSON file with all the appropriate information included.

See the Installation Guide for more information about configuring a JSON based custom API Catalog.

Additionally, it is possible to completely replace the API Catalog implementation, providing your own custom version which retrieves API information from wherever you like.

Like most Apiman components, a custom API Catalog implementation is simply a Java class which implements a specific interface and is enabled/configured in the apiman.properties file.

The interface you must implement is io.apiman.manager.api.core.IApiCatalog and looked like this at the time of this writing:

The catalog is simply one method which returns a list of AvailableApiBean objects.

That class looks something like this:

Create an implementation of this interface and include it in a valid Apiman plugin.

Once the plugin is created with your class inside, configure the catalog in apiman.properties like this:

If your implementation class has a constructor that accepts a Map<String, String>, then Apiman will pass the set of applicable configuration properties it finds in apiman.properties when the class is instantiated.

Whenever Apiman stores data, either in the API Manager or in the API Gateway, it uses a Data Encrypter to first encrypt potentially sensitive information.

Examples are:

By default, the Apiman quickstart comes with a default encrypter that performs very simple synchronous encryption on this data. However, because it is built-in, it is not secure (it uses a hard-coded encryption key, for example). Depending on your security needs, you may wish to implement a custom data encrypter - one that is more secure and perhaps uses externally configured keys.

In order to provide a custom data encrypter, the interface you must implement is io.apiman.common.util.crypt.IDataEncrypter.

This same interface is used in both the API Manager and the API Gateway.

The IDataEncrypter interface looks something like this:

When creating a custom implementation, all you need to do is provide a Java class which implements the above interface inside a valid apiman plugin.

Once the plugin is created with your class inside, configure the data encrypter in apiman.properties like this (note: it only needs to be configured in a single place for both the Manager and Gateway):

Remember, if your implementation class has a constructor that accepts a Map<String, String>, then Apiman will pass the set of applicable configuration properties it finds in apiman.properties when the class is instantiated.

In the example above, your DataEncrypterImpl class will be instantiated, with a Map passed to its constructor containing the following:

When a policy fails (or an error occurs) in the API Gateway, the result of the failure must be sent back to the calling HTTP client.

By default, Apian has a particular format (either JSON or XML depending on the Content-Type of the API being called) it uses when responding to the client.

However, some installers may prefer a custom format. This can be accomplished by providing a custom implementation of io.apiman.gateway.engine.IPolicyFailureWriter and/or a custom implementation of io.apiman.gateway.engine.IPolicyErrorWriter.

When creating a custom implementation, all you need to do is provide a Java class which implements the above interface(s) inside a valid Apiman plugin.

Once the plugin is created with your class inside, configure either the failure writer, the error writer, or both in apiman.properties like this:

Remember, if your implementation class has a constructor that accepts a Map<String, String>, then Apiman will pass the set of applicable configuration properties it finds in apiman.properties when the class is instantiated.

In the example above, your DataEncrypterImpl class will be instantiated, with a Map passed to its constructor containing the following:

Whenever a new user is added to Apiman, a record is added for her in the API Manager data store. No additional steps are taken by default. However, in some cases you may want to perform some specific bootstrapping tasks when a new user is created, for example:

This can be done by providing your own custom implementation of io.apiman.manager.api.core.INewUserBootstrapper:

When invoked, the boostrap method is given the UserBean of the user being created as well as the storage object. The storage object can be used to create additional entities for the user, such as new organizations or new memberships in roles.

When creating a custom implementation, all you need to do is provide a Java class which implements the above interface inside a valid Apiman plugin.

Once the plugin is created with your class inside, configure the user bootstrapper in apiman.properties like this:

Remember, if your implementation class has a constructor that accepts a Map<String, String>, then Apiman will pass the set of applicable configuration properties it finds in apiman.properties when the class is instantiated.

In the example above, your DataEncrypterImpl class will be instantiated, with a Map passed to its constructor containing the following: