We Have Moved
The IBM Application Gateway has a new home - docs.verify.ibm.com/gateway
The documentation on this site will no longer be maintained after v21.02, please update your bookmarks.
Caching Responses
Overview
IBM Application Gateway (IAG) can cache static web content received from resource servers to increase the performance and response time of requests. By default this caching is disabled, but can be selectively enabled for particular resources.
Before configuring the cache you must understand the key concepts, configuration variables, conditions that affect content caching and the impact of HTTP headers. Caching is always a trade-off between performance and memory utilization. It needs to be tuned for each individual environment to maximize the benefits.
The following diagrams illustrate how the IAG manages the cache during a request flow:
Key caching concepts
Caching web content gives you the flexibility of serving static documents locally from IAG rather than retrieving the content from a back-end resource server for every request. With the content caching feature, you can store commonly accessed web document types in the memory of the IAG server. Clients can experience much faster response to follow up requests for documents that are cached in the IAG server.
Cached content can include static text documents and graphic images. Dynamically generated documents, such as database query results, cannot be cached.
Caching is based on MIME type. Separate caches can be configured for different MIME types to give fine control over the caching of each type of document. The following settings can be used to configure the cache based on MIME type:
- Document MIME type;
- Type of storage (Note: only 'memory' is currently supported on the IAG);
- Size of storage;
- Maximum age if expiry information is missing from the original response.
Configuration of content caching
The IAG can be configured to enable content caching, as shown in the following YAML snippet template:
advanced:
configuration:
- stanza: content-cache
operation: set
entry: <mime-type>
value:
- <cache-type>[:<cache-size>:<def-max-age>]
Variable | Description |
---|---|
mime-type | Represents any valid MIME type conveyed in the content-type header of a HTTP response. This value can contain an asterisk '*'. A value of '*/*' represents a default object cache that holds any object that does not correspond to an explicitly configured cache. |
cache-type | Specifies the type of storage medium to use for the cache. IAG only supports "memory" caches. |
cache-size | Specifies the maximum size in KB that the specified cache can grow before objects are removed according to a Least Recently Used (LRU) algorithm. |
def-max-age | Specifies the maximum age of cache entries (in seconds) if expiry information is missing from the original response. If no value is provided, a default maximum age of 3600 (1 hour) is applied. |
Please note:
- The asterisk is a wildcard only for a MIME-type directory and its contents.
Example
The following example caches:
- HTML documents ('text/html');
- Images of any type ('image/*');
- A default cache ('*/*') for other object types. The default cache expires after 600 seconds (10 minutes).
advanced:
configuration:
- stanza: content-cache
operation: set
entry: "text/html"
value:
- "memory:2000"
- stanza: content-cache
operation: set
entry: "image/*"
value:
- "memory:5000"
- stanza: content-cache
operation: set
entry: "*/*"
value:
- "memory:1000:600"
Conditions affecting content caching configuration
The content caching mechanism observes the following conditions:
-
Content caching occurs only when a cache is defined in the IAG YAML file;
- By default, no content caching is enabled by the IAG;
- If you do not specify a default content cache, documents that do not match any explicit cache are not cached;
- Authorization is still performed on all requests for cached information;
- The content caching mechanism does not cache responses to requests that contain query strings.
Impact of HTTP headers on IAG content caching
The following table describes how HTTP Request headers from the client affect whether IAG retrieves the static content from the cache, or proxies the request to the resource server:
Request Header | Impact |
---|---|
Accept-Encoding | The presence of this header in the request allows the response to come from the cache if the value matches the cached encoding type. |
Authorization | Stops the response from being retrieved from the cache unless the resource server has been configured to pass user-identifying data to the protected server. |
Cache-Control | The 'no-cache' and 'no-store' values stop the response from being retrieved from the cache. The 'max-age', 'max-stale', or 'min-fresh' values determine whether the cache is used for the response. |
Pragma | The presence of this header in the request, with a value of "non-cache", stops the response coming from the cache. |
Range | The presence of this header in the request stops the response coming from the cache and the response from being stored in the cache. |
The following table describes how HTTP Response headers from the resource server affect the caching of responses:
Response Header | Impact |
---|---|
Cache-Control | The 'no-cache', 'no-store', or 'private' values will stop the response from being stored in the content cache. If the Cache-Control headers contains a value of 'public' it will allow a response with HTTP authentication information associated with it to be cached. The IAG will store responses with this header in the content cache. |
Content-Range | If the Content-Range header is present it will stop the resource from being stored in the content cache. |
Date | Calculates whether data in the cache is fresh enough to use. |
Expires | The presence of this header in the response allows the resource to be stored in the content cache, even if user identifying data is passed to the junction. |
Pragma | The presence of this header in the response, with a value of "non-cache", stops the resource from being stored in the content cache. |
Transfer-encoding | Stops the resource being stored in the cache. |
Vary | Stops the resource being stored in the cache. |
Note: IAG does not process <meta> tags with http-equiv attributes for Response headers.
Impact of other conditions on IAG content caching
Other conditions that affect IAG content caching include:
- IAG does not cache content if the response from the resource server does not have the status '200 OK';
- IAG does not cache content if the request URL contains a query string;
- IAG does not cache content if the value of the 'Date' header is greater than the value of the 'Expires' header;
- IAG flushes a cache entry if a PUT, POST, or DELETE method is used in the URL;
- IAG only returns values from the cache for HEAD and GET requests;
- IAG regularly sends HEAD requests to resource servers to check that they are running. The response to these health checks are not cached;
- IAG does not cache the response if user-identifying data is passed to the resource server, unless the response has an Expires header.