Package: djangorestframework-jsonmask
OverviewImplements Google's Partial Response in Django RestFrameworkRequirementsPython (2.7, 3.6, 3.7)Django (1.11, 2.0, 2.1)InstallationInstall usingpip...$pipinstalldjangorestframework-jsonmaskExampleMost DRF addons that support?fields=-style data pruning do so purely at the serializaton layer. Many hydrate full ORM objects, including all of their verbose relationships, and then cut unwanted data immediately before JSON serialization. Any unwanted related data is still fetched from the database and hydrated into Django ORM objects, which severely undermines the usefulness of field pruning.rest_framework_jsonmaskaims to do one better by allowing developers to declaratively augment their queryset in direct relation to individual requests. Under this pattern, you only declare the base queryset and any universal relationships on your ViewSet.queryset, leaving all additional enhancements as runtime opt-ins.To userest_framework_jsonmask, first include its ViewSet and Serializer mixins in your code where appropriate. The following examples are taken from the mini-project used in this library's own unit tests.# api/views.pyfromrest_framework_jsonmask.viewsimportOptimizedQuerySetMixinclassTicketViewSet(OptimizedQuerySetMixin,viewsets.ReadOnlyModelViewSet):# Normally, for optimal performance, you would apply the `select_related('author')`# call to the base queryset, but that is no longer desireable for data relationships# that your frontend may stop asking for.queryset=Ticket.objects.all()serializer_class=TicketSerializer# Data-predicate declaration is optional, but encouraged. This# is where the library really shines!@data_predicate('author')defload_author(self,queryset):returnqueryset.select_related('author')# api/serializers.pyfromrest_framework_jsonmask.serializersimportFieldsListSerializerMixinclassTicketSerializer(FieldsListSerializerMixin,serializers.ModelSerializer):# Aside from the mixin, everything else is exactly like normalauthor=UserSerializer()classMeta:models=my_module.models.Ticketfields=('id','title','body','author',)You have now set up your API to skip unnecessary joins (and possibly prefetches), unless the requesting client requires that data. Let's consider a few hypothetical requests and the responses they will each receive. (For brevity, in each of these examples, I will pretend pagination is turned off.)GET /api/tickets/200 OK[{"id": 1,"title": "This is a ticket","body": "This is its text","author": {"id": 5,"username": "HomerSimpson",}}]Because no?fieldsquerystring parameter was provided, author records were still loaded and serialized like normal.Note:rest_framework_jsonmasktreats all requests that lack any field definition as if all possible data is requested, and thus executes all data predicates. In the above example,authordata was loaded viaselected_related('author'), andnotN+1 queries.GET /api/tickets/?fields=id,title,body200 OK[{"id": 1,"title": "This is a ticket","body": "This is its text"}]In this example, sinceauthorwas not specified, it was not only not returned in the response payload - it was never queried for or serialized in the first place.GET /api/tickets/?fields=id,title,body,author/username200 OK[{"id": 1,"title": "This is a ticket","body": "This is its text","author": {"username": "HomerSimpson",}}]In this example,authordata was loaded via the?fieldsdeclaration, but no unwanted keys will appear in the response.Nested RelationshipsThis is all good and fun, but what ifauthorhas rarely used but expensive relationships, too?rest_framework_jsonmasksupports this, via the exact same mechanisms spelled out above, though sometimes a little extra attention to detail can be important. Let's now imagine thatAuthorSerializerlooks like this:classAuthorSerializer(FieldsListSerializerMixin,serializers.ModelSerializer):accounts=AccountSerializer(many=True)classMeta:model=settings.AUTH_USER_MODELfields=('id','username','email','photo','accounts',...)Naturally, ifaccountsis sensitive, internal data, you simply might not usethisserializer for external API consumption. Of course, that would solve your problem about how to decide whether to serializeaccountsdata -- the supplied serializer would know nothing about that field! But, let's pretend that in our case,accountsis safe for public consumption, andsometicketing API calls require it for triaging purposes, whereas others do not. In such a situation, we'll redefine our ViewSet like so:classTicketViewSet(OptimizedQuerySetMixin,viewsets.ReadOnlyModelViewSet):queryset=Ticket.objects.all()serializer_class=TicketSerializer@data_predicate('author')defload_author(self,queryset):returnqueryset.select_related('author')# Add this extra data_predicate with prefetches `accounts` if and only if# the requests promises to use that information@data_predicate('author.accounts')defload_author_with_accounts(self,queryset):returnqueryset.select_related('author').prefetch_related('author__accounts')Now, it is up to the client to decide which of the following options (or anything else imaginable) is most appropriate:# Includes specified local fields plus all author fields and relationshipsGET /api/tickets/?fields=id,title,author200 OK[{"id": 1,"title": "This is a ticket","author": {"id": 5,"username": "HomerSimpson","accounts": [{"all_fields": "will_be_present"}]}}]or# Includes specified local fields plus specified author fields and relationshipsGET /api/tickets/?fields=id,title,author(username,photo)200 OK[{"id": 1,"title": "This is a ticket","author": {"username": "HomerSimpson","photo": "image_url"}}]or# Includes specified local fields plus specified author fields and relationships plus specified accounts fields and relationshipsGET /api/tickets/?fields=id,title,author(id,accounts(id,type_of,date))200 OK[{"id": 1,"title": "This is a ticket","author": {"id": 5,"accounts": [{"id": 8001,"type_of": "business","date": 2018-01-01T12:00:00Z"},{"id": 6500,"type_of": "trial","date": 2017-06-01T12:00:00Z"}]}}]In short, know that as long as the entire chain of Serializers implements theFieldsListSerializerMixin, arbitrarily deep nesting of?fieldsdeclarations will be honored. However, in practice, because relationships are expensive to hydrate, you will probably want to limit that information and control what data you actually load using the@data_predicatedecorator on ViewSet methods.Testing$maketestsor keep them running on change:$makewatchYou can also use the excellenttoxtesting tool to run the tests against all supported versions of Python and Django. Install tox globally, and then simply run:$toxDocumentation$makedocs