Table of contents:

Sorting

The query parameter sort allows to define the sort order for the result of a query.

A sort criteria consists of the name of a field and the sort direction (ASC for ascending and DESC descending).

The sequence of the sort criteria (multiple can be used) defines the sort order of the entities in the result.

The syntax of the sort parameter value is defined as follows:

Parameter	Value
sort	sort_criteria {"," sort_criteria}
sort_criteria	field_name ":" ("ASC"\|"DESC")
field_name	alpha
alpha	(digit\|character){digit\|character};
digit	"0"\|"1"\|"2"\|"3"\|"4"\|"5"\|"6"\|"7"\|"8"\|"9";
character	lowercase_character\|uppercase_character\|special_character
special_character	"_"
lowercase_character	"a"\|"b"\|"c"\|"d"\|"e"\|"f"\|"g"\|"h"\|"i"\|"j"\|"k"\|"l"\|"m"\|"n",\|"o"\|"p"\|"q"\|"r"\|"s"\|"t"\|"u"\|"v"\|"w"\|"x"\|"y"\|"z";
uppercase_character	"A"\|"B"\|"C"\|"D"\|"E"\|"F"\|"G"\|"H"\|"I"\|"J"\|"K"\|"L"\|"M"\|"N",\|"O"\|"P"\|"Q"\|"R"\|"S"\|"T"\|"U"\|"V"\|"W"\|"X"\|"Y"\|"Z";

An example URL with sort query parameter might look like the following:

/targets?sort=field_1:ASC,field_2:DESC,field_3:ASC

Paging

For querying large result sets over the internet, appropriate pagination is important. This is why we automatically apply pagination to all GET requests to collection resources.

You can configure pagination with the following parameters:

offset: the paging offset (default is 0).
limit: the maximum number of entries in a page (default is 50).

The maximum allowed value for limit is 500. When querying for groups the maximum allowed value is 1000 (this value might be decreased in a future version).

If you specify no or an invalid value for offset or limit, the default value will be used. If you specify a limit greater than the maximum, the maximum value will be used.

Examples

URL	Description
/targets?sort=name:ASC	Sorts the targets by name and returns the first 50 targets (because default offset is 0 and default limit is 50)
/targets?sort=name:ASC&limit=10	Sorts the targets by name and returns the first 10.
/targets?sort=name:ASC&offset=10	Sorts the targets by name and returns the next 50 (default limit) targets after the 10th target, i.e. starting with the 11th target.
/targets?sort=name:ASC&offset=20&limit=10	Sorts the targets by name and returns the next 10 targets after the 20th target, i.e. starting with the 21th target.
/targets?sort=name:ASC&offset=100&limit=600	Sorts the targets by name and returns the next 500 targets (not 600, because 500 is the maximum limit) after the 100th target, i.e. starting with the 101th target.

FIQL syntax search query

The parameter ‘q’ is used to filter on the fields of a resource based on the Feed Item Query Language (FIQL). The syntax for using q to filter is:

q=FIQL-expression

A FIQL expression is build as following:/targets?q=name==ccu*

q=field<basic_operator>value<composite_operator>field<basic_operator>value<...>

q: is the identifier for a following FIQL query
field: is the name of the resource field. To see on which fields filtering is possible, go to Entity definitions and have a look to the column Filter Parameter.
value: is the value of the resource field
<basic_operator>: basic operators to do simple queries
<composite_operator>: composite operators to join simple queries

Basic operators and composite operators at a glance

Operator	Description	Example
Basic operator
==	Operator to define a is equal to expression. For example: Filter all targets with the name ccu299792.	/targets?q=name==ccu299792
!=	Operator to define a is not equal to expression. For example: Filter all targets except those with the name ccu299792.	/targets?q=name!=ccu299792
=lt=	Operator to define a is less than expression. For example: Filter all distribution sets with id less than 142.	/distributionsets?q=id=lt=142
=le=	Operator to define a is less than or equal expression. For example: Filter all distribution sets with id less or equal than 142.	/distributionsets?q=id=le=142
=gt=	Operator to define a is greater than expression. For example: Filter all distribution sets with id greater than 142.	/distributionsets?q=id=gt=142
=ge=	Operator to define a is greater than or equal expression. For example: Filter all distribution sets with id greater or equal than 142.	/distributionsets?q=id=ge=142
=li=	Operator to define a like expression. For example: Filter all targets with the pattern “name has 10 character and ends with 0” (_________0) in there name.	/targets?q=name=li=_________0
=in=	Operator to define an in expression. For example: Filter all targets that have the name ccu299792 or shc137.	/targets?q=name=in=(ccu299792, shc137)
=out=	Operator to define a not in (out) expression. For example: Filter all targets that don’t have the name ccu299792 or shc137.	/targets?q=name=out=(ccu299792, shc137)
Composite operator
;	Operator to define an and expression. For example: Filter all targets with status ‘unknown’ and that start with the term SHC in the controllerId.	/rest/v1/targets?q=updatestatus==unknown;controllerId==SHC*
,	Operator to define an or expression. For example: Filter all targets with status ‘unknown’ or ‘error’.	rest/v1/targets?q=updatestatus==unknown,updatestatus==error

Using wildcards to filter

Use the * for wildcard matches.

Example URL	Description
/targets?q=name==ccu*	Returns all targets which name start with ccu.
/targets?q=name==*ccu	Returns all targets which name end with ccu.
/targets?q=name==ccu	Returns all targets which contain ccu in there name.
/targets?q=name=="ccu\\*"	Returns all targets which starts with name ccu*.
/targets?q=name== "\\*"	Returns all targets which contains asterisk(*) in their names.

The sorting and paging operators can also be combined with the FIQL.

Example URL	Description
/targets?sort=controllerId:DESC&limit=5&q=updatestatus==pending	Returns a limit of 5 targets with updatestatus ‘pending’ sorted in a descending order.
/softwaremodules?sort=name:ASC&q=version==5.1.1;type==application	Sorts the software modules in a ascending order by name and returns those with version 5.1.1 and type application
/distributionsets?sort=name:DESC&limit=150&q=name==CCU,description==CCU	Sorts the distribution sets in a descending order by name and returns a limit of 150 distribution sets with CCU in their name or in there description.
/distributionsettypes?limit=100&offset=100&q=key==vhicletypex2015	Returns a limit of 100 distribution set types (starting with the 101th distribution set type) with the key vhicletypex2015.
/targets?sort=name:ASC&offset=100&limit=25&q=(description==SH,name==SH);name=li=_____	Returns a limit of 25 targets, beginning with target count 101 and sorted in an ascending order by name with the term ‘SH’ in their name or description and a name with exactly 5 character (pattern: _____).
/targets?sort=name:DESC&limit=50&q=name=in=(ccu, ecu);updatestatus=in=(pending, in\_sync)	Returns a limit of 50 targets sorted in a descending order by name with the term ‘ccu’ or ‘ecu’ in their name and updatestatus ‘pending’ ‘or in_sync’.