WSO2 API Manager - Using Custom Handler or Mediation Extensions for Message Transformation?

Custom Handlers and Mediation Extensions are some of the extension points which you can use to extend the functionality of WSO2 API Manager. When it comes to message transformation, it is recommended to use Mediation Extensions over Custom Handlers due to following reasons.

• If you want to engage a custom handler to all of your APIs, then you need to add it to all the APIs manually unless you modify velocity_template.xml to include the custom handler. If you are changing velocity_template.xml, then already published APIs won't have any impact. You need to republish those APIs to get the effect. On the other hand, if you copy a global mediation extension into AM, it will be engaged with all the APIs immediately.

• If you decided not to do the transformation, then reverting changes is just a matter of removing mediation extensions from AM. On the other hand, if you are using a custom handler, then you have to remove the custom handler from all the APIs manually. Or else, you need to modify the velocity_template.xml and need to republish all your APIs.

• If you are using a custom handler, it will be a maintenance overhead when it comes migration and all. If you are migrating, then you need to rebuild your custom handler with correct dependencies.

However, there might be some situations where we can't actually implement our usecase using inbuilt features. Then we should definitely go for a custom handler. For example, DBLookup mediator won't return multiple rows. Hence, while message transformation, if you want to retrieve multiple rows from the database, then you need to go for a custom handler.

As you can see, choice depends on many factors. As a simple rule, we need to use the mediation extensions wherever possible for message transformations within API Manager.