Rate limiter

This policy limits the number of requests allowed within a defined time period.

A Rate limiter policy tracks and manages the number of API invocations during a defined interval. It updates or evaluates rate-limit counters and can send events to the configured destinations when limits are reached or exceeded.

You can use this policy to monitor and control usage patterns, enforce subscription-based limits, and trigger alerts for overuse by specific clients.

The Rate limiter policy can generate different types of events depending on the configuration:

  • Policy violation event. Generated when a rate-limit threshold is exceeded. Each violation produces a separate event.
  • Monitor event. Generated at the frequency specified in the configuration to report usage statistics for the limit.

In IBM API Studio, this policy is identified by the kind RateLimit.

Example of a Rate Limiter policy in code view.

kind: RateLimit
apiVersion: api.ibm.com/v2
metadata:
  name: ratelimit
  version: 1.0
  namespace: wm_project
spec:
  target: "Subscribed" #optional - default(all), also All, NonSubscribed, Specified<Vec<GroupID>>
  limits: 
    - limitDef: 
        name: "moderate-limit" #required
        definition: 
          $ref: wm_project:moderate-limit-def:1.0
        operation: "update" # consume | replenish | check | update
  extensions:
    webm-gateway:
      apiVersion: api.ibm.com/v2
      spec:
        destination:
          - api_gateway
          - dev_portals
          - email:
              - nas@sag.com
              - daso@sag.com
          - snmp
          - jdbc
          - centraSite
          - elasticsearch
          - log-file:
              level: info
---
kind: RateLimitDef 
apiVersion: api.ibm.com/v2
metadata:
  name: moderate-limit-def
  version: 1.0
  namespace: wm_project
spec:
  consumerSpecific: true #optional, default is false
  max: 50 #size 
  intervalLen: 1
  intervalUnit: "minute" #second, minute, hour, day, week, calendarweek, calendarmonth
  extensions: 
    webm-gateway:
      apiVersion: api.ibm.com/v2
      spec:
        alertMessage: 'Ratelimit reached'
        alertFrequency: 'always' # always | once

For the RateLimit policy kind, configure these specifications:

Type Description
spec

This defines the RateLimit policy settings that you can configure.

You can set the following specifications:

  • target. Defines the consumer group affected by the rate limit. Supported values include:
    • All. Applies to all consumers.
    • Subscribed. Applies to consumers with a subscription.
    • NonSubscribed. Applies to consumers without a subscription.
    • Specified. Applies to specific consumer groups.
  • limits. Contains one or more rate-limit definitions.
    • limitDef. Describes an individual rate-limit rule.
      • name. Specifies a unique name for the rate-limit rule.
      • definition. References a rate-limit definition. Provide the reference as a $ref in the format: namespace:definition-name:version.
      • operation. Defines how the rule updates or checks the rate-limit counter. Supported values:
        • consume. Decrements the counter.
        • replenish. Increases the counter.
        • check. Evaluates the counter without changing it.
        • update. Modifies the counter using the referenced definition.
  • extensions. Adds gateway-specific behavior.
    • webm-gateway. Configures webMethods API Gateway settings.
      • apiVersion. Specifies the API version for the extension.
      • spec. Defines the destinations that receive rate-limit events.
        • api_gateway
        • centraSite
        • elasticsearch
        • email with one or more addresses
        • jdbc
        • log-file with a log level such as info.
        • snmp

In IBM API Studio, the limit definition is identified by the kind RateLimitDef.

To configure the RateLimitDef, you can specify:

Type Description
spec

This defines the rate-limit parameters used to calculate and manage consumption for this limit definition.

You can configure the following specifications:

  • consumerSpecific. Indicates whether the rate limit applies per consumer. The default value is false.
  • max. Defines the maximum value of the request count beyond which the policy is violated.
  • intervalLen. Specifies the numerical length of the rate-limit interval.
  • intervalUnit. Defines the interval unit. Supported values include:
    • second
    • minute
    • hour
    • day
    • week
    • calendarweek
    • calendarmonth
  • extensions. Adds gateway-specific settings.
    • webm-gateway. Configures the webMethods API Gateway extension.
      • alertMessage. Specifies the message sent when the rate limit is reached.
      • alertFrequency. Controls how often alerts are generated. Supported values:
        • always. Sends an alert every time the limit is reached.
        • once. Sends a single alert for the first occurrence.