DataPower API Gateway only

ratelimit

Use the ratelimit policy to apply one or more rate, burst, or count limits at any point in your API assembly flow. Rate and burst limits restrict the number of calls made to an API in a specified time period, while count limits impose a strict limit on the total number of calls.

Gateway support

Table 1. Table showing which gateways support this policy, and the corresponding policy version
Gateway Policy version
DataPower® API Gateway 2.0.0

2.1.0 (DataPower API Gateway Version 10.0.1.0 or later)

2.2.0 (DataPower API Gateway Version 10.0.2.0 or later)

2.3.0 (DataPower API Gateway Version 10.5.0.0

This topic describes how to configure the policy in your OpenAPI source; for details on how to configure the policy in the assembly user interface, see Rate Limit.

About

The defined rate, burst, and count limits are applied to whatever follows in the assembly flow. For example, if a ratelimit policy is placed before an invoke policy, and the call made by the invoke policy exceeds the limits defined by the ratelimit policy, the API call itself fails.

The ratelimit policy has the following format:
- ratelimit:
    version: version
    title: title
    description: description
    source: rate_and_burst_limit_location
    rate-limit: rate_limits_to_apply
    burst-limit: burst_limits_to_apply

Properties

The following table describes the properties of the ratelimit policy.
Table 2. ratelimit policy properties
Property Required Description Data type
version Yes The policy version number string
title No A title for the policy. string
description No A policy description. string
source Yes The location of all the rate limit, burst limit, and count limit definitions that are included in this policy. Specify one of the following values:
  • catalog-named: the rate or burst limits to be applied are defined in the appropriate api-collection object on the DataPower API Gateway, which is the object that represents your API Connect Catalog in the gateway configuration.

    For details of how to configure a rate, burst, or count limit in the api-collection object, see Configuring a rate, burst, or count limit on the DataPower API Gateway.

  • plan-named: the limits to be applied are assembly burst limits or assembly count limits defined on the Plan to which the calling application is subscribed. For details on how to configure assembly burst limits and assembly count limits in a Plan, see Editing a draft Product.
    Note: The following conditions apply to a plan-named rate limit policy:
    • Every Plan that contains the API that is being limited must have the named rate limit applied.
    • A plan-named rate limit policy cannot be used with automatically generated Products.
  • gateway-named: the limits to be applied are defined in the apigw object, named apiconnect, on the DataPower API Gateway gateway.

    For details of how to configure a rate, burst, or count limit in the apigw object, see Configuring a rate, burst, or count limit on the DataPower API Gateway.

  • plan-default: the rate and burst limits that are applied are the default ones configured in the Plan to which the calling application is subscribed. For details on how to configure default Plan rate and burst limits, see Editing a draft Product.
    Note: The use of this option does not disable any automatic preflow rate limit policy that might be in place, and could result in the application of the rate limiting being repeated. For more information on preflow policies, see Customizing the preflow policies.
 string
rate-limit Yes1 If the source property is set to catalog-named, a list of rate limit names as defined in the DataPower API Gateway configuration,

1You must provide at least one rate, burst, or count limit.

 string
burst-limit Yes2 If the source property is set to catalog-named, a list of a burst limit names as defined in the DataPower API Gateway configuration.

If source is set to plan-named, a list of names of assembly burst limits defined in a Plan.

2You must provide at least one rate, burst, or count limit.

 string
count-limit Yes3 If source property is set to catalog-named, a list of count limit names as defined in the DataPower API Gateway configuration.

If source is set to plan-named, a list of names of assembly count limits defined in a Plan.

3You must provide at least one rate, burst, or count limit..

 string
operation No For a rate limit, specify one of the following values:
  • consume: the policy reduces the balance of available requests that remain in the interval defined by the rate limit specified by the rate-limit property.

    The amount by which the remaining balance is reduced is the value that results from the weight expression defined in the specified rate limit.

  • replenish: the policy increases the balance of available requests that remain in the interval defined by the rate limit specified by the rate-limit property.

    The amount by which the remaining balance is increased is the value that results from the weight expression defined in the specified rate limit.

    The purpose of the replenish operation is to restore an appropriate amount of remaining balance in cases where the amount calculated by an earlier consume operation turns out to be too high. For example, for an assembly rate limit with a limit of 100, a consume operation with a weight of 60 uses 60 requests, leaving 40 requests remaining for the interval. If the weight expression in the subsequent replenish operation computes to 15, meaning that the weight expression calculated that the actual request usage was only 45, the replenish operation increases the remaining requests by 15, to a remaining balance of 55.

    Note that the replenish operation cannot increase the remaining requests allowed beyond the original limit defined in the assembly rate limit scheme. In this example, a replenish operation cannot replenish requests beyond 100. A replenish operation is skipped if the weight expression evaluates to a value of less than 1.

    The default value is consume.

For a count limit, specify one of the following values:
  • inc: the current count is incremented by the value that results from the weight expression defined in the count limit specified by the count-limit property.
  • dec: the current count is decremented by the value that results from the weight expression defined in the count limit specified in the count-limit field.

By default, the count limit is automatically decremented at the end of the API assembly by the total amount incremented during the assembly, minus any decrement operations that are defined in the assembly. You do not need to explicitly define decrement operations unless you want the decrements to occur at specific points in the assembly. However, if the auto decrement feature has been explicitly disabled in the count limit configuration, you must include a corresponding decrement operation, otherwise when the count limit is reached all future calls are blocked. For more information on configuring a count limit, see Configuring a rate, burst, or count limit on the DataPower API Gateway.

The default value is inc.

For a burst limit, the only possible value is consume, meaning that the limit applied is that defined in the burst limit specified by the burst-limit field.

 string

Example


- ratelimit:
    version: 2.0.0
    title: Apply rate and burst limits
    source: catalog-named
    rate-limit:
      - 30perMinute
      - 2000per3Hours
    burst-limit:
      - 5per10Seconds