All APIs that return collections support filtering, arranging, and paging operations in order to deal with large data sets. Filters, arrangers, and paging parameters can all be used in combination with one another to query only the data that the caller needs.

Filtering

There are three kinds of filters:

Name filters allow you to filter the items based on a name pattern. The name pattern supports * and ? wildcards, and is case insensitive. Name filters are specified on a query by using the name query parameter.

An example of specifying a name filter that finds all tenants containing the word "acme":

    GET [apiRoot]/Tenants?name=*acme*

Smart filters allow you to specify a predetermined class of results; for example, find all items which have a health notification raised. App Orchestration has built-in complex search logic to gather the results with the best performance possible. Smart filters are specified on a query by using the filterBy query parameter. The documentation for each API lists the smart filters which are available.

An example of specifying a smart filter that finds all items, including items currently being deleted:

    GET [apiRoot]/Tenants?filterBy=All

Property filters allow you to filter the items based on a property value. You can filter for items where the property is equal to a value, or not equal to a value. Property filters are specified on a query by using the filterProp query parameter. Any property in the items returned in a collection can be filtered with the property filter, but performance may vary depending on the filter chosen.

An example of specifying a property filter that finds items with a property equal to a value:

    GET [apiRoot]/Tenants?filterProp=ResourceDomain.Name eq my.com

An example of specifying a property filter that finds items with a property not equal to a value:

    GET [apiRoot]/Tenants?filterProp=ResourceDomain.Name ne my.com

The three kinds of filters can be combined. For example, to find all tenants including those being deleted, with a name containing "acme", in the domain "my.com" you may issue a request like:

    GET [apiRoot]/Tenants?name=*acme*&filterBy=All&filterProp=ResourceDomain.Name eq my.com

Arranging

The system supports Smart arrangers which allow you to arrange the results using built-in predetermined algorithms. Smart arrangers are specified on a query by using the arrangeBy query parameter. By prefixing an arranger with a minus (-) the order can be reversed. The documentation for each API lists the smart arrangers which are available.

An example of arranging results by name, in ascending order:

    GET [apiRoot]/Tenants?arrangeBy=Name

An example of arranging results by name, in descending order:

    GET [apiRoot]/Tenants?arrangeBy=-Name

Paging

The system supports retrieving items in pages of arbitrary size, using the skip and take query parameters. The skip parameter is processed first, and specifies the number of items to skip from the beginning of the collection. The take parameter is processed second, and specifies the maximum number of items to return.

Paging parameters are always processed after filtering and arranging parameters, allowing you to page even on filtered & arranged result sets.

An example of retrieving the 3rd page of items, where each page has 20 items:

    GET [apiRoot]/Tenants?skip=40&take=20