Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

Accessing the quota service in Node.js

Introduction

This topic explains how to use the apigee-access to access the Apigee Edge quota service from a Node.js application. With apigee-access, you can apply and reset quota values.

On Apigee Edge, a quota is an allotment of request messages that an app is allowed to submit to an API over the course of an hour, a day, a week, or a month. To learn more about quotas and their use cases, see Quota policy.

Example

var apigee = require('apigee-access');
var quota = apigee.getQuota();
quota.apply({ identifier: 'Foo', allow: 10, timeUnit: 'hour' },
    function(err, result) {
         console.log('Quota applied: %j', result);
    });

When working with apigee-access to use the quota service, you are restricted to working only with the service that runs inside Apigee Edge. For another quota implementation that works in multiple environments (in addition to Edge), you may wish to use the Volos.js quota feature. See "Understanding Volos.js" for details.

Methods


apply

Modifies the settings on a Quota object. Use this method to increment or decrement the quota, change time intervals, and make other configurations.

Usage

var apigee = require('apigee-access');
var quota = apigee.getQuota();
quota.apply({parameters}, callback);

Example

var apigee = require('apigee-access');
var quota = apigee.getQuota();

	// Apply a quota of 100 requests per hour
	quota.apply({
	 identifier: 'Foo',
	 timeUnit: 'hour',
	 allow: 100
	}, quotaResult);
		
		function quotaResult(err, r) {
		 if (err) { console.error('Quota failed'); }
		}	

Parameters

The apply() method takes two parameters, an object and a function:

(1) The first parameter is a JSON object with these fields:

  • identifier (string, required): A unique identifier of the quota bucket. In practice it might be an application ID, IP address, or username.
  • timeUnit (string, required): How long the quota bucket will accumulate until it is reset. Valid values are "minute," "hour," "day," "week," and "month."
  • allow (number, required): The maximum value for the quota bucket. This value will be combined with the current value to return whether the quota has succeeded.
  • interval (number, optional): Combined with the "timeUnit" to determine how long before the quota is reset. The default is 1. Set to a larger value to allow quotas such as "two hours," "three weeks," and so on.
  • weight (number, optional): The value to increment the quota by. Default is 1.

(2) The second argument is a callback function with these two arguments:

  • The first argument is an Error object if the quota cannot be incremented, or undefined if the operation succeeded.
  • The second is an object that contains the following fields:
    • used (number): The current value of the quota bucket.
    • allowed (number): The maximum value of the quota bucket before the quota is considered to be exceeded. The same value was passed as "allow" in the request object.
    • isAllowed (boolean): If there is room left in the quota -- true as long as "used" is less than or equal to "allowed."
    • expiryTime (long): The timestamp, in milliseconds since 1970 format, when the quota bucket will be reset.
    • timestamp (long): The timestamp at which the quota was updated.

Example

var apigee = require('apigee-access');
var quota = apigee.getQuota();
 

// Apply a quota of 100 requests per hour
quota.apply({
  identifier: 'Foo',
  timeUnit: 'hour',
  allow: 100
}, quotaResult);
 

// Apply a quota of 500 requests per five minutes
quota.apply({
  identifier: 'Bar',
  timeUnit: 'minute',
  interval: 5,
  allow: 500
}, quotaResult);


// Increment the quota by a value of 10
quota.apply({
  identifier: 'Foo',
  timeUnit: 'hour',
  allow: 100,
  weight: 10
}, quotaResult);


function quotaResult(err, r) {
  if (err) { console.error('Quota failed'); }
}

reset

To reset the quota to zero, call quota.reset(). This method takes two parameters:
  • A JSON object with these fields:
    • identifier (string, required): A unique identifier of the quota bucket. In practice it might be an application ID, IP address, or username.
    • timeUnit (string, required): How long the quota bucket will accumulate until if it is reset. Valid values are "minute," "hour," "day," "week," and "month."
    • interval (number, optional): Combined with the "timeUnit" to determine how long before the quota is reset. The default is 1. Set to a larger value to allow reset times such as "two hours," "three weeks," and so on.
  • A callback function:
    • The callback takes an Error object as the first parameter if the reset fails.

 

Advanced Quota use case

When creating a quota, you can include an optional "options" object. This object has one optional parameter:
  • syncInterval (number, optional): The number of seconds that the distributed quota implementation syncs its state across the network. The default is 10.
Use this parameter to optimize performance of the distributed quota across the network. Keep in mind that a lower setting will degrade performance and dramatically increase the latency of the "apply" operation. The default setting of 10 seconds is a good setting for many applications. The interval may be set as low as zero, which means that the state is synchronized every time "apply" is called. Performance will be much worse in this case.

Help or comments?