Updated on 2023-04-06 GMT+08:00

Creating a Request Throttling Policy

Function

After an API goes online, the system attaches a request throttling policy to it by default. The API provider can change the request throttling policy based on the service capabilities and load of the API.

A request throttling policy restricts the maximum number of times an API can be called within a specified period.

URI

The following table lists the HTTP/HTTPS request method and URI of the API.

Table 1 HTTP/HTTPS request method and URI

Request Method

URI

POST

/v1.0/apigw/throttles

Request

Table 2 Parameter description

Parameter

Mandatory

Type

Description

name

Yes

String

Name of the request throttling policy

The name of a request throttling policy consists of 3–64 characters, starting with a letter. Only letters, digits, and underscores (_) are allowed.

api_call_limits

Yes

Integer

Maximum number of times an API can be accessed within a specified period. The value of this parameter cannot exceed the default limit 200 TPS. You can change the default limit to meet service requirements. The maximum value is 2,147,483,647. Enter a positive integer.

user_call_limits

No

Integer

Maximum number of times the API can be accessed by a user within the same period. The value of this parameter must be less than or equal to that of api_call_limits. The maximum value is 2,147,483,647. Enter a positive integer.

app_call_limits

No

Integer

Maximum number of times the API can be accessed by an app within the same period. The value of this parameter must be less than or equal to that of user_call_limits. The maximum value is 2,147,483,647. Enter a positive integer.

ip_call_limits

No

Integer

Maximum number of times the API can be accessed by an IP address within the same period. The value of this parameter must be less than or equal to that of api_call_limits. The maximum value is 2,147,483,647. Enter a positive integer.

time_interval

Yes

Integer

Period of time for limiting the number of API calls. This parameter applies with each of the preceding three API call limits. The maximum value is 2,147,483,647. Enter a positive integer.

time_unit

Yes

String

Time unit, which can be:

  • SECOND
  • MINUTE
  • HOUR
  • DAY

remark

No

String

Description of the request throttling policy

The description cannot exceed 255 characters.

type

No

Integer

Type of the request throttling policy, which can be:

  • 1: exclusive, limiting the maximum number of times a single API can be called within the specified period.
  • 2: shared, limiting the maximum number of times all APIs can be called within the specified period.

enable_adaptive_control

No

String

Enabling status of dynamic request throttling

  • TRUE
  • FALSE

This function is currently not available.

Example request:

{
	"api_call_limits": 800,
	"user_call_limits": 500,
	"app_call_limits": 300,
        "ip_call_limits": 600,
	"name": "800_calls_per_second",
	"remark": "Total: 800 calls/second; user: 500 calls/second; app: 300 calls/second; IP address: 600 calls/second",
	"time_interval": 1,
	"time_unit": "SECOND"
}

Response

Table 3 Parameter description

Parameter

Type

Description

id

String

ID of the request throttling policy

name

String

Name of the request throttling policy

api_call_limits

Integer

Maximum number of times an API can be accessed within a specified period

user_call_limits

Integer

Maximum number of times the API can be accessed by a user within the same period

app_call_limits

Integer

Maximum number of times the API can be accessed by an app within the same period

ip_call_limits

Integer

Maximum number of times the API can be accessed by an IP address within the same period

time_interval

Integer

Period of time for limiting the number of API calls

time_unit

String

Time unit for limiting the number of API calls

remark

String

Description of the request throttling policy

create_time

Timestamp

Time when the request throttling policy is created

is_include_special_throttle

Integer

Indicates whether an excluded request throttling configuration has been created. The value can be:

  • 1: yes
  • 2: no

type

Integer

Type of the request throttling policy, which can be:

  • 1: exclusive
  • 2: shared

bind_num

Integer

Number of APIs to which the request throttling policy has been bound

enable_adaptive_control

String

Enabling status of dynamic request throttling

  • TRUE
  • FALSE

This function is currently not available.

Example response:

{
	"id": "0325b671-2d50-4614-9868-22102262695d",
	"name": "800_calls_per_second",
	"api_call_limits": 800,
	"user_call_limits": 500,
	"app_call_limits": 300,
        "ip_call_limits": 600,
	"time_interval": 1,
	"time_unit": "SECOND",
	"create_time": "2017-12-29T01:55:59.9904225Z",
	"remark": "Total: 800 calls/second; user: 500 calls/second; app: 300 calls/second; IP address: 600 calls/second",
	"is_inclu_special_throttle": 2,
        "type":1,
	"bind_num": 0,
        "enable_adaptive_control": "FALSE"
}

Status Codes

Table 4 Status codes

Status Code

Description

201

Created

400

Bad Request

401

Unauthorized

500

Server Internal Error