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

Quota reference

Jump to bottom
wwitman edited this page Mar 3, 2015 · 9 revisions

Quota policy

About this policy

Use the Quota policy to configure the number of request messages that an app is allowed to submit to an API over the course of an hour, day, week, or month.

When an app reaches its quota limit, subsequent API calls are rejected; a127 returns a 403 status error message for every request that exceeds the Quota.

NPM modules

You must install the volos-quota-* NPM module corresponding to the quota service implementation you wish to use:

  • volos-quota-apigee - Uses the Apigee Edge quota service for storing and enforcing quota counts. To use this option, you must have an a127 account that is configured with the apigee provider. It's a best practice to use this module if you intend to deploy your API to Apigee Edge.

  • volos-quota-redis - Stores quota counts in a Redis key/value store. You must have a Redis server installed and running if you want to use this option.

  • volos-quota-memory - Stores quota counts in local memory.

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

Configuration options

Set these configuration options in the a127-services part of your project's swagger.yaml file:

      a127-services:
        <quota-name>:
            provider: <npm-module-name>
            options:
              timeUnit: <minute|hour|day|week>
              interval: <integer>
              allow: <integer>
              startTime: <ISO 8601 date>

  • quota-name - The name of this quota instance. You use this declared name when you apply the policy to a path.

  • npm-module-name - The name of the NPM module for the quota implementation you wish to use. See NPM modules

  • timeUnit - (string) Specifies how often the quota resets. Valid values: minute, hour, day, or week. Default: month

  • interval - (integer) Specifies the interval of time (in hours, minutes, or days as defined by timeUnit) applicable to the quota. For example, an interval of 24 with a timeUnit of hours means that the quota will be calculated over the course of 24 hours. Default: 1

  • allow - (integer) Specifies the number of requests to allow in a time interval. For example, an allow attribute value of 100, interval of 1, and a timeUnit of month specify a quota of 100 messages per month.

  • startTime - (string in ISO 8601 date and time format) Specifies when the quota to start the quota timer. If you do not specify a start time, then a quota set to reset in "one day" will reset 24 hours after the first message is received, but if the start time is set to the top of the hour on some day, then the quota will always reset at the top of the hour. Default: The current date at 12:00:00

Policy attributes

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

        x-a127-apply:
            <quota-name>:
                key: <string>
                weight: <integer>
                allow: <integer>

  • quota-name - The name of the quota instance to apply. This name must correspond to the name of a quota policy declared in a127-services.

  • allow - (integer) Specifies the number of requests to allow in a time interval. Overrides the allow value specified in the policy service declaration. For example, an allow attribute value of 100, interval of 1, and a timeUnit of month specify a quota of 100 messages per month.

  • key - (string) Identifies a quota "bucket" instance. This is a string that may be set to any value. Each key locates a single quota instance, which has a separate counter value from other counters.

  • weight - (integer) Not commonly used. Specifies the "weight" assigned to each message. This value increases the impact of requests that, for example, consume more computational resources than others.

    For example, you may want calculate POST messages as being twice as "heavy" or expensive, as GET messages. Or, you can extract a value for messageWeight HTTP headers, query parameters, or an XML or JSON request payload, and then use a helper function to set the weight accordingly.

    If the quota is 10 messages per minute and the messageWeight for POST requests is 2, then the quota will permits 5 POST requests in any 10 minute interval. The quota will be violated starting with the sixth message and messages will start being rejected.

Apigee-specific configuration

If you use the volos-quota-apigee NPM module, then a few extra configuration steps are required. You must:

  • Create an a127 project with the apigee provider.
  • Create a RemoteProxy service.
  • Bind the RemoteProxy service to your a127 project.
  • Add the following parameters to the a127-config section of your project's swagger.yaml file:
    x-a127-config:
      RemoteProxy.key: &apigeeProxyKey CONFIGURED
      RemoteProxy.uri: &apigeeProxyUri CONFIGURED
  • Add the key and uri options when you declare the quota service. These options reference the configured values for key and uri.
    x-a127-services:
      quota:
        provider: volos-quota-apigee
        options:
            timeUnit: minute
            interval: 1
            allow: 2
            key: *apigeeProxyKey
            uri: *apigeeProxyUri

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 quota 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:
      quota:
        provider: volos-quota-redis
        options:
            timeUnit: minute
            interval: 1
            allow: 2
            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-quota-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.

Use with helper functions

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

Usage notes

All Quotas are set to the Coordinated Universal Time (UTC) time zone.

Dates are defined as year, month, and day, in the following format: YYYY-MM-DD. For example, 2015-02-04 represents February 4, 2015.

Time of day is defined as hours, minutes, and seconds in the following format: hours:minutes:seconds. For example, 23:59:59 represents the time one second before midnight.

Note that two notations, 00:00:00 and 24:00:00, are available to distinguish the two midnights that can be associated with one date. Therefore 2015-02-04 24:00:00 is the same date and time as 2015-02-05 00:00:00. The latter is usually the preferred notation.

Example: Declaring the quota service

The "memory" quota module is declared and configured for an a127 project.

Note that in this example, the name of the quota service instance is myquota. You'll reference this name when you apply the quota to a path.

a127-services:
    myquota:
        provider: volos-quota-memory
        options:
          timeUnit: minute
          interval: 1
          allow: 2

Example: Applying the quota service to a path

The quota is applied to the /hello path, and a helper function is configured. The helper source file is ./api/helpers/quota.js. And, the setKey function will be called each time this policy is executed.

The name of the service instance in this example is myquota, 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:
        myquota:
           key:
              helper: quota
              function: setKey
            weight: 2
            allow: 10

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