You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/cache/optimize-performance-using-cache). info

> [!WARNING]
> **Private Cloud Deprecation Notice:**
>
> **Support for [Node.js](https://docs.apigee.com/api-platform/nodejs/overview-nodejs-apigee-edge) proxies
> and [secure vaults](https://docs.apigee.com/api-platform/nodejs/using-secure-store)**
>
> Since 2013, Apigee has supported the
> [use of Node.js proxies within Apigee
> Edge](https://www.programmableweb.com/news/apigee-api-platform-now-supports-node.js-allowing-developers-to-build-highly-customized-apis-and-apps/brief/2013/10/25) through the use of [Trireme](https://github.com/apigee/trireme), which enables you to run your Node.js code
> within Apigee Edge for Private Cloud and expose it as an API.
>
>
> Apigee recommends Private Cloud customers take the following steps:
>
> - Migrate data in secure vaults to [Encrypted Key Value Maps](https://docs.apigee.com/api-platform/cache/key-value-maps#aboutencrypted) (KVM) to access sensitive data from an API proxy.
> - Migrate Trireme (Node.js) based API proxies to a native Node.js environment outside of Apigee.
>
>
> See also [Apigee deprecations and retirements](https://docs.apigee.com/release/deprecated-features).

> [!WARNING]
> **Public Cloud Retired feature:** The traditional, Trireme-based
> Node.js support on Apigee Edge Cloud is retired and, by extension,
> [apigee-access](https://docs.apigee.com/api-platform/nodejs/using-apigee-access) is also
> retired because it is only used in Trireme-based Node.js applications deployed on Apigee Edge.
> Trireme-based Node.js was retired on October 10, 2019. See
> [Trireme-based Node.js End of Life](https://docs.apigee.com/release/notes/trireme-nodejs-eol).

You can use the `apigee-access` module to access the Edge distributed cache from
within a Node.js application. The module includes methods for [getting a
cache](https://docs.apigee.com/api-platform/nodejs/access-cache-nodejs#getCache1) and [putting](https://docs.apigee.com/api-platform/nodejs/access-cache-nodejs#put), [getting](https://docs.apigee.com/api-platform/nodejs/access-cache-nodejs#get), and [removing](https://docs.apigee.com/api-platform/nodejs/access-cache-nodejs#remove) data.

The Apigee Edge distributed cache lets you store strings or other data. Like most caches, it
is a least-recently-used cache with a maximum size. Inside Apigee Edge, the cache is distributed
among all nodes where your Node.js application executes. You can manage the cache through an
Apigee Edge API. Using the API, you can manually create cache resources, or you can use the
default resource. For an introduction to caching on Apigee Edge, see [Persistence tools in Edge](https://docs.apigee.com/api-platform/cache/persistence-tools). To learn more
about the distributed cache, see [Example: General purpose
caching](https://docs.apigee.com/api-platform/cache/optimize-performance-using-cache).

For an introduction to the `apigee-access` module and its other features, see
[Using the apigee-access module](https://docs.apigee.com/api-platform/nodejs/using-apigee-access).

## Methods

- (1) [getCache](https://docs.apigee.com/api-platform/nodejs/access-cache-nodejs#getCache1)
- (2) [getCache](https://docs.apigee.com/api-platform/nodejs/access-cache-nodejs#getCache2)
- [put](https://docs.apigee.com/api-platform/nodejs/access-cache-nodejs#put)
- [get](https://docs.apigee.com/api-platform/nodejs/access-cache-nodejs#get)
- [remove](https://docs.apigee.com/api-platform/nodejs/access-cache-nodejs#remove)

*** ** * ** ***

### (1) getCache

`var
cache = apigee.getCache(cacheName);`  

Look up a named cache and create it if necessary. The resulting cache uses a pre-defined set
of configuration parameters suitable for most situations.

**Parameters:**

***cacheName*** - A string, the name of the
cache. (Not the name of the cache resource).

**Returns:**

A cache object.

**Example:**

```javascript
var apigee = require('apigee-access');
var cache = apigee.getCache('cache');
```

*** ** * ** ***

### (2) getCache

`var
customCache = apigee.getCache(cacheName, options );`  

Access a custom cache resource specified in a configuration object. For information about how
to create a cache resource, see [Creating and editing an environment
cache](https://docs.apigee.com/api-platform/cache/manage-caches-environment).

**Parameters:**

***cacheName*** - A string, the name of the
custom cache. (Not the name of the cache resource)

***options*** - A configuration object. The
object can be empty, or it can contain the following optional parameters:

- **`resource`**: The name of an Apigee "cache resource" where the
  cache data is stored. Cache resources are used to fine-tune memory allocation and other cache
  parameters. If not specified, a default resource will be used. If the cache resource does not
  exist, then the method throws an error.

- **`scope`** : Specifies whether cache entries are prefixed to
  prevent collisions. Valid values are `global`, `application`, and
  `exclusive`.

  - `global`: All cache entries may be seen by all Node.js applications in the
    same Apigee "environment."

  - `application`: All cache entries may be seen by all Node.js caches that are
    part of the same Apigee Edge application.

  - `exclusive`: (Default) Cache entries are only seen by Node.js caches in the
    same application that have the same name. This is the default.

- **`prefix`** : If the cache key name includes a prefix, as
  described in [Populate
  Cache policy](https://docs.apigee.com/api-platform/reference/policies/populate-cache-policy) and [Working with cache keys](https://docs.apigee.com/api-platform/reference/policies/working-cachekeys), use
  this parameter to specify it. Edge automatically adds a double-underscore suffix to the
  prefix name. So if a cache key was created with the prefix "UserToken", the prefix to specify
  here is "UserToken__".

- **`defaultTtl`**: Specifies the default time to live for a cache
  entry, in seconds. If not specified then the default TTL in the cache resource will be
  used.

- **`timeout`**: How long to wait to fetch a result from the
  distributed cache, in seconds. The default 30 seconds. Latency-sensitive applications may
  wish to reduce this in order to prevent slow response times if the cache infrastructure is
  overloaded.

**Returns:**

A custom cache object.

**Example:**

```javascript
var apigee = require('apigee-access');
var customCache = apigee.getCache('doesNotMatter',
  { resource: 'MyCustomResource', scope: 'global', prefix: 'UserToken'} );
customCache.put("myCacheKey", "xyz");
```

This works with a LookupCache policy configured like this:

```javascript
<LookupCache name="Lookup-Cache-1">
  <CacheKey>
    <Prefix>UserToken</prefix>    
    <KeyFragment>myCacheKey</KeyFragment>
  </CacheKey>
  <CacheResource>MyCustomResource</CacheResource>
  <Scope>Global</Scope>
  <AssignTo>contextVariable</AssignTo>
</LookupCache>
```

*** ** * ** ***

### put

`cache.put('key',
data, ttl, function(error));`  

Put data into a cache.

**Parameters:**

- ***`key`***: (Required) A string that uniquely identifies
  the item in the cache. Cache keys are limited to a size of 2 KB.

- ***`data`***: (Required) A string, Buffer, or object that
  represents the data to cache. Any other data type will result in an error. For convenience,
  objects will be converted into a string using "JSON.stringify".

- ***`ttl`***: (Optional) The maximum time to persist the
  data in the cache, in seconds. If not specified then a default TTL will be used.

- ***`callback`***: (Optional) If specified, a function that
  will be called once the data is safely in the cache. It will be called with an Error object
  as the first parameter if there is an insertion error, and otherwise it will be called with
  no parameters.

**Example:**

```javascript
var apigee = require('apigee-access');
var cache = apigee.getCache();
// Insert a string into cache using the default TTL
cache.put('key1', 'Buenos dias, Mundo!');
// Insert a string into cache using a TTL of 120 seconds
cache.put('key2', 'Hello, World!', 120);
// Insert a string with the default TTL, and get notified when the insert is complete
cache.put('key3', 'Ciao, Mondo!', function(error) {
  // "error" will be falsy unless there was an error on insert
});
// Insert a string with a TTL of 600 seconds, and get notified when the insert is complete
cache.put('key4', 'Hallo Wereld!', 600, function(error) {
  // "error" will be falsy unless there was an error on insert
});
```

*** ** * ** ***

### get

`cache.get('key',
function(error, data));`  

Retrieve data from a cache.

**Parameters:**

- ***`key`*** (required): A string that uniquely identifies
  the item in the cache.

  For cache entries put to the cache from an Apigee Edge policy (such as [Populate Cache policy](https://docs.apigee.com/api-platform/reference/policies/populate-cache-policy)), you
  will need to construct the cache key by inferring from the specific way the policy creates
  keys for entries. To do this, you'll need to know how the policy is configured. While
  [Working with cache keys](https://docs.apigee.com/api-platform/reference/policies/working-cachekeys)
  describes how cache keys are created by policies, keep in mind that you shouldn't specify
  string values related to scope; in calls from Node.js, scope is already part of the
  context.
- ***`callback`*** (required): A function that will be called
  when the data is available. If there is cached data, it is returned in the second
  parameter.

  - ***`error`*** - An Error object. If there is an error
    while retrieving from the cache, then an Error object will be set here. Otherwise this
    parameter will be set to "undefined".

  - ***`data`*** - The data retrieved, if any. It will be
    one of four values:

    - If a string was inserted, it will be a string.
    - If a Buffer was inserted, it will be a Buffer.
    - If an object was inserted, it will be a string containing the JSON version of the object as produced by "JSON.stringify".
    - If nothing was found, then it will be "undefined".

**Example:**

```javascript
var apigee = require('apigee-access');
var cache = apigee.getCache();
cache.get('key', function(error, data) {
  // If there was an error, then "error" will be set.
  // If error is falsy, "data" is the item that was retrieved:
  //   - undefined, in the case of cache miss, or
  //   - a Buffer, or
  //   - a String
});
```

*** ** * ** ***

### remove

`cache.remove('key', function(error));`  

Invalidate a cached item. Once a key is invalidated, subsequent get() requests will return
"undefined" unless another value is inserted.

**Parameters:**

- ***`key`*** (Required): A string that uniquely identifies
  the item in the cache to invalidate.

  For cache entries put to the cache from an Apigee Edge policy (such as [Populate Cache policy](https://docs.apigee.com/api-platform/reference/policies/populate-cache-policy)), you
  will need to construct the cache key by inferring from the specific way the policy creates
  keys for entries. To do this, you'll need to know how the policy is configured. While
  [Working with cache keys](https://docs.apigee.com/api-platform/reference/policies/working-cachekeys)
  describes how cache keys are created by policies, keep in mind that you shouldn't specify
  string values related to scope; in calls from Node.js, scope is already part of the
  context.
- ***`callback`*** (Required): A callback function that will
  be called with an Error object as the first parameter if there is an error.

**Example:**

```javascript
var apigee = require('apigee-access');
var cache = apigee.getCache();
cache.remove('key', function(error) {
});
```