This topic introduces caching and persistence features supported by Apigee Edge.


API proxies that run on API Services are stateless. They enforce policies and execute scripts and code, but the environment in which they run is populated with context that is specific to each request/response transaction.

To provide API proxies with access to data over multiple transactions, API Services provides a persistence layer that enables API proxies to store data. The persistence layer consists of L1 and L2 caches and a NoSQL key/value store. These caches and the data store work together to optimize availability and performance.

As a developer, you can access this persistence layer without knowing the details of its implementation. Instead, you use a set of policies to interact with the persistence layer at runtime. API Services defines three policy types that enable you to configure persistence for API proxies using configuration instead of code.

Apigee Edge supports these persistence scenarios:

  • A cache for serving duplicates of stored static response messages
  • A general purpose caching mechanism for persisting any arbitrary objects used by your API proxies
  • HTTP/1.1 compliant caching
  • A highly performant NoSQL key/value store for simple data sets used by your API proxies


Response caching is a dedicated application of the API Services caching mechanism. Response caching is implemented in the ResponseCache policy, so enabling ResponseCaching for your APIs requires no coding on your part.

Not all data is updated in real-time. Services often only update data periodically, for example,  weather data updates every 10 minutes, or product catalog prices update every 24 hours.

When ResponseCache is employed in a proxy, Edge also looks at certain HTTP response caching headers and takes appropriate actions according to the directives of those headers. For example, on responses from backend targets, Edge supports the Cache-Control header, which can be used to control the maximum age of a cached response, among other directives. For more information, see HTTP response caching.

Note: To optimize performance, cached responses larger than 256 KB are not distributed across the Apigee Edge server infrastructure. It's possible that a cached response will not be retrieved if it is cached on one server, but the request is handled by a different distributed server. In this case, you may see API calls that are sent to the backend even though they have been cached. 

See Response Cache policy.


Caching is more general purpose than ResponseCache, enabling you to persist any objects that your API proxies require over multiple request/response sessions. API Services provides policies for populating, retrieving, and flushing the cache at runtime. The interaction mechanism that links the API proxies with the underlying cache is variables. You can use policies or code in your API proxies to populate and retrieve cached objects by interacting with the variables that you define in caching policies. API Services also exposes a RESTful API for managing Cache resources.

Common uses of Cache include temporary storage of:
  • Session IDs for session management
  • Credentials used for our outbound calls (such as API keys or OAUth access tokens)
  • Response content that must be paginated for apps

See Optimize performance using cache.

HTTP/1.1 compliant caching

Apigee Edge supports a subset of HTTP/1.1 compliant cache headers, including the cache-control header and entity tags. For more information, see HTTP response caching.

Key/value Map

If the data you need to store is structured or is long-lived, then use the key/value map.

Examples of situations where you would use the key/value store are:

  • A map of IP addresses to country codes
  • A list of IP addresses for whitelisting/blacklisting
  • A mapping of long URLs to corresponding shortened URLs

API Services provides a set of policies for interacting with the key/value store at runtime. It also exposes a RESTful API for managing the contents of the key/value store. The API enables you, for example, to perform bulk operations to populate the key/value store with large data sets.

Therefore, key/value maps work better for single entities that have many properties. For example:

curl -H "Content-Type:application/json" -X POST -d \
  "entry" : [ {
    "name" : "development",
    "value" : ""
  }, {
    "name" : "production",
    "value" : "" } ],
  "name" : "URLs"
}' \{org_name}/keyvaluemaps \
-u myname:mypass 

The result is a key/value map that can be retrieved as JSON or XML for use at runtime by policies or code that you write.

You can add entries to the key/value map by using the PUT verb. You only need to include the entries to be added:

curl -H "Content-Type:application/json" -X PUT -d \
  "entry" : [ {
    "name" : "staging",
    "value" : ""
  } ],
  "name" : "URLs"
}' \{org_name}/keyvaluemaps \
-u myname:mypass 

See Key Value Map Operations policy.

Cache versus Key/value map

The PopulateCache policy does not persist cache entries. Entries are in memory until the configured expiration time. You can look up the value only until it expires. One limitation is that you cannot find the list of keys that are currently in a cache.

When using KeyValueMap, the keys are persisted indefinitely. There are APIs available to retrieve the list of keys. There is no expiration time for the keys; you must explicitly delete them.

Get help

For help, see Apigee Customer Support.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)