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. A response can contain hundreds of 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 tofalse
.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. |
|
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 include multiple sort operators.
Example: Assume that you want to sort records by the
jobId
values in ascending order, and then sort records by thestart
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 |
---|---|
|
Sort values in descending order (default). |
|
Sort values in ascending order. |
Type: System string.
Pagination¶
Records in a REST API response are sorted by the id
values in ascending order, unless you specify the sorting order by using the sort
function. By default, the REST API splits the response body into sets of 100 records. You can see the next 100 records by specifying the pageStartIndex
value. Or, you can increase the number of records in each response by specifying the pageSize
value.
Parameter 1: pageStartIndex
The initial record number in the ordered records. The records are numbered 0, 1, 2, and so on. You can specify 0 or any positive integer for the pageStartIndex value.
Example: Assume that you want to get records, starting with the 201st record. Each page contains 100 records by default. You can use the following parameter to get the records between the 201st and the 300th:
"pageStartIndex": 200
This operation is equivalent to the following ANSI SQL query:
SELECT * FROM table WHERE id > 200 LIMIT 100
Type: Integer.
Parameter 2: pageSize
The number of records on each page. The default value is 100.
Example: Assume that you want to get 500 records in a response. You can use the following parameter:
"pageSize": 500
This operation is equivalent to the following ANSI SQL query:
SELECT * FROM table LIMIT 500
Type: Integer.