Cache

Tip

This document describes the detailed usage of a specific policy. If you are using Apinizer policy structure for the first time or want to learn the general working principles of policies, we recommend that you first read the What is Policy? page.

Overview

The Cache policy performs standalone cache read (LOOKUP), write (POPULATE), and delete (INVALIDATE) operations within the policy chain. Unlike the embedded cache mechanism of the API Call policy, it lets you explicitly control in the policy flow when the cache is accessed, which value is written, and what is deleted.

The policy can be added to the request, response, and error flows.

What is its Purpose?

• Reduce backend load by keeping rarely changing data in the cache.
• Avoid repeating expensive computations or API calls by storing their results.
• Temporarily store variable values within the policy chain.
• Keep the cache up to date by deleting the related entry (INVALIDATE) when data changes.

Working Principle

Cache Key

All three operation types use a key built the same way:

• Key Prefix: Fixed text added to the beginning of the key (e.g., profile, user-session). Used to prevent the keys of different policies from colliding.
• Key Variables: The list of variables that make up the parts of the key. Any variable can be used, such as an HTTP header, a query parameter, a body field, or a context variable. Up to 32 variables can be added.

The key is built by joining the prefix and the resolved values of the variables in order with the | character:

<Key Prefix>|<variable1 value>|<variable2 value>|...

Warning

• At least one of Key Prefix and Key Variables must be defined; if both are empty, the policy cannot be saved.
• Project, environment, or API Proxy information is not added to the key automatically. The same key is shared across different API Proxies and environments. Use a Key Prefix to avoid collisions.
• If the resulting key exceeds 1024 characters, it is automatically converted to its MD5 digest.

Storage Type

Option	Description
Distributed (default)	Entries are kept in the Apinizer Cache service and shared by all Gateway pods.
Local	Entries are kept in the memory of each Gateway pod; they are not shared between pods.

1. LOOKUP (Read from Cache)

Searches the cache with the built key and updates the Target Variable according to the result. A missing entry is not an error and does not stop the flow. If an error occurs while accessing the cache, the behavior is determined by the Error Handling setting.

LOOKUP Result States

State	When it occurs	Target Variable	Flow
Hit	An entry exists for the key	Cached value is written	Continues
Empty Value Found	An intentionally stored empty value exists for the key (written with "Cache Null/Empty Values" enabled)	Empty value is written — this still counts as a find	Continues
Miss	No entry exists for the key	Custom variable: cleared (any value left by earlier steps is removed). Body / header / parameter: left untouched — the message is never modified on a miss	Continues

Info

Why is a custom target variable cleared on a miss? The same variable may have been populated earlier in the policy chain. If the lookup returns nothing and the variable is left untouched, that stale value could be mistaken for a cached result. To keep behavior predictable, a custom target variable is always emptied on a miss, so later policies can safely check whether it holds a value.

Why are body, header and parameter targets not cleared? Those targets are part of the message itself. Clearing them on a miss would alter the request or response (for example, wiping the request body, adding a null field at the JSON path, or emptying an XML node) before it reaches the backend. On a miss such targets are therefore left exactly as they were; only a hit writes to them.

2. POPULATE (Write to Cache)

Writes the value of the Source Variable to the cache with the built key.

• If the source value is empty, the write is skipped. If Cache Null/Empty Values is checked, the empty value is written as well; a value stored this way is returned as a Hit on later lookups. This avoids repeated backend calls for queries whose result is known to be empty.
• TTL: How long the entry stays in the cache (seconds). A new policy comes with 3600; if the field is cleared, 60 seconds is used.
• Capacity: Capacity of the cache area. A new policy comes with 10000; if the field is cleared, 1000 is used. All Cache policies use the same shared cache area; with Local storage, the capacity of this area is set by the policy that first creates it.
• Dynamic TTL: When enabled, the TTL is calculated from the value of a variable (see Dynamic TTL).

3. INVALIDATE (Invalidate Cache)

Deletes the entry matching the built key from the cache. For example, it is used to clear the old entry after an update operation. There are no additional fields for this operation besides the key.

Dynamic TTL

When Enable Dynamic TTL is turned on for a POPULATE operation, the TTL is calculated from the value of the Dynamic TTL Variable instead of a fixed value. How the variable value is interpreted is set by Dynamic TTL Source:

Dynamic TTL Source	Meaning of the value
ISO 8601 DateTime	The time the entry expires, in ISO 8601 format
Custom DateTime	The time the entry expires, in the format given in the Custom Date Pattern field
Epoch Seconds	Expiration time, epoch seconds
Epoch Milliseconds	Expiration time, epoch milliseconds
Expires-In Seconds	Validity period from now, in seconds
Expires-In Milliseconds	Validity period from now, in milliseconds
TTL String	A duration made of a number and a unit: s (seconds), m (minutes), h (hours); the unit can also be uppercase. E.g. 300s, 5m, 1h

Additional fields:

• Is JWT Token?: When enabled, the variable value is decoded as a JWT and the TTL information is read from the claim given in the JWT Claim Name field. If the claim name starts with $., it is processed as a JSONPath.
• Offset (seconds): Time subtracted from the calculated TTL. For example, if 30 is entered, the entry expires 30 seconds before the calculated time.
• Fallback TTL (seconds): TTL used if the dynamic TTL cannot be resolved.

The TTL is determined in this order:

1. If the dynamic TTL resolves successfully to a positive value, that value is used.
2. If the dynamic TTL resolves but gives zero or a negative value (for example, the expiration time has passed), the entry is not written.
3. If the dynamic TTL cannot be resolved, the Fallback TTL is used.
4. If no Fallback TTL is defined, the value in the TTL field is used (3600 for a new policy), or 60 seconds if that field is empty.

