Skip to main content

Grouped/Nested resources for the Django Rest Framework

Project description


Sourcecode of this package is based from:

This package provides routers and fields to create grouped/nested resources in the [Django Rest Framework](

Nested resources are needed for full REST URL structure, if one resource lives inside another.
Grouped resources allow you to group multiple resource to show in a single root api view.

The following example is about Domains and DNS Nameservers.
There are many domains, and each domain has many nameservers. The "nameserver" resource does not
exist without a domain, so you need it "nested" inside the domain.


You can install this library using pip:

```pip install drf-routers```


The desired URL signatures are:
\domain\ <- Domains list
\domain\{pk}\ <- One domain, from {pk}
\domain\{domain_pk}\nameservers\ <- Nameservers of domain from {domain_pk}
\domain\{domain_pk}\nameservers\{pk} <- Specific nameserver from {pk}, of domain from {domain_pk}

How to do it (example):
from drf_routers import routers
from views import DomainViewSet, NameserverViewSet

router = routers.SimpleRouter()
router.register(r'domains', DomainViewSet)

domains_router = routers.NestedRouter(router, r'domains', lookup='domain')
domains_router.register(r'nameservers', NameserverViewSet, base_name='domain-nameservers')
# 'base_name' is optional. Needed only if the same viewset is registered more than once
# Official DRF docs on this option:

urlpatterns = patterns('',
url(r'^', include(router.urls)),
url(r'^', include(domains_router.urls)),
class NameserverViewSet(viewsets.ViewSet):
def list(self, request, domain_pk=None):
nameservers = self.queryset.filter(domain=domain_pk)
return Response([...])

def retrieve(self, request, pk=None, domain_pk=None):
nameservers = self.queryset.get(pk=pk, domain=domain_pk)
return Response(

(optional) If you need hyperlinks for nested relations, you need need a custom serializer.
# (needed only if you want hyperlinks for nested relations on API)
from drf_routers.relations import NestedHyperlinkedRelatedField

class DomainSerializer(HyperlinkedModelSerializer):
class Meta:
model = Domain

nameservers = HyperlinkedIdentityField(

## OR ##

nameservers = NestedHyperlinkedRelatedField(
read_only=True, # Or add a queryset

Example of nested router 3 levels deep. You can use this same logic to nest routers as deep as you need. This example accomplishes the below URL patterns.

router = DefaultRouter()
router.register(r'clients', ClientViewSet, base_name='clients')

client_router = routers.NestedRouter(router, r'clients', lookup='client')
client_router.register(r'maildrops', MailDropViewSet, base_name='maildrops')

maildrops_router = routers.NestedRouter(client_router, r'maildrops', lookup='maildrop')
maildrops_router.register(r'recipients', MailRecipientViewSet, base_name='recipients')

urlpatterns = patterns (
url(r'^', include(router.urls)),
url(r'^', include(client_router.urls)),
url(r'^', include(maildrops_router.urls)),

class ClientViewSet(viewsets.ViewSet):
serializer_class = ClientSerializer

def list(self, request,):
queryset = Client.objects.filter()
serializer = ClientSerializer(queryset, many=True)
return Response(

def retrieve(self, request, pk=None):
queryset = Client.objects.filter()
client = get_object_or_404(queryset, pk=pk)
serializer = ClientSerializer(client)
return Response(

class MailDropViewSet(viewsets.ViewSet):
serializer_class = MailDropSerializer

def list(self, request, client_pk=None):
queryset = MailDrop.objects.filter(client=client_pk)
serializer = MailDropSerializer(queryset, many=True)
return Response(

def retrieve(self, request, pk=None, client_pk=None):
queryset = MailDrop.objects.filter(pk=pk, client=client_pk)
maildrop = get_object_or_404(queryset, pk=pk)
serializer = MailDropSerializer(maildrop)
return Response(

class MailRecipientViewSet(viewsets.ViewSet):
serializer_class = MailRecipientSerializer

def list(self, request, client_pk=None, maildrop_pk=None):
queryset = MailRecipient.objects.filter(mail_drop__client=client_pk, mail_drop=maildrop_pk)
serializer = MailRecipientSerializer(queryset, many=True)
return Response(

def retrieve(self, request, pk=None, client_pk=None, maildrop_pk=None):
queryset = MailRecipient.objects.filter(pk=pk, mail_drop=maildrop_pk, mail_drop__client=client_pk)
maildrop = get_object_or_404(queryset, pk=pk)
serializer = MailRecipientSerializer(maildrop)
return Response(

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

drf-routers-0.2.tar.gz (11.5 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page