apiman - Developer Guide


Are you interested in contributing to the development of apiman?Maybe you want to embed the project in your own solution?In either case this is the guide for you.

Developer Resources

This section describes a number of resources that are useful if you wish to contribute code to apiman.It is likely also a good starting point for those wishing to provide functionality by implementing a plugin, although more information about plugins can be found in the 'Plugins' section.

Source Code

The apiman source code is located in GitHub here:

Source code for the apiman policies can be found here:

Source code for the apiman project web site is here:

The official apiman docker files are currently here:

Issue Tracking

The apiman project uses JIRA to track issues such as bugs and feature requests. It’s a good place to start if you’re trying to figure out how to get involved!

Development Tools

We’re rather IDE agnostic, so contributors should feel free to use whatever tools they feel most comfortable with. At the time of this writing, the core apiman developers primarily use Eclipse Kepler.

The core apiman project is built using maven. Currently we recommend at least version 3.0.3.

And of course you’ll need to have git installed if you want to check out the code from github.

Building the Project

Building apiman should be a simple matter of doing a standard Maven build:

mvn clean install

This will do a full build of apiman and execute all unit tests. However, the result will not include a ready-to-run version of apiman. For that, you may want to try the following:

mvn clean install -Pinstall-all-wildfly9

This command will do a full apiman build, but will also download WildFly 9 and install apiman into it. The result will be a fully configured install of apiman running in WildFly. The location of this WildFly install will be here:


At this point you can test apiman by simply running WildFly 9 from the above location using a command something like this:

./bin/standalone.sh -b

Setting up a Development Environment

Because apiman is a fairly standard maven project, it should be relatively easy to import the project into Eclipse or IntelliJ IDEA. For now we’ll leave this as an exercise for the reader.


The basic architecture of apiman is fairly straightforward.There are several WARs that make up the default apiman installation.These include:

  • API Manager REST back-end (JAX-RS WAR)

  • API Manager UI (AngularJS/Hawtio WAR)

  • API Gateway Config (JAX-RS WAR)

  • API Gateway (Servlet WAR)

The API Manager REST back-end WAR is responsible for exposing a set of REST endpoints that make up the API Manager REST interface.The API Manager UI uses this REST API directly when the user manages the various entities in the data model.

The API Manager UI is a client-only AngularJS application.Aside from authentication related activities, this WAR only contains HTML, JavaScript, and CSS.The UI uses the browser to make direct, authenticated calls to the REST endpoints exposed by the API Manager REST back-end WAR.

The API Gateway Config exposes the standard apiman Gateway REST API so that the API Gateway can be remotely configured.This is the REST API that the API Manager uses whenever a user publishes an API or registers a Client App.It is responsible for configuring the API Gateway’s embedded Policy Engine.

The API Gateway is the primary runtime component of apiman and is implemented as a servlet that embeds the apiman Policy Engine.All requests to the API Gateway WAR are assumed to be intended for managed APIs previously published to it.


The easiest way to extend the functionality of apiman is by implementing an apiman plugin.This section details how this is done and what functionality can be extended or provided.

Creating a Plugin

An apiman plugin is basically a java web archive (WAR) with a little bit of extra sauce. This approach makes it very easy to build using maven, and should be quite familiar to most Java developers. Because a plugin consists of some resources files, compiled java classes, front-end resource such as HTML and javascript, and dependencies in the form of JARs, the WAR format is a natural choice.

The Plugin Specification File

In addition to the standard layout of a Java Web Archive, an apiman plugin must contain the following plugin specification file (which contains information about the plugin):


This 'plugin.json' file contains the basic meta-data that describes the plugin, and should be of the following format:

  "frameworkVersion" : 1.0,
  "name" : "Plugin Name",
  "description" : "A plugin description goes here.",
  "version" : "3.1.9"
  • frameworkVersion: Indicates the apiman plugin framework version this plugin is compatible with - this should simply be 1.0 for now (reserved for future use)

  • name: The name of the plugin.

  • description: The description of the plugin.

  • version: The plugin version.

If this 'plugin.json' file is missing from the plugin archive, then the plugin will fail to load.

Using Maven to Create a Plugin

One benefit of using WAR as the format of an apiman plugin is that plugins can easily be created using Maven. This section will describe how this can be done. Note that you can use the following simple plugin as a reference if you prefer:

In order to create an apiman plugin using maven, simply create a new maven project and set its 'packaging' type to war.


Next, obviously feel free to include any dependencies you might need:

  <!-- apiman dependencies (must be excluded from the WAR) -->

You’ll want to make any apiman dependencies provided so that there aren’t any classloading conflicts when executing your code.

Finally, we recommend that you put your plugin.json file in the following location in your maven project:


Of course, any resoures in that location are not automatially included in the final WAR, so you should add the following markup to your pom.xml:


This markup will ensure that resources in the src/main/apiman folder will be included in the correct location in the WAR. Also note that resource filtering is enabled, which will make it easier to maintain your plugin.json file:

  "frameworkVersion" : 1.0,
  "name" : "My Plugin Name",
  "description" : "My plugin description.",
  "version" : "${project.version}"

Note that the 'version' of the plugin is set to ${project.version}, which will get automatically changed to the version of your maven project at build time.

Making Your Plugin Available to apiman

Plugins are identified by their Maven coordinates (groupId, artifactId, version, classifier, type). Note that 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.

You can configure additional remote repositories when you set up apiman. Please refer to the Installation Guide for details.

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. In production, the plugin will need to be available from a remote maven repository.

