Throttling

1. Overview

• A throttling plug-in is used to control traffic from the perspectives of APIs, apps, users who own the apps, and custom parameters. You can control the traffic of apps based on their AppKeys.

• The throttling plug-in supports two configuration templates:

  • Configuration template for parameter-based throttling: This template is used to configure custom parameter-based throttling.

  • Configuration template for basic throttling: This template is compatible with the throttling feature in the API Gateway console.

• Throttling is integrated into the plug-in system. The original throttling interface and console are still in use. Throttling policies and throttling plug-ins belong to the same plug-in type. If you bind a throttling plug-in to an API, the throttling policies that are bound to this API become invalid.

• When you create or modify throttling policies in the original throttling interface or console, modifications are synchronized to the plug-in system. However, the modifications you made in the plug-in system cannot be synchronized to the throttling interface or console.

2. Basic throttling configuration

2.1. Throttling thresholds

Basic throttling supports the following throttling thresholds:

• API-level throttling threshold: the maximum number of times that an API bound with a throttling policy can be called within a specific unit of time. This unit of time can be second, minute, hour, or day. For example, you can set this threshold to 5,000 times per minute.

• App-level throttling threshold: the maximum number of times that each app can call an API bound with a throttling policy within a specific unit of time. For example, you can set this threshold to 50,000 times per hour.

• User-level throttling threshold: the maximum number of times that each Alibaba Cloud account can call an API bound with a throttling policy within a specific unit of time. An Alibaba Cloud account may have multiple apps. This throttling threshold limits the total number of API calls that all the apps under this account can initiate. For example, you can set this threshold to 500,000 times per day.

You can specify all the preceding thresholds in one throttling policy. The user-level throttling threshold cannot be greater than the API-level throttling threshold. The app-level throttling threshold cannot be greater than the user-level throttling threshold.

You can also add special apps or users to a throttling policy. Only the API-level throttling threshold in the throttling policy applies to these special apps or users. However, you still need to set a special throttling threshold for each of them. This special throttling threshold cannot be greater than the API-level throttling threshold.

2.2. Plug-in configuration

You can configure a throttling plug-in in JSON or YAML format. The two formats use the same schema. You can use the YAML to JSON converter to convert the configuration format of a throttling plug-in. The following code describes a plug-in configuration template in YAML format:

---
unit: SECOND         # The unit of time. Valid values: SECOND, MINUTE, HOUR, and DAY.
apiDefault: 1000     # The default API-level throttling threshold.
userDefault: 30      # Optional. The default user-level throttling threshold. If you set this threshold to 0, user-level throttling is not performed. The user-level throttling threshold cannot be greater than the API-level throttling threshold.
appDefault: 30       # Optional. The default app-level throttling threshold. If you set this threshold to 0, app-level throttling is not performed. The app-level throttling threshold cannot be greater than the user-level throttling threshold.
specials:            # Optional. The special throttling settings. You can set throttling thresholds for special apps or users in a throttling policy.
  - type: "APP"      # The special throttling type. The value APP indicates that throttling is performed for special apps based on their AppKeys.
    policies:
    - key: 10123123  # The app ID. You can obtain the ID of an app from the app details page. To go to this page, click Consume APIs and then APPs in the left-side navigation pane of the API Gateway console and click the name of the app.
      value: 10      # The special throttling threshold for the app. This threshold cannot be greater than the user-level throttling threshold in the throttling policy.
    - key: 10123123  # The app ID.
      value: 10      # The special throttling threshold for the app. This threshold cannot be greater than the user-level throttling threshold in the throttling policy.
  - type: "USER"     # The special throttling type. The value USER indicates that throttling is performed for special Alibaba Cloud accounts.
    policies:
    - key: 123455    # The ID of an Alibaba Cloud account. You can move the pointer over the profile picture in the upper-right corner of the Alibaba Cloud Management Console to obtain the ID.
      value: 100     # The special throttling threshold for the Alibaba Cloud account. This threshold cannot be greater than the API-level throttling threshold in the throttling policy.

3. Parameter-based throttling configuration

Parameter-based throttling allows you to control traffic based on the request parameters of users and conditional executions. The following parameter-based throttling configurations are supported:

• Throttling at the second, minute, hour, or day level is supported.

• You can use request and system parameters to set conditions and implement different throttling thresholds.

• You can configure throttling by using a single parameter or a combination of multiple parameters.

• You can set the throttling scope to API or PLUGIN.

3.1. Quick start

Use a scenario where the following throttling rules apply as an example: If the AppKey of the app with the ID of 10001 is used as the signature information of a user, the throttling threshold for each client IP address is 100 requests per second. Otherwise, the throttling threshold is 10 requests per second.

For this scenario, a throttling plug-in in YAML format is configured.

---
scope: "PLUGIN"
#
# Throttling depends on two system parameters.
# 1. The app ID signed by the user is obtained from the CaAppId system parameter.
# 2. The client IP address of the user is obtained from the CaClientIp system parameter.
parameters:
  AppId: "System: CaAppId"
  ClientIP: "System: CaClientIp"
rules:
  # The first throttling policy. This policy applies to the app whose ID is 10001. The throttling threshold for each client IP address is 100 requests per second.
  - name: "Vip"
    condition: "$AppId = 10001"
    byParameters: "ClientIP"
    value: 100
    period: SECOND
  # The second throttling policy named PerClientIP. The throttling threshold for each client IP address is 10 requests per second.
  - name: "PerClientIP"
    byParameters: "ClientIP"
    value: 10
    period: SECOND

3.2. Plug-in configuration

The YAML or equivalent JSON format is used to configure the metadata of the throttling plug-in.

---
scope: "PLUGIN"                # The scope of the throttling plug-in. Valid values: PLUGIN and API.
defaultLimit: 100              # The default throttling threshold.
defaultPeriod: SECOND          # The default unit of time for throttling.
defaultErrorMessage: "Throttled by 100/SECOND"
parameters:                    # The parameters that can be used for throttling.
  clientIp: "System:CaClientIp"
  userId: "Token:userId"
rules:
  - name: "ByClientIp"
    byParameters: "clientIp"
    condition: "$clientIp ! in_cidr '61.7.8.8/24'"
    limit: 10
    period: MINUTE
    errorMessage: "Throttled by 10/MINUTE from ${clientIp}"
  - name: "A maximum of 10 requests per minute are allowed for each user, except the administrator."
    byParameters: "clientIp"
    condition: "$userId ! like 'admin%'"
    limit: 10
    period: MINUTE
  - name: "A maximum of 10 requests per minute are allowed for each client IP address."
    byParameters: "clientIp"
    condition: "$clientIp in_cidr '67.0.0.0/8'"
    limit: 10
    period: MINUTE
  - name: "A maximum of 15 requests per minute are allowed for each user."
    condition: "$userId ! like 'admin%'"
    limit: 15
    period: MINUTE
    byParameters: "clientIp"

Fields:

• scope: required. The scope of the throttling plug-in. Valid values: API and PLUGIN. If one throttling plug-in is bound to multiple APIs, the setting of the scope field affects the scope of throttling policies bound to the APIs. For example, a throttling policy is 10 times per second.

  • If the value of this field is API, the throttling threshold for each API is 10 times per second.

  • If the value of this field is PLUGIN, the total throttling threshold for all the APIs is 10 times per second.

• parameters: required. The parameters that are used for throttling. For more information, see Use parameters and conditional expressions

• rules: optional. The throttling policies. If defaultLimit and defaultPeriod are not specified, the rules field must be specified. Each throttling policy contains the following fields:

  • name: required. The name of the throttling policy. The value of this field must comply with the [A-Za-z0-9_-]+ regular expression. The name of each throttling policy must be unique in a throttling plug-in.

  • byParameters: required. The parameter that is used for throttling. If multiple parameters are specified, separate them with commas (,). If the value of this field is clientIp, throttling is performed based on the value of the clientIp parameter. If the value of this field is userId,action, throttling is performed based on the combined values of the two parameters.

  • condition: optional. If you specify this field, the related throttling policy is used only when the condition indicated by this field is met.

  • limit: required. The throttling threshold. The value must be a positive integer. If you set this field to -1, throttling is not performed if the specified condition is met.

  • period: required. The unit of time for throttling. Valid values: SECOND, MINUTE, HOUR, and DAY.

  • errorMessage: required. The error message. You can use a template to customize error messages. For parameters specified in the parameters field, you can define error messages for them by using the ${Name} format.

• defaultLimit: optional. The default throttling threshold. The value must be a positive integer.

• defaultPeriod: optional. The unit of time for throttling. Valid values: SECOND, MINUTE, HOUR, and DAY.

