Filter and sort API

You can use the following system query options to filter, sort, or count any collection of data items:

• $filter
• $count
• $orderby
• $select
• $skip

For more advances queries, you can combine the above in one request.

To filter by field value, you need to specify the field name and the field value.

To get the items, whose field contains a specific word from a module, you must execute a GET request to the following endpoint:

{baseurl}/api/default/{entity}?$filter=contains({fieldName},'{filterWord}')

Where:

• {entity} is the entity of the module that you are working with
• {fieldName} is the name of the field that will be filtered
• {filterWord} is the string value the filter word

Sample request

GET http://mysite.com/api/default/newsitems?$filter=contains(Title,'news')

Sample response

To filter by field value that does not contain a specific value, you must specify the field name and the value and use the NOT operator.

To get the items, whose field does not contains a specific word from a module, you must execute a GET request to the following endpoint:

{baseurl}/api/default/{entity}?$filter=not contains({fieldName},'{filterWord}')

Where:

• {entity} is the entity of the module you are working with
• {fieldName} is the name of the field which will be filtered
• {filterWord} is the string value of the filter word

Sample request

GET http://mysite.com/api/default/newsitems?$filter=not contains(Title,'news')

Sample response

To filter by range, you need to specify the field name and the value, and use the compare operators, such as:

• gt – greater than
• ge – greater than or equal to
• lt – less than
• le – less than or equal to

To get the items, whose field contains a value in a specific range from a module, you must execute a GET request to the following endpoint:

{baseurl}/api/default/{entity}?$filter= {fieldName} {compareOperator} {firstValue} and {fieldName} {compareOperator} {secondValue}

Properties

• {entity} is the entity of the module you are working with
• {fieldName} is the name of the field which will be filtered
• {compareOperator} is the operator for comparison, for example gt and lt
• {firstValue} and {secondValue} are the values of the range

Sample request

GET http://mysite.com/api/default/newsitems?$filter=PublicationDate gt 2021-04-13T08:21:21Z and PublicationDate lt 2021-04-14T08:21:21Z

Sample response

To filter by field value that is equal to something specific, you need to specify the field name and the field value.

To get the items, whose field equals a specific word from a module, you must execute a GET request to the following endpoint:

{baseurl}/api/default/{entity}?$filter={fieldName} eq {filterValue}

Where:

• {entity} is the entity of the module you are working with
• {fieldName} is the name of the field which will be filtered
• {filterValue} is the value for the filter to check equality against

Sample request

GET http://mysite.com/api/default/newsitems?$filter=NumberField eq 5

Sample response

To filter by field value that is different from a specific word, you need to specify the field name and the field value.

To get the items, whose field is different from a specific word from a module, you must execute a GET request to the following endpoint:

{baseurl}/api/default/{entity}?$filter={fieldName} ne {filterValue}

Where:

• {entity} is the entity of the module you are working with
• {fieldName} is the name of the field which will be filtered
• {filterValue} is the required value for the filter to check inequality against

Sample request

GET http://mysite.com/api/default/newsitems?$filter=NumberField ne 5

Sample response

To filter a collection of items by the taxon they have been classified with, you must use the $filter operator and specify the taxonomy name, for example – Tags or Categories, and the ID of the taxon you want to filter by.

To get a list of items, that have been classified with a specified taxon, you must execute a GET request to the following endpoint:

{baseurl}/api/default/{entity}$filter={taxonomyName}/any(x:x eq {taxaId})

Where:

• {entity} is the entity of the module you are working with
• {taxonomyName} is the name of the taxonomy which the taxon belongs to
• {taxaId} is the ID of the taxon that you want to filter by

Sample request

GET http://mysite.com/api/default/newsitems?$filter=Tags/any(x:x eq 10600c0c-5fc1-427d-9c10-bb5eab098823)&$select=*

Sample response

To narrow down filtering and get only the items tagged with a specific tag and classified with a specific category you must execute a GET request to the following endpoint:

{baseurl}/api/default/{entity}$filter=(Tags/any(x:x eq {tagId}) and Category/any(x:x eq {categoryId}))

Where:

• {entity} is the entity of the module you are working with
• {tagId} is the ID of the specific tag
• {categoryId} is the ID of the specific category

Sample request (two filters)

GET http://mysite.com/api/default/newsitems?$filter=(Tags/any(x:x eq 10600c0c-5fc1-427d-9c10-bb5eab098823)and Category/any(x:x eq 9eee95aa-bba0-4fd6-8577-1ba1600dd284))&$select=*

Sample response

When your Sitefinity CMS is in multilingual mode, you can query the items from a specific language culture. To do that you must use the sf_culture filter and append the desired culture.

To get the items that are translated in a particular language, you must execute a GET request to the following endpoint:

{baseurl}/api/default/{entity}?sf_culture={culture}

Where:

• {entity} is the entity of the module you are working with
• {culture} is the culture of the items

Sample request

GET http://mysite.com/api/default/newsitems?sf_culture=de

Sample response

To filter any type of content by the content provider, you must use the sf_provider filter and append the provider name.

To get all items from a specific provider, you must execute a GET request to the following endpoint:

