Migration Guide

If you would like to switch from django-filter to rest-filters, you can incrementally migrate your code. Here is what you need to do:

If you port the entire FilterSet definition, you’ll just need to change the filter backend. This is suitable for simple FilterSet classes.

If you don’t want to port your entire FilterSet, you can start writing your new filters using rest-filters and use both libraries together. To do so:

  • Your django-filter FilterSet must be specified using the filterset_class attribute.

  • Your rest-filters FilterSet must be specified using the get_filterset_class method.

  • Your view must have both filter backends.

Additionally, if you don’t want to add known parameters from the django-filter FilterSet, you’ll need to disable rest_filters.conf.AppSettings.HANDLE_UNKNOWN_PARAMETERS.

Limitations

  • rest-filters doesn’t support generating filters from the model definition, so you’ll need to declare these filters explicitly.

  • rest-filters uses serializer fields to parse and validate query parameters. You may get slightly different behavior from django-filter, which uses Django forms.

  • rest-filters doesn’t support HTML input.

It is highly recommended to have test coverage for your FilterSets before migrating them.