The Filters are that powerful that it's possible to apply filters on related entities.
Whenever you see Related Filter Attribute
in the column Attribute Type it's a signal that related filters can be used.
Each entity has a section listing all possible filters per entity. Please note, that not all attributes from the Entity Object have filters.
What is a Related Filter?A related Filter is basically a filter applied on an (entity) attribute. Sounds weird? It is weird.
Let's see an example:
A Device has an attributeorganization
as it can be assigned to only one organization. Now remember the filters of Organization.Hence you can filter devices based on a specific field of the organization at the same time. It follows the following scheme:
<entity_attribute>__<entity_attribute_filter>
.Practically it means requesting one or more devices, that meet the condition of a specific field. In our case it is the device(s) that are assigned to an organization with a specific name.
Return ObjectPlease note, the Related Filters are intended to limit (or filter) the output of that specific endpoint, in other words, if the request is made to
api/v2.0/devices/
using a Related Filtervariables
like this:api/v2.0/devices/?variables__unit=km
simply means that request intends to obtain allDevices
that contain variables with a synthetic unit. (It does not mean the request obtains the variables that have "synthetic" as unit).
GET https://industrial.api.ubidots.com/api/v2.0/devices/?organization__name=organization_name
//Returns Array 'results' with devices that are assigned to 'organization_name'
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"organization": {
"url": "https://industrial.api.ubidots.com/api/v2.0/organizations/5e5427ea1d84725ac9d80f8d",
"_deprecated_id": 49886,
"id": "5e5427ea1d84725ac9d80f8d",
"label": "organization_name",
"name": "organization_name"
},
...
},
{
"organization": {
"url": "https://industrial.api.ubidots.com/api/v2.0/organizations/5e5427ea1d84725ac9d80f8d",
"_deprecated_id": 49886,
"id": "5e5427ea1d84725ac9d80f8d",
"label": "organization_name",
"name": "organization_name"
},...
}
]
}
The same principle can be applied to other variable type, such as Booleans, Texts, or Numbers.
GET https://industrial.api.ubidots.com/api/v2.0/devices/?organization__name__startswith=comp
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"organization": {
"url": "https://industrial.api.ubidots.com/api/v2.0/organizations/5e5427ea1d84725ac9d80f8d",
"_deprecated_id": 49886,
"id": "5e5427ea1d84725ac9d80f8d",
"label": "company_1",
"name": "company_1"
},
...
},
{
"organization": {
"url": "https://industrial.api.ubidots.com/api/v2.0/organizations/5e5427ea1d84725ac9d80f8d",
"_deprecated_id": 49886,
"id": "5e5427ea1d84725ac9d80f8d",
"label": "company_2",
"name": "company_2"
},
...
}
]
}