Help Center/ API Gateway/ User Guide/ API Policies/ Request Throttling 2.0
Updated on 2024-11-01 GMT+08:00

Request Throttling 2.0

A request throttling 2.0 policy limits the number of times that an API can be called within a specific time period. Parameter-based, basic, and excluded throttling is supported.

  • Basic throttling

    Throttle requests by API, user, credential, or source IP address. This function is equivalent to a traditional request throttling policy (see Request Throttling) but is incompatible with it.

  • Parameter-based throttling

    Throttle requests based on headers, path parameter, method, query strings, or system parameters.

  • Excluded throttling

    Throttle requests based on specific credentials or tenants.

If your gateway does not support this policy, contact technical support to upgrade the gateway to the latest version.

Usage Guidelines

  • You have understood the guidelines for policy creation and API binding.
  • A request throttling policy becomes invalid if a request throttling 2.0 policy is bound to the same API as the existing one.
  • You can define a maximum of 100 parameter-based throttling rules. The parameter name can contain 1 to 32 characters.
  • The policy content cannot exceed 65,535 characters.

Parameter Description

Table 1 Parameter description

Parameter

Description

Throttling

High-performance throttling is recommended.

  • High precision: better for low concurrency scenarios (performance is affected)
  • High performance: better for medium concurrency scenarios (performance is less affected, with small occasional errors)
  • Single node: better for high concurrency scenarios (request throttling within each node; performance is least affected, with small occasional errors)

Policy Type

  • API-specific

    Monitor and control the requests for a single API.

  • API-sharing

    Monitor and control requests for all APIs bound with the policy.

Period

For how long you want to limit the number of API calls. This parameter can be used together with the following parameters:

  • Max. API Requests: Limit the maximum number of times an API can be called within a specific period.
  • Max. User Requests: Limit the maximum number of times an API can be called by a user within a specific period.
  • Max. Credential Requests: Limit the maximum number of times an API can be called by a credential within a specific period.
  • Max. IP Address Requests: Limit the maximum number of times an API can be called by an IP address within a specific period.

Max. API Requests

The maximum number of times each bound API can be called within the specified period.

This parameter must be used together with Period.

Max. User Requests

The maximum number of times each bound API can be called by a user within the specified period. For APIs with IAM authentication, the throttling is based on a project ID; for APIs with app authentication, the throttling is based on an account ID. For details about account ID and project ID, see the description about Excluded Tenants in this table.

  • The value of this parameter cannot exceed that of Max. API Requests.
  • This parameter must be used together with Period.
  • If there are many users under your account that access an API, the request throttling limits of the API will apply to all these users.

Max. Credential Requests

The maximum number of times each bound API can be called by a credential within the specified period. This limit only applies to APIs that are accessed through app authentication.

  • The value of this parameter cannot exceed that of Max. API Requests.
  • This parameter must be used together with Period.

Max. IP Address Requests

The maximum number of times each bound API can be called by an IP address within the specified period. You can configure the real_ip_from_xff parameter of the gateway to use the IP address in the X-Forwarded-For header as the basis for request throttling.

  • The value of this parameter cannot exceed that of Max. API Requests.
  • This parameter must be used together with Period.

Parameter-based Throttling

Enable or disable parameter-based throttling. After this function is enabled, API requests are throttled based on the parameters you set.

Parameters

Define parameters for rule matching.

  • Parameter Location: the location of a parameter used for rule matching.
    • path: API request URI. This parameter is configured by default.
    • method: API request method. This parameter is configured by default.
    • header: the key of a request header.
      NOTE:

      For security purposes, do not include sensitive information in these parameters.

    • query: the key of a query string.
    • system: a system parameter.
  • Parameter: the name of a parameter to match the specified value in a rule.

Rules

Define throttling rules. A rule consists of conditions, an API request throttling limit, and a period.

To add more rules, click Add Rule.

  • Rule

    Click to set condition expressions. To set an expression, select a parameter and operator, and enter a value.

    • =: equal to
    • !=: not equal to
    • pattern: regular expression
    • enum: enumerated values. Separate them with commas (,).
  • Max. API Requests

    The maximum number of times that an API can be called within a specific time period.

  • Period

    A period of time that will apply with the throttling limit you set. If this parameter is not specified, the period set in the Police Information area will be used.

For example, configure parameter-based throttling as follows: add the Host parameter and specify the location as header; add the condition Host = www.abc.com, and set the throttling limit to 10 and the period to 60s. For APIs whose Host parameter in the request header is equal to www.abc.com, they cannot be called again once called 10 times in 60s.

Excluded Throttling

Enable or disable excluded throttling. After this function is enabled, the throttling limits for excluded tenants and credentials override the Max. User Requests and Max. Credential Requests set in the Basic Throttling area.

Excluded Tenants

Tenant ID: an account ID or project ID.

Threshold: the maximum number of times that a specific tenant can access an API within the specified period. The threshold cannot exceed the value of Max. API Requests in the Basic Throttling area.

Excluded Credentials

Select a credential, and specify the maximum number of times that the credential can access an API within the specified period. The threshold cannot exceed the value of Max. API Requests in the Basic Throttling area.

Example Script

{
  "scope": "basic",
  "default_interval": 60,
  "default_time_unit": "second",
  "api_limit": 100,
  "app_limit": 50,
  "user_limit": 50,
  "ip_limit": 20,
  "specials": [
    {
      "type": "app",
      "policies": [
        {
          "key": "e9230d70c749408eb3d1e838850cdd23",
          "limit": 10
        }
      ]
    },
    {
      "type": "user",
      "policies": [
        {
          "key": "878f1b87f71c40a7a15db0998f358bb9",
          "limit": 10
        }
      ]
    }
  ],
  "algorithm": "counter",
  "parameters": [
    {
      "id": "3wuj354lpptv0toe0",
      "value": "reqPath",
      "type": "path",
      "name": "reqPath"
    },
    {
      "id": "53h7e7j11u38l3ocp",
      "value": "method",
      "type": "method",
      "name": "method"
    },
    {
      "id": "vv502bnb6g40td8u0",
      "value": "Host",
      "type": "header",
      "name": "Host"
    }
  ],
  "rules": [
    {
      "match_regex": "[\"Host\",\"==\",\"www.abc.com\"]",
      "rule_name": "u8mb",
      "time_unit": "second",
      "interval": 2,
      "limit": 5
    }
  ]
}