Filtering, Sorting, and Pagination

When performing list operations, you may include query parameters for filtering, sorting, and pagination to better manage the results.

Certain operations also support the embed query parameter, providing an even richer output by embedding related resources into the current request. For more information about the embed query parameter, go to Embedding Referenced Resources.

Filtering

The filter query parameter narrows down the results of a GET List request to only the items that satisfy the filter criteria. Certain endpoints support the filter parameter. To determine if an endpoint supports the filter parameter, refer to the endpoint descriptions in this guide.

Filter query parameters are specified in the following JSON format:

?filter={
    "FIELD_NAME": {
        "FILTER_CONDITION":VALUE
    },
    "FIELD_NAME":{
        "FILTER_CONDITION":VALUE
    }
}

The Clumio REST API supports the following filter conditions. Different endpoints support a subset of these filter conditions on a subset of their fields:

Filter Condition	Description
$eq	equal to
$neq	not equal to
$gte	greater than or equal to
$lte	less than or equal to
$gt	greater than
$lt	less than
$in	value of the field in given input set
$all	matches all fields
$contains	partial match
$begins_with	begins with

For example, the /tasks resource supports several filter parameters, including the start_timestamp field, which can be set to query only the tasks that began before the given time (specified in RFC-3339).

GET /tasks?filter={"start_timestamp":{"$lte":"2020-04-12T23:20:50Z"}}

Common Filters

Protection Status

The following table lists Clumio supported protection statuses:

Protection Status	Description
protected	An entity that is protected by a policy.
unprotected	An entity that is not protected by a policy.
unsupported	An asset whose backup is not supported by Clumio.
null	An asset that has been deleted.

Compliance Status

The following table lists Clumio supported compliance statuses:

Compliance Status	Description
compliant	The number of assets with scheduled backups or snapshots that have been in compliance with their protection policies (SLAs) for the past 7 days. All of their recurring backups and snapshots generated within the last 7 days have successfully completed.
non-compliant	The number of assets with scheduled backups or snapshots that have violated the policy's SLA due to backup or snapshot issues encountered in the last 7 days or because there were no successful backup since the last attempt. An asset falls out of compliance when it does not meet its policy’s recovery point objective (RPO).
wait_for_seeding	The number of assets that will begin generating their first baseline backups or snapshots under new or modified policies at their next scheduled intervals.
seeding	The number of assets that are in the process of generating their first baseline backup or snapshot.
null	An asset that has been deleted or is protected.

Sorting

The sort query parameter returns the response items of a GET list operation in the order based on the specified field name.

For example, to sort a list of individual alerts in the order in which they were last updated from first to last (e.g., chronological ascending order), append the ?sort=updated_timestamp query parameter to the /alerts/individual path:

GET /alerts/individual?sort=updated_timestamp

To sort the items in reverse order (e.g., chronological descending order), prefix the field name with a minus (-) sign.

For, example, to sort the same list of individual alerts in reverse order so that the alert that was most recently updated appears at the beginning of the output, set ?sort=-updated_timestamp:

GET /alerts/individual?sort=-updated_timestamp

Only certain fields can be used for sorting. Refer to the resource descriptions throughout this guide to determine the default sort order of each collection and to determine which fields can be used for sorting.

Pagination

Pagination controls the size and starting point of a page.

The limit query parameter controls the number of results returned per page. The default value of limit depends on the resource. The start query parameter defines the starting point from where results are to be returned. Depending on the resource, the parameter may take a page number to start from or a token that identifies the starting point of results.

In the following example, the number of results per page has been limited to 5 tasks.

GET /tasks?limit=5

The limit parameter controls the number of response items returned per page, but the consistency of the content returned may not be guaranteed in that, as you are paginating, items that are inserted or deleted between requests may cause rows in your response to be skipped or duplicated.

The Clumio REST API uses HATEOAS _links for pagination by leveraging the start query parameter to traverse between pages.

Pagination _links include the following:

Link	Description
_first	Link to the first page of results.
_last	Link to the last page of results.
_nest	Link to the next page of results. Only appears if there are results to display on the next page.
_prev	Link to the previous page or results. Only appears if there are results to display on the previous page.

The _next token represents the link to the next page of results relative to the current start page, while the _prev token represents the link to the previous page of results relative to the current start page.

In the following example, the GET /tasks request returns a response of "start": "1", representing the first page of results. The _first link is set to the first page (start=1) of results. The _last link is set to the last page (start=1009) of results. The _next link is set to the next page (start=2) of results. If "start": "2", the _next link would be set to start=3. To freeze the results in time while browsing, a filter on the start_timestamp value is automatically applied to the HATEOAS links to other pages.

{
    "current_count": 10,
    "limit": 10,
    "start": "1",
    "total_count": 10088,
    "total_pages_count": 1009,
    "filter_applied": "{\"start_timestamp\":{\"$lte\":"2020-04-12T23:20:50Z"}}",
    "_links": {
        "_self": {
            "href": "/tasks",
            "type": "get",
            "templated": false
        },
        "_first": {
            "href": "/tasks?filter=%7B%22start_timestamp%22%3A%7B%22%24lte%22%3A"2020-04-12T23:20:50Z"%7D%7D&start=1",
            "type": "get",
            "templated": false
        },
        "_next": {
            "href": "/tasks?filter=%7B%22start_timestamp%22%3A%7B%22%24lte%22%3A"2020-04-12T23:20:50Z"%7D%7D&start=2",
            "type": "get",
            "templated": false
        },
        "_last": {
            "href": "/tasks?filter=%7B%22start_timestamp%22%3A%7B%22%24lte%22%3A"2020-04-12T23:20:50Z"%7D%7D&start=1009",
            "type": "get",
            "templated": false
        }
    }
}