DataPower API Gateway only

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.

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

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

  2. 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.
  3. 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.