Contributing a Policy

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:

  • An implementation of IPolicy (Java code)

  • A policy definition (JSON file)

  • An optional policy configuration form that the API Manager UI will present to the user when configuring the policy

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

Policy Implementation

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.

Standard IPolicy

All policies must implement the IPolicy interface, consisting of several methods.

The apply method with ApiRequest is called during the request phase, and the apply with ApiResponse during the response phase:

void apply(ApiRequest request, IPolicyContext context, Object config, IPolicyChain<ApiRequest> chain);

void apply(ApiResponse response, IPolicyContext context, Object config, IPolicyChain<ApiResponse> chain);

The API objects, respectively, provide abstracted representations of the head of a request and response for a given conversation. These can be modified in any manner the implementor sees fit.

Policy instances are stateless, so it is not a good idea to use fields for any reason. The IPolicyContext can be used to pass information from the request phase to the response phase. Any state that must span multiple requests will need to use one of the policy components described in the Provided Components section.
Object parseConfiguration(String jsonConfiguration) throws ConfigurationParseException;

The final IPolicy method is used to parse JSON configuration into an arbitrary object configuration which will be passed in in its parsed form to doApply, where the implementor may cast it their native configuration object. This method will be invoked for each unique configuration of the policy.

For mroe information about policy configuration, see the Policy Configuration section below.

Indicating Successes

If a policy determines that the conversation can continue, chain.doApply should be signalled. Any modifications you wish to pass onto the next policy should be completed and included in the invocation.

Indicating Failures

If it is determined that a conversation should be interrupted for governance reasons (i.e. according to business logic and not exceptional), then chain.doFailure should be signalled. A useful PolicyFailure should be provided, which allows gateways to respond in a sensible way to the requestor.

The platform’s IPolicyFailureFactoryComponent can be used to generate failures. See the Provided Components section for more details on this component.
Handling Exceptions

As a factor of the asynchronous nature of apiman, any exceptions that may occur during the operation of a policy should be caught and explicitly handed to chain.doError. If exceptions are left uncaught, then it is possible that they will be lost.

IData Policy

Whilst standard policies are concerned only with the head of the conversation, it is also possible for policies to access and manipulate the body in transit. A data policy must implement the IDataPolicy interface.

Handling of data streams is a performance sensitive area, implementors should strive to be as efficient as possible and avoid any unnecessary interactions with the stream.

The getRequestDataHandler and getResponseDataHandler methods are the data corollaries of apply. Implementors must return IReadWriteStream streams, which apiman uses to write data chunks into policies, and the policies write data to subsequent policies:

IReadWriteStream<ApiRequest> getRequestDataHandler(ApiRequest request, IPolicyContext context);

IReadWriteStream<ApiResponse> getResponseDataHandler(ApiResponse response, IPolicyContext context);
Do not return an IApimanBuffer with a different native type than you received. Instantiate new buffers using the IBufferFactoryComponent (refer to Provided Components) and prefer append patterns where possible.

Implementors must explicitly hand each chunk onto apiman when they are finished interacting with it. A convenient way to achieve this is via AbstractStream<H>:

