assembly-burst-limit

This command specifies an assembly burst limit scheme to apply to a rate limit assembly action.

Syntax

assembly-burst-limit schemeName rate [interval] [unit] [cache-first] [is-client] [use-api-name] [use-app-id] [use-client-id] [dynamic-value] [weight]

Parameters

schemeName
Specifies the name for the burst limit scheme. This parameter is a string.

Assembly limits defined in different configurations, including an API gateway, API collection, or API plan, need unique names. If two limits with the same name are used in an assembly and both limits are applied, information about only one of the limits is included in the response headers.

rate
Specifies the maximum allowed burst rate within a unit of time. The value of 0 indicates no limit. When the burst limit is exceeded, messages are rejected.
interval
Specifies the time interval for the burst limit. Specify a value that is greater than or equal to 1. The default value is 1.
unit
Specifies the unit of time for the burst limit. For example, when the unit is second, the requests that are received in a second cannot exceed the specified rate. The following values are supported. The default value is second.
  • second
  • minute
cache-first
Specifies whether to use the local cache first to enforce the rate limit. In peer group mode, the local cache first can prevent transaction delays if communication problems arise across the peer group. However, the transaction count is less precise when this setting is enabled. The default setting is on.
is-client
Specifies whether to apply the burst limit to the client or to an internal component. Client burst limits return a 429 error when exceeded. Nonclient burst limits return a 503 error when exceeded. The default setting is on. When set to off, burst limit information is not included in the response header.
use-api-name
Specifies whether to use the API name as part of the burst limit key. The default setting is off.
use-app-id
Specifies whether to use the application ID as part of the burst limit key. The default setting is off.
use-client-id
Specifies whether to use the client ID as part of the burst limit key. The default setting is off.
dynamic-value
Specifies the dynamic value string for the burst limit, which contains one or more context variables.

With the dynamic value, burst limits can be enforced based on parameters that are not defined in the burst limit scheme, such as a username, incoming IP address, or server name. The context variable can be set in a GatewayScript action and then included in the dynamic value.

The following example uses the context object in a GatewayScript action to add the variable my.server to the API context.
context.set("my.server", "server34")

The dynamic value can then include the my.server variable, which resolves to the server name server34.

The default value is an empty string.

weight
Specifies a JSONata expression that assigns a weight value to the transaction. You use a subset of JSONata notation to define the expression. For more information, see JSONata and assembly actions.

For each API call, the value that is computed by the weight expression is applied to the limit. The default value is 1. If the weight expression evaluates to a value that is less than or equal to 0, it is set to 1. An empty string results in an error.

Guidelines

The assembly-burst-limit command specifies an assembly burst limit scheme to apply to a rate limit assembly action. The burst limit scheme helps prevent usage spikes that might damage infrastructure. The burst limit takes higher priority than the rate limit. When a message arrives within an interval, the message is first checked against the burst limit scheme and then against the rate limit scheme.