API custom filters

We use a query parameter 'map', in the form of filter[fieldName]=value, or its extended form filter[fieldName]=operator:value

The syntax can be broken up into several parts:

1. filter - self-explanatory - just a keyword

2. fieldName - name of the attribute, on which the operation is performed, this must be one of the data attributes of the requested entity, or the id attribute.

3. operator - Optional operator, which denotes what filtering operation is performed. By default, the operation is considered to be equality

   • eq - equality comparison - default value
   • neq - inequality comparison
   • gt - numeric or lexical ordering
   • lt- numeric or lexical ordering
   • leq - ordering
   • geq - ordering
   • in - Containment within set, in this case, the value parameter is a list of values separated by commas
   • notin - Inverse of the previous, utility is questionable
   • between - Numeric or alphabetical ordering, the value parameter is a list of 2 values, separated by comma

4. : - Separator, which only needs to be present, if we specify the operator

5. value - The value, or a list of values, on which the filtering is performed, separated by commas

Semantics

When providing multiple filters, the result is filtered according to each of those filters. In order to perform OR operation, you have to use the in operator, and provide a list of values.

Usage of multiple filters:

Example use case: We want to show a list of systems which were not disabled, and have not been updated in a week, let's call this Critical systems page.

In order to retrieve systems which satisfy this condition, we would have to specify following query string:

/hosts?filter[enabled]=true&filter[last_updated]=<:2019-01-01T14:00:00

Retrieval of multiple erratas:

/errata?filter[id]=in:RHSA-2019:3908,RHSA-2019:3909,RHSA-2019:2001