Skip to main content
API7.ai Logo

Parameters​

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

  • count

    integer | string

    vaild vaule:

    greater than 0

    The maximum accumulated GraphQL query cost allowed within a given time interval. Query cost is depth under the default strategy. Required when rules is not configured. The value can use built-in variables when configured as a string.

  • time_window

    integer | string

    vaild vaule:

    greater than 0

    The time interval corresponding to the rate limiting count in seconds. Required when rules is not configured. The value can use built-in variables when configured as a string.

  • rules

    array[object]

    An array of rate-limiting rules that are applied sequentially. Configure either rules or the top-level count and time_window, but not both.

    • count

      integer | string

      required

      vaild vaule:

      greater than 0

      The maximum accumulated GraphQL query cost allowed within the rule's time_window. Query cost is depth under the default strategy. The value can use built-in variables when configured as a string.

    • time_window

      integer | string

      required

      vaild vaule:

      greater than 0

      The time interval corresponding to the rule's count in seconds. The value can use built-in variables when configured as a string.

    • key

      string

      required

      The key to count requests by. Supports combinations of built-in variables, with each variable prefixed by a dollar sign ($). If the key cannot be resolved, the rule is not applied.

    • header_prefix

      string

      Prefix inserted into the rate limiting response headers for this rule. For example, foo produces X-foo-RateLimit-Limit, X-foo-RateLimit-Remaining, and X-foo-RateLimit-Reset.

  • cost_strategy

    string

    default: depth

    vaild vaule:

    depth, complexity, or node_quantifier

    How the raw cost of a GraphQL document is computed. depth counts the selection nesting depth, which is what this plugin has always done. complexity scores the nodes the query resolves. node_quantifier scores only nodes whose matching cost decoration resolves an argument listed in mul_arguments. If no node has both a matching decoration and a usable quantifier, the document's raw score is 0. For complexity and node_quantifier, the plugin adds 0.01, applies score_factor, and rounds up before charging the quota. The default factor produces a charged cost of 1 from a zero raw score; a factor greater than 100 increases it. Introduced in API7 Enterprise 3.10.6.

  • max_cost

    number

    default: 0

    vaild vaule:

    greater than or equal to 0

    Reject a document whose charged cost exceeds this value with 403 Forbidden before it reaches the upstream. The request consumes quota before this check. 0 disables the check and lets the quota alone decide. Introduced in API7 Enterprise 3.10.6.

  • score_factor

    number

    default: 1

    vaild vaule:

    greater than 0

    Scaling applied before the cost is rounded up, charged against the quota, and compared with max_cost. Introduced in API7 Enterprise 3.10.6.

  • resolve_variables

    boolean

    default: true

    If true, resolve supplied GraphQL variables, variable defaults declared by the operation, and argument defaults from the upstream schema when computing cost. The default ensures variable-based quantifiers contribute their resolved value. Introduced in API7 Enterprise 3.10.6.

  • introspection_endpoint

    string

    vaild vaule:

    starts with http:// or https://

    Endpoint used to introspect the upstream GraphQL schema, which the complexity and node_quantifier strategies need in order to match cost decorations. Derived from the upstream when unset. The result is cached per worker and Service. Introduced in API7 Enterprise 3.10.6.

  • introspection_headers

    object

    Headers sent on the schema introspection request for an upstream whose introspection endpoint requires credentials. The headers come from the configuration rather than from the request because the introspected schema is cached per worker and Service. When Data Plane data encryption is enabled, this field is encrypted at rest. Introduced in API7 Enterprise 3.10.6.

  • 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, or redis-cluster

    The policy for rate limiting counter. If it is local, the counter is stored in memory locally. If it is redis, the counter is stored on a Redis instance. If it is redis-cluster, the counter is stored in a Redis cluster.

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

  • show_limit_quota_header

    boolean

    default: true

    If true, includes the rate limiting response headers. Specifically:

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

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

  • 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_keepalive_timeout

    integer

    default: 10000

    vaild vaule:

    greater than or equal to 1000

    Keepalive timeout in milliseconds for Redis when policy is redis or redis-cluster.

    This parameter is available in API7 Enterprise from version 3.9.16 on the 3.9 line and from version 3.10.3 on the 3.10 line, and in APISIX from version 3.17.0.

  • redis_keepalive_pool

    integer

    default: 100

    vaild vaule:

    greater than or equal to 1

    Keepalive pool size for Redis when policy is redis or redis-cluster.

    This parameter is available in API7 Enterprise from version 3.9.16 on the 3.9 line and from version 3.10.3 on the 3.10 line, and in APISIX from version 3.17.0.

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

Plugin Metadata​

  • limit_header

    string

    default: X-RateLimit-Limit

    Default response header name for the total rate limit quota. Available in API7 Enterprise from version 3.10.6.

  • remaining_header

    string

    default: X-RateLimit-Remaining

    Default response header name for the remaining rate limit quota. Available in API7 Enterprise from version 3.10.6.

  • reset_header

    string

    default: X-RateLimit-Reset

    Default response header name for the number of seconds until the rate limit counter resets. Available in API7 Enterprise from version 3.10.6.