Introduction

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 and putting, getting, and removing 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 between 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. To learn more about the distributed cache, see Optimize performance using cache.

When you use this module locally, outside of Apigee Edge, the cache is stored in memory inside Node.js. This support is provided primarily for testing purposes.

For an introduction to the apigee-access module and its other features, see Using the apigee-access module.

Methods


(1) getCache

var cache = apigee.getCache('cache-name');

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:

cache-name - The name of the cache to access.

Returns:

A cache object.

Example:

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

 


(2) getCache

var customCache = apigee.getCache('cache-name', { parameter: 'value'} );

Access a custom cache resource specified in a configuration object. For information about how to create a cache resource, see Manage Caches for an Environment.

Parameters:

cache-name - The name of the custom cache.

{parameter: 'value'} - (Optional) 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.

  • 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:

var apigee = require('apigee-access');
var customCache = apigee.getCache('MyCustomCache',
  { resource: 'MyCustomResource'} ); 

 


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.

  • 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:

var apigee = require('apigee-access');
var cache = apigee.getCache();
// Insert a string with a timeout of 120 seconds
cache.put('key2', 'Hello, World!', 120);
// Insert a string and get notified when insert is complete
cache.put('key4', 'Hello, World!', function(err) {
  // "err" will be undefined 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.

  • 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:

var apigee = require('apigee-access');
var cache = apigee.getCache();
cache.get('key', function(err, data) {
  // If there was an error, then "err" will be set
  // "data" is the item that was retrieved
  // It will be a Buffer or a String depending on what was inserted.
});

 


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.

  • callback (Required): A callback function that will be called with an Error object as the first parameter if there is an error.

Example:

var apigee = require('apigee-access');
var cache = apigee.getCache();
cache.remove('key', function(err) {

});

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?)