Flexible, dynamic fields and nested models for Django REST Framework serializers. Works with both Python 2 and 3.
FlexFields (DRF-FF) for Django REST Framework is a package designed to provide a common baseline of functionality for dynamically setting fields and nested models within DRF serializers. To remove unneeded fields, you can dynamically set fields, including nested fields, via URL parameters (?fields=name,address.zip) or when configuring serializers. Additionally, you can dynamically expand fields from simple values to complex nested models, or treat fields as "deferred", and expand them on an as-needed basis.
This package is designed for simplicity and provides two classes - a viewset class and a serializer class - with minimal magic and entanglement with DRF's foundational classes. If you are familar with Django REST Framework, it shouldn't take you long to read over the code and see how it works.
There are similar packages, such as the powerful Dynamic REST, which does what this package does and more, but you may not need all those bells and whistles. There is also the more basic Dynamic Fields Mixin, but it lacks functionality for field expansion and dot-notation field customiziation.
Table of Contents:
- Installation
- Requirements
- Basics
- Dynamic Field Expansion
- Dynamically Setting Fields
- Combining Dynamically-Set Fields and Field Expansion
- Serializer Introspection
- Testing
- License
pip install drf-flex-fields
- Python (2.7, 3.2, 3.3, 3.4, 3.5)
- Django (1.8, 1.9, 1.10)
To use this package's functionality, your viewsets need to subclass FlexFieldsModelViewSet and your serializers need to subclass FlexFieldsModelSerializer:
from rest_flex_fields import FlexFieldsModelViewSet, FlexFieldsModelSerializer
class PersonViewSet(FlexFieldsModelViewSet):
queryset = models.Person.objects.all()
serializer_class = PersonSerializer
class CountrySerializer(FlexFieldsModelSerializer):
class Meta:
model = Country
fields = ('id', 'name', 'population')
class PersonSerializer(FlexFieldsModelSerializer):
class Meta:
model = Person
fields = ('id', 'name', 'country', 'occupation')
expandable_fields: {
'country': (CountrySerializer, {source: 'country'})
}
Now you can make requests like GET /person?expand=country&fields=id,name,country to dynamically manipulate which fields are included, as well as expand primitive fields into nested objects. You can also use dot notation to control both the fields and expand settings at arbitrary levels of depth in your serialized responses. Read on to learn the details and see more complex examples.
To define an expandable field, add it to the expandable_fields within your serializer:
class CountrySerializer(FlexFieldsModelSerializer):
class Meta:
model = Country
fields = ['name', 'population']
class PersonSerializer(FlexFieldsModelSerializer):
country = serializers.PrimaryKeyRelatedField(many=True, read_only=True)
class Meta:
model = Person
fields = ['id', 'name', 'country', 'occupation']
expandable_fields = {
'country': (CountrySerializer, {'source': 'country', 'fields': ['name']})
}
If the default serialized response is the following:
{
"id" : 13322
"name" : "John Doe",
"country" : 12,
"occupation" : "Programmer",
}
When you do a GET /person/13322?expand=country, the response will change to:
{
"id" : 13322
"name" : "John Doe",
"country" : {
"name" : "United States"
},
"occupation" : "Programmer",
}
Notice how population was ommitted from the nested country object. This is because fields was set to ['name'] when passed to the embedded CountrySerializer. You will learn more about this later on.
Alternatively, you could treat country as a "deferred" field by not defining it among the default fields. To make a field deferred, only define it within the serializer's expandable_fields.
Let's say you add StateSerializer as serializer nested inside the country serializer above:
class StateSerializer(FlexFieldsModelSerializer):
class Meta:
model = State
fields = ['name', 'population']
class CountrySerializer(FlexFieldsModelSerializer):
class Meta:
model = Country
fields = ['name', 'population']
expandable_fields = {
'states': (StateSerializer, {'source': 'states', 'many': True})
}
class PersonSerializer(FlexFieldsModelSerializer):
country = serializers.PrimaryKeyRelatedField(many=True, read_only=True)
class Meta:
model = Person
fields = ['id', 'name', 'country', 'occupation']
expandable_fields = {
'country': (CountrySerializer, {'source': 'country', 'fields': ['name']})
}
Your default serialized response might be the following for person and country, respectively:
{
"id" : 13322
"name" : "John Doe",
"country" : 12,
"occupation" : "Programmer",
}
{
"id" : 12
"name" : "United States",
"states" : "http://www.api.com/countries/12/states"
}
But if you do a GET /person/13322?expand=country.states, it would be:
{
"id" : 13322
"name" : "John Doe",
"occupation" : "Programmer",
"country" : {
"id" : 12
"name" : "United States",
"states" : [
{
"name" : "Ohio",
"population": 11000000
}
]
}
}
Please be kind to your database, as this could incur many additional queries. Though, you can mitigate this impact through judicious use of prefetch_related and select_related when defining the queryset for your viewset.
You could accomplish the same result (expanding the states field within the embedded country serializer) by explicitly passing the expand option within your serializer:
class PersonSerializer(FlexFieldsModelSerializer):
class Meta:
model = Person
fields = ['id', 'name', 'country', 'occupation']
expandable_fields = {
'country': (CountrySerializer, {'source': 'country', 'expand': ['states']})
}
By default, you can only expand fields when you are retrieving single objects, in order to protect yourself from careless clients. However, if you would like to make a field expandable even when listing collections of objects, you can add the field's name to the permit_list_expands property on the viewset. Just make sure you are wisely using select_related in the viewset's queryset. You can take advantage of a utility function, is_expanded to adjust the queryset accordingly.
Example:
from drf_flex_fields import is_expanded
class PersonViewSet(FlexFieldsModelViewSet):
permit_list_expands = ['employer']
queryset = models.Person.objects.all().select_related('employer')
serializer_class = PersonSerializer
def get_queryset(self):
if is_expanded(self.request, 'employer'):
models.Person.objects.all().select_related('employer')
return models.Person.objects.all()
You can set expand=~all to automatically expand all fields that are available for expansion. This will take effect for only the top-level serializer; if you need to also expand fields that are present on deeply nested models, then you will need to explicitly pass their values using dot notation.
You can dynamically set fields, with the configuration originating from the URL parameters or serializer options.
Consider this as a default serialized response:
{
"id" : 13322
"name" : "John Doe",
"country" : {
"name" : "United States",
"population: 330000000
},
"occupation" : "Programmer",
"hobbies" : ["rock climbing", "sipping coffee"}
}
To whittle down the fields via URL parameters, simply add ?fields=id,name,country to your requests to get back:
{
"id" : 13322
"name" : "John Doe",
"country" : {
"name" : "United States",
"population: 330000000
}
}
Or, for more specificity, you can use dot-notation, ?fields=id,name,country.name:
{
"id" : 13322
"name" : "John Doe",
"country" : {
"name" : "United States",
}
}
You could accomplish the same outcome as the example above by passing options to your serializers. With this approach, you lose runtime dynamism, but gain the ability to re-use serializers, rather than creating a simplified copy of a serializer for the purposes of embedding it.
from rest_flex_fields import FlexFieldsModelSerializer
class CountrySerializer(FlexFieldsModelSerializer):
class Meta:
model = Country
fields = ['id', 'name', 'population']
class PersonSerializer(FlexFieldsModelSerializer):
country: CountrySerializer(fields=['name'])
class Meta:
model = Person
fields = ['id', 'name', 'country', 'occupation', 'hobbies']
serializer = PersonSerializer(person, fields=["id", "name", "country.name"])
print(serializer.data)
>>>{
"id" : 13322
"name" : "John Doe",
"country" : {
"name" : "United States",
}
}
You may be wondering how things work if you use both the expand and fields option, and there is overlap. For example, your serialized person model may look like the following by default:
{
"id" : 13322
"name" : "John Doe",
"country" : {
"name" : "United States",
}
}
However, you make the following request HTTP GET /person/13322?include=id,name&expand=country. You will get the following back:
{
"id" : 13322
"name" : "John Doe"
}
The include field takes precedence over expand. That is, if a field is not among the set that is explicitly alllowed, it cannot be expanded. If such a conflict occurs, you will not pay for the extra database queries - the expanded field will be silently abandoned.
When using an instance of FlexFieldsModelSerializer, you can examine the property expanded_fields to discover which, if any, fields have been dynamically expanded.
Tests are found in a simplified DRF project in the /tests folder. Install the project requirements and do ./manage.py test to run them.
See License.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent