Welcome back! In this lesson, we'll dive into advanced filtering techniques to make our To-Do API even more powerful and user-friendly. You've already learned the basics of filtering in the previous lesson. Here, we will focus on adding more flexible filtering capabilities using the django-filter library, which makes complex queries easier to handle. By the end of this lesson, you will be able to create custom filters to refine your API queries.

Before we get started with advanced filtering, let's briefly recap the initial setup of our Django-based To-Do API. This will ensure we're all on the same page.

Here's the summary code of our current setup:

This setup provides a model we will work with. Now, let's take it a step further by adding powerful filtering options.

The django-filter library allows you to create advanced custom filters. Filters are defined in a FilterSet class that specifies which fields are available for filtering and how filtering should be performed. We will create a separate filters.py file to store filters. Inside, we'll define a TodoFilter class to filter To-Do items based on various fields. This class should be inherited from filters.FilterSet, as follows:

A common filter is one that allows you to search for a field containing specific text. For example, to filter tasks based on a substring match in their names, use the CharFilter with lookup_expr set to icontains:

Here, we create a filter for the task field, allowing case-insensitive, partial matches using icontains. This means users can find To-Do items with tasks that include specific text. However, it's important to note that the behavior of icontains and contains can depend on your database settings, particularly the collation settings. Some databases may not support case-insensitive searches by default, which could affect the functionality of icontains.

For other cases, django-filters provide a comprehensive set of options for lookup_expr:

• exact: Matches exactly.
• iexact: Case-insensitive exact match.
• contains: Contains substring.
• icontains: Case-insensitive contains substring.
• startswith: Starts with substring.
• istartswith: Case-insensitive starts with substring.
• endswith: Ends with substring.
• iendswith: Case-insensitive ends with substring.

A Boolean filter is used for binary fields, such as completed status. You can use BooleanFilter:

This filter allows users to query tasks based on their completion status. There is nothing special about it, but we should include it to ensure our custom filter has the complete required functionality.

Filters can also be used for numeric fields, such as priority:

This allows exact matches against the specified numeric value.

The completed and priority filters do not specify a field_name. In such cases, django-filter defaults to using the filter name ('completed' and 'priority') as the field name. The default value for lookup_expr is 'exact', meaning it performs an exact match unless specified otherwise.

For comparing numerical values, you can create filters using lookup expressions like lt (less than) and gt (greater than):

These filters allow users to find tasks with priority less than or greater than a specified value.

Here are other options you can use for lookup_expr in a similar manner:

• exact: Matches exactly.
• gt: Greater than.
• gte: Greater than or equal.
• lt: Less than.
• lte: Less than or equal.

django-filter also provides filters for date and time fields. You can filter To-Do items based on creation or due date using DateFilter or DateTimeFilter. Here is an example:

Imagine we added a due_date field to our model:

You can specify different lookup_expr values for date and datetime fields, just as with other filters:

• exact: Matches the exact date/time.
• gt: Greater than the specified date/time.
• gte: Greater than or equal to the specified date/time.
• lt: Less than the specified date/time.
• lte: Less than or equal to the specified date/time.
• date: Extracts the date part of the datetime.
• year: Extracts the year part of the datetime.
• month: Extracts the month part of the datetime.
• day: Extracts the day part of the datetime.
• hour: Extracts the hour part of the datetime.
• minute: Extracts the minute part of the datetime.
• second: Extracts the second part of the datetime.
• week_day: Extracts the week day part of the datetime.

For instance, to filter tasks due after a specific date:

When sending a request to filter on a DateTimeField, dates and times should be formatted in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

Finally, we must connect the FilterSet with the model and specify available fields using a Meta class:

The Meta class connects the TodoFilter with the Todo model and specifies the fields available for filtering.

Here is the full content of the filters.py file:

Next, we need to integrate our custom filters with the Django views. We'll update the TodoListCreate view to use our TodoFilter.

By adding DjangoFilterBackend to filter_backends and specifying TodoFilter as the filterset_class, we enable advanced filtering for our To-Do list view.

To test our filters, we can use the following examples in send_request.py:

1. Filter where task contains "Task" and completed is True:

1. Filter where priority is less than 3:

1. Filter where priority is greater than 1:

These examples illustrate how to send HTTP GET requests with query parameters and verify the filtered results.

Also let's look at some examples with calling datetime filters, as they can be quite specific:

1. Filter where due_date is in October 2023:

1. Filter where due_date falls on a Tuesday:

Week day 2 means Tuesday. 1 is Monday, 2 is Tuesday, 3 is Wednesday, etc.

In this lesson, we've extended our To-Do API by adding sophisticated filtering capabilities. You now know how to create custom filters using the django-filter library and integrate them into your Django views. These skills are essential for building flexible and user-friendly APIs.

Congratulations on completing this lesson and, indeed, the entire course! Your dedication has brought you here, and now you're well-equipped to build advanced Django-based APIs. Keep practicing with the exercises that follow and continue honing your skills. Great job!