1. Overview

A plug-in of the Routing type is used to route API requests to different backends by changing the backend type, address, path, and response parameters of an API operation based on request and system parameters in API requests. These plug-ins can be used for multi-tenant routing and blue-green release. They can also be used to distinguish between environments, that is, route all requests for API operations that are published to the same environment to the same server.

2. Configurations

2.1. Template

You can configure a plug-in of the Routing type in the JSON or YAML format. The two formats have the same schema and can be converted to each other by using a conversion tool. The following code snippet is a YAML template for configuring a plug-in of the Routing type:

---
routes:
# Route requests from the same caller to an independent backend service address. In this example, requests from the caller whose AppId is 123456 are routed to an address that belongs to the Classless Inter-Domain Routing (CIDR) block of a virtual private cloud (VPC) and is named slbAddressForVip.
- name: Vip
  condition: "$CaAppId = 123456"
  backend:
    type: "HTTP-VPC"
    vpcAccessName: "slbAccessForVip"
# If an API request is sent from an out-dated client, return a message to remind the caller that the client version is no longer supported. You can specify the ClientVersion parameter as needed when you create an API operation.
- name: MockForOldClient
  condition: "$ClientVersion < '2.0.5'"
  backend: 
    type: "MOCK"
    statusCode: 400
    mockBody: "This version is not supported!!!"
# In scenarios where blue-green release is involved, route a specified percentage of requests to a backend that applies blue-green release. In this example, the specified percentage is 5%.
- name: BlueGreenPercent05
  condition: "Random() < 0.05"
  backend:
    type: "HTTP"
    address: "https://beta-version.api.foo.com"
  constant-parameters:
  - name: x-route-blue-green
    location: header
    value: "route-blue-green"

The template shows a routes object that contains multiple route objects. Each route object is used to specify a routing rule. Each routing rule consists of the following parts:

  • name: the name of the routing rule. The name must be unique within each plug-in, and can contain letters and digits. If an API request hits the rule, an HTTP header field X-Ca-Routing-Name that contains the name of the rule is added to the request before the request is routed to the backend.
  • condition: the conditional expression of the routing rule. For information about how to write conditional expressions, see section 2.2. If an API request meets the condition, the request hits the routing rule. A plug-in of the Routing type checks the routing rules based on the order in which they are configured. An API request is routed to the backend in the first routing rule that the request hits. After that, the plug-in does not check the remaining routing rules. If you configure multiple routing rules, make sure that they are configured in the order that meets your service expectations.
  • backend: the information about the backend. Configurations of the backend must be consistent with the OpenAPI specification files that are imported to API Gateway. For more information, see []. The backend configurations in a plug-in of the Routing type override the backend configurations in an API operation that is bound to the plug-in. If the backend configurations are incomplete after the overriding, the following message is returned to the client: X-Ca-Error-Code: I504RB. If you receive this message, check whether the backend configurations are complete. For more information about how to configure a backend, see section 2.3.
  • constant-parameters: the constant parameters that you can customize in the routing rule. The constant parameters are attached to an API request before the request is routed to the backend. These parameters are used in the business logic of the backend. The location parameter can be set to header or query.

2.2. Conditional expressions

2.2.1 Syntax

  • The syntax of conditional expressions in plug-ins of the Routing type are similar to that of SQL statements. The basic format is $A = 'A' and '$B = 'B'.
  • Each parameter starts with $. You can reference the request parameters that are defined in an API operation to which a plug-in is bound. The request mode of the API operation can be set to either mapping or passthrough. If you defined a request parameter named query1 when you configured the API operation, you can use $query1 to reference the parameter in conditional expressions.
  • The following constant types are supported:
    • STRING: the string data type. Single quotation marks (' ') or double quotation marks (" ") can be used to enclose a string, for example, "Hello".
    • INTEGER: the integer data type, such as 1001 and -1.
    • NUMBER: the floating-point data type, such as 0.1 and 100.0.
    • BOOLEAN: the Boolean data type. Valid values: true and false.
  • You can use and and or to connect different expressions.
  • You can use parentheses () to specify the priority of conditional expressions.
  • The built-in function Random() can be used to generate a floating-point number in the range of [0, 1).
  • You can use $CaAppId to reference system parameters in an API request. You do not need to define system parameters in an API operation. However, if you have defined a parameter in the API operation with the same name as a system parameter, the value of the system parameter is overwritten by that of the parameter that is defined in the API operation. The following system parameters can be referenced in a plug-in of the Routing type:
    • CaStage: the environment to which the requested API operation is published. Valid values: RELEASE, PRE, and TEST.
    • CaDomain: the domain name of the API group to which the requested API operation belongs.
    • CaRequestHandleTime: the time in UTC at which the current request is received.
    • CaAppId: the value of the AppId parameter in the current request.
    • CaAppKey: the value of the AppKey parameter in the current request.
    • CaClientIp: the IP address of the client from which the current request is sent.
    • CaApiName: the name of the requested API operation.
    • CaHttpScheme: the protocol used by the current request. Valid values: HTTP, HTTPS, and WS.
    • CaClientUa: the user agent string in the current request.
  • If you use a non-existent parameter in a conditional expression, such as $UnknonwParameter = 1, the result of the expression is false.

