Skip to content
This repository has been archived by the owner on Jul 14, 2022. It is now read-only.

Cache reference

Jump to bottom
Will Witman edited this page Mar 12, 2015 · 6 revisions

Cache policy

About this policy

You can improve your API's performance dramatically with the cache policy.

To see a quick example, see Adding a cache policy.

Example: Declaring the cache policy

In this example, the "in-memory" cache module is declared and configured for an a127 project.

Note that in this example, the name of the cache policy instance is mycache. You'll reference this name when you apply the cache to a path.

   x-a127-services
    mycache:     
      provider: volos-cache-memory
      options:
        name: hello-cache
        ttl: 60000

Example: Applying the cache policy to a path

In this example, the cache is applied to the /hello path, and a helper function is configured. The helper source file is ./api/helpers/cache.js. And, the setKey function will be called each time this policy is executed. See also Understanding helper functions.

The name of the service instance in this example is mycache, and that name must match the name that was used when the quota service was declared.

  paths:     
    /hello:
        x-swagger-router-controller: hello_world
        x-a127-apply:
          mycache:
            key:
                helper: cache
                function: setKey

Here's a sample helper function, where the cache key is set based on a query parameter value:

      'use strict';

      module.exports = {
        setKey : setKey,
      };

      function setKey(req) {
      // This can check for a specific query parameter ("name" in this case)
        var key = req.swagger.params.name.value;
        return key;
      }

What you need to know about cache

Your a127 API will fetch response data from the cache whenever the response data changes or when the cache reaches its configured time to live.

Installing cache modules

You must install the volos-cache-* NPM module corresponding to the cache policy implementation(s) you wish to use. Note that these modules are automatically installed when you create a new a127 project. By default, they are listed in a new project's package.json. They include:

  • volos-cache-memory - The in-memory cache works no matter where you deploy your a127 project. See also Memory-specific configuration.

  • volos-cache-apigee - Uses the Apigee Edge native caching service. It only works when your project is deployed to Apigee Edge. If you attempt to start a project locally that has this cache configured, a127 returns an error unless a fallback cache is specified. See Setting a fallback cache. See also Apigee-specific configuration.

  • volos-cache-redis - Uses Redis to store cache data. Works only if you have a Redis server set up and running and that is reachable by your a127 project. See also Redis-specific configuration.

You can read more about these open-source modules in the apigee-127/volos repository on GitHub.

Configuration options

Set these configuration options when you declare a cache policy in the a127-services part of your project's swagger.yaml file. For example:

  a127-services:
    <cache-name>:
      provider: <npm-module-name>
      options:
        name: <string>
        ttl: <integer>

  • cache-name - (string) The name of this cache policy instance. You use this declared name when you apply the policy to a path. Required.

  • npm-module-name - (string) The name of the NPM module for the cache implementation you wish to use. See NPM modules. Required.

  • ttl - (integer) Time to live for the cache entries, in milliseconds. Default: 300 ms

  • encoding - (integer) Specifies the default string encoding to use for cached values. Default: none

  • maxEntries - (integer) Specifies he maximum number of entries maintained before dropping the least recent entries Default: 1000

See also Apigee-specific configuration if you are using the Apigee provider, Redis-specific configuration for the Redis provider, or In-memory-specific configuration for the in-memory provider.

Policy attributes

Set these attributes when you apply the policy to a path:

  x-a127-apply:
    <cache-name>:
      key: <string>

or, if you want to use a helper function to set the cache key:

  x-a127-apply:
    cache: 
      key:
        helper: cache
        function: setKey

  • cache-name - (string) The name of the cache policy to apply. This name must correspond to the name of a cache policy declared in a127-services. Required.

  • key - (string) Identifies a cache. This is a string that may be set to any value. Or, you can call a helper function to set the value (the second example). Each key locates a single quota instance, which has a separate counter value from other counters. See also Understanding helper functions.

Apigee-specific configuration

