All Products
Search

This Product

    API Gateway:Configure policies and plug-ins

    Document Center

    API Gateway:Configure policies and plug-ins

    Last Updated:Dec 17, 2025

    Cloud-native API Gateway supports adding policies and configuring plug-ins for APIs and API operations to improve their security, performance, and maintainability.

    Important

    • Policy configurations take effect immediately without needing to republish the API.

    • By default, API-level plug-in configurations are applied at the operation level.

    • While API-level policies cannot be deleted at the operation level, operation-level policies can overwrite API-level policies.

    Procedure

    1. Cloud-native API Gateway provides two ways to add API policies: outside instances and inside instances:

      APIs outside instances

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

      2. Click the target API, and you can select the instance for which you want to add a policy from the dropdown list.image

      APIs inside instances

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

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

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

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

      • Operation level: In the operations list, click the target operation, click the Policy Configuration tab, and click Enable Policy/Plug-in.

    3. In the Enable Policy/Plug-in panel, select a policy or plug-in to configure. For more information, see Policy configuration and Plug-in configuration.

    Policy configuration

    Throttling policy

    Cloud-native API Gateway supports implementing throttling policies at the API and operation levels to effectively prevent external requests from exceeding the capacity of backend services and avoid cascading failures. The throttling feature helps you block some requests when the number of concurrent requests is large. This ensures the availability of backend services. You can precisely control the number of requests for each API and operation within a specified time period, ensuring it does not exceed the preset threshold.

    Throttling policies include Concurrency Control, Traffic Shaping, and Circuit Breaking policies.

    • Concurrency control policy: The concurrency rule works by counting the total number of requests being processed by the gateway. When the metric reaches the set threshold, traffic is immediately blocked. You can configure the maximum number of concurrent requests that the backend service can process to protect the availability of backend services under high concurrency.

      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

      If you turn on this switch, the concurrency rule takes effect.

      Overall Concurrency Threshold

      Set the Overall Concurrency Threshold.

      Web Fallback Behavior

      Return Specified Content

      HTTP Status Code

      Set the HTTP Status Code. The default value is 429.

      Return Content-type

      Select Plain Text or JSON as the Return Content-type.

      HTTP Return Text

      Enter the returned text.

      Return Specified Content

      Redirect URL

      Enter the Redirect URL.

    • Traffic shaping policy: The traffic control rule works by monitoring the QPS metric of APIs and operations. When the metric reaches the set threshold, traffic is immediately blocked to prevent backend services from being overwhelmed by sudden traffic spikes, ensuring high availability.

      Procedure

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

      Parameter

      Description

      Enable

      If you turn on the switch, the traffic control policy takes effect.

      Overall QPS Threshold

      Set the Overall QPS Threshold.

      Web Fallback Behavior

      Return Specified Content

      HTTP Status Code

      Set the HTTP Status Code. The default value is 429.

      Return Content-type

      Select Plain Text or JSON as the Return Content-type.

      HTTP Return Text

      Enter the returned text.

      Redirect To Specified Page

      Redirect URL

      Enter the Redirect URL.

    • Circuit breaking policy: The circuit breaking rule works by monitoring the response time or error rate of APIs and operations. When the specified threshold is reached, the dependency priority is immediately reduced. If circuit breaking is triggered, the system does not call the requests on the route in the specified period of time. This ensures high availability of backend services. After the specified period of time elapses, the system resumes the calls to the requests on the route.

      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

      If you turn on this switch, the configured throttling rule takes effect.

      Statistics Window Duration

      The length of the time window. The valid range is from 1 second to 120 minutes.

      Minimum Number Of Requests

      The minimum number of requests to trigger circuit breaking. If the number of requests in the current time window is less than the value of this parameter, circuit breaking is not triggered even if the circuit breaking rule is met.

      Threshold Type

      Select Slow Call Percentage (%) or Error Percentage (%) as the threshold.

      1. If you select Slow Call Percentage (%) as the threshold, you need to set the allowed Slow Call RT (maximum response time). Requests with response times greater than this value are counted as slow calls. Set the Downgrade threshold to a threshold for the percentage of slow calls. After the circuit breaking rule is enabled, if the number of requests that are initiated in a specified period of time is greater than the specified minimum number of requests and the percentage of slow calls is greater than the specified threshold, circuit breaking is automatically implemented on requests that are processed in the next circuit breaking period. After the circuit breaking period elapses, the circuit breaker starts to detect the RT of the next request. If the RT of the next request is less than the value of the Slow Call RT parameter, circuit breaking ends. If the RT of the next request is greater than the value of the Slow Call RT parameter, circuit breaking is triggered again.

      2. If you select Error Percentage (%) as the threshold, you need to set the Downgrade threshold to a threshold for the percentage of errors. After the rule is enabled, if the number of exceptional requests in a specified period of time is greater than the specified minimum number of requests and the percentage of exceptional requests is greater than the specified threshold, circuit breaking is automatically implemented on requests that are processed in the next circuit breaking period.

      Slow Call RT

      Set the allowed Slow Call RT (maximum response time).

      Circuit Breaking Threshold

      The percentage threshold for slow calls. If the specified threshold is reached or exceeded, circuit breaking is triggered. Valid values: 0-100. These values represent 0% to 100%.

      Circuit Breaking Duration (s)

      The period in which circuit breaking is implemented. If circuit breaking is implemented on the resources, the calls to all the resources fail in the configured duration.

      Web Fallback Behavior

      Return Specified Content

      HTTP Status Code

      Set the HTTP Status Code. The default value is 429.

      Return Content-type

      Select Plain Text or JSON as the Return Content-type.

      HTTP Return Text

      Enter the returned text.

      Redirect To Specified Page

      Redirect URL

      Enter the Redirect URL.

    Rewrite policy

    You can configure a rewrite policy to flexibly change the paths and hostnames in requests before they are forwarded to their destination backend services. This meets the requirements for specific business environments and architectures. Rewrite policies allow you to precisely control the paths and hostnames of requests, ensuring that requests are correctly routed to the appropriate services or endpoints.

    Procedure

    On the Add Policy page, click HTTP Rewrite to enter the Add Policy: HTTP Rewrite panel and configure the following parameters.

    • Path rewrite

      For path rewrites, cloud-native API gateways support the following two rewrite methods.

      • Exact Rewrite: Only operation-level rewrites are supported.

      • Regex Rewrite: Both operation-level and API-level rewrites are supported.

      Exact rewrite

      The exact rewrite method changes the prefix of the path in a request.

      Example 1

      The path in the original request is /app/test, but the path in the request that is forwarded to the backend service is /test. We recommend that you configure the following rewrite policy:

      • API and operation matching condition: The matching method is exact match, and the path is /app/.

      • Rewrite: The rewrite method is exact rewrite, and the path is /.

      Note

      The path in the API and operation matching condition must be set to /app/ because the exact rewrite method only modifies the exact matching string. If the path in the API and operation matching condition is set to /app, the path after rewriting will be //test, which does not meet the expectation.

      Example 2

      The path in the original request is /v1/test, but the path in the request that is forwarded to the backend service is /v2/test. We recommend that you configure the following settings:

      • API and operation matching condition: The matching method is exact match, and the path is /v1.

      • Rewrite: The rewrite method is exact rewrite, and the path is /v2.

      Important

      The exact rewrite method requires that the matching method of the API and operation is exact match. Prefix match and regex match do not support the exact rewrite method. Because the matching method of the API and operation is exact match and can match all requests with the specified path prefix, you need to consider whether you want to rewrite all these requests when you configure an exact rewrite policy. Otherwise, we recommend that you use the exact rewrite method.

      Regex rewrite

      Partially changes the path in a request. A regex rewrite configuration consists of the mode and replacement fields. The value of the mode field is used to match the specified parts that you want to modify in the original path. The value of the replacement field is used to replace the matched parts. For more information about the regular expression syntax, see Regular Expression Syntax.

      Example 1

      The path in the original request is /aaa/one/bbb/one/ccc, but the path in the request that is forwarded to the backend service is /aaa/two/bbb/two/ccc. We recommend that you configure the following settings:

      • API and operation matching condition: The matching method is exact match, and the path is /aaa/one/bbb/one/ccc.

      • Rewrite: The rewrite method is regex rewrite, the mode is one, and the replacement is two.

      Example 2

      The path in the original request is /httpbin/(.*)/(.*). You want to remove the prefix /httpbin and swap the positions of the two regular expression parts. We recommend that you configure the following settings:

      • API and operation matching condition: The matching method is regex match, and the path is /httpbin/(.*)/(.*).

      • Rewrite: The rewrite method is regex rewrite, the mode is /httpbin/(.*)/(.*), and the replacement is /\2/\1. \1 represents the first string matched by the regular expression, and \2 represents the second string matched by the regular expression, which corresponds to the usage of $1 and $2 in Nginx.

      Example 3

      For a REST API with version management enabled and using the path method, you want to remove the version field from the request path when forwarding to the backend. For example, the original request path is /basePath/version/order/get, but the path forwarded to the backend service is /basePath/order/get. We recommend that you configure the following settings:

      • Select Use API Policy Configuration

      • Rewrite: The rewrite method is regex rewrite, the mode is (/.*)/version(/.*), and the replacement is \1\2. \1 represents the first string matched by the regular expression, and \2 represents the second string matched by the regular expression, which corresponds to the usage of $1 and $2 in Nginx.

      Note

      The regex rewrite method is more complex than the prefix rewrite and exact rewrite methods. We recommend that you use the exact rewrite method.

    • Hostname rewrite

      Cloud-native API gateways allow you to modify hostnames in requests by using the exact rewrite method.

      For example, the hostname in the original request is test.com, but the hostname in the request that is forwarded to the backend service is dev.com. In the rewrite policy, set the rewrite hostname to dev.com.

    Header setting policy

    You can configure a header setting policy to modify the headers in requests or responses before the requests are forwarded to destination backend services or before the responses of backend services are returned to clients.

    Procedure

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

    Parameter

    Description

    Enable

    Specifies whether to enable the header setting policy.

    • If you enable the header setting policy, the gateway controls the headers in requests or responses.

    • If you disable the header setting policy, the gateway does not control the headers in requests or responses.

    Header Type

    Select a header type.

    • Request: The header in a request is set.

    • Response: The header in a response is set.

    Action Type

    Select an action type.

    • Add: A header is added to a request or a response.

      Note

      If the specified header already exists in a request or a response, the specified header value in this rule is concatenated to the existing header value. The values are separated by commas (,).

    • Modify: The specified header in a request or a response is modified.

      Note

      • If the specified header does not exist in a request or a response, the header is added to the request or response based on the header key and value specified in this rule.

      • If the specified header already exists, its value will be replaced by the specified header value in this rule.

    • Delete: The specified header in a request or a response is deleted.

    Header Key

    Enter a header key.

    Header Value

    Enter a header value.

    Cross-origin resource sharing policy

    CORS is an important security policy that allows web application servers to perform cross-origin access control. This helps implement secure data transfer. Cloud-native API Gateway supports configuring CORS policies at the API and operation levels. You can limit the domain names and request methods that are allowed to access resources based on your business requirements.

    Important

    The CORS policy does not take effect for a mock service. You must configure an actual backend test service.

    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 switch to the right of Enable.

    • If you enable the policy, CORS requests are allowed.

    • If you disable the policy, all CORS requests are rejected.

    Allowed Origins

    The origins that are allowed to access resources in the current server by using a browser. Format:

    • To allow all origins: *.

    • To allow origins with a specific root domain name: *.example.com.

    • To allow multiple specific origins: Enter origins that start with http:// or https://. Enter each origin in a separate row.

    Note

    This parameter is used for the Access-Control-Allow-Origin header. When the Origin header in a client request matches any of the allowed origins that you specify, the Access-Control-Allow-Origin header in the CORS response is set to the Origin header in the client request.

    Allowed Methods

    The allowed HTTP methods for CORS requests. Common methods include GET, POST, PUT, DELETE, HEAD, OPTIONS, and PATCH.

    Note

    This parameter is used for the Access-Control-Allow-Methods header.

    Allowed Request Headers

    The extra headers that are allowed in CORS requests other than the built-in headers of browsers. Format:

    • To allow all request headers: *.

    • To specify multiple request headers, enter each request header in a separate row.

    Note

    This parameter is used for the Access-Control-Allow-Headers header.

    Allowed Response Headers

    The response headers that browsers and JavaScript files can obtain. Format:

    • To allow all response headers: *.

    • To specify multiple response headers, enter each response header in a separate row.

    Note

    This parameter is used for the Access-Control-Expose-Headers header.

    Allow Credentials

    Specifies whether to allow credentials in CORS requests.

    Note

    This parameter is used for the Access-Control-Allow-Credentials header.

    Max Age Of Preflight Request

    The maximum period of time for which a preflight request that uses the OPTIONS method is cached.

    Note

    This parameter is used for the Access-Control-Max-Age header.

    Traffic replication policy

    The traffic replication policy allows you to replicate online application traffic to a specified service. This feature provides support for simulation tests and fault location on the system and helps you efficiently evaluate application performance and troubleshoot issues.

    Procedure

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

    Parameter

    Description

    Enable

    The switch that enables or disables the traffic replication policy for the API or operation.

    Destination Service

    The destination service to which you want to forward replicated traffic.

    Note

    Only HTTP- or HTTPS-based services are supported.

    Port

    The port of the destination service. You can select Dynamic Port.

    Note

    Dynamic Port is suitable for scenarios in which service ports dynamically change. You cannot select Dynamic Port for multi-port services.

    Traffic Replication Percentage (%)

    The traffic replication percentage. Valid values: 0 to 100.

    Note

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

    Timeout policy

    Cloud-native API Gateway provides timeout settings at the API and operation levels. You can configure the maximum period of time for which a gateway waits for a response to a request for a specified API and operation. If a gateway does not receive a response from the backend service within the specified period of time, the gateway returns the 504 (Gateway Timeout) HTTP status code to the client.

    Procedure

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

    Note

    After the timeout policy is created and enabled, you can check whether the timeout policy takes effect based on your business requirements.

    Parameter

    Description

    Enable

    Specifies whether to enable the timeout policy.

    • Enable: The timeout policy for the API or operation in the gateway takes effect.

    • Disable: The timeout policy for the API or operation in the gateway does not take effect.

    Timeout Period

    The timeout duration for the current API and operation. Unit: seconds.

    Note

    If you set this parameter to 0 or keep the timeout policy disabled, the gateway waits for responses all the time.

    Retry policy

    Cloud-native API Gateway provides retry settings at the API and operation levels to automatically retry failed requests. You can configure a retry condition, such as failed connections, unavailable backend services, or a response with a specified HTTP status code.

    Retry conditions for APIs and operations

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

    image

    • The retry conditions for HTTP Protocol are as follows:

      • 5xx: If the backend service returns any 5xx response, or if a connection is disconnected or reset, or if a read timeout occurs, Cloud-native API Gateway attempts to retry the failed request.

        Note

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

      • reset: If a connection is disconnected or reset, or if a read timeout occurs, Cloud-native API Gateway attempts to retry the failed request.

      • connect-failure: If a request fails because a connection is disconnected, Cloud-native API Gateway attempts to retry the failed request.

      • refused-stream: If the backend service resets a stream with the REFUSED_STREAM error code, Cloud-native API Gateway attempts to retry the failed request.

      • retriable-status-codes: If the HTTP status code in the response from the backend service matches the retry status code that you specify, Cloud-native API Gateway attempts to retry the request.

        Note

        You can use the retry status code only if you specify retriable-status-codes in the retry condition.

    • The retry conditions for GRPC Protocol are as follows:

      • cancelled: If the gRPC status code in the response header from the backend gRPC service is cancelled, Cloud-native API Gateway attempts to retry the request.

      • deadline-exceeded: If the gRPC status code in the response header from the backend gRPC service is deadline-exceeded, Cloud-native API Gateway attempts to retry the request.

      • internal: If the gRPC status code in the response header from the backend gRPC service is internal, Cloud-native API Gateway attempts to retry the request.

      • resource-exhausted: If the gRPC status code in the response header from the backend gRPC service is resource-exhausted, Cloud-native API Gateway attempts to retry the request.

      • unavailable: If the gRPC status code in the response header from the backend gRPC service is unavailable, Cloud-native API Gateway attempts to retry the request.

    Procedure

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

    Note

    After the retry policy is created and enabled, you can verify the results based on your business requirements.

    Parameter

    Description

    Enable

    Specifies whether to enable the retry policy.

    • Enable: The retry policy for the API or operation in the gateway takes effect.

    • Disable: The retry policy for the API or operation in the gateway does not take effect.

      After the retry policy is disabled, the gateway uses the default retry configuration. The default number of retries is 2, and the default retry conditions are connect-failure, refused-stream, unavailable, cancelled, and retriable-status-codes.

    Retry Times

    The maximum number of retries for a failed request. You can set this parameter to an integer from 0 to 10. We recommend that you set this parameter to 0, 1, or 2.

    If you set this parameter to 0, failed requests are not retried.

    Retry Condition

    Select appropriate conditions. You can select multiple conditions.

    Retry Status Code

    The HTTP status codes for which you want to retry requests. You can configure multiple HTTP status codes.

    Important

    You can configure Retry Status Code only if you specify retriable-status-codes for Retry Condition.

    Plug-in configuration

    1. Click Add Plug-in tab.

    2. In the Quick Navigation section, select the type of plug-in you want to install or search for a plug-in name, and click the plug-in card:

      • If the plug-in is not installed, click Install and Configure in the installation popup, configure the plug-in rules in the panel, and enable it.

      • If the plug-in is already installed, configure the plug-in rule and enable it.

    3. Click OK to return to the API list, where you can see the mounting and enabling status of the plug-in.

      image