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 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. The 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 in either the API Gateway or the key manager server.

This section covers the following:

Caching at API Gateway

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 cache, it calls the key manager server. This process is carried out using Web service calls. Once the key manager server returns the validation information, it gets stored in the Gateway. Because 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 <APIM_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 configure the <RevokeAPIURL> element in 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 form 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.

Given below is how to configure this in a distributed API Manager setup.

In the api-manager.xml file of the key manager 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,

<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 caching

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 comes. 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 <APIM_HOME>/repository/conf/api-manager.xml file:

<EnableGatewayResourceCache>true</EnableGatewayResourceCache>

Caching at Key Manager server

In this method, the cache is maintained at the key manager server rather than the API Gateway. As a result, for each and every API call that hits the API Gateway, the Gateway issues a Web service call to the key manager server. If the cache entry is available in the key manager server, it is returned to the Gateway. Else, the database will be checked for the validity of the token.

This method has low performance compared to the earlier one, but the the advantage of this method over the other is that we do not have to store any security-related information at the Gateway side.

By default, caching is enabled at the Gateway side as it is the faster method. If you want to change this default configuration, disable caching at the Gateway side and enable it at the key manager server side by using the instructions below.

Disable caching at API Gateway by adding the following entry to APIGateway section of <APIM_HOME>/repository/conf/api-manager.xml file.
```
<EnableGatewayKeyCache>false</EnableGatewayKeyCache>
```
Enable key manager server-side caching by adding the following entry to APIKeyManager section of the api-manager.xml file.
```
<EnableKeyMgtValidationInfoCache>true</EnableKeyMgtValidationInfoCache>
```
The API Manager generates JWT tokens for each validation information object. Usually, JWT tokens also get cached with the validation information object, but you might want to generate JWT per each call. You can do this by enabling JWT caching at key manager server. Add the following entry to APIKeyManager section of the api-manager.xml file.
```
<EnableJWTCache>true</EnableJWTCache>
```
Note that you must disable caching at the key manager server side in order to generate JWT per each call.
Also enable token generation by setting the following entry to true at the root level of the api-manager.xml file.
```
<APIConsumerAuthentication> 
    <EnableTokenGeneration>true</EnableTokenGeneration> 
    ...
</APIConsumerAuthentication>
```

Response caching

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

You enable response caching when creating a new API or editing an existing one using the API Publisher UI. Go to the API Publisher and click 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 it 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 <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. An optional attribute, with the default value 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. See sample here. 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.