Operation parameters for JSON object output

Most responses from the REST API are nested JSON objects that contain multiple records in the JSON object format. In some cases, the response contains over 100 records.

The REST API has optional, operation parameters that transform a JSON object in a response. These functions are similar to those seen in the American National Standards Institute (ANSI) Structured Query Language (SQL), which uses the WHERE clause, the ORDER BY clause, and so on. You can include REST API operation parameters in your HTTP request and receive a response in JSON object format.

Filter

The filter parameter filters the JSON objects in a response by retrieving only the JSON objects that satisfy given criteria.

Parameter 1: filter

Filters JSON objects. The value is an array, which can include multiple criteria. You will get only the records that meet at least one of the given criteria.

  • Example: Assume that you want to get records that meet one of the criteria:

    • Criterion 1: The value acknowledged is equal to false.

    • Criterion 2: The value jobId is one of the items in the list: [“1005”, “1014”].

"filter": [
    {
        "property": "acknowledged",
        "value":    false,
        "op":       "=",
    },
    {
        "property": "jobId",
        "value":    ["1005", "1014"],
        "op":       "IN",
    }
]

This operation is equivalent to the following ANSI SQL query:

SELECT * FROM table WHERE (acknowledged = 0) OR (value IN ("1005", "1014"))

Parameter 1.1: filter > List > JSON object > property

The key name of the values to evaluate.

  • Type: String. Required.

Parameter 1.2: filter > List > JSON object > value

The value to compare. The data format must match the property value to evaluate.

  • Type: Various. Required.

Parameter 1.3: filter > List > JSON object > op

The operator to evaluate the criteria.

  • Value: Use one of the following values:

Value

Description

=

The property is equal to the value.

<

The property is smaller than the value.

>

The property is greater than the value.

IN

The property exists in the set of the value.

  • Type: System string. Required.

A Python snippet that is similar to the following example can be used to send a request to IBM Spectrum Protect Plus to get alert records that meet the specified criteria:

_params = {
    "sort": f'''[
        {{
            "property": "jobId",
            "direction": "ASC"
        }},
        {{
            "property": "first",
            "direction": "DESC"
        }}
    ]'''
}

_response = requests.get('https://' + spp_ipv4
    + '/api/endeavour/alert/message/download/csv',
    headers={...}, params=_params, verify=...)

print(_response.text)

Sort

The sort parameter sorts records by given object values.

Parameter 1: sort

Sorts records. The value is an array, where you can add multiple sort operators.

  • Example: Assume that you want to sort the records by the jobId values in ascending order, and then sort records by the start values in descending order. You can use the following parameter:

"sort": [
    {
        "property":  "jobId",
        "direction": "ASC"
    },
    {
        "property":  "start",
        "direction": "DESC"
    }
]

This operation is equivalent to the following ANSI SQL query:

SELECT *  FROM table  ORDER BY jobId ASC, start DESC
  • Type: List.

Parameter 1.1: sort > List > JSON object > property

The value to sort.

  • Type: String. Required.

Parameter 1.2: sort > List > JSON object > direction

The order (ascending or descending ) in which to sort records.

  • Value: Use one of the following values:

Value

Description

DESC

Sort values in descending order (default).

ASC

Sort values in ascending order.

  • Type: System string.