Rate limit API traffic using Quota

The API Platform maintains counters that tally the number of requests received from individual apps. This capability enables API providers to enforce limits on the number of API calls made by apps over an interval of time. For example, you may want to limit apps to 1 request per minute, or to 10,000 requests per month.

When an app reaches the defined Quota limit, subsequent API calls are rejected. The requester receives an error message. Quotas are typically defined as the number of request messages that are permitted over the course of an hour, a day, a week, or a month.

For example, if a Quota is defined as 10,000 messages per month, then limiting happens only when 10,000 messages is reached, regardless of whether 10,000 messages were counted in the first day or last day of that period. The app thereafter is blocked from making additional requests until the Quota counter automatically resets at the end of the specified time interval, or until the Quota is explicitly reset using Reset quota counter using ResetQuota.

(A variation on Quota called SpikeArrest prevents traffic spikes (or bursts) that can be caused by an increase in usage, buggy clients, or malicious attacks. For more information on SpikeArrest, see Shield APIs using SpikeArrest.)

Quota settings can be static or dynamic. The following examples demonstrate static and dynamic Quota configurations.

Sample static Quota configuration:

In a simple, static Quota, you set a count, a time interval, and a time unit.. The following static Quota configuration limits requesting apps to 10,000 requests per month:

<Quota name="QuotaPolicy">
    <Allow count="10000"/>
    <Interval>1</Interval>
    <TimeUnit>month</TimeUnit>
</Quota>

In the example above the count is 10,000 client requests, over the course of 1 month.

Sample dynamic Quota configuration:

Dynamic Quota configurations are more useful than static Quotas.Dynamic Quotas enable to you configure a single Quota policy that enforces different Quota settings for different apps, based on the identity of the requesting app. (Another term for Quota settings in this context is "Service Plan". The dynamic Quota checks the apps' "Service Plan" and then enforces those settings.) Dynamic Quota configurations retrieve Quota settings from API product definitions based on reference to Flow variables.

Quota variables are populated at runtime by resolving an app identifier to an API product. The Identifier can be a field in the request that is unique to each app. For API proxies where OAuth is enforced, you can use client_id as the Identifier, as demonstrated in the sample policy below.

<Quota name="CheckQuota"> 
  <Interval ref="apiproduct.developer.quota.interval"/>
  <TimeUnit ref="apiproduct.developer.quota.timeunit"/>
  <Allow countRef="apiproduct.developer.quota.limit"/>
  <Identifier ref="client_id"/>
</Quota>

The example above uses the variable client_id to identify the requesting app. This works as long as the request message contains a client_id (associated with an OAuth-enabled request).

In some circumstances, Quota settings must be retrieved where no client_id is available, for example for API proxies that do not have security policies applied. In those situations, AccessEntity policy used to retrieve the appropriate API product settings. For more information, see Retrieve API product settings using GetAPIProduct.

Configuring a Quota policy

Configure Quota policy using the following elements.

Policy schema

Each policy must conform to a policy schema. All policy constructs such as elements and attributes mentioned above are defined in a schema. To download the schema, click here.

Quota flow variables

The following predefined Flow variables are automatically populated when a Quota policy executes. For more information about Flow variables, see Variables reference.

Variables after executing the Quota policy