Configuring Caching

When an API call hits the API Gateway, the Gateway carries out security checks to verify if the token is valid. During these verifications, the API Gateway extracts parameters such as the access token, API and API version that are passed on to it. Since the entire load of traffic to APIs goes through the API Gateway, this verification process needs to be fast and efficient in order to prevent overhead and delays. WSO2 API Manager uses caching for this purpose, where the validation information is cached with the token, API name and version, and the cache is stored either in the API Gateway or the Key Manager server.

This section covers the following:

Apart from response caching, all the other caches are enabled by default. When the WSO2 API Manager components are clustered, they work as distributed caches. This means that a change done to one node is visible to another node in the cluster.

API Gateway cache

When caching is enabled at the Gateway and a request hits the Gateway, it first populates the cached entry for a given token. If a cache entry does not exist in the cache, it calls the Key Manager server. This process is carried out using Web service calls. When the Key Manager server returns the validation information, it gets stored in the Gateway. Since the API Gateway issues a web service call to the Key Manager server only if it does not have a cache entry, this method reduces the number of web service calls to the Key Manager server. Therefore, it is faster than the alternative method.

By default, the API Gateway cache is enabled by setting the <EnableGatewayKeyCache> element to true in the <API-M_HOME>/repository/conf/api-manager.xml file:

<EnableGatewayKeyCache>true</EnableGatewayKeyCache>

Clearing the API Gateway cache

To remove old tokens that might still remain active in the Gateway cache, you need to configure the <RevokeAPIURL> element in the api-manager.xml file by providing the URL of the Revoke API that is deployed in the API Gateway node. The revoke API invokes the cache clear handler, which extracts information from transport headers of the revoke request and clears all associated cache entries. If there's a cluster of API Gateways in your setup, provide the URL of the revoke API deployed in one node in the cluster. This way, all revoke requests route to the OAuth service through the Revoke API.

Follow the instructions below to clear API Gateway caching in a distributed API Manager setup.

In the api-manager.xml file of the API Store node, point the revoke endpoint as follows:
```
<RevokeAPIURL>https://${carbon.local.ip}:${https.nio.port}/revoke</RevokeAPIURL>
```

In the API Gateway, point the Revoke API to the OAuth application deployed in the Key Manager node. For example,

Example

<api name="_WSO2AMRevokeAPI_" context="/revoke">
        <resource methods="POST" url-mapping="/*" faultSequence="_token_fault_">
            <inSequence>
                <send>
                    <endpoint>
                        <address uri="https://keymgt.wso2.com:9445/oauth2/revoke"/>
                    </endpoint>
                </send>
            </inSequence>
            <outSequence>
                <send/>
            </outSequence>
        </resource>
        <handlers>
            <handler class="org.wso2.carbon.apimgt.gateway.handlers.ext.APIManagerCacheExtensionHandler"/>
        </handlers>
</api>

Resource cache

An API's resources are HTTP methods that handle particular types of requests such as GET, POST, etc. They are similar to methods of a particular class. Each resource has parameters such as its throttling level, Auth type, etc.

Users can make requests to an API by calling any one of the HTTP methods of the API's resources. The API Manager uses the resource cache at the Gateway node to store the API's resource-level parameters (Auth type and throttling level). The cache entry is identified by a cache key, which is based on the API's context, version, request path, and HTTP method. Caching avoids the need to do a separate back-end call to check the Auth type and throttling level of a resource every time a request to the API is received. It improves performance.

Note that if you change a resource's parameters, such as the Auth type, through the UI, it takes about 15 minutes to refresh the resource cache. During that time, the server returns the old Auth type from the cache. If you want the changes to be reflected immediately, please restart the server after changing the value.

By default, the resource cache is enabled by setting the <EnableGatewayResourceCache> element to true in the <APIM_HOME>/repository/conf/api-manager.xml file:

<EnableGatewayResourceCache>true</EnableGatewayResourceCache>

Key Manager cache

The following caches are available:

Key cache

In a typical WSO2 API Manager deployment, the Gateway is deployed in a DMZ, while the Key Manager is in MZ. By default, caching is enabled at the Gateway. If you do not like to cache token related information in a leniently secured zone, you can do that on the Key Manager side. In this method, the Gateway issues a web service call to the Key Manager server for every API call that hits the API Gateway. If the cache entry is available in the Key Manager server, it is returned to the Gateway. Otherwise, the database will be checked for the validity of the token.