2.2.2 Examples

  • The following expression indicates that a probability must be less than 5%:

    Random() < 0.05

  • The following expression indicates that the requested API operation must be published to the test environment:

    $CaStage = 'TEST'

  • The following expression indicates that the custom parameter UserName must be specified as Admin and the IP address of the client must be 47.47.74.77:

    $UserName = 'Admin' and $CaClientIp = '47.47.74.77'

  • The following expression indicates that the AppId parameter must be specified as 1001, 1098, or 2011, and the protocol that is used by the API request must be HTTPS:

    $CaHttpScheme = 'HTTPS' and ($CaAppId = 1001 or $CaAppId = 1098 or $CaAppId = 2011)

2.3. Backend configuration and overriding rules

Configurations of a backend must be consistent with the OpenAPI specification files that are imported to API Gateway. For more information, see Import Swagger files to create APIs. The following examples show the supported backend types and configuration samples. The backend configurations in a plug-in of the Routing type override the backend configurations in an API operation that is bound to the plug-in. If you do not need to change the backend type, specify only the parameters whose values you want to change.

  • HTTP
---
backend:
  type: HTTP
  address: "http://10.10.100.2:8000"
  path: "/users/{userId}"
  method: GET
  timeout: 7000
  • HTTP-VPC
---
backend:
  type: HTTP-VPC
  vpcAccessName: vpcAccess1
  path: "/users/{userId}"
  method: GET
  timeout: 10000
  • Function Compute
---
backend:
  type: FC
  fcRegion: cn-shanghai
  serviceName: fcService
  functionName: fcFunction
  arn: "acs:ram::111111111:role/aliyunapigatewayaccessingfcrole"
  • MOCK
---
backend:
  type: MOCK
  mockResult: "mock resul sample"
  mockStatusCode: 200
  mockHeaders:
    - name: server
      value: mock
    - name: proxy
      value: GW

2.4. Limits

  • For each plug-in of the Routing type, you can configure a maximum of 16,384 bytes of metadata. If this limit is exceeded, the InvalidPluginData.TooLarge error is returned.
  • A maximum of 16 routing rules can be configured in each plug-in of the Routing type. If this limit is exceeded, the InvalidPluginData.TooManyRoutes error is returned.
  • Each conditional expression can contain a maximum of 512 characters. If this limit is exceeded, the InvalidPluginData.ConditionTooLong error is returned.
  • Configuration updates of a plug-in of the Routing type are synchronized in real time to all API operations that are bound to the plug-in. The minimum interval between two updates is 45 seconds. If you try to update a plug-in in less than 45 seconds after the last update, the InvalidPluginData.UpdateTooBusy error is returned.

3. Typical scenarios

3.1. Configure multi-tenant routing: Route API requests to different backend addresses based on the value of the AppId parameter

Assume that users whose AppId is 10098 or 10099 are your VIP customers. You want to route API requests from these two users to an independent server cluster.

---
routes:
# If the AppId of the caller is 10098 or 10099, route the API request to an independent address.
# In this example, the address belongs to the CIDR block of a VPC and is named slbAddressForVip.
- name: Vip
  condition: "$CaAppId = 10098 or $CaAppId = 10099"
  backend:
    type: "HTTP-VPC"
    vpcAccessName: "slbAccessForVip"

3.2. Configure routing based on environments: Route all requests for API operations that are published to the same environment to the same server

Assume that you want all requests for API operations that are published to the test environment to be directed to your test server on the Internet.

---
routes:
# Route all requests for API operations that are published to the test environment to the test server on the Internet.
- name: Vip
  condition: "$CaStage = 'TEST'"
  backend:
    type: "HTTP"
    address: "https://test-env.foo.com"

3.3. Configure routing for performing blue-green release

You want to direct 5% of API requests to a group of test servers when you perform blue-green release.

---
routes:
# In scenarios where blue-green release is involved, route a specified percentage of requests to a backend that applies blue-green release. In this example, the specified percentage is 5%.
- name: BlueGreenPercent05
  condition: "Random() < 0.05"
  backend:
    type: "HTTP"
    address: "https://beta-version.api.foo.com"