Skip to main content
API7.ai Logo

Static Configurations​

The gateway reads up to 1 MiB of GraphQL request data by default. Increase this limit when GraphQL documents or variables can produce larger request bodies. The following examples raise it to 2 MiB (2,097,152 bytes):

For host or Docker deployments, configure the following setting:

config.yaml
graphql:
  max_size: 2097152

Then reload the gateway for the change to take effect.

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.

  • window_type

    string

    default: fixed

    vaild vaule:

    fixed or sliding

    The rate limiting window algorithm. fixed enforces each time window independently. sliding weights the previous window when calculating the current cost to smooth bursts at window boundaries.

    Introduced in API7 Enterprise 3.9.14 and 3.10.1, and APISIX 3.18.0.

  • sync_interval

    number

    default: -1

    vaild vaule:

    -1 or greater than or equal to 0.1; must be smaller than a numeric top-level time_window

    The interval in seconds at which a local counter is synchronized to Redis. It applies to redis, redis-cluster, and redis-sentinel. -1 synchronizes every request. Delayed synchronization reduces Redis round trips but allows slightly looser enforcement.

    If the applicable time_window is less than or equal to sync_interval at runtime, the gateway synchronizes that request directly.

    Introduced in API7 Enterprise 3.9.14 and 3.10.1, and APISIX 3.18.0.

  • 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 and remains the default.

    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 raw score is 0.

    For complexity and node_quantifier, the plugin adds 0.01, applies score_factor, and rounds up before charging the quota. With the default factor, a zero raw score costs 1; a factor greater than 100 increases it.

    Introduced in API7 Enterprise 3.10.6 and APISIX 3.19.0.

  • 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 rate limiter evaluates the charge first, so a request rejected by this check may still consume quota. 0 disables the check. Introduced in API7 Enterprise 3.10.6 and APISIX 3.19.0.

  • 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 and APISIX 3.19.0.

  • 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 and APISIX 3.19.0.

  • 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 to match cost decorations. Derived from the upstream when unset. Each worker caches the schema for its lifetime. Introduced in API7 Enterprise 3.10.6 and APISIX 3.19.0.

  • introspection_headers

    object

    Headers sent when schema introspection requires credentials. When data encryption is enabled on the data plane, this field is encrypted at rest. Introduced in API7 Enterprise 3.10.6 and APISIX 3.19.0.

  • 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

    Where rate limiting counters are stored. local uses each gateway instance's memory. The Redis policies share counters through a single Redis server, Redis Cluster, or Redis Sentinel deployment.

    The redis-sentinel policy was introduced in API7 Enterprise 3.9.14 and 3.10.1, and APISIX 3.18.0.

  • allow_degradation

    boolean

    default: false

    If true, continue handling requests without rate limiting when the counter backend fails or a variable-resolved count or time_window is invalid. If false, these failures return 500 Internal Server Error.

  • 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 algorithm-specific reset or delay value in seconds.
    • X-Graphql-Query-Cost shows the charged query cost in API7 Enterprise 3.10.6 and APISIX 3.19.0.

  • group

    string

    vaild vaule:

    non-empty

    The group ID used to share one counter across routes with identical plugin configuration. Do not configure group together with rules.

  • 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 ACL authentication when policy is redis or redis-sentinel. If Redis uses only the legacy requirepass method, configure redis_password without a username.

  • redis_password

    string

    The password used to authenticate with Redis when policy is redis, redis-cluster, or redis-sentinel.

    The password is encrypted at rest in API7 Enterprise. In APISIX, enable data encryption to encrypt it before etcd storage.

    Encryption was introduced in API7 Enterprise 3.9.16 and 3.10.2, and APISIX 3.18.0.

  • redis_database

    integer

    default: 0

    vaild vaule:

    greater than or equal to 0

    The Redis database number 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_server_name

    string

    TLS server name used for SNI and, when certificate verification is enabled, hostname verification. Applies when policy is redis and redis_ssl is true. Defaults to redis_host. If the selected value is an IP address, no server name is sent. To verify a DNS-named certificate when connecting by IP, set this field to the certificate's DNS name and enable redis_ssl_verify.

    Introduced in API7 Enterprise 3.9.21 and 3.10.8, and in APISIX 3.19.0. This field applies to the single-node Redis connector, not Redis Cluster or Sentinel.

  • 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` for `redis` or `redis-cluster`; `60000` for `redis-sentinel`

    vaild vaule:

    redis and redis-cluster: greater than or equal to 1000; redis-sentinel: greater than or equal to 1

    Time in milliseconds that an idle Redis connection remains in the connection pool.

    Introduced for redis and redis-cluster in API7 Enterprise 3.9.16 and 3.10.3, and in APISIX 3.17.0. Redis Sentinel support was introduced in API7 Enterprise 3.9.14 and 3.10.1, and in APISIX 3.18.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.

    Introduced in API7 Enterprise 3.9.16 and 3.10.3, and in APISIX 3.17.0.

  • redis_cluster_nodes

    array[string]

    A non-empty list of Redis Cluster node addresses. Required when policy is redis-cluster. Provide multiple reachable nodes so initial discovery can continue when one node is unavailable.

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

  • redis_sentinels

    array[object]

    The Redis Sentinel nodes. Required when policy is redis-sentinel.

    • host

      string

      required

      vaild vaule:

      at least 2 characters

      Hostname or IP address of a Redis Sentinel node.

    • port

      integer

      required

      vaild vaule:

      between 1 and 65535 inclusive

      Port of a Redis Sentinel node.

  • redis_master_name

    string

    The master group monitored by the Sentinel nodes. Required when policy is redis-sentinel.

  • redis_role

    string

    default: master

    vaild vaule:

    master or slave

    The Redis role requested from Sentinel when policy is redis-sentinel.

  • redis_connect_timeout

    integer

    default: 1000

    vaild vaule:

    greater than or equal to 1

    Timeout in milliseconds for connecting to Redis when policy is redis-sentinel.

  • redis_read_timeout

    integer

    default: 1000

    vaild vaule:

    greater than or equal to 1

    Timeout in milliseconds for reading from Redis when policy is redis-sentinel.

  • sentinel_username

    string

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

  • sentinel_password

    string

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

    The password is encrypted at rest in API7 Enterprise. In APISIX, enable data encryption to encrypt it before etcd storage.

    Encryption was introduced in API7 Enterprise 3.9.16 and 3.10.2, and APISIX 3.18.0.

Plugin Metadata​

  • limit_header

    string

    default: X-RateLimit-Limit

    Default response header name for the total rate limit quota. Introduced in API7 Enterprise 3.10.6 and APISIX 3.19.0.

  • remaining_header

    string

    default: X-RateLimit-Remaining

    Default response header name for the remaining rate limit quota. Introduced in API7 Enterprise 3.10.6 and APISIX 3.19.0.

  • reset_header

    string

    default: X-RateLimit-Reset

    Default response header name for the number of seconds until the rate limit counter resets. Introduced in API7 Enterprise 3.10.6 and APISIX 3.19.0.