This method has low performance compared to the API Gateway caching, but when using the Key cache, you do not have to store any security-related information at the Gateway side. It is not recommended to use the Key cache combined with the Gateway cache.

Follow the instructions below to enable Key cache:

Disable caching at the API Gateway.
Add the following entry under the <APIGateway> element in the <APIM_HOME>/repository/conf/api-manager.xml file.
```
<EnableGatewayKeyCache>false</EnableGatewayKeyCache>
```
Enable the Key Manager cache.
Add the following entry under the <APIKeyValidator> element in the api-manager.xml file.
```
<EnableKeyMgtValidationInfoCache>true</EnableKeyMgtValidationInfoCache>
```

JWT cache

You need to use JSON Web Tokens (JWT) when you need to pass certain end-user attributes to the back-end. If you enable JWT generation, the token is generated in the Key Manager server for each validation information object and is sent as part of the key validation response. Usually, the JWT also gets cached with the validation information object, but you may want to generate JWTs for each call, and you can do this by enabling JWT caching at the Key Manager server.

A validation information object is an object that stores information to ensure validation. This resides in the APIKeyValidationInfoDTO.java class and contains the following information:

Whether or not the user is authorized to access the resource.
The subscriber, tier and subscription type.
Details about the API invoker (application, end user token, etc)
Information on the key validation status (issued time, validity period, etc.)

Enable JWT caching at the Key Manager server as follows:
Add the following entry under the <APIKeyValidator> element in the <APIM_HOME>/repository/conf/api-manager.xml file.
```
<EnableJWTCache>true</EnableJWTCache>
```
Enable Key Manager cache.

Enabling JWT cache only works if you have enabled the Key Manager cache.
Add the following entry under the <APIKeyValidator> element in the api-manager.xml file.
```
<EnableKeyMgtValidationInfoCache>true</EnableKeyMgtValidationInfoCache>
```

Enable token generation.
Set the following entry to true at the root level of the api-manager.xml file.

<APIConsumerAuthentication> 
    <EnableTokenGeneration>true</EnableTokenGeneration> 
</APIConsumerAuthentication>

OAuth cache

The OAuth token is saved in this cache, which is enabled by default. Whenever a new OAuth token is generated, it is saved in this cache to prevent constant database calls. Unless an OAuth expires or is revoked, the same token is sent back for the same user. Therefore, you do not need to change this cached token most of the time.

Response cache

WSO2 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 multiple times for a request. You need to set an appropriate timeout period to offset the risk of stale data in the cache.

You enable response caching when creating a new API or editing an existing API using the API Publisher UI. Go to the API Publisher and click on the Add API menu (to create a new API) or the Edit link associated with an existing API. Then, navigate to the Manage tab where you find the response caching section. You can set the Response Caching field to Enabled and give a timeout value. This enables the default response caching settings.

To change the default response caching settings, edit the following cache mediator properties in the <APIM_HOME>/repository/resources/api_templates/velocity_template.xml file:

Property	Description
`collector`	`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. This is an optional attribute and its default value is set to `unlimited`.
`maxSize`	Defines the maximum number of elements to be cached
`hashGenerator`	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 `REQUESTHASHGenerator` class written to generate the hash value. Click here to view the sample. 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 `REQUESTHASHGenerator` 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.

API Store cache

The API Store has several caches to reduce the page-load times and increase its responsiveness when multiple users access it simultaneously.

Tag cache: This cache saves the API's tags after they have been retrieved from registry. If your APIs and associated tags change frequently, it is recommended to configure a smaller cache refresh time (in milliseconds). This cache disabled by default. To enable it, uncomment the <TagCacheDuration> element in the <APIM_HOME>/repository/conf/api-manager.xml file.
Recently-added-API cache: This cache saves the five most recently added APIs. It is disabled by default. If you have multiple API modifications during a short time period, it is recommended to not enable this cache. To enable it, set the <EnableRecentlyAddedAPICache> to true in the <APIM_HOME>/repository/conf/api-manager.xml file.