rest_framework_json_api.django_filters.backends module

class rest_framework_json_api.django_filters.backends.DjangoFilterBackend

Bases: django_filters.rest_framework.backends.DjangoFilterBackend

A Django-style ORM filter implementation, using django-filter.

This is not part of the jsonapi standard per-se, other than the requirement to use the filter keyword: This is an optional implementation of style of filtering in which each filter is an ORM expression as implemented by DjangoFilterBackend and seems to be in alignment with an interpretation of http://jsonapi.org/recommendations/#filtering, including relationship chaining. It also returns a 400 error for invalid filters.

Filters can be:

  • A resource field equality test:

    ?filter[qty]=123

  • Apply other https://docs.djangoproject.com/en/stable/ref/models/querysets/#field-lookups operators:

    ?filter[name.icontains]=bar or ?filter[name.isnull]=true...

  • Membership in a list of values:

    ?filter[name.in]=abc,123,zzz (name in [‘abc’,‘123’,’zzz’])

  • Filters can be combined for intersection (AND):

    ?filter[qty]=123&filter[name.in]=abc,123,zzz&filter[...]

  • A related resource path can be used:

    ?filter[inventory.item.partNum]=123456 (where inventory.item is the relationship path)

If you are also using rest_framework.filters.SearchFilter you’ll want to customize the name of the query parameter for searching to make sure it doesn’t conflict with a field name defined in the filterset. The recommended value is: search_param=”filter[search]” but just make sure it’s filter[<something>] to comply with the jsonapi spec requirement to use the filter keyword. The default is “search” unless overriden but it’s used here just to make sure we don’t complain about it being an invalid filter.

search_param = 'filter[search]'
filter_regex = re.compile('^filter(?P<ldelim>\\[?)(?P<assoc>[\\w\\.\\-]*)(?P<rdelim>\\]?$)')
get_filterset(request, queryset, view)

Sometimes there’s no filterset_class defined yet the client still requests a filter. Make sure they see an error too. This means we have to get_filterset_kwargs() even if there’s no filterset_class.

get_filterset_kwargs(request, queryset, view)

Turns filter[<field>]=<value> into <field>=<value> which is what DjangoFilterBackend expects

Raises

ValidationError – for bad filter syntax