Custom Java Interceptors

Custom Java interceptors allow users to create and execute custom Java classes contained in .jar files, following a specific development model.

To create custom Java interceptors, you must have a .jar file in your machine and upload it to the Manager. On this page, we explain how to configure the Manager settings and offer examples of .jar files to assist you.

Creating a project for a Java interceptor

To create a custom interceptor on the Manager, you must first upload the .jar file of your project to our Platform.

For a .jar file to be considered valid, it should have these characteristics:

  • it must contain at least one class @ApiSuiteInterceptor;

  • it must contain at least one method @InterceptorMethod;

  • by default, the maximum file size should be 1 MB;

  • it should not contain any other .jar within the file;

  • it must be implemented with Java 8 or later and using openJDK;

  • it should make use of a specific dependency (check below).

A common mistake is selecting folders such as bin or target in addition to src to compile the source code into the .jar file, which can lead to error because it creates invalid references to other files. You only need to reference the src folder.


This is the dependency you need to use:

If you are using an older version of the Manager, you might need to download this dependency file (feel free to get in touch with our support team if you need assistance):


See below some examples of custom Java interceptors:

You can check this page to see a more detailed example of how to create and upload a custom Java interceptor to the API Platform.


Here you can get JavaDocs to assist you:

Registering a new interceptor on the Manager

New interceptors are created on the Interceptors menu page, through the + button on the bottom right corner.

custom create

To create a Java interceptor, click or hover the cursor over the + button and select the option Create Custom Java.

custom java create

To configure the interceptor, you must fill in some attributes, as shown in the image below.

custom java new
  • Name: it identifies the Java Interceptor that will to be created;

  • Select JAR file: a button used to select the .jar file that will be used;

  • Abort request if fail: when this option is checked, the gateway does not forward the request to the backend in case of an error, but immediately returns an error response to the client.

After entering the data, click Save. The system will then perform an analysis to validate the file uploaded. If it is valid, the system will save it. Otherwise, the message "Invalid JAR file" will be displayed.

Custom Java interceptors list

Existing Java interceptors will be displayed on cards separated by tags. Interceptors which have not been assigned any tags will be listed under the Uncategorised grouping and with a tag signalling that they are custom Java interceptors.

custom java list

Configuring the interceptor

To use the interceptor, drag it into the desired flow. Custom interceptors might be added both to the request and the response flows.

A modal window will open up displaying the name of the Java interceptor and the list containing the classes and methods that can be used to intercept calls.

config java interceptor

You can specify parameters to be used inside Java interceptors. To do so, you need to add the keys/values and interpret these parameters inside the method that will intercept the call.

If you edit a custom interceptor you must remove all instances of this interceptor that had been inserted in API flows before your modifications. That is because changes made to an interceptor will not be reflected upon interceptor instances in API flows.


Upon receiving a request, the system performs a validation analysis of the .jar file code looking for potentially malicious functions that may somehow compromise the interceptor. If the system finds any potential security breach, the interceptor won’t run and a security exception will be triggered.

Thanks for your feedback!

Share your suggestions with us!
Click here and then [+ Submit idea]