API Gateway:Use parameters and conditional expressions

2. Parameter definitions

2.1 Definition method

Before using a conditional expression, you must explicitly define all required parameters in the parameters field. For example:

---
parameters:
  method: "Method"
  appId: "System:CaAppId"
  action: "Query:action"
  userId: "Token:UserId"

The parameters field contains key-value pairs of the string type. The key and value are defined as follows:

• key: The name of a variable to use in a conditional expression. The name must be unique and follow the format [a-zA-Z_][a-zA-Z0-9]+.

• value: The location of a parameter. Define the location in the {location} or {location}:{name} format. For example:

  • location: The location of a parameter. For more information, see the next section.

  • name: The name of a parameter. Use the name to locate the parameter at a specific location. For example, Query:q1 indicates the first value of the parameter named q1 in the query string.

2.2 Parameter locations

Before you use a conditional expression, you must define the parameters that are required in this conditional expression. The following table describes parameters at specific locations that the plug-ins of API Gateway can use.

Usage notes of parameter locations

• Parameter-based access control plug-ins, traffic shaping plug-ins, and backend routing plug-ins run during the request phase. These plug-ins support only parameters from the following request locations: Method, Path, Header, Query, Form, Parameter, System, Token, and XFF.

• Error code mapping plug-ins run during the response phase. These plug-ins support only parameters from the following response locations: StatusCode, ErrorCode, Header, BodyJsonField, System, and Token.

• For the Method, Path, StatusCode, ErrorCode, and XFF locations, you need to provide only the location. A name is not required.

• When a parameter at the Header location is used in a plug-in during the request phase, the plug-in reads the header from the client request. When the parameter is used in a plug-in during the response phase, the plug-in reads the header from the backend response.

• Parameters at the Parameter location are used only in plug-ins during the request phase. The system searches for a parameter with the same name in the API definition using the parameter name, not the backend parameter name. If the parameter does not exist, null is returned.

• Parameters at the Host location are supported only for wildcard domain name parameter extraction. For more information, see Use a custom domain name to call an API. To retrieve the full host, use the System:CaDomain system parameter.

• The Path parameter specifies the full request path. If the Path contains parameters, define them in the Parameter section.

• Parameters at the BodyJsonField location are currently supported only in the error code mapping plug-in. Use a JSONPath expression to read the value from the JSON response body. For more information, see JSONPath usage notes.

• Token: If a JWT authentication plug-in is configured, you can use Token:{ClaimName} to read the value defined in the plug-in. For more information, see the documentation for the corresponding plug-in.

2.3 Usage notes of JSONPath

You can use a JSONPath expression at the BodyJsonField location to extract JSON fields from the JSON body of a backend response. This feature is supported only for the error code mapping plug-in. For more information about JSONPath, see the JSONPath documentation.

• Example: Use code:"BodyJsonField:$.result_code" to retrieve the value of result_code from the following response body. The parsed result is code: ok.

{ "result_code": "ok", "message": ... }

2.4 System parameters

3. Conditional expressions

You can use conditional expressions in plug-ins and other scenarios to perform flexible conditional evaluations.

3.1 Syntax

• Conditional expressions are similar to SQL expressions. For example: $A > 100 and '$B = 'B'.

• The basic format of an expression is {parameter} {operator} {parameter}. For example, in $A > 100, the parameters can be variables or constants.

• A variable starts with $ and references a parameter defined in the context. For example, if the parameter q1:"Query:q1" is defined in parameters, you can use the variable $q1 in the expression. The value of this variable is the value of the query parameter named q1 in the current request.

• A constant can be a string, number, or Boolean type, such as "Hello", 'foo', 100, -1, 0.1, or true. For more information, see Parameter types and judgment rules.

• The following operators are supported:

• = and ==: Equal to.

• <> and !=: Not equal to.

• >, >=, <, and <=: Comparison.

• like and !like: Similarity check. The % wildcard at the start or end of a string can be used to check for string similarity. For example: $Query like 'Prefix%'.

• in_cidr and !in_cidr: Check if an IP address is within a specific CIDR block. For example: $ClientIp in_cidr '47.89.XX.XX/24'.

• Use null to check if a parameter is empty. For example: $A == null or $A != null.

• Use and, or, and xor to combine different expressions. The default evaluation order is from right to left.

• Use parentheses ( and ) to specify the priority of conditions.

• Use !( and ) to perform a NOT operation on the enclosed expression. For example, the result of !(1=1) is false.

