Configuring a rate, burst, or count limit on the DataPower API Gateway

If you want to include a rate limiting policy in your API assembly flow, you must first configure the required rate, burst, and count limits on the Gateway. Rate and burst limits restrict the number of calls that an application can make to API in specified time period, while count limits impose a strict limit on the total number of calls.

About this task

You configure rate, burst, and count limits on the DataPower® API Gateway by defining them in one or more configuration files that you package and then add to the Gateway as a Gateway extension.

You define Catalog scoped rate, burst, and count limits 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. The defined rate, burst, and count limits will be available to be included in Rate Limit policies in the assembly flows of all the APIs that are published to that Catalog.

You define Gateway scoped rate, burst, and count limits in the appropriate apigw object on the DataPower API Gateway. The defined rate, burst, and count limits will be available to be included in Rate Limit policies in the assembly flows of all the APIs that are published to that Gateway.

The system clock determines the start time for rate, burst, and count limits. The intervals are configured as follows:

1 second interval starts at each new second.
1 minute interval starts at the beginning of each minute.
1 hour interval starts at the beginning of each hour.
1 day interval starts at midnight UTC.
1 week interval starts on Thursday at 00:00:00 UTC.

Note:

Only one Gateway extension can be in use at any one time, so you should package all required rate, burst, and count limits in a single Gateway extension.
To apply a Catalog scoped or Gateway scoped rate, burst, or count limit, it must be referenced in a Rate Limit policy in an API assembly.
You should ensure that all rate, burst, and count limit names are unique across all your Plans and Catalogs. When an API is called, information about any rate, burst, or count limits (such as name, limiting criteria, and remaining number of calls) is returned in the HTTP headers of the response. If two or more limit definitions with exactly the same name are applied during the invocation of an API, information about only one of them is returned. However, all limiting criteria are applied.

Procedure

Create a .cfg file that includes the DataPower API Gateway CLI commands that define the rate, burst, or count limit.
To define a rate limit, use the assembly-rate-limit command. To define a burst limit, use the assembly-burst-limit command. To define a count limit, use the assembly-count-limit command. For details of the command parameters, see assembly-rate-limit, assembly-burst-limit, and assembly-count-limit in the DataPower product documentation.
Example 1: Configuring a Catalog scoped rate limit
top; config; switch apiconnect; api-collection myorg_mycatalog_collection assembly-rate-limit 30per1min 30 1 minute on off on on off off "" "my.vars.expected-amount - my.vars.actual-amount" exit
In this example, the assembly-rate-limit command specifies a rate limit name, and the API call limits that you want to impose, 30 calls per minute in this case. The final, optional argument, "my.vars.expected-amount - my.vars.actual-amount", is a weight expression. You use weight expressions in cases where you want to restore an appropriate amount of remaining rate limit balance when an earlier usage calculation in your assembly flow turns out to be too high. You define two rate limiting policies in your assembly flow, one with a consume operation, and a subsequent one with a replenish operation that restores some of the remaining rate limit balance if appropriate. The weight expression calculates the amounts to be consumed or replenished; for more information, see Rate Limit.
The api-collection command specifies the api-collection object in which you want to configure the rate, burst, or count limits. The name of the api-collection object has the following format:
org_catalog_collection
where:

org is the name of the provider organization that contains your Catalog.

catalog is the name of the Catalog.
This api-collection object name is assigned automatically by the Gateway the first time that a Product is published to the Catalog.
Example 2: Configuring a Catalog scoped count limit
top; config; switch apiconnect; api-collection myorg_mycatalog_collection assembly-count-limit maxsixty 60 1 on on off off off off "" "1" off exit
The final argument is the autodecrement property that controls whether the count limit is automatically decremented at the end of an API assembly. The default value is on, meaning that at the end of the assembly the count limit is automatically decremented 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.
Example 3: Configuring a Gateway scoped rate limit
top; config; switch apiconnect; apigw apigw_object_name assembly-rate-limit 30per1min 30 1 minute on off on on off off "" "my.vars.expected-amount - my.vars.actual-amount" exit
The apigw command specifies the name of the apigw object in which you want to configure the rate, burst, or count limits; the apigw object name is the same as the name of the API Connect domain in your DataPower API Gateway configuration.
Package the .cfg file in a .zip file.
You can package multiple .cfg files in a single .zip file if you want; the .cfg files must all be at the root of the .zip file.
Add the .zip file to the DataPower API Gateway as a Gateway extension. For details, see Configuring your Gateway server extensions.

What to do next

Apply the rate, burst, or count limits to an API by adding a Rate Limit policy to the API assembly flow.