• About this policy
• Example: Declaring the quota policy
• Example: Applying the quota policy to a path
• NPM modules
• Configuration options
• Policy attributes
• Apigee-specific configuration
• Redis-specific configuration
• In-memory-specific configuration
• Use with helper functions
• Usage notes
• Understanding the quota policy
• For more information

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.

For more details, see Understanding the quota policy

In this example, 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

In this example, 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

You must install the volos-quota-* NPM module corresponding to the quota service implementation you wish to use. Note that these modules are automatically installed when you create a new a127 project. They are listed in the project's package.json by default.

• volos-quota-apigee - Uses the Apigee Edge quota service for storing and enforcing quota counts. The a127 API communicates directly with Apigee Edge for quota storage and enforcement. To use this option, you must have an a127 account that is configured with the apigee provider. See also Apigee-specific configuration.

• 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. See also Redis-specific configuration.

• volos-quota-memory - Stores quota counts in local memory. See also Memory-specific configuration.

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

Set these configuration options when you declare the policy 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 - (string) The name of this quota 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 quota implementation you wish to use. See NPM modules. Required.

• 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

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.

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

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

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

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

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. (See Using remote services.)
• Bind the RemoteProxy service to your a127 project.
• Add the following parameters to the a127-config section of your project's swagger.yaml file, where is the name of the remote proxy service you created and bound to the project:

    x-a127-config:
      <RemoteProxy-Name>.key: &apigeeProxyKey CONFIGURED
      <RemoteProxy-Name>.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

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

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.

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.

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.

Use a quota 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.

Use a quota when you want to limit the number of connections apps can make to your API proxy's target backend over a specific period of time.

Quota is typically used to enforce business contracts or SLAs with developers and partners, rather than for operational traffic management. For example, you may have one quota set for paying customers and another for "freemium" (non-paying) users.

Don't use it to protect your API proxy against traffic spikes. For that, use a spike arrest policy.

A quota enforces consumption limits on client apps by maintaining a distributed 'counter' that tallies incoming requests. The counter can tally API calls for any identifiable entity, including apps, developers, API keys, access tokens, and so on. Usually, API keys are used to identify client apps. In this example, we show how to enforce a quota based on the incoming client IP address.

Quota can be computationally expensive so, for high-traffic APIs, it should configured for longer time intervals, such as a day or month.

It’s important to choose the right tool for the job at hand. Quota policies configure the number of request messages that a client app is allowed to submit to an API over the course of an hour, day, week, or month. The quota policy enforces consumption limits on client apps by maintaining a distributed counter that tallies incoming requests.

Use a quota policy to enforce business contracts or SLAs with developers and partners, rather than for operational traffic management. For example, a quota might be used to limit traffic for a free service, while allowing full access for paying customers.

Use spike arrest to protect against sudden spikes in API traffic. Typically, spike arrest is used to head off possible DDoS or other malicious attacks. See also Spike arrest policy.

• Adding a quota policy
• Blog: Adding a request quota to your Apigee-127 API
• weather-advanced sample on GitHub
• quota-example on GitHub