JSONPath Query and JSONPath Builder

JSONPath Builder is a helper utility used when creating REST API Active and Performance monitors, as well as REST API Active and Performance application monitoring (APM) components. This tool helps users select the JSON element they want to monitor, and generates a JSONPath Query for the selected JSON element.

The JSONPath Query can be written in two styles, bracket-notation and dot-notation, for example:

• [‘name’]
• $.name

This topic describes the workflow and supported syntaxes for the JSONPath Builder tool.

JSONPath Builder in the REST API Performance Monitor

When you add a new REST API Performance Monitor from the Monitors Library, the Add REST API Performance Monitor window opens. This window contains two related sections, REST API and JSONPATH, that are used in the JSONPath Builder tool.

Provide a REST API Performance Monitor name, description, and timeout value, and then follow these steps to use the JSONPath Builder tool:

1. Specify the REST API URL endpoint that you want to get Performance metrics about.
2. (Optional) Add custom headers using the Edit Custom Headers button.
3. (Optional) Select Ignore Certificate Errors if you need to suppress certificate error messages.
4. (Optional) Select Use anonymous access to bypass sending REST API Credentials to the endpoint. This option is only valid if the REST API endpoint does not require authentication to access.
5. Click the JSONPath Builder button. If the REST API URL was valid, the JSONPath Builder window opens. In this window, you can select the numeric field you want to monitor for performance data. The following image shows the JSONPath Builder window with example "Children's Library" data:

1. Click Verify to run a test on the endpoint. If the Performance Monitor can extract a numeric result from the JSONPATH endpoint value, then the monitor can be saved and added to the Performance Monitors Library. The following image shows an example of the JSONPath that returns a valid numeric value to the Performance Monitor, which was built using the JSONPath Builder:

JSONPath Builder in the REST API Active Monitor

When you add a new REST API Active Monitor from the Monitors Library, the Add REST API Active Monitor window opens. This window contains two related sections, REST API and Down Condition, which includes the JSONPath Query grid as a method for adding down conditions for the monitor. The JSONPath Query grid makes use of the JSONPath Builder when you select the magnifying glass button.

While working with REST API Active Monitors, you can define multiple JSONPath Queries to evaluate a down state for the monitor. Also, unlike Performance Monitors, Active Monitors support validating down conditions against Numeric, Boolean, and String types of variables.

Upon selecting the JSON element in the JSONPath builder, the JSONPath Query grid automatically detects the type of the element, and inputs it in the Type column in the JSONPath Query grid.

Provide a REST API Active Monitor name, description, and timeout value, and then follow these steps to use the JSONPath Builder tool:

1. Specify the REST API URL endpoint that you want to get Performance metrics about.
2. (Optional) Add custom headers using the Edit Custom Headers button.
3. (Optional) Select Ignore Certificate Errors if you need to suppress certificate error messages.
4. (Optional) Select Use anonymous access to bypass sending REST API Credentials to the endpoint. This option is only valid if the REST API endpoint does not require authentication to access.
5. Select the HTTP response codes that will report the monitor as down.
6. Select the + button to add a row to the JSONPath Query grid. The row is empty by default.
7. Double-click inside of the empty row in the JSONPath Query grid, and then select the magnifying glass button to open the JSONPath Builder. This prompts you to enter a REST API Credential if the Use anonymous access button is not checked. The JSONPath Builder window opens. In this window, you can select the numeric, boolean, or string type endpoint that you want to monitor for down conditions. The following image shows an example of down conditions for a sample API about library books:
   
8. Click Save to add the monitor to the Active Monitors Library.

JSONPath Builder in the REST API Performance application monitoring (APM) Component

The REST API Performance application monitoring (APM) Component works similarly to the REST API Performance Monitor, with the addition of the Warning and Down threshold conditions for the numeric value response. A REST API APM Component can be attached to a test device and validated. The following image shows the example numeric API endpoint along with Warning and Down Threshold values:

JSONPath Builder in the REST API Active application monitoring (APM) Component

The REST API Active application monitoring (APM) Component works similarly to the REST API Active Monitor, with the addition of a test device that the REST API Active APM component can be attached to and the monitor validated.

Advanced JSONPath Queries

As mentioned above, the JSONPath Query can be written in two styles, bracket-notation and dot-notation, for example:

• [‘name’]
• $.name

If there was a JSON array of 'books' where the first item in the array had the name "The Cat in the Hat", you could access that value by entering either of the following JSON Queries:

• [‘books’][0]['name']
• $.books[0].name

In addition to support for generating JSONPath queries for JSON elements using the JSONPath Builder, you can also write advanced queries to validate the JSON response using filters in the JSONPath Queries. The filters can be used to perform operations using comparison operators. Additionally, the "length" property is available to return the length of a JSON array.

These properties can be used in the JSONPath Query filter to return values based on conditions and filter out values that are not required.

Note: The token selector will only return a value if the captured object is of length 1. A parsing error will be thrown if multiple values are returned by the JSONPath query.

Supported comparison operators are listed in the following table:

Comparison Operator Name	Comparison Operator	Example (Bracket-notation)	Example (Dot-notation)	Notes
Equal to	==	['books'][?(@.name == 'The Cat in the Hat')]['copies']	$.books[?(@.name == 'The Cat in the Hat')].copies	The query returns the number of copies of "The Cat in the Hat" in stock.
Not Equal to	!=	['books'][?(@.name != 'The Cat in the Hat')]['copies']	$.books[?(@.name != 'The Cat in the Hat')].copies
Less than	<	['books'][?(@.copies < 3)]	$.books[?(@.copies < 3)]	For Active Monitors and Active APM Components, the Down Condition would be a String that contains 'The Cat in the Hat', if "The Cat in the Hat" contained less than 3 copies, for example.
Less than or equal to	<=	['books'][?(@.copies <= 3)]	$.books[?(@.copies <= 3)]
Greater than	>	['books'][?(@.copies > 1)]['bookId']	$.books[?(@.copies > 1)].bookId	For Active Monitors and Active APM Components, the Down Condition could be a Number that does not contain 1 (the bookId of 'The Cat in the Hat'), if "The Cat in the Hat" contained more than 1 copy, for example.
Greater than or equal to	>=	['books'][?(@.copies > 1)]['bookId']	$.books[?(@.copies > 1)].bookId
Length	.length	['books'].length	$.books.length	Returns the length of the JSON Array.