Helper functions

Understanding helper functions

Helper functions let you programmatically set certain option values for the cache, quota, spike arrest, and oauth2 policies.

• What are helper functions used for?
• What can I set with helper functions?
• How to configure a helper function
• Sample helper implementation
• More examples

What are helper functions used for?

Use helper functions to programmatically set certain values for Apigee-127 policies. Helper functions are attached to individual policies and are called whenever the policy is invoked.

What can I set with helper functions?

You can programmatically set the following policy parameter values with helper functions:

• Cache policy

  • key -- Sets the cache key.

• Spike arrest policy

  • key -- Specifies a distinct spike arrest counter "bucket". If not set, a single count is maintained for all API traffic.

• Quota policy

  • key -- Specifies a distinct quota "bucket". Each bucket maintains a separate counter value from other counters. If not set, a single quota count is maintained for all APIs.

• OAuth 2.0 policy

  • passwordCheck -- Specifies a function that validates the password for the password grant type.

How to configure a helper function

Let's look at how to configure a helper function to set a cache key for the cache policy.

To set up a cache, you first add a cache provider it to your swagger.yaml file with the x-a127-services extension:

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

Then, here's the pattern for applying the cache to a path using the x-a127-apply extension:

      paths:
          /hello_cached:
              x-swagger-router-controller: hello_world
              x-a127-apply:
                mycache: 
                  key:
                    helper: volos
                    function: cacheKey
              get:
                ...

The key property specifies a helper function that programmatically sets the cache key whenever this API path is invoked.

In this example, the helper function is called cacheKey, and it is defined in the ./api/helpers/volos.js. file.

Sample helper implementation

Continuing with the cache example, here's a simple cacheKey helper function implementation. It sets a cache key value passed in a query parameter.

This approach is useful where you want to selectively cache data. For example, you might want to cache data returned from an /addresses endpoint based on the name of a user or a business name, or something similar. For example: /addresses?name=Wallgreens

      'use strict';

      var debug = require('debug')('helpers');

      module.exports = {
        cacheKey: cacheKey,
      };

      function cacheKey(req) {
      // This can check for a specific query parameter ("name" in this case)
        var key = req.swagger.params.name.value;
        if (debug.enabled) { debug('Cache Key: '+key); }
        return key;
      }

By default, helper files must be located in the ./api/helpers directory of your Apigee-127 project.

More about programmatic access to Apigee-127 services

In addition to using helper functions, you can

More examples

Several examples in the a127-samples repository on GitHub use helper functions. See for example:

• cache-example
• quota-example
• oauth-password-sample

See also these blog posts:

• Tutorial: Adding Caching to your Apigee-127 API
• Tutorial: Adding a Request Quota to your Apigee-127 API