Skip to main content

Paginating, scoping, filtering, sorting, including data, and excluding data in responses

You can use query parameters to limit the number of returned objects and to include, exclude, filter, and sort data in the response body.

Paginating data​

If a request returns all resource instances in the response body, you can use query parameters to limit the number of objects that are returned at one time. This is especially useful for the user interface when only a limited number of rows are displayed in a table.

You can use the limit query parameter to identify the number of elements to return at one time. The default limit is 10.

You can use the offset query parameter to it identify the offset. The default offset is 0.

The following example returns the first 20 users.
/api/v1/auth/users
The following example returns the next 20 users.
/api/v1/auth/users?limit=20&offset=20
The following example returns all users without pagination.
/api/v1/auth/users?limit=0&offset=0

Scoping data​

If a request returns multiple resource instances in the response body, can narrow the scope of data to only those resources that are in specific resource managers and groups

You can use the following scoping query parameters, based on the resources that you want to scope.

  • managerIDs. Returns data for all resources that are managed by the specified resource managers.
    ?managerIDs={ID_list}

    Where {ID_list} is one or more resource manager IDs, separated by a comma. The following example scopes the returned data to devices that are managed by specific resource managers.

    ?managerIDs=2A04DFF7DDA8777EBCCD3DAF9F9BEDFD,8D735FCEFBCD49118C68169312166C68
  • groupIDs. Returns data for all resources that are members of the specified groups.
    ?groupIDs={ID_list}

    Where {ID_list} is one or more resource group IDs, separated by a comma. The following example scopes the returned data to devices that are managed by specific resource groups.

    ?groupIDs=2A04DFF7DDA8777EBCCD3DAF9F9BEDFD,8D735FCEFBCD49118C68169312166C68

You can use scoping query parameters in addition to other filtering query parameters. The response body returns only data that matches all queries.

Including data​

You can use the includeAttributes query parameter to include specific attributes in the response body. If this query parameter is present, only the specified attributes are returned. If it is missing, all attributes are returned by default.

?includeAttributes={attributes_list}

Where {attributes_list} is one or more attributes that are listed in the response body, separated by a comma.

Note
  • To specify child attributes, use a JSON path separated by a period (for example, drives.capacity).
  • When the includeAttributes query parameter is specified, the excludeAttributes query parameter is ignored.
  • Base attributes are essential attributes that are always returned in the response body unless excluded using excludeAttributes query parameter.
The following example returns data for the base attributes plus two additional attributes (name and severity) in the response body.
?includeAttributes=name,severity

Excluding data​

You can use the excludeAttributes query parameter to exclude specific attributes from the response body. If this query parameter is present, the specified attributes are not returned. If it is missing, all attributes are returned by default.

?excludeAttributes={attributes_list}

Where {attributes_list} is one or more attributes that are listed in the response body, separated by a comma.

The following example does not return data for two attributes (name and severity). Data for all other attributes are returned in the response body.

?excludeAttributes=name,severity
Note
To specify child attributes, use a JSON path separated by a period (for example, drives.capacity).

Filtering resources​

If a request returns all resource instances in the response body, you can use the filter query parameters to return data for only those resources that match all the specified criteria.

A single filter query contains two keys-value pairs, separated by an ampersand (&): one pair to specify the response attribute and another pair set to specify the value for that attribute. You can also use an ampersand to separate multiple filter queries in the same URI. If you specify multiple filter queries, data is returned only if it matches all filter queries individually.

You can use the following filter query parameters, based on the type of filter that you want to perform.

  • filterContains[]. Returns data that contains a specific pattern. Within the same filter query, data matches the query if the value of any one of the specified attributes contains any one of the specified patterns.
    ?filterContains[{index}][attributes]={attribute_list}
    &filterContains[{index}][values]={pattern_list}
  • filterNotContains[]. Returns data that does not contain a specific pattern. Within the same filter query, data matches the query if the value of any one of the specified attributes does not contain any of the specified patterns.
    ?filterNotContains[{index}][attributes]={attribute_list}
    &filterNotContains[{index}][values]={pattern_list}
    Note
    If you specify filterContains[] and filterNotContains[] with the same attributes and values, the result is an empty array.
  • filterEquals[]. Returns data that exactly matches a specific pattern. Within the same filter query, data matches the query if the value of any one of the specified attributes exactly matches any one of the specified patterns.
    ?filterEquals[{index}][attributes]={attribute}
    &filterEquals[{index}][values]={pattern_list}
  • filterNotEquals[]. Returns data that does not exactly match a specific pattern. Within the same filter query, data matches the query if the value of any one of the specified attributes does not exactly match any of the specified patterns.
    ?filterNotEquals[{index}][attributes]={attribute}
    &filterNotEquals[{index}][values]={pattern_list}
    Note
    If you specify filterEquals[] and filterNotEquals[] with the same attributes and values, the result is an empty array.
  • filterRange[]. Returns data that exactly matches a pattern in a specific range. Within the same filter query, data matches the query if the value of any one of the specified attributes exactly matches a pattern in any one of the specified ranges.
    ?filterRange[{index}][attributes]={attribute_list}
    &filterRange[{index}][values]={pattern_list}

Where:

  • {index}. Index number for the filter query. This number must be the same for the attribute and value filters. If there is only one filter query of specific type in the URI, the index number is not required.
  • {attribute_list}. Zero or more attributes that are associated with the resource, separated by a comma. If an attribute name is not provided, all attributes are evaluated.
    You can specify:
    • Attributes that are associated with the resource, regardless of the whether the attributes are included in the response for the REST API.
      Tip
      If you choose an attribute that is not in the base response, you can add it to the response by using the includeAttributes query parameter.
    • Attributes at the any level. To specify child attributes, use a JSON path separated by a period (for example, drives.capacity).
    • Attributes that contain string values for filterContains[], filterNotContains[], filterEquals[], and filterNotEquals[] queries.
    • Attributes that contain timestamp (string) or numerical values for filterRange[]queries.
  • {pattern_list}. One or more patterns, separated by a comma. Patterns are not case sensitive.
    For filterRange[] queries:
    • Each pattern can be a range of timestamps or numbers.
    • Each range contains the start and end values in the range, separated by a comma. Multiple ranges are also separated by a comma.
    • If the first value in the range is later than second value, the values are swapped during processing.
    • A timestamp must be specified using ISO-8601 format (for example, 2019-05-02T19:28:14.000Z). For information about ISO-8601 format, see the W3C Date and Time Formats webpage.

Sorting data​

If a request returns all resource instances in the response body, you can use the sort[] query parameter to sort the returned data. If this query parameter is present, the data is sorted in the order specified. If it is missing, the data is sorted using the default sorting order for the base attributes. The default sorting order varies depending on the resource, and can be determined from the metadata response attribute (see Metadata).

?sort[{sort_priority}]={attribute},{sort_order}

Where:

  • {sort_priority}. Sort priority. This can be an integer, where the lowest number is sorted first. If a number is not specified, the priority defaults to the order of the sort[] query parameter.
  • {attribute}. Response attribute name to sort by.
  • {sort_order}. Sort order. This can be asc (ascending) or desc (descending).

    Dates and numbers are sorted in descending order by default. Other strings are sorted in ascending order by default.

The following example sorts data first by name in ascending order and then by severity in descending order.

?sort[]=name,asc&sort[]=severity,desc

The following example sorts data first by severity in descending order and then by name in ascending order.

?sort[1]=name,asc&sort[0]=severity,desc