Filters

Filters are used to define the output of your responses. The only fields returned in the response are the ones specified in the filters. If not specified, the field will not be part of the response.

Note

Important: If filters are not defined, the response will be an empty dictionary.

Filtering Options

ALWAYS

The response field will always be returned.

NEVER

The response field will never be returned.

IF_TRUTHY

Only return if the response field value is a python truthy value.

Structure for defining a filter

FilterName = {
    Model: {
        'response_field': filtering_option
    }
}

Example: Creating a new filters.py file and defining a filter for a Todo app’s response.

TodoResponseFilter = {
    Todo: {
        'task': filtering.ALWAYS,
        'priority': filtering.ALWAYS,
        'created_date': filtering.NEVER,
        'completion_status': filtering.IF_TRUTHY
    },
}

• task and priority fields are set to ALWAYS . Therefore, they will always be returned in the response.

• create_date is set to NEVER , thus, it will not appear in the response object.

• completion_status will only be included in the response if it is a python truthy value.

Define Filters

Filters can be defined in four places:

Note

Important: Items lower in the list take precedence over items at the top of the list. For instance, response_filter overrides the default filter defined in settings.py.

1. settings.py

   Required | Set default filters for the entire application in settings.py by setting DECLARATIVE_ENDPOINT_DEFAULT_FILTERS to your filters.py file.

   Example: Set the Todo filter as the default filter in settings.py.

   DECLARATIVE_ENDPOINT_DEFAULT_FILTERS = "todo.filters.TodoResponseFilter"
   

2. response_filter

   Optional | Defines filters for a class and can be used interchangeably with @endpoint_resource(). To implement, set response_filter as a class-level field on your EndpointDefinition.

   Default Value | None

   Example:

   class TodoCreationEndpoint:
       response_filter = filters.TodoResponseFilter
   

3. @endpoint_resource

   Optional | Defines filters for a class and can be used interchangeably with response_filter. To implement, set filter=<filter> in an argument to the @endpoint_resource decorator.

   Default Value | None

   Example

   from django-declarative-apis.machinery import endpoint_resource
   
   class TodoDefinition(TodoResourceMixin, machinery.ResourceEndpointDefinition):
       resource_model = Todo
   
       @endpoint_resource(type=Todo, filter=filters.TodoResponseFilter)
       def resource(self):
           return Todo.objects.all()
   

4. _api_filter

   Optional | Defines filters for a return object. To implement, set _api_filter on the object returned from @endpoint_resource.

   Default Value | None

   Example

   class TodoDefinition(TodoResourceMixin, machinery.ResourceUpdateEndpointDefinition):
       task = field(required=True, type=str)
       priority = field(required=True, type=str)
       completion_status = field(type=bool, default=False)
   
       @endpoint_resource(type=Todo)
       def resource(self):
           task, created = Todo.objects.get_or_create(
               task=self.task,
               priority=self.priority,
               completion_status=self.completion_status,
           )
   
           task._api_filter = filters.TodoResponseFilter
   
           return task