WSO2 API Manager Gateway Extension points

WSO2 API Manager Gateway provides a synapse based runtime, which is similar to the WSO2 ESB runtime. Default mediation flow of the gateway can be extended with different extensions. Three main extensions are listed bellow.

[1] Custom Sequences - https://docs.wso2.com/display/AM210/Adding+Mediation+Extensions
[2] Custom API Handlers - https://docs.wso2.com/display/AM210/Writing+Custom+Handlers
[3] Custom Synapse Handlers - http://prabu-lk.blogspot.co.uk/2015/10/how-to-write-synapse-handler.html

Provided links contain details on how to implement each of above extensions. In this post we will discuss mainly the execution order of these extensions if someone has placed all of them. Hope that will help someone to understand which extension should be used for their use case and where to troubleshoot if you have any issues in the mediation flow.

Custom Synapse Handler

Global extension handler, which will execute for each API invocation. If someone needs to perform some actions for each and every API, then we could write a global synapse handler.

You can implement concrete handler by implementing org.apache.synapse.SynapseHandler interface or can extends org.apache.synapse.AbstractSynapseHandler class.

There are four methods that you need to implement.
+handleRequestInFlow(MessageContext messageContext) - Execute just after request hitting to the synapse engine (API GW)
+handleRequestOutFlow(MessageContext messageContext) - Execute just before request dispatch to endpoint
+handleResponseInFlow(MessageContext messageContext) - Execute just after response received to API GW
+handleResponseOutFlow(MessageContext messageContext) - Execute just before response dispatch to client

Custom API Handler

Need to engage per API. If you need to engage handler of all the APIs, that can be done by editing velocity_template.xml provided in API Manager. Refer doc [2] provided above fore details.

Concrete implementation should be done by extending org.apache.synapse.rest.AbstractHandler class.

There are two method that you need to implement.
+handleRequest(MessageContext messageContext) - Execute in the request flow, before dispatching request to endpoint
+handleResponse(MessageContext messageContext) - Execute in the response flow, before dispatching response to client

Custom Sequence

Synapse sequences . Can be engage in the request in flow or the response out flow. Sequence should be named in a convention. Refer doc [1] provided above. 

Custom sequences are executed using a default handler (APIManagerExtensionHandler) provided in APIM. This handler has been places as the last handler in the API synapse definition. So that custom sequences are getting executed after executing all other handlers.

Execution Order

Following diagram explains the execution order if someone has Global synapse handler, Custom API handler, Custom IN/OUT sequences are deployed. 

Request first hit the handleRequestInFlow() method of global synapse handler, then it goes through all the handleRequest() methods of all API handlers, then the custom IN sequences are getting executed, then it goes to handleRequestOutFlow() method of global synapse handler, and finally request getting dispatch to the endpoint. 

Then the response sent by endpoint is getting first hit to the handlerResponseInFlow() method of global synapse handler, then it goes through all handleResponse() methods of all API handlers, then the custom OUT sequences are getting executed, then it goes to the handleResponseOutFlow() method of the global synapse handler, and finally response getting dispatch to the client. 

Hope this post helps to understand the API Manager Gateway mediation extensions and execution order of them!