Service Result Cache

Edit online

This policy enables caching of the results of API invocations depending on the caching criteria defined. You can define the elements for which the API responses are to be cached based on the criteria such as HTTP Header, XPath, Query parameters, and so on. You can also limit the values to store in the cache using a whitelist. For the elements that are stored in the cache, you can specify other parameters such as Time to Live and Maximum Response Payload Size.

Caching the results of an API request increases the throughput of the API call and improves the scalability of the API.

The cache criteria applicable for a SOAP-based API request are HTTP Header and XPATH. The cache criteria applicable for a REST-based API request are HTTP Header and Query parameters. The caching works only for GET methods for REST APIs.

Note: If there are no values set for any of the criteria, then, by default, all the SOAP requests and GET requests for the Rest API are based on the URL.
The table lists the properties that you can specify for this policy:
Property Description
Cache Criteria. Specifies the criteria that API Gateway uses to determine the request component, that is, the actual payload based on which the results of the API invocation are cached.
HTTP Header Uses the HTTP header in the API request. You can use this criterion for APIs that accept payloads only in HTTP format.

Header Name. Specifies the HTTP header name.

Cache responses only for these values. API Gateway caches the API responses only for requests whose cache criteria match with those set for the action, and whose criteria evaluation results in any one of the values in this list. You can add multiple entries by clicking .
Note: If this field is empty, all the values that satisfy the criterion are cached.
Query Parameters You can use this criterion for REST-based API requests. Specifies the names and values of the query parameters to filter the incoming requests and cache the results based on the names and values specified.

Parameter Name. Specifies the parameter name.

Cache responses only for these values. API Gateway caches the API responses only for requests whose cache criteria match those set for the action, and whose criteria evaluation results in any one of the values in this list. You can add multiple entries by clicking .

XPath You can use this criterion for SOAP-based API requests whose payload is a SOAP envelope. Uses the XPath expression in the API request.
  • Name Space. Specifies the namespace of the XPath expression.
    • Prefix. Specifies the prefix for the namespace.
    • URI. Specifies the namespace URI.

    You can add multiple entries by clicking .

XPath Expression. Specifies the XPath expression in the API request.

Cache responses only for these values. API Gateway caches the API responses only for requests whose cache criteria match those set for the action, and whose criteria evaluation results in any one of the values in this list. You can add multiple entries by clicking .
Note: If this field is empty, all the values that satisfy the criteria are cached.
Time to Live (e.g., 5d 4h 1m) Specifies the lifespan of the elements in the cache after which the elements are considered to be out-of-date.

The time is specified in terms of days, hours, and minutes; for example, 5d 4h 1m.

If you do not specify any value, the Time to Live is considered to be unlimited (does not expire). If you set the value to 0d 0h 0m, the API results are not cached.

The default time format is minutes if the input is a number.

Maximum Response Payload Size (in KB) Specifies the maximum payload size for the API in kilo bytes.

The value -1 stands for unlimited payload size.

Example of enforcing caching criteria:

Cache criteria HTTP Header Query parameters XPATH Values
C1 Header1 h1, h2
C2 Header2
C3 query1 q1, q2

In the example, there are two HTTP headers and one query parameter as cache criteria. The HTTP Header Header2 has no values specified. Hence, all the incoming requests with the HTTP Header Header2 are cached.

When there are multiple cache criteria, the following behaviour is observed in the cache result:
  • If the incoming request R1 matches criteria C1, then the result is cached. API Gateway responds to any further incoming request R1 that matches criteria C1 from the cache.
  • If the incoming request R1 matches criteria C1 and C2, then the result is cached as a new request.
  • If you configure multiple cache criteria, and if one or more cache criteria match, then the result is cached. The criteria are matched with the cached results while caching the request, and it follows the AND condition among the matched criteria.