All Products
Search

This Product

    API Gateway:routing plug-in

    Document Center

    API Gateway:routing plug-in

    Last Updated:May 27, 2020

    1. Overview

    A routing plug-in can change the back-end service address, back-end request path, back-end service type, and request and system parameters of an API. Routing plug-ins can be used for multi-tenant routing and blue-green release. They can also be used to distinguish between different environments.

    2. How to configure a routing plug-in

    2.1 Use a template

    You can use a JSON or YAML template to configure your plug-in. The two formats have the same schema. You can use a YAML to JSON converter to convert the configuration format. The following table shows a template in YAML format.

    1. ---
    2. routes:
    3. # When the AppId of an API caller is 123456, requests to the API are routed to an independent address. In this example, the VPC access name is set as slbAddressForVip.
    4. - name: Vip
    5.   condition: "$AppId = 123456"
    6.   backend:
    7.     type: "HTTP_VPC"
    8.     vpcAccessName: "slbAccessForVip"
    9. # Responses that are no longer supported are returned to legacy clients. ClientVersion is a custom parameter in the API.
    10. - name: MockForOldClient
    11.   condition: "$ClientVersion < '2.0.5'"
    12.   backend: 
    13.     type: "MOCK"
    14.     statusCode: 400
    15.     mockBody: "This version is not supported!!!"
    16. # Blue-green release scenarios: Five percent of requests are routed to the back end of a blue-green release.
    17. - name: BlueGreenPercent05
    18.   condition: "Random() < 0.05"
    19.   backend:
    20.     type: "HTTP"
    21.     address: "https://beta-version.api.foo.com"
    22.   constant-parameters:
    23.   - name: x-route-blue-green
    24.     location: header
    25.     value: "route-blue-green"

    The root object of the template is routes, which contains multiple route objects. Each route object is used to specify a route. Each route consists of the following parts:

    • name: the name of the route. The name must be unique within each plug-in, and can contain letters and digits. If the route is selected by the system, the back end receives a request that contains an HTTP header named X-Ca-Routing-Name. X-Ca-Routing-Name indicates the name of the route.
    • condition: the conditional expression of the route. For more information about conditional expressions, see section 2.2. If a route request meets the conditional expression, the route is then selected by the system. A plug-in selects routes based on the order in which they are configured. The first route in the configured list that meets the conditional expression will be selected and subsequent routes will be ignored. If you configure multiple routes, ensure that they are configured in the order that meets your service expectations.
    • backend: the description of the back end. The description is consistent with the Swagger specification files for API Gateway. For more information, see []. The back-end configurations for an API in a routing plug-in override the original back-end configurations in the API. If the back-end configurations are incomplete after the overriding, the X-Ca-Error-Code: I504RB error is reported to the client. When you see this error, check whether your back-end configurations are complete. For more information, see section 2.3.
    • constant-parameters: the constant parameters of the route. The constant parameters are attached to requests that are passed to the back end through the route, and are used for back-end business logic processing. The location parameter can be set to header or query.

    2.2. Conditional expressions

    2.2.1 Syntax

    • Conditional expressions have similar syntax to SQL expressions. The basic format is $A = 'A' and '$B = 'B'.
    • Each parameter starts with $. You can refer to parameters defined in an API. The API mapping relationship can either be mapping or passthrough. If the API has a defined parameter named query1, the request would represent that parameter as $query1.
    • The following constant types are supported:
      • STRING: the string data type. Single 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 ( and ) to specify the priority of conditional expressions.
    • As a built-in function, Random () can generate a NUMBER type parameter, which returns a random number in the range of [0, 1).
    • You can use $ CaAppId to refer to system parameters of the current request. You can refer to system parameters without defining them in the API. However, if you have defined a parameter in the API with the same name as a system parameter, the obtained value is overwritten by the custom API parameter. The system parameters that apply to routing plug-ins are as follows:
      • CaStage: the environment to which the current API request is made. Valid values: RELEASE, PRE, and TEST.
      • CaDomain: the domain name of the current request.
      • CaRequestHandleTime: the time in UTC at which the current request is handled.
      • CaAppId: the AppId request parameter.
      • CaAppKey: the AppKey request parameter.
      • CaClientIp: the IP address of the client.
      • CaApiName: the name of the API.
      • CaHttpScheme: the protocol used for the request. Valid values: HTTP, HTTPS, and WS.
      • CaClientUa: the UserAgent field uploaded from the client.
    • If a non-existent parameter is used in an expression, such as $UnknonwParameter = 1, the expression evaluates to false.

    2.2.3 Conditional expression examples

    • The following expression indicates a probability of 5%:

      Random() < 0.05

    • The current API request is made to the test environment.

      $CaStage = 'TEST'

    • The custom parameter UserName is set to Admin and the source IP address is 47.47.74.77.

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

    • The user ID of the current request can be 1001, 1098, or 2011, and the HTTPS protocol is used for the request.

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

    2.3. Back end definition and overriding rules

    The structure of the back end is consistent with the Swagger definitions imported into API Gateway. For more information, see Create an API by importing Swagger. The supported back end types and configuration samples are as follows. If you do not need to change the back end type in a routing plug-in, specify only the fields you want to change.

    • HTTP
    1. ---
    2. backend:
    3.   type: HTTP
    4.   address: "http://10.10.100.2:8000"
    5.   path: "/users/{userId}"
    6.   method: GET
    7.   timeout: 7000
    • HTTP_VPC
    1. ---
    2. backend:
    3.   type: HTTP_VPC
    4.   vpcAccessName: vpcAccess1
    5.   path: "/users/{userId}"
    6.   method: GET
    7.   timeout: 10000
    • FC
    1. ---
    2. backend:
    3.   type: FC
    4.   fcRegion: cn-shanghai
    5.   serviceName: fcService
    6.   functionName: fcFunction
    7.   arn: "acs:ram::111111111:role/aliyunapigatewayaccessingfcrole"
    • MOCK
    1. ---
    2. backend:
    3.   type: MOCK
    4.   mockResult: "mock resul sample"
    5.   mockStatusCode: 200
    6.   mockHeaders:
    7.     - name: server
    8.       value: mock
    9.     - name: proxy
    10.       value: GW

    2.4. Limits

    • The text size of a plug-in can be a maximum of 16,384 bytes. If this limit is exceeded, the InvalidPluginData.TooLarge error is reported.
    • The maximum number of routing entries that can be specified in a single routing plug-in is 16. If this limit is exceeded, the InvalidPluginData.TooManyRoutes error is reported.
    • The maximum size of a single conditional statement is 512 bytes. If this limit is exceeded, the InvalidPluginData.ConditionTooLong error is reported.
    • Configuration updates in a plug-in are synchronized to all APIs bound to the plug-in in real time. The maximum update frequency of plug-in configurations is 45 seconds. If this limit is exceeded, the InvalidPluginData.UpdateTooBusy error is reported.

    3. Typical scenarios

    3.1. Configure multi-tenant routing (different back-end service addresses are allocated based on AppId)

    Users whose AppId is 10098 or 10099 are my VIP users. I want requests from these two users to be routed to an independent server cluster.

    1. ---
    2. routes:
    3. # When the AppId of an API caller is 10098 or 10099, requests to the API are routed to an independent address.
    4. # In this example, the VPC access name is set as slbAddressForVip.
    5. - name: Vip
    6.   condition: "$AppId = 10098 or $AppId = 10099"
    7.   backend:
    8.     type: "HTTP-VPC"
    9.     vpcAccessName: "slbAccessForVip"

    3.2. Route API requests based on the value of the CaStage parameter (TEST, PRE, or RELEASE)

    My official environment is Alibaba Cloud VPC, but I want API requests made to the test environment to be routed to my public network test server.

    1. ---
    2. routes:
    3. # API requests made to the test environment are routed to my public network server.
    4. - name: Vip
    5.   condition: "$CaStage = 'TEST'"
    6.   backend:
    7.     type: "HTTP"
    8.     address: "https://test-env.foo.com"

    3.3. Perform a blue-green release

    I plan to direct five percent of requests to a group of Beta servers to perform a blue-green release.

    1. ---
    2. routes:
    3. # Blue-green release scenarios: Five percent of requests are routed to the back end of a blue-green release.
    4. - name: BlueGreenPercent05
    5.   condition: "Random() < 0.05"
    6.   backend:
    7.     type: "HTTP"
    8.     address: "https://beta-version.api.foo.com"