Info

While Dynamic TTL is enabled, the TTL field cannot be edited on the screen.

Error Handling

Field	Default	Description
Cache Connection Timeout (Second)	3	Connection timeout for distributed cache operations. Applies only when Storage Type is Distributed.
Behavior on Cache Error	Continue Flow	Behavior when an error occurs during the cache operation (for example, when the cache service cannot be reached). With Continue Flow, the flow proceeds; with Stop Flow, the policy raises an error. This setting also applies when a delete fails in an INVALIDATE operation; with Local storage, deleting a key that does not exist also counts as a failure.

Configuring Policy Parameters

In this step, users can create a new Cache policy or configure existing policy parameters to define cache operations.

Creating New Cache Policy

Configuration Steps

Step	Description / Operation
Step 1: Go to Creation Page	Go to Global Policies → Cache from the left menu and create a new policy. The policy can also be added directly to an API Proxy's flow.
Step 2: General	Status: Shows Active/Passive status. Name (Required): The name of the policy. The system checks whether the name is available. Description: Text explaining the purpose of the policy.
Step 3: Operation	Select the operation type (Required): - Read from Cache (LOOKUP) - Write to Cache (POPULATE) - Invalidate Cache (INVALIDATE)
Step 4: Cache Key	Storage Type: Local or Distributed (default: Distributed). Key Prefix: Fixed text added to the beginning of the key. Key Variables: Add the variables that make up the key with the + button. At least one of Key Prefix and Key Variables must be filled.
Step 5a: Lookup Details	Target Variable (Required): The variable the value read from the cache is written to.
Step 5b: Populate Details	Source Variable (Required): The variable whose value is written to the cache. Capacity (entries): 1 – 1,000,000 (default 10000). TTL (seconds): 1 – 2,592,000 (default 3600). Cache Null/Empty Values: Writes the entry even when the source value is empty. Enable Dynamic TTL: When enabled, the Dynamic TTL Variable (required), Dynamic TTL Source (required), Custom Date Pattern (required when Custom DateTime is selected), Is JWT Token?, JWT Claim Name (required when JWT is selected), Offset (seconds), and Fallback TTL (seconds) fields appear.
Step 5c: INVALIDATE	There are no additional fields; the entry matching the key defined in Step 4 is deleted.
Step 6: Error Handling	Cache Connection Timeout (Second) (Required): Default 3. Behavior on Cache Error: Continue Flow (default) or Stop Flow.
Step 7: Conditions (Optional)	On the Conditions tab, you can define that the policy runs only when certain conditions are met.
Step 8: Error Message Customization (Optional)	On the Error Message Customization tab, you can customize the message returned when the policy raises an error (Stop Flow).
Step 9: Save	Click Save and Deploy on the Global Policies page, or Save in the dialog opened from an API Proxy flow. The button stays disabled if the name, operation type, key (prefix or variable), or the Target/Source Variable required by the operation is missing; other required fields such as the Dynamic TTL fields and the timeout are checked on save and the save is rejected if they are missing.

For descriptions of Conditions and Error Message Customization panels, you can review the Conditions and Error Message Customization sections on the What is Policy? page.

For a complete guide on all layers, priority order and scenario examples of the error message configuration system, see the Error Message Configuration Guide page.

Deleting Policy

For deletion steps of this policy and operations to be applied when in use, you can refer to the Removing Policy from Flow section on the Policy Management page.

Exporting/Importing Policy

For export and import steps of this policy, you can refer to the Export/Import page.

Binding Policy to API

For the process of how this policy will be bound to APIs, you can refer to the Binding Policy to API section on the Policy Management page.

Frequently Asked Questions (FAQ)

Category	Question	Answer
General	What is the difference between the Cache policy and the API Call policy's cache?	The API Call policy's cache stores the response of the call made by that policy. The Cache policy lets you decide which value is read and written and when, with standalone LOOKUP / POPULATE / INVALIDATE operations.
General	Can I use multiple Cache policies in the same API?	Yes. For example, you can read a value with a LOOKUP policy and, if it is missing, write it with a POPULATE policy after the backend call. To access the same data, both policies must use the same Key Prefix and Key Variables.
Technical	How are long keys handled?	If the resulting key exceeds 1024 characters, it is automatically converted to its MD5 digest. No separate setting is needed.
Technical	What happens if the dynamic TTL cannot be resolved?	The Fallback TTL is used; if that is missing, the value in the TTL field; if that field is empty, 60 seconds. If the dynamic TTL is zero or negative (the expiration time has passed), the entry is not written.
Usage	What happens to the flow on a LOOKUP hit?	The value is written to the Target Variable and the flow continues normally.
Usage	What happens to the Target Variable on a LOOKUP miss?	A custom Target Variable is cleared; a body, header, or parameter target is left untouched. The flow continues; a miss is not an error.
Usage	How does LOOKUP behave if an empty value was written to the cache?	An empty value stored with "Cache Null/Empty Values" is treated as a Hit on lookup, and the empty value is written to the Target Variable.
Error	What happens when a cache access error occurs?	It depends on the Behavior on Cache Error field: with Continue Flow the flow proceeds; with Stop Flow the policy raises an error.
Error	Writing to the cache succeeds but reading returns a miss. Why?	Check that the Key Prefix and Key Variables in the POPULATE and LOOKUP policies are the same and that the variables produce the same values at runtime. Also make sure both policies use the same Storage Type.