{baseurl}/api/default/{entity}?sf_provider={providerName}

Where:

• {entity} is the entity of the module you are working with
• {providerName} is the name of the provider

NOTE: If you do not pass a provider filter, the service returns content from the default provider.

Sample request

GET http://mysite.com/api/default/newsitems?sf_provider=OpenAccessDataProvider&$select=*

Sample response

To return the count of the items in a collection or, if you want to know how many items in a collection meet a certain criterion, you should use the $count parameter

To get the count of items in a module, you must execute a GET request to the following endpoint:

{baseurl}/api/default/{entity}/$count

Where {entity} is the entity of the module you are working with.

Sample request

GET http://mysite.com/api/default/newsitems/$count

Sample response

If you want to return both the count and the collection data, you can use the $count=true parameter.

To get all the items in a collection, together with their count, you must execute a GET request to the following endpoint:

{baseurl}/api/default/{entity}?$count=true

Where {entity} is the entity of the module you are working with.

Sample request (count and collection)

GET http://mysite.com/api/default/newsitems?$count=true

Sample response

You can use the $orderby system query option to request resources in ascending or descending order. To do this you must specify the field name that you want to sort by and use the asc or desc keywords.

To sort a list of items alphabetically by a specific field value, execute a GET request to the following endpoint:

{baseurl}/api/default/{entity}?$orderby={fieldName} {desc/asc}

Where:

• {entity} is the entity of the module you are working with
• {fieldName} is the name of the field you want to sort

Sample request

GET http://mysite.com/api/default/newsitems?$orderby=Title desc

Sample response

It is also possible to sort by multiple fields, using comma separated format.

To sort a collection by multiple fields, you must execute a GET reaquest to the following endpoint:

{baseurl}/api/default/{entity}?$orderby={firstFieldName} {asc/desc}, {secondFieldName} {asc/desc}

Where:

• {entity} is the entity of the module you are working with
• {fieldName} are the names of the fields you want to sort by in the order that you pass them

Sample request (nested sort)

GET http://mysite.com/api/default/newsitems?$orderby=Title asc, PublicationDate desc

Sample response

To get the value of selected fields for an item, use the $select operator and specify the names of the fields.

To get only specific properties of the items, execute a GET request to yhe following endpoint:

{baseurl}/api/default/{entity}({itemId})?$select={fieldName1}, {fieldName2}, …

Where:

• {entity} is the entity of the module you are working with
• {itemId} is the ID of the item
• {fieldName} are the names of the fields that you want to return

Sample request

GET http://mysite.com/api/default/newsitems(3b177186-8b09-497c-8def-58613183d670)?$select=Title, Summary

Sample response

To return all fields for an entity, you must execute a GET request to the following endpoint:

{baseurl}/api/default/{entity}({itemId})?$select=*

Where:

• {entity} is the entity of the module you are working with
• {itemId} is the ID of the item

Sample request (all fields)

GET http://mysite.com/api/default/newsitems(3b177186-8b09-497c-8def-58613183d670)?$select=*

Sample response

You can apply pagination to the results that are returned from the request, using the $skip and $top system query options and specifying the number of items that you want to retrieve. You can also combine pagination with other filtering and sorting options.

To get a specific number of items from a module, ordered by a specific field name, you must execute a GET request to the following endpoint:

{baseurl}/api/default/{entity}?$orderby={fieldName} asc&$skip={itemsToSkip}&$top={itemsToGet}

Where:

• {entity} is the entity of the module you are working with
• {fieldName} is name of the field that you want to sort the list by
• {itemsToSkip} is the number of items to skip from the top of the ordered list
• {itemsToGet} is the numbers of items to get from the collection

Sample request

GET http://mysite.com/api/default/newsitems?$orderby=Title asc&$skip=0&$top=1

Sample response

To narrow down your request conditions, you can combine multiple filters.

To get the items from a specific culture and a specific provider, you must execute a GET request to the following endpoint:

{baseurl}/api/default/{entity}?sf_culture={culture}&sf_provider={providerName}

Where:

• {entity} is the entity of the module you are working with
• {culture} is the culture of the items
• {providerName} is the provider for the items

Sample request

GET http://mysite.com/api/default/newsitems?sf_culture=bg&sf_provider=OpenAccessDataProvider&$select=*

Sample response

You can also filter with multiple filter parameters using the AND and OR operators to create more complex filter clauses.

To get all the items with a particular field that contains a particular word and are modified after a specific date, you must execute a GET request to the following endpoint:

{baseurl}/api/default/{entity}?$filter= contains({fieldName},'{filterWord}') and {fieldName2} {compareOperator} {fieldValue}

Where:

• {entity} is the entity of the module that you are working with
• {fieldName} is the name of the field that will be filtered
• {filterWord} is the string value the filter word
• {fieldName2} is the name of the field which will be compared to a certain criterion, for example – LastModified
• {compareOperator} is the operator for comparison, for example – gt
• {firstValue} is the value of the field to be compared against, for example – 2021-04-08T08:21:21Z

Sample request (logical operators)

GET http://mysite.com/api/default/newsitems?$filter=contains(Title,'news') and LastModified gt 2021-04-08T08:21:21Z

Sample response