This documentation is for WSO2 API Manager 2.1.0. View documentation for the latest release.

All docs This doc

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Updated info on key cache and GW cache

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 (i.e., access token, API name, 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 in either the API Gateway or the Key Manager server.

The default cache size of any type of cache in a WSO2 product is 10,000 elements/records. Cache eviction occurs from the 10001st element.  All caches in WSO2 products can be configured using the <PRODUCT_HOME>/repository/conf/carbon.xml file. The defaultCacheTimeout is 15 minutes which comes by default.

...

Tip

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

API Gateway cache

When caching caching is enabled at the Gateway and 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. After the Key Manager server returns the validation information, it gets stored in the Gateway. As 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.

If you enable the API Gateway cache and disable the Key Manager cache, you can have two Gateways per Key Manager (GW 2: KM 1). However, if you disable the API Gateway cache and enable the Key Manager cache in a clustered environment, as every request is sent to the Key Manager, you should have only one Gateway per Key Manager (GW 1: KM 1). 

Note

At any given time you should only have one cache enabled, which is either the Key Cache or the API Gateway Cache. WSO2 does not recommend using both caches at the same time.

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

...

languagehtml/xml

...

You can also configure the gateway token cache expiry by editing the following elements in the <APIM_HOME>/repository/conf/api-manager.xml file:

PurposeConfiguration Elements
Enable the API Gateway cache. This is enabled by default.

Under <CacheConfigurations>, set <EnableGatewayTokenCache>true</EnableGatewayTokenCache>

Disable the Key Manager cache. This is disabled by default.Under <CacheConfigurations>, set <EnableKeyManagerTokenCache>false</EnableKeyManagerTokenCache>
Change the token cache duration, which expires after 900 seconds by default.<TokenCacheExpiry>900</TokenCacheExpiry>
Note

If you need to enable Gateway caching across the entire cluster, see Working with Hazelcast Clustering. However, WSO2 does not recommend Hazelcast clustering, because you can seamlessly deploy WSO2 API Manager using local caching in a clustered setup without using Hazelcast clustering.

Clearing the API Gateway cache

If you wish to remove old tokens that might still remain active in the Gateway cache, you need to configure the <RevokeAPIURL> element in the  <API-M_HOME>/repository/conf/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.

...

In a typical 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. To avoid caching token-related information in a leniently secured zone, you can store the cache on the Key Manager side. If you do, 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 is checked for the validity of the token.

Storing the cache in Therefore, if you enable the Key Manager causes lower performance than when storing it in the Gateway, but it is more secure. If you enable the key cache and disable the API Gateway cache in a clustered environment, as every request is sent to the Key Manager, you should have only one Gateway per Key Manager (GW 1: KM 1). However, if you disable the Key Manager cache and enable the API Gateway cache, whereas you can have two Gateways per Key Manager (GW 2: KM 1). Storing the cache in the Key Manager causes lower performance than when storing it in the Gateway cache is enabled instead. Note that you should always have one of the caches enabled, but we do not recommend using both caches combined. For more information, see Clustering Gateways and Key Managers with key caching in the WSO2 Clustering Guide, but it is more secure. 

Note

At any given time you should only have one cache enabled, which is either the Key Manager cache or the API Gateway cache. WSO2 does not recommend using both caches at the same time.

You configure the key cache by editing the following elements in the <APIM_HOME>/repository/conf/api-manager.xml file:

PurposeConfiguration Elements
Disable the API Gateway cache.

Under <CacheConfigurations>, set <EnableGatewayTokenCache>false</EnableGatewayTokenCache>

Enable the Key Manager cache.Under <CacheConfigurations>, set <EnableKeyManagerTokenCache>true</EnableKeyManagerTokenCache>
Change the key cache durationkey cache duration, which expires after 900 seconds by default.<TokenCacheExpiry>900</TokenCacheExpiry><TokenCacheExpiry>900</TokenCacheExpiry>
Note

If you need to enable Key caching across the entire cluster, see Working with Hazelcast Clustering. However, WSO2 does not recommend Hazelcast clustering, because you can seamlessly deploy WSO2 API Manager using local caching in a clustered setup without using Hazelcast clustering.

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

...

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:  

PropertyDescription
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.
maxSizeDefines 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.

...

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 Invalidatemediatocache()operation of the org.wso2.carbon.mediatio n MBean for this as shown below.

JMX monitoring through JConsoleImage Modified

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.