Configuring plan rate limits for DataPower Nano Gateway with IBM API Studio

When you use plan limits on application programming interfaces (APIs) for DataPower Nano Gateway with IBM API Studio, you must manually add a plan rate limit policy to your API assemblies in addition to configuring the plan limit in your product and plan.

About this task

When you use DataPower Nano Gateway with IBM API Studio, plan rate limits require configuration in two places:

Product and plan configuration: Define the plan rate limit values in your product plans by using the rate limit map in the components.rateLimits section.
API assembly: Manually add the plan rate limit policy to your API assembly flow to enforce the limits.

Important: In standalone DataPower Nano Gateway deployments, the plan limit policy is automatically added to the preflow. However, when you use the current version of IBM API Studio, this automatic behavior does not occur, and you must manually add the plan limit policy to the beginning of any API assembly where you want to enforce plan limits.

Procedure

Complete the following steps to configure plan rate limits for DataPower Nano Gateway with IBM API Studio:

Define the plan rate limit in the product's components.rateLimits section.
In your product YAML file, define the plan rate limit parameters in the components.rateLimits section. Each plan rate limit definition includes the maximum number of calls that are allowed (max), the interval length (intervalLen), and the interval unit (intervalUnit).

The following example shows a plan rate limit definition:
```
components:
  rateLimits:
    limit-100-per-hour:
      - max: 100
        intervalLen: 1
        intervalUnit: hour
```
Configure the plan rate limit in your product plan's rate limit map.
In the plan configuration, add a rateLimitMap entry that references the plan rate limit definition. Use the special key plan-limit to designate this configuration as a plan limit that is applied to all calls to the plan.

The following example shows a plan configuration:
```
plans:
  default-plan:
    title: Default Plan
    description: Default Plan
    approval: false
    rateLimitMap:
      plan-limit: limit-100-per-hour
    apis:
      - name: my-api
```
Add the plan rate limit policy to your API assembly.
To enforce the limit, a special plan rate limit policy that applies plan limits must be added to the beginning of your API assembly flow.

The plan rate limit policy uses an alias limit that references the plan-limit key in the plan's rate limit map.

The plan-limit key is case-sensitive and has special behavior. It is always safe to place a rate limit policy with alias name plan-limit in an API assembly. Unlike any other alias name, if an alias limit named plan-limit is executed but the effective plan at transaction time does not have a rateLimitMap with key plan-limit, the limit is simply not applied and there is no error. (For any other alias name, it is a startup or transaction time error if the alias name is not a key in the effective plan's rateLimitMap.)

The following example shows an API assembly configuration:
```
assembly:
  execute:
    - rateLimit:
        name: preflow-plan-limit
        target: all
        limits:
          - alias:
              name: plan-limit
    - invoke:
        title: invoke
        version: 2.0.0
        verb: keep
        target-url: $(target-url)$(api.operation.path)
        follow-redirects: false
        timeout: 60
        parameter-control:
          type: blocklist
          values: []
        header-control:
          type: blocklist
          values: []
        inject-proxy-headers: true
```
Important:
The placement of the plan rate limit policy in the assembly is critical. The plan limit policy should be placed near the very beginning of the assembly flow to prevent the execution of the API assembly if the plan limit has been exceeded. That's why the plan limit policy is intended to occur in the preflow. In this special situation, where the user has to place the plan limit policy in the mainflow themselves, it should be placed at or very near the beginning of the mainflow. Any action that appears before the plan rate limit action will be executed even if the plan limit is exceeded.

However, if there is an authorization action that determines if the caller is subscribed, the plan limit policy must occur after the authorization action (because subscription information is used to determine what plan the caller is subscribed to, and the plan limit must match that information to apply the correct plan limit).
- The alias name plan-limit is case-sensitive and must match exactly the key in the plan's rateLimitMap.
- The special plan rate limit action that applies plan limits should always use a target of all.