public IReadWriteStream<ApiRequest> getRequestDataHandler(final ApiRequest request, final IPolicyContext context) {
  return new AbstractStream<ApiRequest>() {
    public void write(IApimanBuffer chunk) {
      // Mutate chunk by appending a string.
      chunk.append("my modification");
      // We're finished: write the chunk back to apiman
      // using super.write().

    public void end() {
      // End of stream signalled, do cleanup, etc.
Do not mutate an IApimanBuffer once handed over. Immediately see

The request or response body will not begin streaming before the corresponding doApply has been called, however, it is still possible to interrupt the conversation during the streaming phase by signalling doFailure or doError.

Performance Considerations

Policies are amongst the most impactful elements of the system for performance. To minimise the impact of a policy implementors may wish to follow these guidelines:

  • Maintain as little state within a policy instance as possible.

  • Call doApply, doFailure or doError as soon as possible.

  • Data policies should interact with the data stream as efficiently as possible and prefer mutating in-place (especially with small changes).

  • If you are contributing a policy to apiman: implement any long-running tasks asynchronously (e.g. database calls); do not block the main thread (e.g. blocking futures, wait, sleep); use asynchronous techniques to interact with the outside world, such as callbacks.


Typically a policy implementation should minimize the number of third party libraries it depends on, but often times this is unavoidable. Plugins are isolated from one another, so it is a simple matter of including any required dependencies inside the plugin’s WAR archive in the standard location of:

You should make sure that any apiman dependencies you use (for example the apiman core module that contains the IPlugin and other necessary interfaces) are marked as 'provided' in your maven project so that they are not included in the plugin archive.


A policy’s logger can be accessed through the context objects provided to apply. Use getLogger with a class. The IApimanLogger interface provides the methods available for logging, with a variety of pluggable backends available to implement the functionality.


  public void apply(final ApiRequest request, final IPolicyContext context, final Object config,
          final IPolicyChain<ApiRequest> chain) {
      IApimanLogger logger = context.getLogger(getClass());
      logger.info("Hello, I am an info message in the request"); (1)
      logger.debug("Hello, I am a debug message in the request");
      logger.trace("I am powered by: %s", request.getHeaders().get("X-Powered-By"));

  public void apply(ApiResponse response, IPolicyContext context, Object config,
          IPolicyChain<ApiResponse> chain) {
      IApimanLogger logger = context.getLogger(getClass());
      logger.info("Response info message: %d", 42); (2)
1 Consult the interface’s javadoc for the full list of available methods.
2 Format string with arguments.


A few logging backends are provided, which should satisfy most user’s requirements.

In apiman.properties, provide a reference to the logger factory.


Those shipped in the project, are:

  • SLF4J: io.apiman.common.logging.slf4j.Slf4jLoggerFactory

  • Log4j2: io.apiman.common.logging.log4j2.Log4j2LoggerFactory

  • NoOp/Null: io.apiman.common.logging.impl.NoOpLoggerFactory

Ensure that the implementation is available on the classpath.

Custom Implementation

To provide your own implementation, you must implement IDelegateFactory and which should create instances your implementations of IApimanLogger. Ensure that your implementations are available on the classpath, and refer to Configuration to set the logger-factory to your IDelegateFactory,which will cause the registry to load your factory.

Example IDelegateFactory implementation

public class ExampleLoggerFactory implements IDelegateFactory {

    public ExampleLoggerFactory() {}
    public ExampleLoggerFactory(Map<String, String> opts) {} (1)

    public IApimanLogger createLogger(String name) {
        return new ExampleLogger(MyLoggerFactory.getLogger(name)); (2)

    public IApimanLogger createLogger(Class<?> klazz) {
      return new ExampleLogger(MyLoggerFactory.getLogger(klazz)); (3)
1 If you pass config options from apiman.properties to your factory, they will appear here.
2 MyLogger is an example of the logger you’re wrapping.
3 By class rather than string.

Example IApimanLogger implementation

public class ExampleLogger implements IDelegateFactory {
  MyLogger logger;

  public TestLogger() {}
  public TestLogger(MyLogger logger) {
    this.config = config;

  public void info(String message) {
    logger.message(message); (1)

  // And many more... (2)
1 Passing the message through to your logger.
2 Debug, trace, etc. Consult the interface.

Provided Components

All policy implementations have access to various resources at runtime. These resources are primarily accessed through the IPolicyContext object that is passed to the policy when it is executed. Along with the ability to set conversation-level attributes, the policy context is how you access Policy Components.

A Policy Component is simply a runtime component that a policy implementation may find useful. To access a component, use the 'getComponent' method found on the policy context, passing it the interface of the component you wish to use. The following components are available:

Component Name Description


Used to create a policy failure that is needed to call 'doFailure' on the policy chain (indicating that the policy failed).


Used to share state information across the conversation boundary.


Allows HTTP requests to be made from within a policy.


Supports standard quota/rate limiting behavior, maintaining the current number of requests.


Provides the ability to authenticate with an LDAP server and execute simple queries against it.


Enables querying of JDBC-capable datasources.

All the components have asynchronous APIs in order to better support the runtime philosophy in the API Gateway.

For more information about each component, see its javadoc.

Policy Definition

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:

  "id" : "policy_name",
  "name" : "Policy Name",
  "description" : "A useful description of what the policy does.",
  "policyImpl" : "plugin:${project.groupId}:${project.artifactId}:${project.version}:${project.packaging}/com.example.plugins.MyFirstPolicy",
  "icon" : "document",
  "formType" : "JsonSchema",
  "form" : "schemas/policy_name.schema"
  • id: The unique id of the policy.

  • name: The name of the policy.

  • description: The description of the policy.

  • policyImpl: Identifies the java class that implements the policy.

  • icon: The icon to use when displaying the policy in the UI (name of a Font Awesome icon).

  • formType: The type of form to use in the UI when configuring an instance of the policy. See the Policy Configuration section below for details. Valid values: Default, JsonSchema

  • form: (optional) Path to a UI form that should be used when configuring an instance of the policy. See the Policy Configuration section below for details.

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:


Policy Configuration Form

You may be wondering how 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).

Default Policy Configuration

If the policy definition indicates that the configuration form type is Default, then it is up to the UI to determine how to display configuration information. For the policies provided by apiman itself, there are UI forms provided. If the policy is contributed from a plugin, then the UI has no way to know the format of the configuration data. In this case, a simple TextArea is presented to the user.

This approach is clearly not recommended, because users will likely have no idea what to enter into the TextArea presented to them.

JSON Schema Policy Configuration

Alternatively, the policy definition can specify a JSON Schema in the policy definition JSON file. For example, the policy definition might include the following:

  "formType" : "JsonSchema",
  "form" : "schemas/policy_name.schema"

In this case, apiman will look for a file inside the plugin artifact in the following location:


The file in this location must be a JSON Schema file, which describes the JSON format of the configuration data expected by the policy implementation. The UI will use this JSON schema to generate an appropriate UI form that can edit the JSON configuration data needed by the policy implementation.

Perhaps it’s best if we have an example. The following illustrates a policy contributed from a plugin, its JSON Schema file, the resulting form displayed in the UI, and the configuration data format that will be passed to the policy implementation at runtime.

  "id" : "my-policy",
  "name" : "My First Policy",
  "description" : "A policy with custom configuration!",
  "policyImpl" : "plugin:${project.groupId}:${project.artifactId}:${project.version}:${project.packaging}/io.apiman.plugins.config_policy.ConfigPolicy",
  "icon" : "pie-chart",
  "formType" : "JsonSchema",
  "templates" : [
      "language": null,
      "template": "Set policy with @{property1} and @{property2}!"
  "form" : "schemas/config-policyDef.schema"
The templates 'language' field will support other languages in future, but for now is null (i.e. single-language only). The template field itself is MVEL (Orb tag syntax), and displays in the UI after a plugin has been selected by a user.
  "title" : "Configure My Policy",
  "description" : "Configure all of the necessary properties used by my policy.",
  "type" : "object",
  "properties": {
    "property1": {
      "title" : "Property 1",
      "type" : "string",
      "minLength" : 1,
      "maxLength" : 64
    "property2": {
      "title" : "Property 2",
      "type" : "string",
      "minLength" : 1,
      "maxLength" : 64
Generated UI Form
Figure 1. Generated UI Form
JSON Configuration Data Format
  "property1" : "USER_DATA_1",
  "property2" : "USER_DATA_2"
You can easily consume the JSON configuration data above in your policy implementation by having your policy implementation Java class extend the AbstractMappedPolicy base class provided by apiman (in the apiman-gateway-engine-policies module) and creating a simple Java Bean to hold the JSON configuration data.

First, here is the java bean used to (un)marshal the JSON configuration data.

public class MyConfigBean implements Serializable {

  private static final long serialVersionUID = 683486516910591477L;

  private String property1;
  private String property2;

   * Constructor.
  public MyConfigBean() {

  public String getProperty1() {
    return property1;

  public void setProperty1(String property1) {
    this.property1 = property1;

  public String getProperty2() {
    return property2;

  public void setProperty2(String property2) {
    this.property2 = property2;


Now have a look at how to use that class when extending the AbstractMappedPolicy.

public class MyPolicy extends AbstractMappedPolicy<MyConfigBean> {

   * Constructor.
  public MyPolicy() {

  protected Class<MyConfigBean> getConfigurationClass() {
    return MyConfigBean.class;

  protected void doApply(ApiRequest request, IPolicyContext context, MyConfigBean config, IPolicyChain<ApiRequest> chain) {
    // Do something with MyConfigBean here?  It has all the configuration data!
    super.doApply(request, context, My, chain);

  protected void doApply(ApiResponse response, IPolicyContext context, MyConfigBean config, IPolicyChain<ApiResponse> chain) {
    // Do something with MyConfigBean here?  It has all the configuration data!
    super.doApply(response, context, config, chain);


JSON Schema Policy Configuration SDK

If you are creating a non-trivial JSON Schema (more than just a couple of simple fields) it can be difficult to get it right without a few iterations. For this reason, we have created a simple "SDK" to help you create your JSON Schema quickly. The SDK can be found in the apiman github repository at the following location:


If you have the apiman source code checked out, you can simply open that file in your browser and start using it to author a custom JSON Schema.

Alternatively you can use "rawgit" and just go straight to the following URL:

The SDK provides a way to edit your JSON schema and then see how that schema will look in the apiman UI, as well as the format that the policy configuration data will ultimately be in when it is sent to your policy at runtime.

Once you have the JSON Schema finalized, you could also use the online jsonschema2pojo tool to generate a good starting point for a Java Bean that can be used to marshal/unmarshal your policy’s configuration data at runtime. See the discussion about AbstractMappedPolicy above for additional information.

Unit Testing a Plugin Policy

While it is quite simple to create a custom policy for apiman, you may be wondering the best way to unit test your implementation. Fortunately we have made this extremely easy by including an easy-to-use Policy Testing junit framework. Once you have followed the instructions above to create your custom policy, refer to this section to learn how to test it using junit.

Import the Framework (Maven Dependency)

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):


Create and Annotate a JUnit Test Case

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:

  • @TestingPolicy(<classname>) - indicates which of your policy implementations you wish to test

  • @Configuration("<custom_policy_configuration_data>") - specifies the policy configuration to use for the 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 testsing, but you still need to actually send requests to a "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:

public class CustomPolicyTest extends ApimanPolicyTest {

    public void testGet() throws Throwable {
        // Send a test HTTP request to the API (resulting in executing the policy).
        PolicyTestResponse response = send(PolicyTestRequest.build(PolicyTestRequestType.GET, "/some/resource")
                .header("X-Test-Name", "testGet"));

        // Now do some assertions on the result!
        Assert.assertEquals(200, response.code());
        EchoResponse entity = response.entity(EchoResponse.class);
        Assert.assertEquals("GET", entity.getMethod());
        Assert.assertEquals("/some/resource", entity.getResource());
        Assert.assertEquals("testGet", entity.getHeaders().get("X-Test-Name"));
        // Assert the request header that was added by the policy
        Assert.assertEquals("Hello World", entity.getHeaders().get("X-MTP-Header"));
        // Assert the response header was added by the policy
        Assert.assertEquals("Goodbye World", response.header("X-MTP-Response-Header"));


Providing a Custom Back-End API Mock

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 do this 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:

public class CustomPolicyTest extends ApimanPolicyTest {

    public void testGetWithCustomBackEndSvc() throws Throwable {
        // Send a test HTTP request to the API (resulting in executing the policy).
        PolicyTestResponse response = send(PolicyTestRequest.build(PolicyTestRequestType.GET, "/some/resource")
                .header("X-Test-Name", "testGet"));

        // Now do some assertions on the result!
        MyCustomBackEndApiResponseBean entity = response.entity(MyCustomBackEndApiResponseBean.class);


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).

Using a Plugin Policy

Once you have built and unit tested your plugin policy, you will most likely want to actually use the policy in apiman. This can be done by adding the plugin to apiman via the Plugin Management UI in the API Manager user interface.

The Plugin Management UI is restricted to admin users of the API Manager.

For more information about how to use the Plugin Management UI, please see the apiman User Guide.

Iterating a Plugin Policy

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, only then will 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:

  1. Ensure that you are testing a "-SNAPSHOT" version of your custom plugin policy

  2. Configure the policy on one or more API

  3. Publish the API(s) to the API Gateway

  4. Send an HTTP request to an API that uses your custom policy

  5. Make a change to your Policy implementation

  6. Rebuild your plugin and "install" it into your .m2 directory (do not change the version)

  7. Repeat starting at #4

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.

As of version 1.2.4.Final, you must explicitly enable this "auto plugin reloading" feature by setting the following apiman.properties property to "true": apiman-gateway.policy-factory.reload-snapshots
Don’t use this "auto plugin reloading" feature in production as the lack of policy caching will be a significant performance problem.

Uninstalling a Plugin

Again, you can use the Plugin Management UI to uninstall a plugin. Please note that 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.

Upgrading a Plugin

Often times 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.

Contributing a Core Component

In addition to policies, the apiman plugin framework allows developers to provide custom implementations of core apiman components. What does this mean? Apiman is composed of a number of different core components, all working together to provide API Management functionality. Both the API Gateway and the API Manager have core components that can be customized by providing new implementations via plugins.

Some examples of API Manager components include (but are not limited to):

  • Storage Component

  • Query Component

  • IDM Component

  • Metrics Accessor (consumes metrics data recorded by the API Gateway at runtime)

Additionally, some examples of API Gateway components include:

  • Configuration Registry

  • Rate Limiting Component

  • Metrics Emitter (records metrics data for each request)

By default, the apiman quickstart uses default values for all of these, resulting in a stable, working system with the following characteristics:

  • Stores API Manager data in a JDBC database

  • Records and queries metrics data via Elasticsearch

  • Stores Gateway configuration information in Elasticsearch

  • Uses Elasticsearch to share rate limiting state across gateway nodes

However, if you wish to provide a custom implementation of something, you can implement the appropriate Java interface for the correct component, bundle the implementation up into a plugin, and then tell apiman to use yours instead of the default.

Implementing a Custom Core Component

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:

package io.apiman.gateway.engine;

public interface IRegistry {

    public void getContract(ApiRequest request, IAsyncResultHandler<ApiContract> handler);

    public void publishApi(Api api, IAsyncResultHandler<Void> handler);

    public void retireApi(Api api, IAsyncResultHandler<Void> handler);

    public void registerClient(Client client, IAsyncResultHandler<Void> handler);

    public void unregisterClient(Client client, IAsyncResultHandler<Void> handler);

    public void getApi(String organizationId, String apiId, String apiVersion, IAsyncResultHandler<Api> handler);


Perhaps you’d 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. Simple create a new plugin and include in it the following Java class:

package org.example.apiman.plugins;

public class MongoDbRegistry implements IRegistry {

    public MongoDbRegistry(Map<String, String> config) {
        // TODO consume any config params - these come from apiman.properties

    public void getContract(ApiRequest request, IAsyncResultHandler<ApiContract> handler) {
        // TODO implement mongodb specific logic here

    public void publishApi(Api api, IAsyncResultHandler<Void> handler) {
        // TODO implement mongodb specific logic here

    public void retireApi(Api api, IAsyncResultHandler<Void> handler) {
        // TODO implement mongodb specific logic here

    public void registerClient(Client client, IAsyncResultHandler<Void> handler) {
        // TODO implement mongodb specific logic here

    public void unregisterClient(Client client, IAsyncResultHandler<Void> handler) {
        // TODO implement mongodb specific logic here

    public void getApi(String organizationId, String apiId, String apiVersion, IAsyncResultHandler<Api> handler) {
        // TODO implement mongodb specific logic here

While optional, it is often useful to provide a constructor that takes a map of configuration params. These values comes from the apiman.properties and is an arbitrary set of keys/values. It can be extremely helpful when, for example, configuring the mongodb connection information.

Enabling Your Custom Component

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. Obviously you can use "mvn install" to accomplish this.

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:


Core Component Customization Points

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

API Manager Components

Component Interface Description


Allows customizing users upon first login (e.g. create an org for the user).


Primary storage of all API Manager data.


Allows querying of the API Manager data.


Used by the API Manager to query Metrics data collected by the API Gateway.


Used to create an API Key for each created API Contract.


Used primarily by the storage layer to encrypt potentially sensitive data prior to storing it.


Provides access to external APIs which users may wish to import.

io.apiman.manager.api.core.INewUserBootstrapper Example Configuration
io.apiman.manager.api.core.IStorage Example Configuration
io.apiman.manager.api.core.IStorageQuery Example Configuration
If your custom IStorage implementation also implements IStorageQuery, then it will be used instead of trying to create a separate instance of IStorageQuery.
io.apiman.manager.api.core.IMetricsAccessor Example Configuration
io.apiman.manager.api.core.IApiKeyGenerator Example Configuration
io.apiman.common.util.crypt.IDataEncrypter Example Configuration
io.apiman.manager.api.core.IApiCatalog Example Configuration

API Gateway Components

Component Interface Description


Stores gateway configuration data (e.g. published APIs).


Used to encrypt potentially sensitive data prior to storing in the registry.


Creates connectors to back-end APIs based on API meta-information.


Loads policy implementations (from plugins or else internally).


Writes a policy failure to the HTTP response.


Writes a policy error to the HTTP response.


Creates an ApimanBuffer (typically this is provided by the platform support).


Allows storing data into a cache store.


Creates HTTP clients for use in policies.


Async component used to perform JDBC operations in policies.


Async component used to perform LDAP operations in policies.


Creates timers (for use by policies).


Creates policy failures (for use by policies).


Used by the rate limiting and quota policies.


General purpose component to share state across policy invokations.

io.apiman.gateway.engine.IRegistry Example Configuration
io.apiman.common.util.crypt.IDataEncrypter Example Configuration
io.apiman.gateway.engine.IConnectorFactory Example Configuration
io.apiman.gateway.engine.policy.IPolicyFactory Example Configuration

Note: there is rarely a reason to provide a custom policy factory.

io.apiman.gateway.engine.IPolicyFailureWriter Example Configuration
io.apiman.gateway.engine.IPolicyErrorWriter Example Configuration
io.apiman.gateway.engine.components.IBufferFactoryComponent Example Configuration

Note: typically the buffer factory is specific to the platform. For example, there is a buffer factory used when the API Gateway is running in EAP or WildFly. There is a different buffer factory used when the API Gateway is running in vert.x. There is typically not another reason to override this.

io.apiman.gateway.engine.components.ICacheStoreComponent Example Configuration
io.apiman.gateway.engine.components.IHttpClientComponent Example Configuration
io.apiman.gateway.engine.components.IJdbcComponent Example Configuration
io.apiman.gateway.engine.components.ILdapComponent Example Configuration
io.apiman.gateway.engine.components.IPeriodicComponent Example Configuration
io.apiman.gateway.engine.components.IPolicyFailureFactoryComponent Example Configuration
io.apiman.gateway.engine.components.IRateLimiterComponent Example Configuration
io.apiman.gateway.engine.components.ISharedStateComponent Example Configuration

Providing a Custom API Catalog

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 propertly formatted JSON file with all of 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 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:

 * Represents some sort of catalog of live APIs.  This is used to lookup
 * APIs to import into apiman.
public interface IApiCatalog {

     * Called to find available APIs that match the given search keyword.  Note that
     * the search keyword may be a partial word (for example "ech" instead of "echo").  It
     * is up to the implementation to decide how to handle partial cases.  Typically this
     * should return all APIs that contain the partial keyword, thus returning things
     * like "echo" "public-echo" and "echo-location".
     * @param keyword the search keyword
     * @return the available APIs
    public List<AvailableApiBean> search(String keyword);


The catalog is simply one method which returns a list of AvailableApiBean objects. That class looks something like this:

 * A bean modeling an API available in one of the configured API catalogs.
public class AvailableApiBean implements Serializable {

    private String id;
    private String icon;
    private String endpoint;
    private EndpointType endpointType = EndpointType.rest;
    private String name;
    private String description;
    private String definitionUrl;
    private ApiDefinitionType definitionType;

     * Constructor.
    public AvailableApiBean() {


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

See the "Creating a Plugin" section of this guide for more information.

Once the plugin is created with your class inside, configure the catalog 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.

Providing a Custom Data Encrypter

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:

  • Policy Configuration

  • Endpoint Properties

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:

 * Provides a way to encrypt and decrypt data. This is useful when encrypting sensitive
 * data prior to storing it in the database.
public interface IDataEncrypter {

    public String encrypt(String plainText);

    public String decrypt(String encryptedText);


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.

See the "Creating a Plugin" section of this guide for more information.

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:

  • property1=value-1

  • property2=value-2

Providing a Custom Policy Failure/Error Writer

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, apiman 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 for these. 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.

public interface IPolicyFailureWriter {

    public void write(ApiRequest request, PolicyFailure failure, IApiClientResponse response);

public interface IPolicyErrorWriter {

    public void write(ApiRequest request, Throwable error, IApiClientResponse response);


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.

See the "Creating a Plugin" section of this guide for more information.

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:

  • property1=value-1

  • property2=value-2

Providing a Custom User Bootstrapper

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:

  • Grant specific roles to the user

  • Auto-create an Organization for the user

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

 * This class is used to bootstrap new users.  This bootstrapper is used
 * whenever a new user logs into the API Manager UI for the first time.
public interface INewUserBootstrapper {

     * Called to bootstrap a user.
    public void bootstrapUser(UserBean user, IStorage storage) throws StorageException;


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.

See the "Creating a Plugin" section of this guide for more information.

Once the plugin is created with your class inside, configure the user bootstrapper in 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:

  • property1=value-1

  • property2=value-2

Gateway Implementations

At the heart of any apiman gateway implementation is the flexible, lightweight apiman-core.The core serves to execute policies upon the traffic passing through it, determining whether a given conversation should continue or not.

A set of simple, asynchronous interfaces are provided which an implementor should fulfill using the platform’s native functionality to allow apiman to interact with its various components and services.

Implementing IApimanBuffer

Before you can send any data through apiman, you must implement the IApimanBuffer interface. It provides a set of methods which allow apiman to access your native buffer format as effectively as possible. Any data you pass into apiman must be wrapped in your implementation of IApimanBuffer, whilst any data returned to you by apiman will be an IApimanBuffer which you can extricate your native buffer from.

Implementation is fairy self explanatory, but a few points are worth noting:

public class YourApimanBufferImpl implements IApimanBuffer {

  private YourNativeBuffer nativeBuffer;

  public VertxApimanBuffer(YourNativeBuffer nativeBuffer) {
    this.nativeBuffer = nativeBuffer;

  // This is your mechanism to efficiently yank your native buffer back
  public Object getNativeBuffer() {
    return nativeBuffer;

  public int length() {
    return nativeBuffer.length();

  public void insert(int index, IApimanBuffer buffer) {
    nativeBuffer.setBuffer(index, (Buffer) buffer.getNativeBuffer());

Implementors of IApimanBuffer should ensure that the native format is preserved within the instance, this allows it to be retrieved again using getNativeBuffer. Any mutation should be on the native buffer.

Executing apiman-core

Let’s consider the following snippet:

IEngine engine = new <your engine>.createEngine();

// Request executor, through which we can send chunks and indicate end.
final IApiRequestExecutor requestExecutor = engine.executor(request,
  new IAsyncResultHandler<IEngineResult>() {
    public void handle(IAsyncResult<IEngineResult> result) { ... }

// streamHandler called when back-end connector is ready to receive data.
requestExecutor.streamHandler(new IAsyncHandler<IApiConnection>() {
  public void handle(final IApiConnection writeStream) { ... }

// Execute the request

After instantiating your engine implementation, you can call execute. This is the main point through which you pipe data into and out of apiman. In order to avoid any buffering you must write body data through streamHandler’s `IApiConnection which will be called when the connection to the backend API is ready to receive. The result is provided to executor’s `IAsyncResultHandler, which can be evaluated to determine the result of the call, and, if successful, retrieve a ApiResponse and attach handlers to receive response data.

Streaming data

Exploring streamHandler further:

requestExecutor.streamHandler(new IAsyncHandler<IApiConnection>() {

  public void handle(final IApiConnection writeStream) {
    // Just for illustrative purposes
    IApimanBuffer apimanBuffer =
      new YourApimanBufferImpl(nativeBuffer);

    // Call #write as many times as desired.

    // Call #end only once.

Any data flowing into the executor must first be wrapped in your implementation of IApimanBuffer before being passed to write. You may call write an unlimited number of times, and indicate that transmission has completed by signalling end.

No further calls to write should occur after end has been called.

Handling results

An excerpt of the executor’s result handler and considering a successful result:

engine.executor(request, new IAsyncResultHandler<IEngineResult>() {
  public void handle(IAsyncResult<IEngineResult> result) {
    // Did an exception occur?
    if (result.isSuccess()) {
      IEngineResult engineResult = result.getResult();

      if (engineResult.isResponse()) {
        // Our successfully returned API response.
        ApiResponse response = engineResult.getApiResponse();

        // Set a bodyHandler to receive the response's body chunks.
        engineResult.bodyHandler(new IAsyncHandler<IApimanBuffer>() {

          public void handle(IApimanBuffer chunk) {
            // Important: for efficiency, retrieve native buffer format directly if possible.
            if(chunk.getNativeBuffer() instanceof YourNativeBuffer) {
              YourNativeBuffer buffer = (YourNativeBuffer) chunk.getNativeBuffer();

        // Set an endHandler to receive the end signal.
        engineResult.endHandler(new IAsyncHandler<Void>() {

          public void handle(Void flag) {
            // Transmission has now completed.

      } else {
        // Handle policy failure.

    } else {
      // Handle exception.

After testing IAsyncResult.isSuccess, we can be certain that the request completed without an exception occurring. Next, we verify IEngineResult.isFailure, which indicates whether there was a policy failure or the response returned successfully.

Upon success the ApiResponse can be extracted, and a bodyHandler and endHandler can be attached in order to receive the response’s associated data as it arrives. At this point the data has exited apiman, and can handled as makes sense for your implementation. For instance, you may wish to translate the ApiResponse into its native equivalent and return it to the requestor.

Where possible, it is advisable to use getNativeBuffer on any IApimanBuffer chunks you receive; avoiding any expensive format conversions. You must cast it back to your native format; instanceof is helpful to ensure the the correct type has been received.

Handling Failures

In the case of errors or policy failures, a variety of information is provided which can be used to construct a sensible response:

if (result.isSuccess()) {
  IEngineResult engineResult = result.getResult();

  if (!engineResult.isFailure()) {
  } else {
    PolicyFailure policyFailure = engineResult.getPolicyFailure();
    log.info("Failure type: " + policyFailure.getType());
    log.info("Failure code: " + policyFailure.getFailureCode());
    log.info("Failure Message: " + policyFailure.getMessage());
    log.info("Failure Headers: " + policyFailure.getHeaders());
} else {
  Throwable throwable = engineResult.getError();
  log.error("Something bad happened: " + throwable);

The appropriate response to failures will vary widely depending upon implementation. For instance, a RESTful platform may wish to transmit an appropriate HTTP error code, message and possibly body.

Creating an API Connector

Connectors enable apiman to transmit and receive data from the backend APIs under management. For instance, should your system need to connect to an HTTP API, an HTTP connector must be created. The following samples illustrate in general terms how an implementor may go about creating a connector, and although the specifics will vary extremely widely depending upon the platform some general principals should be obeyed.

Connector basics

Inside of your IConnectorFactory implementation you must return an IApiConnector corresponding to the type of request and API being interacted with:

public class ConnectorFactory implements IConnectorFactory {

  public IApiConnector createConnector(ApiRequest request, Api api) {
    return new IApiConnector() {

Inspecting the IApiConnector more closely, we can see the key interface of a connector:

public IApiConnection request(ApiRequest request,
  IAsyncResultHandler<IApiConnectionResponse> resultHandler) {

The IApiConnection you must return is used by apiman to write request chunks; hence, it will be read by your connector. Conversely, the IApiConnectionResponse handler must be called in order to send the ApiResponse and its associated data chunks back to apiman once a response has returned from the API; hence, you will write data to it.

The IAsyncResultHandler is also used to indicate whether an exception has occurred during the conversation with the backend.

Creating the IApiConnection

Generally, an implementor must attempt to return their IApiConnection as soon as it is valid for apiman to write data to the backend. Until you respond, apiman will not fire IApiRequestExecutor.streamHandler, and hence no data will arrive prematurely to your connector. Following this guideline should help to minimise or eliminate any buffering requirements in your connectors.

Looking at an example:

// Native platform's connector (e.g. HTTP)
ImaginaryBackendConnector imaginaryConnector = ...;
Connection c = imaginaryConnector.establishConnection(api.getEndpoint(), ...);

// Prepare in advance to do something sensible with the response
// See next section for more detail.
c.responseHandler(<Handle the response; return an IApiConnectionResponse>);

// From our perspective IApiConnection is
// *inbound data* (i.e. the user writes to us).
return new IApiConnection() {
  boolean finished = false;

  public void write(IApimanBuffer chunk) {
    // Handle arriving data chunk
    YourNativeBuffer nativeBuffer =
      (YourNativeBuffer) chunk.getNativeBuffer();


  public void end() {
    // Handle the signal to indicate stream has completed
    finished = true;

  public void abort() {
    // Handle immediate abort, for instance by closing your connection.
    finished = true;

  public boolean isFinished() {
    return finished;

imaginaryConnector represents your platform’s backend connector. After establishing a connection that can accept data, you should return an IApiConnection, allowing data to be written to your connector. You can extract your native buffer format using getNativeBuffer plus a cast. Although we haven’t yet explored how to handle a response, we can imagine that the platform’s ImaginaryBackendConnector would allows us to set a responseHandler, which will be fired when a response has arrived; this is point at which we can build an IApiConnectionResponse.

Creating the IApiConnectionResponse

Handling a successful response

Apiman’s resultHandler should be called with an IApiConnectionResponse when your connector has received a response from the API.

Let’s imagine that responseHandler is called when the platform’s response has arrived, and looks like this:

c.responseHandler(new Handler<ImaginaryResponse> {
  public void handle(ImaginaryResponse response) {

This is where we must build our apiman response, using the data returned in the platform’s response, and attaching appropriate handlers to capture any data that arrives.

In the following example, we expand the response handle method to build an IApiConnectionResponse:

void handle(final ImaginaryResponse response) {

  IApiConnectionResponse readStream = new IApiConnectionResponse() {
    IAsyncHandler<IApimanBuffer> bodyHandler;
    IAsyncHandler<IApimanBuffer> endHandler;
    boolean finished = false;
    ApiResponse response = YourResponseBuilder.build(response);

    public IApiConnectionResponse() {

    private void doConnection() {
      // We stop any data arriving

      // This will be called when we resume transmission
      response.bodyHandler(new Handler<NativeDataChunk>() {

        void handle(NativeDataChunk chunk) {
          IApimanBuffer apimanBuffer =
            new YourApimanBufferImpl(nativeBuffer);


      // Transmission has finished
      response.endHandler(new Handler<Void>() {

        void handle(Void flag) {
          endHandler.handle((Void) null);
          // You may want to close your backend connection here.

    public void bodyHandler(IAsyncHandler<IApimanBuffer> bodyHandler) {
      this.bodyHandler = bodyHandler;

    public void endHandler(IAsyncHandler<Void> endHandler) {
      this.endHandler = endHandler;

    public ApiResponse getHead() {
      return apiResponse;

    public boolean isFinished() {
      return finished;

    public void abort() {
      // Abort

    // We explicitly resume transmission
    public void transmit() {

  // We're ready to transmit the response, let apiman know.
  IAsyncResult result = AsyncResultImpl.
    <IApiConnectionResponse> create(readStream);


We imagine that our response object contains what we need to build a ApiResponse, and that handlers can be attached in order to retrieve body data and an end signal. It can be paused using pause, which prevents any data from arriving until resume is called.

Importantly, data transmission must not begin until transmit has been called, otherwise the appropriate handlers may not yet have been set, and data will be liable to disappear. Hence, in this example, resume is called in transmit where we are certain that it’s safe to send data.

After end has been signalled, clean up on the native connection can be performed, such as closing it. In this example was assume the connection is closed for us.

Once we are sure our stream is ready, we pass it to apiman using resultHandler.handle wrapped inside of an IAsyncResult indicating we were successful. Some helpful create methods are available in AsyncResultImpl.

Whilst a given platform’s implementation may look very different, implementors must be careful to preserve the same external behaviour; some platforms may require buffering of data if pause-like functionality is not available. In many cases it may be possible to implement IApiConnectionResponse and IApiConnection in the same class.

Do not transmit any response data into apiman until transmit has been signalled.
Handling an error

If an error occurs, you must return a failure IAsyncResult, which may be caused, for instance, by an endpoint being unresolvable. The simplest way to share this is by using AsyncResultImpl:

try { ... }
catch(Exception e) {
  IAsyncResult errorResult =
  	AsyncResultImpl.<IApiConnectionResponse> create(e);

Remember to clean up any resources you may have left open.

Implementation strategies

Implementors may notice that the only overlap between the IApiConnection and IApiConnectionResponse interfaces is the isFinished method. Hence, it is often possible to implement both interfaces using the same class, which may be a cleaner way to orchestrate the process.

Implementation exemplars: