If an endpoint for listing some entity has a parameter filter_str, then the endpoint can be filtered in various ways. The filter_str-parameter should be a valid JSON string representing an object with only keys found in the schema used by the endpoint, with or without an operator suffix appended ("__le", "__ge", "__in" or "__contains") to the key.

Each key-value pair in the provided JSON object is one filter constraint, and the endpoint will return objects that match all the constraints.

There are five kinds of filtering constraints:

  • "fieldname" I.e. a key with the same name as a key in the response schema. This is an equality constraint. Only records that have this exact value for the field are matched.
  • "fieldname__le" and "fieldname__ge" are "lesser than or equal" and "greater than or equal" constraints. Numerical values are compared with natural ordering and string values are compared with lexicographical ordering.
  • "fieldname__in" is a set membership constraint. It should be given as a list of values of the same type that the field has. Records match if they match any of the values in the list exactly.
  • "fieldname__contains" is a substring constraint and is only available for fields of string type. Records match if the value of the record contains the given string as a substring. The matching is case-insensitive.

Many constraints can be combined to create more complex filters. As an example for the endpoint /project/, the following filter_str uses all of the constraints above:

  "workplacecity": null,
  "note__in": ["Very long", null],
  "name__contains": "highway"

This filter could be used to get all projects that:

  • are for a specified customer with customerid=32
  • does not specify a workplace city
  • started during 2021
  • has a note with the value "Very long" OR lacks a value
  • has a name that contains "highway" as a substring

If the given filter is invalid JSON or contains keys that are not valid filters, an HTTP 422 - Unprocessable Entity response will be returned.