Skip to main content
API7.ai Logo

Parameters​

See plugin common configurations for configuration options available to all plugins.

This plugin supports referencing sensitive parameter values from environment variables using the env:// prefix, or from a secret manager, such as HashiCorp Vault’s KV secrets engine, using the secret:// prefix. For more information, see environment variables in plugin and secrets.

note

In API7 Enterprise (from 3.8.17), you should configure one of the following parameter sets, but not both:

  • count, time_window
  • rules

  • count

    integer | string

    required

    vaild vaule:

    greater than 0

    The maximum number of requests allowed within a given time interval.

    In API7 Enterprise (from 3.8.17), this parameter also supports the string data type and allows the use of built-in variables prefixed with a dollar sign ($).

  • time_window

    integer | string

    required

    vaild vaule:

    greater than 0

    The time interval corresponding to the rate limiting count in seconds.

    In API7 Enterprise (from 3.8.17), this parameter also supports the string data type and allows the use of built-in variables prefixed with a dollar sign ($).

  • window_type

    string

    default: fixed

    vaild vaule:

    fixed or sliding

    Rate limiting algorithm, fixed window or sliding window.

  • key_type

    string

    default: var

    vaild vaule:

    var, var_combination, or constant

    The type of key.

    If the key_type is var, the key is interpreted as a variable.

    If the key_type is var_combination, the key is interpreted as a combination of variables.

    If the key_type is constant, the key is interpreted as a constant.

  • key

    string

    default: remote_addr

    The key to count requests by.

    If the key_type is var, the key is interpreted as a variable. The variable does not need to be prefixed by a dollar sign ($). See built-in variables for available variables.

    If the key_type is var_combination, the key is interpreted as a combination of variables. All variables should be prefixed by dollar signs ($). For example, to configure the key to use a combination of two request headers custom-a and custom-b, the key should be configured as $http_custom_a $http_custom_b.

    If the key_type is constant, the key is interpreted as a constant value.

  • rejected_code

    integer

    default: 503

    vaild vaule:

    between 200 and 599 inclusive

    The HTTP status code returned when a request is rejected for exceeding the threshold.

  • rejected_msg

    string

    vaild vaule:

    any non-empty string

    The response body returned when a request is rejected for exceeding the threshold.

  • policy

    string

    default: local

    vaild vaule:

    local, redis, redis-cluster, or redis-sentinel

    The policy for rate limiting counter.

    Set to local to store the counter in memory locally.

    Set to redis to store the counter on a Redis instance.

    Set to redis-cluster to store the counter in a Redis cluster.

    Set to redis-sentinel to store the counter on the Redis primary node managed by Redis Sentinel, which ensures high availability by automatically promoting a replica to primary in case of failure. Redis Sentinel provides high availability for Redis when not using Redis Cluster.

  • redis_sentinels

    array[object]

    An array of Redis Sentinel nodes (host and port). Required when policy is redis-sentinel.

  • redis_master_name

    string

    The name of the Redis master group that Sentinels are monitoring. Required when policy is redis-sentinel.

  • redis_role

    string

    default: master

    vaild vaule:

    master or slave

    The Redis node role to connect to. Configurable when policy is redis-sentinel. Set to master to connect to the current Redis master, and set to slave to connect to a Redis replica.

  • redis_connect_timeout

    integer

    default: 1000

    vaild vaule:

    greater than or equal to 1

    Timeout in milliseconds for establishing a connection to a Redis node. Configurable when policy is redis-sentinel.

  • redis_read_timeout

    integer

    default: 1000

    vaild vaule:

    greater than or equal to 1

    Timeout in milliseconds for reading data from a Redis node. Configurable when policy is redis-sentinel.

  • redis_keepalive_timeout

    integer

    default: 60000

    vaild vaule:

    greater than or equal to 1

    Time in milliseconds that an idle Redis connection is kept alive in the connection pool before being closed. Configurable when policy is redis-sentinel.

  • sentinel_username

    string

    Username used to authenticate with the Redis Sentinel instance. Configurable when policy is redis-sentinel.

  • sentinel_password

    string

    Password used to authenticate with the Redis Sentinel instance. Configurable when policy is redis-sentinel.

  • allow_degradation

    boolean

    default: false

    If true, allow the gateway to continue handling requests without the plugin when the plugin or its dependencies become unavailable.

  • rules

    array[object]

    An array of rate-limiting rules that are applied sequentially.

    Available in API7 Enterprise from 3.8.17.

    • count

      integer | string

      required

      vaild vaule:

      greater than 0

      The maximum number of requests allowed within a given time interval.

      This parameter also supports the string data type and allows the use of built-in variables prefixed with a dollar sign ($).

    • time_window

      integer | string

      required

      vaild vaule:

      greater than 0

      The time interval corresponding to the rate limiting count in seconds.

      This parameter also supports the string data type and allows the use of built-in variables prefixed with a dollar sign ($).

    • key

      string

      required

      The key to count requests by. If the configured key does not exist, the rule will not be executed.

      The key is interpreted as a combination of variables, for example, $http_custom_a $http_custom_b.

    • header_prefix

      string

      Prefix for all rate limiting response headers. Available in API7 Enterprise from version 3.8.19.

      When configured, the prefix is inserted after X- in the header name. For example, with header_prefix set to test, the headers become X-Test-RateLimit-Limit, X-Test-RateLimit-Remaining, and X-Test-RateLimit-Reset.

      When not configured, the index of the rule in the rules array is used as the prefix. For example, headers for the first rule will be X-1-RateLimit-Limit, X-1-RateLimit-Remaining, and X-1-RateLimit-Reset.

  • show_limit_quota_header

    boolean

    default: true

    If true, includes the rate limiting response headers. Specifically, if rules is not set, the headers are:

    • X-RateLimit-Limit shows the total quota.
    • X-RateLimit-Remaining shows the remaining quota.
    • X-RateLimit-Reset shows the number of seconds until the counter resets.


    When rules is set, a prefix (followed by a hyphen) is inserted after X-. See rules.header_prefix for details.

  • group

    string

    vaild vaule:

    non-empty

    The group ID for the plugin, such that routes of the same group can share the same rate limiting counter.

  • redis_host

    string

    The address of the Redis node. Required when policy is redis.

  • redis_port

    integer

    default: 6379

    vaild vaule:

    greater than or equal to 1

    The port of the Redis node when policy is redis.

  • redis_username

    string

    The username for Redis if Redis ACL is used. If you use the legacy authentication method requirepass, configure only the redis_password. Used when policy is redis.

  • redis_password

    string

    The password of the Redis node when policy is redis, or redis-cluster.

  • redis_database

    integer

    default: 0

    vaild vaule:

    greater than or equal to 0

    The database number in Redis when policy is redis or redis-sentinel.

  • redis_ssl

    boolean

    default: false

    If true, use SSL to connect to Redis when policy is redis.

  • redis_ssl_verify

    boolean

    default: false

    If true, verify the server SSL certificate when policy is redis.

  • redis_timeout

    integer

    default: 1000

    vaild vaule:

    greater than or equal to 1

    The Redis timeout value in milliseconds when policy is redis or redis-cluster.

  • redis_cluster_nodes

    array[string]

    The list of Redis cluster nodes with at least two addresses. Required when policy is redis-cluster.

  • redis_cluster_name

    string

    The name of the Redis cluster. Required when policy is redis-cluster.

  • redis_cluster_ssl

    boolean

    default: false

    If true, use SSL to connect to Redis cluster when policy is redis-cluster.

  • redis_cluster_ssl_verify

    boolean

    default: false

    If true, verify the server SSL certificate when policy is redis-cluster.

  • sync_interval

    number

    default: -1

    vaild vaule:

    greater than or equal to 0.1, or the default -1

    The frequency of synchronizing counter data to Redis. Available only in Enterprise.

    The sync_interval value should be smaller than time_window. A value of 1 results in synchronizing counter data every second. A value of -1 yields no change in synchronizing behaviour, i.e. counter data will be synchronized for each request.