CA API Gateway 9.1

9.4 9.1

Evaluate JSON Path Expression Assertion

Evaluate JSON Path Expression assertion is used to query JSON objects, similar to querying XPaths. You enter a JSON expression and this assertion parses the target message and places the results into context variables.
gateway93
 
Evaluate JSON Path Expression
 assertion is used to query JSON objects, similar to querying XPaths. You enter a JSON expression and this assertion parses the target message and places the results into context variables.
 Place a Protect Against JSON Document Structure Assertion before this assertion to protect against DOS attacks.
 
Detecting Invalid JSON
 
The Evaluate JSON Path Expression assertion fails if the expression does not match. But it also fails when an invalid JSON payload is encountered and this may not be evident. One solution is to use this assertion with the expression of '$'. This selects the root node and validates the JSON payload. If it is invalid, the expression fails.
 
Using Strings
 
To use string values with the Evaluate JSON Path Expression assertion, convert them to message format first. To do this, convert the String to a Message using the Set Context Variable Assertion, with "Data type: Message" and "Content-Type:application/json".
 (Available as of version 9.3 CR3) The cluster property, 
json.evalJsonPathAcceptEmptyArray, 
preserves the backward compatibility in resulting empty arrays. By default, the value of this property is set to 
true
. If this property value is set to 
false
, the assertion is falsified for empty arrays.
Context Variables Created by This Assertion
The Evaluate JSON Path Expression assertion sets the following context variables. The default 
<prefix>
 is "jsonPath" and can be changed in the assertion properties.
To learn about selecting the target message for this assertion, see Select a Target Message.
Variable
Description
<
prefix
>
.found
 
 
 
Indicates whether a match was found for the expression:
  •  
    true
     = Match found
  •  
    false
     = No match found
<
prefix
>
.count
 
 
 
Returns the number of matches.
<
prefix
>
.result
 
 
 
Returns the result of the match, if a single match was made.
 
 
<
prefix
>
.results
 
Returns the results of the match, if multiple matches were made.
Using the Assertion
  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Add an Assertion.
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. When adding the optional assertion, the Evaluate JSON Path Expression Properties automatically appear. When modifying the assertion, right-click 
     
    <target>:
     Evaluate JSON Path Expression 
    in the policy window and select 
    Evaluate JSON Path Expression Properties
     or double-click the assertion in the policy window. The assertion properties are displayed.
  3. Configure the optional evaluator and expression.
    Setting
    Description
     
    Evaluator 
     
    Currently, the only supported evaluator is 
    JsonPath
    .
     If a JSON object contains a forward slash in the JSON object input, then the Gateway appends a backslash to 'escape' the forward slash in the JSON output. To prevent this from happening, set the 
    json.evalJsonPathWithCompression
     cluster property to '
    true
    '.
     
    Expression
     
    Enter the expression to be matched against a message. You may reference context variables.
     The Expression field can only contain a single expression. To evaluate multiple expressions, configure multiple Evaluate JSON Expression assertions within a policy
  4. Configure 
    [Source and Destination]
     tab as follows:
    Setting
    Description
     
    Target Message
     
    Specify whether to match against the 
    Request
    , 
    Response
    , or 
    Other Message Variable
     that contains the value to analyze. If other variable, specify the variable name is the box. (You do not need to enclose the variable name within the "${ }" characters.)
     The message target can also be set outside of the assertion properties. For more information, see Select a Target Message.
     
    Variable Prefix
     
    Enter a prefix that is added to the context variables created by this assertion. This prefix ensures uniqueness and prevents the variables from overwriting each other when multiple instances of this assertion appear in a policy.
    For an explanation of the validation messages that are displayed, see "Context Variable Validation" in Context Variables.
     
  5. Select the [
    Test
    ] tab to test your JSON expression against sample test input.
    • In the 
      Test Input
       box, paste some JSON code that might be found in the target message. When you click the [
      Test
      ] button, the assertion attempts to the specified expression against the test input.
    • The 
      Test Output
       box shows the results of the match. Examine the results carefully to see if this is what you intended. The figure below illustrates how the assertion interprets the test input given the sample expression shown.
      Evaluate_JSON_XPath_Properties_Test.PNG
      • For the test input shown in the figure, the test results are 
        found = true 
        and 
        count = 2
        . This means that there were two inputs that fulfilled the criteria:
         Nigel Rees 
        and 
        Evelyn Waugh
        . The assertion was able to locate the author but not the category, title, or price, because they were not specified.
      • If you used the test input 
        "bicycle"
        , no test results appear because it does not fulfill the expression criteria ".author".
  6. Click [
    OK
    ] when done.

Content feedback and comments