Tutorial: Filtering

Filtering is in an experimental phase and breaking changes are possible without announcements. Errors occurring when using filters will not be handled with the highest priority.

The SkillEngine API provides a syntax to filter the entities returned and used for a response.

It allows you to find entities with specific properties easily.

Because the SkillEngine API is developed in Django the syntax is fairly similar to the one used by Django.

GET /employees?$employees=external_id='1'
# Will only display the employee with external id equal to `1`
# in the response

GET /reports/count?$employees=external_id='1'&$jobs=external_id='2'
# Will only use the employee with external id equal to `1` and
# the job with external id equal to `2` when calculating its response

Current filterable entities are

employees
jobs
job_families
vacancies
courses

Operators

The following operators are supported.

exact (default)
iexact
contains
icontains
startswith
istartswith
endswith
iendswith
gt
gte
lt
lte
is_null

The operators can be used by separating the field and operators with __ like this

GET /employees?$employees=external_id__contains='1'
# Will only display employees of which the external id contains '1'

More information on the workings of these operators can be found at Django filter reference.

For some entities additional operators may be available; in those cases the behavior of the additional property will be explained in the API reference of that entity.

Logical operators (AND, OR, NOT)

Multiple filters can be combined using and and or; filters can also be negated by using not.

GET /employees?$employees=(external_id__startswith='1' or external_id__startswith='2')
# Will only display employees of which the external id either starts with '1' or with '2'

GET /employees?$employees=(external_id__contains='1' and external_id__contains='2')
# Will only display employees of which the external id both contains '1' and '2'

The precedence of the operators is not, and, or equal to the operator precedence of Python and most other programming languages.

Related fields can also be filtered, meaning you can limit the jobs returned by filtering on a property of the related job family as follow.

GET /jobs?$jobs=job_family__external_id='1'
# Will only display jobs which have the job family with external id equal to '1'

Custom properties

Custom properties can also be used for filtering entities by using the cp_ prefix.

GET /employees?$employees=cp_language='de'
# Will only display employees that have value 'de' for the customer property
# with property name 'language'

Nuances

When requesting an entity that is filtered out, you will get a 404 Not Found response, while trying to create this entity will result in a 409 Already Exists response.

Addition to other filters

If you have a credential that already has certain filters bound to it, all these filters will be added on top.

Limitations

Complex filters might significantly increase response times and database load, for that reason, the following limitations are in place.

The number of logical operators can not exceed 5
Fields allowed for filtering are specified per entity