Extending WSO2 API Manager — Service Chaining

Randika Navagamuwa
4 min readFeb 2, 2021

Service chaining is a popular integration use-case. Most of the times, a single service needs to be exposed by combining multiple resources. Assume that there are two services available and they need to be called sequentially. The ideal way to implement this is via service chaining. WSO2 Enterprise Integrator[1] is a leading open source integration platform and this use-case can be implemented easily via this product. Refer to this[2] documentation for more information on implementing this with WSO2 Enterprise Integrator. Even though this can be achieved with either WSO2 API Manager or WSO2 API Manager, this blog explains the way to do this only with WSO2 API Manager. The reason for using only the API Manager is explained under the “Service Chaining” sub-topic.

Use case

Assume that there is an organization where they have a custom “ validation service" implemented. The purpose of this service is to check whether that request has permission to access that particular service. That means each request should go through this " validation service ". Yes, this is somewhat similar to authorization but the difference is this needs to be done at the backend layer instead of the authentication layer. Refer to the below components diagram to get a clear idea on the flow.


API Management

Since the expected security mechanisms are not implemented at the backend layer, having a proper API Management solution is a must. To achieve this, WSO2 API Manager[3] will be used. WSO2 API Manager is a fully-fledged API Management solution that can be used to expose web services as managed APIs.

Service Chaining

Since the API Management requirements are catered by WSO2 API Manager, let’s focus on the service chaining use-case. As we have discussed earlier, WSO2 Enterprise Integrator can be easily used here to achieve this. But, due to the following reasons, having a separate integration layer doesn’t really makes sense.

  • There will be only a single integration use-case which is this service chaining scenario.
  • Having a separate integration layer means more infrastructure and that means more cost.
  • With a separate integration layer the management will also be a bit complex.

Since there is a single integration use-case, all the burden we’ll have to face if we have a separate integration layer doesn’t make any sense here.

In this case, we can utilise the extending capabilities of WSO2 API Manager. Since WSO2 API Manager’s runtime is built using the same WSO2 Enterprise Integrator this can be achieved very easily.

Extending WSO2 API Manager

When it comes to achieving this via WSO2 API Manager, there are two approaches

  1. Implement this using a custom mediation sequence[4]
    The API Gateway has a default mediation flow and if required custom mediation flows can be selected. Whenever an API is created custom mediation sequence can be chosen for in-flow, out-flow, or fault-flow as per the requirement. This approach is easier when compared to the 2nd approach but if you want to deploy this across all the APIs, having a custom handler will make more sense.
  2. Implement this via a custom handler[5]
    Custom Handler is a way of extending API Manager which the product offer to change the API flow through the API Gateway. This approach is a bit complex as a custom java code needs to be written but the advantage is the logic can be applied at the gateway layer so all the APIs will inherit this and you don’t need to configure this per API.

Backend services

The required mock backend service can be found in the github.com/rnavagamuwa/service-chaining-mock-services[6] repository and the following services are implemented there.

Swagger UI for the mock services

Since this is just a demonstration “device_19th6281” needs to be passed as the scope in order to access the “userservice”. So the sample JSON payload is as follows.

{ "scope":"device_19th6281", "service":"userservice" }


If you are not familiar with WSO2 API Manager, please refer to t his documentation[7] first for more information.

The following mediation sequence can be used to implement this through a custom mediation sequence.

The above custom mediation can be easily enabled per API and please refer to this[4] documentation for more information.

2. Implement using a custom handler

With this approach, this validation will be implemented across all the APIs. Exact implementation steps can be found in this documentation[5].

The source code of the implemented custom handler can be found in https://github.com/rnavagamuwa/custom-auth-handler-wso2-apim and this was done by extending the “ org.apache.synapse.rest.AbstractHandler “ class.

First, the custom handler jar file[8] needs to be placed in the <APIM_HOME>/repository/components/lib directory.

To engage the custom handler with it’s logic, that needs to be added to the velocity_template.xml file which can be found in <APIM_HOME>/repository/resources/api_templates/velocity_template.xml directory. The following can be used to enable this in the velocity_template.xml.

<handler class="com.rnavagamuwa.wso2.customAuthHandler.CustomAuthHandler">
<property name="authUrl" value="http://localhost:8595/api/validate"/>

My current velocity template can be found here[9]

Special Note: The ideal way to implement mediations is through a proper integration layer such as WSO2 Enterprise Integrator[1], but there might be use cases where that will be a waste of resources, and for that kind of use cases this approach is better.

[1] https://wso2.com/integration/
[2] https://ei.docs.wso2.com/en/7.2.0/micro-integrator/use-cases/tutorials/exposing-several-services-as-a-single-service/
[3] https://wso2.com/api-management/
[4] https://apim.docs.wso2.com/en/latest/learn/api-gateway/message-mediation/changing-the-default-mediation-flow-of-api-requests/
[5] https://apim.docs.wso2.com/en/latest/develop/extending-api-manager/extending-gateway/writing-custom-handlers/
[6] https://github.com/rnavagamuwa/service-chaining-mock-services
[7] https://apim.docs.wso2.com/en/latest/learn/api-controller/getting-started-with-wso2-api-controller/
[8] https://github.com/rnavagamuwa/custom-auth-handler-wso2-apim/blob/main/target/customAuthHandler-1.0-SNAPSHOT.jar
[9] https://gist.github.com/rnavagamuwa/b0a986a1afac8300be3cc22c154d42c4

Originally published at https://rnavagamuwa.com on February 2, 2021.



Randika Navagamuwa

Solutions Architect. Open Source Enthusiast. Works at StarTree Inc. Graduated from University of Moratuwa, Sri Lanka. | https://rnavagamuwa.com