If you use the volos-cache-apigee NPM module, you must deploy your project to Apigee Edge. If you run locally (outside Apigee Edge), you'll receive an error. To avoid an error when you run outside of Apigee, you can specify a fallback cache. See Setting a fallback cache.

If you're using analytics, see Is cache analytics data available?.

Redis-specific configuration

If you wish to use the Redis service implementation, you need to install and run Redis. You can use a shell script like this to install and start Redis:

#!/bin/bash  
curl -O http://download.redis.io/releases/redis-2.8.17.tar.gz
tar xzf redis-2.8.17.tar.gz
cd redis-2.8.17
make
src/redis-server

If you do not wish to use the default Redis server host, port, and database, you can specify these options when you declare the cache policy service in a127-service section of the project's swagger.yaml:

  • host - The host where your Redis instance is running. Default: 127.0.0.1

  • port - The port number of the Redis instance. Default: 6379

  • db - Redis database instance to use. Default: 0

For example:

  x-a127-services:
    mycache:
      provider: volos-cache-redis
      options:
        key:
          helper: cache
          function: setKey
        host: 192.168.52.100
        port: 9003
        db: 1

In-memory-specific configuration

There are no extra configurations to perform when you use the volos-cache-memory NPM module. You can specify any of the options described previously in "Configuration options" and "Policy attributes" when declaring and applying the in-memory quota policy.

Setting a fallback cache

If you configure the volos-cache-apigee cache provider, you may wish to also specify a fallback cache. The fallback takes effect if you try to run the a127 project locally. Fallback is optional; however, if you do not specify a fallback, you'll receive an error if you try to use the Apigee cache in a local context.

Simply declare a cache that will serve as the fallback (typically an in-memory cache) and then reference that cache name in the fallback option. For example:

   x-a127-services:
    memorycache:
      provider: volos-cache-memory
      options:
        name: mymemcache
        ttl: 10000
    apigeecache:
      provider: volos-cache-apigee
      options:
        name: test-weather-cache
        ttl: 5000
        fallback: memorycache

If you run this project locally, it will use the in-memory cache. If deployed to Apigee Edge, it will use the native Edge cache.

Use with helper functions

You can use helper functions to set quota policy attributes programmatically, such as the cache key. For example, you could set the cache key based on a value obtained from the request, such as a query parameter or header. See Understanding helper functions.

Accessing cache services programmatically

In addition applying cache policies in your swagger.yaml file, you can also access the underlying cache services directly in your controllers. For details, see Programmatic access to a127 services.

Is cache analytics data available?

Currently, the Apigee Edge Analytics Services do not capture a127 cache data. This is true whether or not you add an analytics policy to your API. Therefore, a127 cache information does not show up in the Cache Performance dashboard on Edge. For example, the number of cache hits will not show up in the dashboard, as you might expect.

How do I know the cache was hit?

Currently, the a127 analytics service does not collect data on cache hits. Here are some ways you can determine that the cache is working properly:

  • Look for a Cache-Control response header. When a response is served from the cache, expect a header like this: Cache-Control: public, max-age=5, must-revalidate. The max-age should correspond to the TTL of your configured cache.
  • When a response is served from the cache, the path's controller method will not execute.
  • Test the cache with a short TTL -- sometimes it's easy to tell the difference between the time it takes to receive a cached response versus one that requires a back-end trip.

Why use a cache?

You might want to use a general purpose cache to:

  • Reduce latency: A request satisfied from the cache gets the representation and displays it in a shorter time. The server is more responsive with requests satisfied from the cache, which is closer to the client than the origin server.

  • Reduce network traffic: Representations are reused, reducing the impact of processing duplicate or redundant requests. Using a cache also reduces the amount of bandwidth you use.

For more information

Having Trouble? Try posting your question to the Apigee Community. Or, for more links and resources, check out our Help Page

Contents

Need help? Visit the Apigee Community !
Clone this wiki locally