We saw that by using the command without an ID at the end, it is possible to retrieve list of objects.
For example if we use:
then we fetch all the devices under a specific network.
Or if we use:
we fill be able to fetch all the devices owned or shared with the user.
However the API provides the possibility to filter these documents in relation of some criteria. Here there are some possibility.
Remember to not use quotes " or spaces in a query.
If you want to have more interesting results, you can add the query "expand=0".
All these filter work not only with "GET" requests, but also with "PATCH" and "DELETE" requests.
All the filters can be combined with each other to obtain interesting filters. Like this:
Filter by ID
We can retrieve multiple specific objects by specifying them on the ID. In the following way:
Filter with offset and limit
We can limit and offset our returning results by using offset and limit.
This will skip the first three found devices and it will return only the next five. Default are offset equal to 0 and limit equal to 50. Max limit is 200.
Order by creation/last update
If we want to retrieve by creation or the last update of an object, then you can use:
The possibility are "update", "creation" and "timestamp". In the last case it will order in relation of the "timestamp" attribute if existing, otherwise il will be equivalent to "update". By default order_by is undefined and it will returns the objects as are stored.
Order from last
If we want to retrieve by starting from the last element, then you can use:
By default from_last is equal to false.
Filter by method
Sometimes we do not have permission to use some method ("retrieve", "update", "add" or "delete"). We can filter in relation if we are able to use a method or not.
In the example we wants to retrieve the devices that we can retrieve and update.
Filter by attributes
We can use the attribute of an object to filter. For example if we use:
will return all the devices with the name that contains the value "light". The syntax is "this_" plus the attribute we want to filter.
We can filter in relation of the parent of the object. Like this:
will return all the devices with the parent network that contains the value "light". The syntax in this case is "parent_" plus the attribute we want to filter. If we want to go higher in the parenthood we can repeat "parent_". Like this "parent_parent_parent_name".
We can even filter in relation of the children of the object. Like this:
In this case we return all the devices that have at least one child with in the name the string "colour". The syntax in this case is "children_" plus the attribute we want to filter. If we want to go higher in the "childhood" we can repeat "children_". Like this "children_children_children_name".
If we have some attribute deep in an hash we can use a dot to retrieve. Like this:
Filter by owned
Owned has three possibility:
- default: returns owned and shared object
- "true": returns only owned object
- "false": returns only shared object
Filter by shared_with
We can filter only the object shared with particular users or installations.
Filter by not_shared_with
We can filter only the object not shared with particular users or installations.
Filter in relation of parenthood
We can filter only the object that have been shared with us, but without its parent.
In this case it will returns all the devices that have been shared with the user without having the network shared with the user.
Filter by deepness
Some services, like contract, file or set are children of multiple object. For this reason using a list to retrieve will not bring out all the objects but only the one of a certain level.
returns only the sets assigned to the user.
At the contrary:
will return all the sets assigned to the user and to the children of the user (network, application, installation, ...)