policy

This command defines the caching policy for the API gateway.

Syntax

policy pattern [priority] [TTL] [data-grid] [cache-responses] [return-expired] [REST-invalidation] [cache-response-PUT-POST-request]

policy pattern [priority] protocol [data-grid] [cache-responses] [cache-validation] [return-expired] [REST-invalidation]

policy pattern [priority] nocache

Parameters

pattern
A shell-style match pattern that identifies documents.
priority
Specifies the priority of a document to add to or remove from the cache. The greater the value, the higher its priority. Enter a value in the range 1 - 255. The default value is 128.
  • When the cache adds documents, the cache uses the policy with the highest priority. If the document matches multiple policies with the same priority, the cache uses the first matching policy in the alphabetized list.
  • When the cache removes documents, the cache removes documents that were added by policies with the lowest priority. If multiple documents have the same priority, the cache removes the document that was least recently accessed.
TTL
Specifies the validity period in seconds for a document in the cache. Enter a value in the range 5 - 31708800. The default value is 900.
nocache
Indicates that documents that conform to the match pattern are not cached.
protocol
Indicates that documents that conform to the match pattern are cached in compliance to HTTP caching rules.
data-grid
Specifies the name of the eXtreme Scale configuration for document caching.
cache-responses
Specifies whether to cache the response to an HTTP GET request. The default value is off.
on
Caches server responses.
off
Does not cache server responses.
cache-validation
Specifies whether the document cache operates on HTTP cache validation requests from the client. The default value is off.
on
Operates on HTTP cache validation requests, which include any of the following request-header fields.
  • If-Modified-Since
  • If-Unmodified-Since
  • If-Match
  • If-None-Match
off
Does not operate on HTTP cache validation requests that include the request header fields.
return-expired
Indicates whether to return expired, or stale, content. The default value is off.
on
To return expired content, the client request must indicate that it is acceptable to receive a stale resource by using the Cache-Control: max-stale directive. In the following situations, the expired content is returned.
  • When unable to establish a connection with the origin server.
  • When another request is actively fetching a fresh version of the resource from the origin server.
off
Does not return expired content.
REST-invalidation
Specifies whether to invalidate the document cache entry when a PUT, POST, or DELETE request matches the entry. The default value is off.
on
Invalidates the document cache entry on PUT, POST, or DELETE requests.
off
Does not invalidate the document cache entry on PUT, POST, or DELETE requests.
cache-response-PUT-POST-request
Specifies whether to cache the response to POST and PUT requests. To cache responses to POST and PUT requests, in addition to requests in a processing policy, enable the cache-response-PUT-POST-request and cache-responses parameters. The default value is off.
on
Caches responses to POST and PUT requests.
off
Does not cache responses to POST and PUT requests.

Guidelines

The policy command defines the caching policy for the API gateway. A document cache policy can define the following characteristics.
  • Which documents to cache. Eligibility is determined by a shell-style match pattern that specifies which documents that are acquired over HTTP are cached. Candidate documents are evaluated against the expression. Only documents with a URL that matches the expression are cached. If a document matches multiple policies, the cache uses the policy with the highest priority. If the document matches multiple policies with the same priority, the cache uses the first matching policy in the alphabetized list.
  • The priority of a document in the cache. When the cache exceeds its maximum size, the assigned priority determines which documents to delete. The cache deletes documents that were added by policies with the lowest priority. If multiple documents have the same priority, the cache deletes the document that was least recently accessed.
  • Whether to use the eXtreme Scale grid for document caching. The document cache supports the grid as a highly available and highly scalable shared cache.
  • Whether to cache the response to an HTTP GET request. Ensure that the document cache size is sufficiently large to contain the cached documents. You might receive an error if the specified document cache size is smaller that the response document. When the cache policy type is protocol-based and the response contains the Vary header or the response does not contain the Date header, the response is not cached.
  • Whether the document cache operates on HTTP cache validation requests from the client that include certain conditional GET request header fields. If the HTTP GET request results in a cache match, the cache is validated to determine the appropriate response. If there is a cache miss, the request is forwarded to the origin server.
  • Whether to cache the response from POST and PUT requests. For the cache response to POST and PUT requests property to take effect for server responses, ensure the following conditions.
    • Specify the fixed policy type.
    • Enable the property to cache server responses.

    If you do not enable server response caching, responses to POST and PUT requests during only processing are cached.

  • To return expired content, the client request must indicate that it is acceptable to receive a stale resource by using the Cache-Control: max-stale directive. In the following situations, the expired content is returned.
    • When unable to establish a connection with the origin server.
    • When another request is actively fetching a fresh version of the resource from the origin server.

    When the return expired documents property is enabled, a document might persist in the cache after the document is expired. The cached document is returned even though it is potentially stale. A warning header indicates that the document is stale.

  • Whether to invalidate the document cache entry when a PUT, POST, or DELETE request matches the entry. This property cannot be enabled when the cache response to POST and PUT requests property is enabled.
  • The validity period for a document in the cache. The time-to-live (TTL) or lifetime of the document in the cache. When this time expires, the document is marked as expired but remains in the cache. The next request for the expired document retrieves the document again.
When the document cache policy is a protocol-based policy, the policy is set as follows.
  • If the document does not contain a Data or Last-Modified header, do not cache the document.
  • If the document contains a Vary header, do not cache the document.
  • If the document contains a Cache-Control header (HTTP/1.1), cache the document and use the contents of that field to determine a document shelf-life.
  • If the document contains an Expires header (HTTP/1.0), cache the document and use the contents of that field to determine a document shelf-life.
  • If the document contains a Last-Modified header, cache the document and use the contents with the Data header to heuristically determine a document shelf-life. The shelf-life cannot exceed 8 hours.

When the document cache policy is a fixed policy or protocol-based policy and the document contains a x-dp-cache-key header, cache the document and use the contents of that field for the unique identifier of the document cache entry.

You can specify multiple policies, but the policies are stored in an alphabetized sequence. Candidate documents are evaluated against each policy to find a match.

The priority of policies is important to ensure that candidate documents are cached for the appropriate validity period.
  • Use a high priority for policies that use the nocache keyword.
  • Use a low priority for generic policies. For example, set the priority to 1 when * or *.xml is the match pattern.