Constructing Filters and Sorts
Fleetio is introducing a new, simpler method to filter and sort results. During the transition to this new method, there will be endpoints where the original q[]
sorting is used, and new endpoints where the new sorting will be used instead.
The new filtering and sorting methods only exist in API versions starting with 2024-01-01
. They can be identified by the response, which returns an object with pagination data, applied filters and sorts, and the array of records in the records
attribute.
New filtering and sorting method (for endpoints which accept filter
and sort
query params)
Filters
- Filters are constructed using
filter[<field_name>][<operator>]=<value>
as query parameters in the url. - The available filters and operators for an endpoint can be found in the response schema
filtered_by
attribute. - Filters applied to a response are returned as an array in the
filtered_by
response attribute. - The
q[]
filter format is not available.
Sorts
- Sorts are constructed using the
sort[<field_name>]=<direction>
as query parameters in the url. - The available sorts for an endpoint can be found in the response schema
sorted_by
attribute. - Sorts applied to a response are returned as an array in the
sorted_by
response attribute. - The
q[s]
sort format is not available.
Examples
/api/v1/vehicles?filter[name][like]=foo&sort[created_at]=desc
Would result in records
containing Vehicles with name
including the characters foo
, ordered by created_at
from newest to oldest.
/api/v1/vehicles?filter[labels][include]=green,blue&filter[license_plate][like]=yz
Would result in records
containing Vehicles with labels
of blue
or green
, and license_plate
containing the characters yz
.
Original filtering and sorting method (for endpoints which do not accept filter
and sort
query params)
Filters
- Each filter is wrapped in a
q[]
block. - Inside each
q[]
block is a condition (an attribute combined with a predicate). - Each query parameter is assigned a value.
Sorts
- Sorts still include a
q[]
block, but follow a slightly different syntax:q[s]=attribute+order
order
can beasc
ordesc
- The default sort order is
asc
if noorder
is passed. So,q[s]=attribute
is also valid.
The Filter Parameter
Values
The condition represents which properties to use for filtering and how to filter them, but we still need a target value to apply. For example, to retrieve all vehicles where the color
is "red"
, you can pass red
as the value to the q[color_eq]=
filter parameter. If you want all vehicles with an id
greater than 100
, you can pass 100
as the value to q[id_gt]=
.
Bringing it Together
Let's say that you want to construct a filter that returns all Vehicles created after January 1st, 2016. You take the attribute, created_at
, and join it with the gteq
predicate with an underscore, then wrap it in q[]
, and set the value to 2016-01-01
.
q[created_at_gteq]=2016-01-01
To retrieve the same result set, but filtering out vehicles that have no license plate, add another filter using the null
predicate:
q[created_at_gteq]=2016-01-01&q[license_plate_null]=1
The Sort Parameter
You can sort by any attribute in Fleetio. Sorts can be passed by themselves, or combined with filters. Here's what a sort could look like appended to the above examples:
q[created_at_gteq]=2016-01-01&q[s]=updated_at
q[created_at_gteq]=2016-01-01&q[license_late_null]=1&q[s]=make+desc