All Products
Search

This Product

    API Gateway:Configure policies and plug-ins

    Document Center

    API Gateway:Configure policies and plug-ins

    Last Updated:Jun 02, 2026

    Cloud-native API Gateway supports API-level and operation-level policies and plug-ins to improve security, performance, and maintainability.

    Important

    • Policy configuration changes take effect immediately without republishing the API.

    • By default, API-level plug-in configurations apply to the operation level.

    • You cannot delete API-level policies at the operation level. However, operation-level policies can override API-level policies.

    Procedure

    1. Add API policies in either of the following two ways:

      APIs outside an instance

      1. Log on to the Cloud-native API Gateway console. In the left-side navigation pane, select APIs and select a region in the top menu bar.

      2. Click the target API and select the destination instance from the drop-down list.image

      APIs within an instance

      1. Log on to the Cloud-native API Gateway console. In the left-side navigation pane, select Instances and select a region in the top menu bar.

      2. On the Instances page, click the ID of the target gateway instance. In the left-side navigation pane, select APIs, and click the target API.

    2. You can configure policies and plug-ins at the API or operation level:

      • API level: Click the API Policy Configuration tab to configure API-level policies and plug-ins for all operations. Then, click Enable Policy/Plug-in.

      • Operation level: On the Operations tab, click the target operation, click the Policy Configuration tab, and then click Enable Policy/Plug-in.

    3. In the Enable Policy/Plug-in panel, select and configure a policy or plug-in from the Policies or Plug-ins section.

    Policies

    Throttling policy

    Throttling controls request volume per API and operation within a configured threshold over a specified period. It prevents external requests from overwhelming backend services and avoids cascading failures by rejecting excess requests under high concurrency.

    Throttling policies include concurrency control, traffic shaping, and circuit breaking.

    • Concurrency control policy: Limits the total number of concurrent requests processed by the gateway. When the threshold is reached, new requests are rejected. Set the threshold to match your backend capacity.

      Procedure

      On the Add Policy page, click the Concurrency Control card. In the Add Policy: Concurrency control panel, configure the following parameters.

      Parameter

      Description

      Enable or Not

      Enables the concurrency control policy.

      Overall Concurrency Threshold

      Set the Overall Concurrency Threshold.

      Web Fallback Behavior

      Return Specific Content

      HTTP Status Code

      Sets the HTTP Status Code for the response. The default is 429.

      Type of Returned Content

      Select a Type of Returned Content, either Regular Text or application/json.

      HTTP Text

      Enter the content of the response body.

      Return Specific Content

      Redirect URL

      Enter the Redirect URL.

    • Traffic shaping policy: Monitors queries per second (QPS) for APIs and operations. When QPS exceeds the threshold, new requests are rejected to protect backend services from traffic spikes.

      Procedure

      On the Add Policy page, click the Traffic Shaping card. In the Add Policy: Traffic shaping panel, configure the following parameters.

      Parameter

      Description

      Enable or Not

      Enables the traffic shaping policy.

      Overall QPS Threshold

      Set the Overall QPS Threshold.

      Web Fallback Behavior

      Return Specific Content

      HTTP Status Code

      Sets the HTTP Status Code for the response. The default is 429.

      Type of Returned Content

      Select a Type of Returned Content, either Regular Text or application/json.

      HTTP Text

      Enter the content of the response body.

      Redirect to Specified Page

      Redirect URL

      Enter the Redirect URL.

    • Circuit breaking policy: Monitors the response time or error rate of APIs and operations. When a threshold is reached, the circuit breaker trips and fails subsequent requests for a set period to prevent cascading failures. After the timeout, the gateway allows a limited number of test requests to check whether the backend has recovered.

      Procedure

      On the Add Policy page, click the Circuit Breaking card. In the Add Policy: Circuit breaking panel, configure the following parameters.

      Parameter

      Description

      Enable or Not

      Enables the circuit breaking policy.

      Statistical Window Duration

      Time window for statistical analysis. Valid values: 1 second to 120 minutes.

      Minimum Number of Requests

      Minimum number of requests within a time window required to trigger circuit breaking. If the count is below this value, circuit breaking is not triggered even if the threshold is met.

      Threshold Type

      Select either Slow Call Ratio (%) or Exception Ratio (%) as the threshold.

      1. If you select Slow Call Ratio (%), you must set the Slow Call RT (maximum response time). Requests exceeding this value count as slow calls. If the slow call ratio exceeds the threshold within a time window (with sufficient requests), circuit breaking triggers for the configured duration. The circuit then enters a half-open state: if the next request meets the RT limit, normal operation resumes; otherwise, it trips again.

      2. If you select Exception Ratio (%), set the error ratio threshold. If the error ratio exceeds the threshold within a time window (with sufficient requests), circuit breaking triggers for the configured duration.

      Slow Call RT

      Specifies the allowed Slow Call RT (maximum response time) in milliseconds.

      Circuit Breaking Ratio Threshold

      Slow call or error ratio threshold. Valid values: 0 to 100 (0% to 100%).

      Circuit breaking duration (s)

      Duration the circuit stays open after tripping. Requests fail fast during this period.

      Web Fallback Behavior

      Return Specific Content

      HTTP Status Code

      Sets the HTTP Status Code for the response. The default is 429.

      Type of Returned Content

      Select a Type of Returned Content, either Regular Text or application/json.

      HTTP Text

      Enter the content of the response body.

      Redirect to Specified Page

      Redirect URL

      Enter the Redirect URL.

    Rewrite policy

    Rewrite policies modify request paths and host headers before forwarding to backend services, ensuring requests reach the correct endpoints.

    Procedure

    On the Add Policy page, click HTTP Rewrite. In the Add Policy: HTTP Rewrite panel, configure the parameters.

    • Path rewrite

      For path rewrites, Cloud-native API Gateway supports the following two rewrite modes.

      • Constant rewrite: Supported at the operation level only.

      • Regex Rewrite: Supported at both the operation and API levels.

      Constant rewrite

      Constant rewrite allows you to replace the path prefix of an incoming request.

      Example 1

      The original request path is /app/test, but the path forwarded to the backend service should be /test. The recommended configuration is:

      • API operation matching condition: Set the match type to Prefix Match and the path to /app/.

      • Rewrite rule: Set the rewrite type to Constant Rewrite and the path to /.

      Note

      The operation's matching path must be set to /app/ because constant rewrite only replaces the matched prefix. If the matching path were set to /app, the rewritten path would become //test, which is incorrect.

      Example 2

      The original request path is /v1/test, but the path forwarded to the backend service should be /v2/test. The recommended configuration is:

      • API operation matching condition: Set the match type to Prefix Match and the path to /v1.

      • Rewrite rule: Set the rewrite type to Constant Rewrite and the path to /v2.

      Important

      Constant rewrite requires the API operation's match type to be Prefix Match. The Exact Match and Regex Match types do not support constant rewrite. Since Prefix Match applies to all requests starting with that prefix, be aware that all will be rewritten. If you need more specific targeting, use Regex Rewrite instead.

      Regex rewrite

      Regex rewrite modifies parts of the original request path using a regular expression pattern and a replacement string. The pattern follows Regular Expression Syntax.

      Example 1

      The original request path is /aaa/one/bbb/one/ccc, but the path forwarded to the backend service should be /aaa/two/bbb/two/ccc. The recommended configuration is:

      • API operation matching condition: Set the match type to Exact Match and the path to /aaa/one/bbb/one/ccc.

      • Rewrite rule: Set the rewrite type to Regex Rewrite, the pattern to one, and the replacement string to two.

      Example 2

      The original request path matches /httpbin/(.*)/(.*). You want to remove the /httpbin prefix and swap the positions of the two captured groups. The recommended configuration is:

      • API operation matching condition: Set the match type to Regex Match and the path to /httpbin/(.*)/(.*).

      • Rewrite rule: Set the rewrite type to Regex Rewrite, the pattern to /httpbin/(.*)/(.*), and the replacement string to /\2/\1. Here, \1 represents the first captured group and \2 represents the second, similar to the $1 and $2 syntax in Nginx.

      Example 3

      For a versioned REST API that includes the version in the path, you want to remove the version segment before forwarding the request to the backend. For example, an original path of /basePath/version/order/get should be rewritten to /basePath/order/get. The recommended configuration is:

      • Apply the policy at the API level using API Policy Configuration.

      • Rewrite rule: Set the rewrite type to Regex Rewrite, the pattern to (/.*)/version(/.*), and the replacement string to \1\2. Here, \1 represents the first captured group and \2 represents the second.

      Note

      Regex rewrite is an advanced feature. Use Constant Rewrite when possible.

    • Host header rewrite

      For host header rewrites, Cloud-native API Gateway supports constant rewrite.

      For example, if the original request's Host header is test.com, but the backend service expects dev.com, you can set the rewrite host to dev.com in the rewrite policy.

    Header modification policy

    Header modification lets you modify request headers before forwarding to the backend, or response headers before returning to the client.

    Procedure

    On the Add Policy page, click the Edit Header card. In the Add Policy: Header Modification panel, configure the following parameters.

    Parameter

    Description

    Enable

    Enables or disables the header modification policy.

    • Enabled: The gateway will modify request and response headers as configured.

    • Disabled: The gateway will not modify request or response headers.

    Header Type

    Select the type of header to modify.

    • Request: Modifies the headers of the incoming request.

    • Response: Modifies the headers of the outgoing response.

    Operation Type

    Select the action to perform.

    • Add: Adds a new header to the request or response.

      Note

      If a header with the same name already exists, the new value is appended to the existing value, separated by a comma (,).

    • Modify: Sets the value of a specified header in the request or response.

      Note

      • If the specified header does not exist, it will be added.

      • If the specified header already exists, its value will be overwritten.

    • Delete: Removes a specified header from the request or response.

    Header key

    Enter the name of the header.

    Header value

    Enter the value of the header.

    CORS policy

    Cross-Origin Resource Sharing (CORS) controls access to resources from different origins (domain, scheme, or port). Configure CORS policies at the API and operation levels to specify allowed origins and request methods.

    Important

    The CORS policy does not apply to mock services. You must configure an actual backend service for testing.

    Procedure

    On the Add Policy page, click the CORS card. In the Add Policy: CORS panel, configure the following parameters.

    Parameter

    Description

    Enable

    Turn on the Enable switch on the right.

    • Enabled: Allows cross-origin requests from configured third-party origins.

    • Disabled: Rejects all cross-origin requests from any third-party origin.

    Allowed Origins

    Origins allowed to access resources through a browser.

    • Allow all access sources: *.

    • Allows access from origins of a specified root domain: *.example.com.

    • To allow multiple specific access sources: Start each source with http:// or https:// and separate them with line breaks.

    Note

    This parameter sets the Access-Control-Allow-Origin response header. If the Origin header of an incoming request matches a value in this list, the response's Access-Control-Allow-Origin header is set to the value of the request's Origin header.

    Allowed Methods

    Select the allowed HTTP methods for cross-origin requests. Common methods include GET, POST, PUT, DELETE, HEAD, OPTIONS, and PATCH.

    Note

    This parameter applies to the Access-Control-Allow-Methods header.

    Trusted Request Headers

    Request headers allowed during cross-origin requests, beyond the standard browser-supported headers.

    • Allow all request headers: *.

    • To allow multiple specific headers, enter each header name on a new line.

    Note

    This parameter applies to the Access-Control-Allow-Headers header.

    Trusted Response Headers

    Response headers accessible to browser clients.

    • Allow all response headers: *.

    • To expose multiple specific headers, enter each header name on a new line.

    Note

    This parameter affects the Access-Control-Expose-Headers header.

    Allow to Carry Credentials

    Whether the browser sends credentials (cookies, authorization headers) with cross-origin requests.

    Note

    This parameter applies to the Access-Control-Allow-Credentials header.

    Precheck Expiration Time

    How long the browser caches the preflight (OPTIONS) response for non-simple requests.

    Note

    This parameter applies to the Access-Control-Max-Age header.

    Traffic replication policy

    Traffic replication mirrors a percentage of live traffic to a specified service for simulation testing and fault diagnosis.

    Procedure

    On the Add Policy page, click the Mirror Traffic card. In the Add Policy: Traffic Replication panel, configure the following parameters.

    Parameter

    Description

    Enable

    Enables or disables the traffic replication policy for the API or operation.

    Destination Service

    The service to which the replicated traffic is forwarded.

    Note

    The destination service must use the HTTP or HTTPS protocol.

    Port

    The port of the destination service. You can also select a dynamic port.

    Note

    Dynamic ports are suitable for services whose ports change dynamically. This option is not supported for multi-port services.

    Traffic Mirror Percentage

    The percentage of traffic to replicate. Valid values: 0 to 100.

    Note

    If you set this parameter to 50, 50% of the traffic for the current API or operation is replicated to the destination service.

    Timeout policy

    Configure the maximum time the gateway waits for a backend response. If no response is received within this time, the gateway returns an HTTP 504 (Gateway Timeout) error.

    Procedure

    On the Add Policy page, click the Timeout card. In the Add Policy: Timeout panel, configure the following parameters.

    Note

    After you configure and enable the timeout policy, verify that the service timeout behavior meets your business requirements.

    Parameter

    Description

    Enable

    Specifies whether to enable the timeout policy.

    • Enabled: The timeout policy for the API or operation takes effect.

    • Disabled: The timeout policy for the API or operation is disabled.

    Timeout Period

    Sets the timeout duration for the API or operation, in seconds.

    Note

    If set to 0 or if the policy is disabled, the gateway waits indefinitely for a response.

    Retry policy

    Configure automatic retries for failed requests. Retry conditions include connection failure, backend unavailability, and specific HTTP status codes.

    Retry conditions

    When a backend service returns a 5xx error, the Cloud-native API Gateway automatically retries the failed request according to the configured number of retries.

    image

    • The retry conditions for the HTTP protocol are as follows:

      • 5xx: The gateway retries the request if the backend service returns any 5xx response, or if a connection is disconnected, reset, or times out.

        Note

        5xx includes the connect-failure and refused-stream conditions.

      • reset: The gateway retries the request if the connection is disconnected, reset, or times out.

      • connect-failure: The gateway retries the request if it fails due to a connection failure.

      • refused-stream: The gateway retries the request if the backend service resets the stream with a REFUSED_STREAM error code.

      • retriable-status-codes: The gateway retries the request if the HTTP status code of the response matches one of the user-specified status codes.

        Note

        Retry status codes can be used only if retriable-status-codes is specified in the retry condition.

    • The retry conditions for the gRPC protocol are as follows:

      • cancelled: Retries when the backend gRPC service returns cancelled.

      • deadline-exceeded: Retries when the backend gRPC service returns deadline-exceeded.

      • internal: Retries when the backend gRPC service returns internal.

      • resource-exhausted: Retries when the backend gRPC service returns resource-exhausted.

      • unavailable: Retries when the backend gRPC service returns unavailable.

    Procedure

    On the Add Policy page, click the Retry card. In the Add Policy: Retry panel, configure the following parameters.

    Note

    After you configure and enable the retry policy, verify that the service retry behavior meets your business requirements.

    Parameter

    Description

    Enable

    Specifies whether to enable the retry policy.

    • Enabled: The retry policy for the API or operation takes effect.

    • Disabled: The retry policy for the API or operation is disabled.

      Even if you disable retries, the gateway has a default internal retry configuration. The number of retries defaults to 2, and the retry conditions default to connect-failure, refused-stream, unavailable, cancelled, and retriable-status-codes.

    Retry Times

    Maximum retry attempts. Valid values: 0 to 10. Recommended: 2 or less.

    A value of 0 disables retries.

    Retry Condition

    Conditions that trigger a retry.

    Retry Status Code

    HTTP status codes that trigger a retry. Multiple codes can be configured.

    Important

    You must set Retry Condition to retriable-status-codes to configure Retry Status Code.

    Plug-ins

    1. Click the Add Plug-in tab.

    2. In the Quick Navigation section, find the target plug-in by type or name, and click its card.

      • If the plug-in is not yet installed, click Install and Configure in the dialog box. Configure the rules and enable it.

      • If the plug-in is already installed, configure its rules and enable it in the dialog box.

    3. Click OK. You return to the API plug-in list, where you can view the status of the new plug-in.

      image