API filtering, sorting, and pagination

The Fabric Services System REST API supports the ability to filter, sort, and paginate results from REST API GET requests.

Filtering

To filter the results of an HTTP GET requests for lists of objects, specify an attribute name and the value of the attribute for which you want to filter.

Filtering can be combined with pagination and sorting. When you apply filtering, the HTTP HEAD request returns the total number of objects that would be returned with a GET request, and the filter is applied to this result. For example, if there are 100 objects and a filter is used that results in the GET API call returning 20 of them, the HEAD request also returns the number 20.

The following table describes the parameters used for filtering.

Table 1. Filtering parameters
Name	Type	Required	Description
`attribute_name`	String	No	The name of an attribute
`value`	String	No	The text string to match

Using wildcards

You can use the wildcard character (*) at the beginning or the end of a specified value. The wildcard character * represents one or more characters.

As multiple fields in the API can contain an asterisk (*) as a valid character, to use it as a wildcard in the filtering, you must also include wildcardsearch=true in the expression.

The following expression returns externalId values that start with connect-:

?externalId=connect-*&wildcardsearch=true

The following expression returns name values that contain example:

?name=*example*&wildcardsearch=true

Combining expressions

You can further refine the results returned by combining multiple query expressions. Use the ampersand character & to combine multiple filters.

When you search on multiple different attributes, these attributes are combined in an AND-based search. When using multiple search values for the same attribute, the search looks for any of the specified values for that attribute in an OR-based search.

Using the AND operator

The following example returns results where the name attribute contains example and the externalId starts with connect-:

?name=*example*&externalId=connect-*&wildcardsearch=true

Using the OR operator

The following expression returns results where the name attribute contains example or sample:

?name=*example*&name=*sample*&wildcardsearch=true

AND and OR operators

The following example returns results where the name attribute value contains example or sample and the externalId attribute starts with connect- or con-:

?name=*example*&name=*sample*&externalId=connect-*&externalId=con-*&wildcardsearch=true

Sorting

You can sort the results of an HTTP GET request. You can sort on a single attribute or multiple attributes. You can combine sorting with pagination and filtering.

The following table describes the parameters used for sorting.

Table 2. GET query parameters
Name	Type	Required	Description
`sort_by`	String	No	Use this field to sort the results.
`sort_dir`	String	No	This field specifies whether to sort in ascending (asc) or descending (desc) order. The value is case insensitive. Default: asc

Sort on a single attribute

sort_by=name&sort_dir=asc

Sort on multiple attributes

sort_by=name,externalId&sort_dir=asc,desc

Pagination

Pagination prevents the overloading of the API backend when it has to return hundreds or even thousands of objects in a single HTTP GET request. Pagination also prevents overloading the receiving side in the amount of data and the number of objects to process.

Provide information about pagination in the GET request parameters.

A link header is returned to highlight the next page or previous page URIs for easy reference; they are only present if they are relevant.

The table below describes the parameters used for the pagination request.

Table 3. Request parameter definitions
Name	Type	Required	Description
`page`	Integer	No	The page number to display. Default: 1
`page_size`	Integer	No	The number of items to return in the response. Default: 100

The table below describes the link header parameter.

Table 4. Link header parameter definitions
Name	Type	Required	Description
`rel`	String	Yes	This parameter specifies link relation for the specific page results. The link relation can be: `next` - the next page of results `prev` - the previous page of results

Pagination request for the second page with a page size of 100

GET https://fss.domain.tld/rest/...?page=2&page_size=100

Link header that contains a link to the next page

<https://fss.domain.tld/rest/...?page=2&page_size=100>; rel=next

Link header that contains a link to the previous page

<https://fss.domain.tld/rest/...?page=1&page_size=100>; rel=prev