rest_framework_json_api.django_filters.backends module

class rest_framework_json_api.django_filters.backends.DjangoFilterBackend

Bases: DjangoFilterBackend

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

This is not part of the JSON:API 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 https://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 JSON:API 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

get_schema_operation_parameters(view)

Convert backend filter name to JSON:API-style filter[name]. For filters that are relationship paths, rewrite ORM-style __ to our preferred .. For example: blog__name__contains becomes filter[blog.name.contains].

This is basically the reverse of get_filterset_kwargs above.