• defaultErrorMessage: optional. The custom error message. If this field is specified, the returned X-Ca-Error-Message header contains the custom error message.

3.3. Parameters supported by a throttling plug-in

The following table describes the parameters that are supported by a throttling plug-in.

3.4. Throttling rules

API Gateway performs parameter-based throttling by using the following rules:

• Plug-ins use the parameters field to obtain parameters from the context of a request.

• If all specified conditions are met or no conditions are specified in a throttling policy, the policy is executed.

• If multiple matched policies have the same byParameters setting, only the policy that comes first in the throttling plug-in takes effect.

4. Configuration examples

4.1. Basic throttling configuration

You can perform basic throttling for APIs, apps, or users. Throttling for apps is based on their AppKeys.

---
unit: SECOND           # The default unit of time for throttling. Valid values: SECOND, MINUTE, HOUR, and DAY.
apiDefault: 50         # The default API-level throttling threshold.
appDefault: 20         # Optional. The default app-level throttling threshold. This threshold cannot be greater than the user-level throttling threshold.
userDefault: 30        # Optional. The default user-level throttling threshold. This threshold cannot be greater than the API-level throttling threshold.
specials:              # Optional. The special throttling settings. You can set throttling thresholds for special apps and users in a throttling policy.
  - type: "APP"        # The special throttling type. The value APP indicates that throttling is performed for special apps based on their AppKeys.
    policies:
      - key: 10001     # The app ID. You can obtain the ID of an app from the app details page. To go to this page, click Consume APIs and then APPs in the left-side navigation pane of the API Gateway console and click the name of the app.
        value: 3       # The special throttling threshold for the app. This threshold cannot be greater than the user-level throttling threshold.
      - key: 10003
        value: 40
  - type: "USER"       # The special throttling type. The value USER indicates that throttling is performed for special Alibaba Cloud accounts.
    policies:
      - key: 102       # The ID of an Alibaba Cloud account. You can move the pointer over the profile picture in the upper-right corner of the Alibaba Cloud Management Console to obtain the ID.
        value: 10      # The special throttling threshold for the Alibaba Cloud account. This threshold cannot be greater than the API-level throttling threshold.
      - key: 233
        value: 35

4.2. Throttling based on the ClientIP parameter

In this example, the following throttling policies are used:

• A maximum of 100 API calls per minute are allowed for each client IP address.

• If a client IP address falls in the 58.66.66.0/24 CIDR block, throttling is not performed for this client IP address.

• If a client IP address falls in the 63.0.0.22/24 or 73.0.2.0/24 CIDR block, a maximum of five API calls per day are allowed for this client IP address.

---
scope: API             # The throttling scope. Valid values: API and PLUGIN.
parameters:            # The parameters that are used for throttling. Throttling is performed only based on the ClientIP parameter. You can obtain the values of this parameter from the CaClientIp system parameter.
  ClientIp: "System:CaClientIp"
rules:
  - name: whitelist    # The whitelist policy. Throttling is not performed for client IP addresses that meet the condition specified in this policy.
    condition: "$ClientIp in_cidr '58.66.66.0/24'"
    limit: -1          # The value -1 indicates that throttling is not performed.
  - name: banList      # The special throttling policy. If a client IP address meets the condition specified in this policy, a maximum of five API calls per day are allowed for the client IP address.
    condition: "$ClientIp in_cidr '63.0.0.22' or $ClientIp in_cidr '73.0.2.0/24'"  
    byParameters: "ClientIp"
    limit: 5
    period: DAY
  - name: 100perIp     # The default throttling policy. A maximum of 100 API calls per minute are allowed for each client IP address.
    byParameters: "ClientIp"
    limit: 100
    period: MINUTE     # The unit of time. Valid values: SECOND, MINUTE, HOUR, and DAY.

5. Error codes

6. Limits

• A maximum of 16 parameters can be specified in a throttling plug-in.

• A single expression can contain a maximum of 512 characters.

• The metadata of a throttling plug-in can contain a maximum of 16,380 characters.

• A maximum of 16throttling policies can be defined in a throttling plug-in.

• A maximum of three parameters can be specified in the byParameters field of each throttling policy.

• If day-level throttling is specified for client IP addresses and the system stores excessive throttling records, some records are released. For a shared instance, a throttling plug-in can control traffic based on a maximum of 1,000 parameters. For a dedicated instance, a throttling plug-in can control traffic based on a maximum of 100,000 parameters.