• The system has built-in functions for evaluations in special scenarios.

  • Random(): Generates a floating-point number between 0 and 1. This function is used in scenarios that require randomness, such as blue-green deployments.

  • Timestamp(): Returns a Unix timestamp in milliseconds.

  • TimeOfDay(): Returns the number of milliseconds that have elapsed since midnight of the current day in the GMT time zone.

3.2 Value types and judgment rules

• The following value types are supported in expressions:

  • STRING: A string type. You can use single or double quotation marks. For example: "Hello", 'Hello'.

  • NUMBER: An integer or floating-point number type. For example: 1001, -1, 0.1, -100.0.

  • BOOLEAN: A Boolean type. For example: true, false.

• For the equal to, not equal to, and comparison operators, the evaluation rules for different types are as follows:

  • STRING: Uses string order for evaluation. For example:

    • The result of '123' > '1000' is true.

    • The result of 'A123' > 'A120' is true.

    • The result of '' < 'a' is true.

  • NUMBER: Evaluates based on numerical value.

    • The result of 123 > 1000 is false.

    • The result of 100.0 == 100 is true.

  • BOOLEAN: The evaluation rule for Boolean values is that true is greater than false.

    • The result of true == true is true.

    • The result of false == false is true.

    • The result of true > false is true.

• For the equal to, not equal to, and comparison operators, if the parameter types of the left and right operands are different, the following evaluation rules apply:

  • STRING NUMBER: If the left operand can be converted to the NUMBER type, the values are compared numerically. Otherwise, they are compared as strings. For example:

    • The result of '100' = 100.0 is true.

    • The result of '-100' > 0 is false.

  • STRING BOOLEAN: If the left operand can be converted to the BOOLEAN type (case-insensitively equal to true or false), the comparison is based on the BOOLEAN type. Otherwise, except for the != comparison, the result of all other comparisons is false. For example:

    • The result of 'True' = true is true.

    • The result of 'False' = false is true.

    • The result of 'bad' = false is false.

    • The result of 'bad' != false is true. For a left operand that is not true or false, only the != operator returns true. All other comparison operators return false.

    • The result of 'bad' != true is true.

    • The result of '0' > false is false.

    • The result of '0' <= false is false.

  • NUMBER BOOLEAN: Always returns false.

• The null value can be used to check if a field is empty. For the equal to, not equal to, and comparison operators, the evaluation rules are as follows:

  • When the parameter $A is empty, the result of $A == null is true, and the result of $A != null is false.

  • An empty string '' is not equal to null. The result of '' == null is false, and the result of '' == '' is true.

  • For the comparison operator, if either operand is null, the result is false.

• The like and !like operators can be used to check for string prefixes, suffixes, and inclusion. The evaluation rules are as follows:

  • The expression only supports a STRING constant as the right operand. For example: $Path like '/users/%'.

  • The '%' character can be used at the start or end of the right operand to support prefix, suffix, and inclusion checks. For example:

    • Prefix check: $Path like '/users/%', $Path !like '/admin/%'.

    • Suffix check: $q1 like '%search', $q1 !like '%.do'.

    • Inclusion check: $ErrorCode like '%400%', $ErrorCode !like '%200%'.

  • If the left operand is not a NUMBER or BOOLEAN type, it is converted to the STRING format before evaluation.

  • If the left operand is null, the result is false.

• The in_cidr and !in_cidr expressions can be used to check if an IP address is within a CIDR block. The evaluation rules are as follows:

  • The expression only supports a STRING constant that is in IPv4 or IPv6 CIDR format as the right operand. For example:

    • $ClientIP in_cidr '10.0.0.0/8'

    • $ClientIP !in_cidr '0:0:0:0:0:FFFF::/96'

  • If the left operand is a STRING type, it is evaluated as an IP address.

  • If the left operand is a NUMBER or BOOLEAN type, or is empty, the result is false.

  • The System:CaClientIp parameter returns the client's IP address and is typically used for this type of evaluation.

Random() < 0.05

parameters:
  stage: "System:CaStage"

$CaStage = 'TEST'

parameters:
  UserName: "Token:UserName"
  ClientIp: "System:CaClientIp"

$UserName = 'Admin' and $CaClientIp in_cidr '47.47.XX.XX/24'

parameters:
  CaAppId: "System:CaAppId"
  HttpSchema: "System:CaHttpSchema"

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

parameters:
  StatusCode: "StatusCode"
  ResultCode: "BodyJsonField:$.result_code"

$StatusCode = 200 and ($ResultCode <> null and $ResultCode <> 'ok')