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

You can filter the results of an HTTP GET requests for lists of objects by specifying 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 requests returns the total number of objects that would be returned with a GET request, and filtering 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.

Table 1. Parameters
Name Type Required Description
attribute_name String No The name of an attribute.
value String No

The text pattern 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. You use the ampersand character & to combine multiple filters.

When you use multiple different attributes to search on, 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 (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.

Table 2. GET query parameters
Name Type Required Description
sort_by string No The field to use to sort the results.
sort_dir string No 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 back-end 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.

You provide information about pagination in the GET request parameters.

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

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
Table 4. Link header parameter definitions
Name Type Required Description
rel String Yes The link relation for the specific page results. The link relations 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