Some of the resources in the Xentral API will support filtering, ordering, and pagination. The Xentral API uses a query string for this.

Filtering

Filters can be seen as an array of statements that are AND-grouped. Each statement takes the thing we want to filter (key), the operation we want to apply (op) and the values for that operation. It is specified per endpoint which filtering operations are possible, and which filtering keys are allowed.

Two filtering criteria would be represented as JSON the following way:

{ "filter": [
  { "key": "companyName", "op": "startsWith", "value": "X" },
  { "key": "keysCount", "op": "between", "from": 1, "to": 10 }
] }

Represented as query string this would look like:

?filter[0][key]=companyName&filter[0][op]=startsWith&filter[0][value]=X
&filter[1][key]=keysCount&filter[1][op]=between&filter[1][from]=1&filter[1][to]=1

Operators & Values

The most common operators and their values for applying filters in the Xentral API:

operator	behaviour	values
equals	string / numeric	value `string` OR value `numeric`
notEquals	string / numeric	value `string` OR value `numeric`
in	string / numeric	value `string` OR value `numeric`
notIn	string / numeric	value `string` OR value `numeric`
lessThan	numeric / datetime	value `numeric`
lessThanOrEquals	numeric / datetime	value `numeric`
greaterThan	numeric / datetime	value `numeric`
greaterThanOrEquals	numeric / datetime	value `numeric`
startsWith	string	value `string`
endsWith	string	value `string`
between	numeric / datetime	from `integer`, to `integer`

Filtering example

For the product endpoint /api/productsthe query string to filter for the name cola would look like the following:

/api/products?filter[0][key]=name&filter[0][op]=contains&filter[0][value]=cola

If you also want to filter for a specific project you can append the following query string to the previous one:

&filter[1][key]=project&filter[1][op]=contains&filter[1][value]=standard

To filter by date, you may use something resembling the following:

?filter[0][key]=date&filter[0][op]=greaterThan&filter[0][value]=2023-01-01T00:00:00+01:00

Please, note that if you use Postman, you might have to encode the date "manually" 2023-01-01T00%3A00%3A00%2B01%3A00

Ordering

Ordering can be done in ascending (ASC) or descending (DESC) direction. The ordering array describes a list of ordering criteria, where the first element is the most important ordering criteria, and the last the least important ordering criteria.

Represented as JSON the ordering object would be:

{
	order: [
  	{ "field": "companyName", "dir": "desc" },
  	{ "field": "createdAt", "dir": "asc" }
	]

}

Represented as query string this would look like:

order[0][field]=companyName&order[0][dir]=desc&order[1][field]=createdAt&order[1][dir]=asc

Pagination

Pagination uses a page number and page size as a solution to describe the window of requested data. In the Xentral API the default page size is 10, the max page size is currently set to 50.

A page query where you would like to get the 5th page, with a page size of 10 would look like:

?page[number]=5&page[size]=10