Collection Filtering

When querying collections, filters can be specified by providing one or more filter[]=…​ parameter.

GET /api/:collection?filter[]=...&filter[]=...&filter[]=...

Syntax for a filter is as follows:

filter[]=attribute op value

By default, filters are logically anded together, for a logical or, prefix the attribute with or as follows:

filter[]=or attribute op value

Where op supports the following operators:

Operator Description Operands

=

Equality

Numeric or string. For String, supports % or * as wildcard

NULL or nil can also be specified instead of quoted string

!=

Inequality

<

Less Than

Numeric

<=

Less Than or Equal

Numeric

>=

Greater Than or Equal

Numeric

>

Greater Than

Numeric

When strings, value to be quoted in single or double quotes.

Example Query VMs named sample* and return name and vendor

GET /api/vms?expand=resources&attributes=name,vendor&filter[]=name='sample%'

Example Query looking for services that are retired but have an unspecified service_id

GET /api/services?expand=resources&attributes=retired&filter[]=service_id=nil&filter[]=retired=true

Attributes specified via the filter[] parameter can include virtual attributes, including one level association of the virtual attribute as follows:

GET /api/vms?attributes=name,vendor,hardware&filter[]=vendor='vmware'&filter[]=hardware.memory_mb>=8192

Here filtering on the virtual attribute hardware including the one level association memory_mb off hardware.