Response caching

The API Manager uses WSO2 ESB's cache mediator to cache response messages for each API. Caching improves performance, because the backend server does not have to process the same data for a request multiple times. You need to set an appropriate timeout period to offset the risk of stale data in the cache.

Enabling Response Caching for an API

You need to enable response caching when creating a new API or editing an existing API using the API Publisher.

Please follow below steps to enable response caching for an API.

  1. Create an API.

  2. Navigate to the Runtime tab under API Configurations where you find the response caching configuration. Then turn on Response caching and give a timeout value. This enables the default response caching settings.


    When creating a new API by using a Swagger or Open API definition, response caching can be set up by defining an API-M supported Open API extension “x-wso2-response-cache”.


        enabled: true
        cacheTimeoutInSeconds: 400
  3. If you want to change the default response caching settings, edit the following cache mediator properties in the <API-M_HOME>/repository/resources/api_templates/velocity_template.xml file:

    Property Description
    • true : specifies that the mediator instance is a response collection instance.
    • false : specifies that the mediator instance is a cache serving instance.

    max MessageSize

    Specifies the maximum size of a message to be cached in bytes. An optional attribute, with the default value set to unlimited .
    maxSize Defines the maximum number of elements to be cached.


    Defines the hash generator class.

    When caching response messages, a hash value is generated based on the request's URI, transport headers and the payload (if available). WSO2 has a default HttpRequestHashGenerator class written to generate the hash value. See sample here . Please note that prior to API-M 4.0.0, a different hash generator implementation REQUESTHASHGenerator was used by default and from API-M 4.0.0, this new hash generator implementation is being used.

    If you want to change this default implementation (for example, to exclude certain headers), you can write a new hash generator implementation by extending the HttpRequestHashGenerator and overriding its getDigest() method. Once done, add the new class as the hashGenerator attribute of the <cache> element in the velocity_template.xml file and api_product_template.xml file.


When running a distributed deployment, you need to enable the JSON stream builders on the API Gateway and maintain the standard builders on the API Developer Portal node.

Follow the instructions below to enable the stream builders in the API gateway:

  1. Open the <API-M_HOME>/repository/conf/deployment.toml file.
  2. Add following configuration.

        json = "org.apache.synapse.commons.json.JsonStreamBuilder"

Invalidating Cached Responses Remotely

You can invalidate all cached response remotely by using any JMX monitoring tool such as Jconsole using the exposed MBeans. You can use the InvalidateMediatorCache() operation of the org.wso2.carbon.mediation MBean for this as shown below.

JMX monitoring through JConsole