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.
Configure Quota policy using the following elements.
|XML Field Name||Description|
Specifies the interval of time (in hours, minutes, or days as defined by TimeUnit) applicable to the Quota. For example, a value of 24 for the
Valid value: integer
|TimeUnit (Mandatory)||Valid values: second, minute, hour, day, or month Note: Distributed quotas cannot be configured in seconds for the time interval.|
|Allow count (Mandatory)||
Specifies a message count for the quota.
For example, a value of 100 for the Allow count with a duration of 1 month means that the quota is set to be 100 messages per month.
Valid value: integer
Note: If a count reference is specified, it takes precedence over the Allow count value.
For example, the element <Allow count="2000" countRef="request.header.allowed_quota"/> has a count header (countRef="request.header.allowed_quota") along with the count value of 2000.
|Identifier (Optional)||Variable used for uniquely identifying the client.|
Specifies the weighting defined for each message.
Message weight is used to increase impact of request messages that, for example, consume more computational resources than others. For example, you may want calculate POST requests as being twice as expensive as GET requests. A value representing
If set to
Valid values: true or false
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.
The following predefined Flow variables are automatically populated when a Quota policy executes. For more information about Flow variables, see Variables reference.
|ratelimit.allowed.count||Long||Read-Only||Defined quota for which alerts are raised|
|ratelimit.used.count||Long||Read-Only||Used quota within a quota interval|
|ratelimit.available.count||Long||Read-Only||Available quota in the counter|
|ratelimit.exceed.count||Long||Read-Only||Exceeded quota in the current counter|
|ratelimit.total.exceed.count||Long||Read-Only||Total exceeds count across the counters, because the quota policy is attached|
|ratelimit.expiry.time||Long||Read-Only||Time in milliseconds at which new quota counter starts|
|ratelimit.identifier||String||Read-Only||Resolved value of the identifier reference|
|ratelimit.class||String||Read-Only||Resolved value of the quota class identifier reference|
Variables after executing the Quota policy
|ratelimit.<policy-name>.allowed.count||Long||Read-Only||Returns the allowed quota count|
|ratelimit.<policy-name>.used.count||Long||Read-Only||Returns the current quota used within a quota interval|
|ratelimit.<policy-name>.available.count||Long||Read-Only||Returns the available quota count in the counter|
|ratelimit.<policy-name>.exceed.count||Long||Read-Only||Returns the count that exceeds the limit in the current counter|
|ratelimit.<policy-name>.total.exceed.count||Long||Read-Only||Returns the total count that exceeds the limit, because the quota policy is attached|
|ratelimit.<policy-name>.expiry.time||Long||Read-Only||Returns the time in milliseconds, which determines when the quota expires and new quota counter starts|
|ratelimit.<policy-name>.identifier||String||Read-Only||Returns the (client) identifier reference attached to the policy|
|ratelimit.<policy-name>.class||String||Read-Only||Returns the class associated with the client identifier|
|ratelimit.<policy-name>.class.allowed.count||Long||Read-Only||Returns the allowed quota count defined in the class|
|ratelimit.<policy-name>.class.used.count||Long||Read-Only||Returns the used quota within a class|
|ratelimit.<policy-name>.class.available.count||Long||Read-Only||Returns the available quota count in the class|
|ratelimit.<policy-name>.class.exceed.count||Long||Read-Only||Returns the count that exceeds the limit in the class|
|ratelimit.<policy-name>.class.total.exceed.count||Long||Read-Only||Returns the total count that exceeds the limit in the class, because the quota policy is attached|