Skip to main content
Help us improve PyPI by participating in user testing. All experience levels needed!

Grouped/Nested resources for the Django Rest Framework

Project description

drf-routers
=====================

Sourcecode of this package is based from: https://github.com/alanjds/drf-nested-routers

This package provides routers and fields to create grouped/nested resources in the [Django Rest Framework](http://django-rest-framework.org/)

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.

Installation
------------

You can install this library using pip:

```pip install drf-routers```

Quickstart
----------

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):
```python
# urls.py
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: http://www.django-rest-framework.org/api-guide/routers/

urlpatterns = patterns('',
url(r'^', include(router.urls)),
url(r'^', include(domains_router.urls)),
)
```
```python
# views.py
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(serializer.data)
```

(optional) If you need hyperlinks for nested relations, you need need a custom serializer.
```python
# serializers.py
# (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(
view_name='domain-nameservers-list',
lookup_url_kwarg='domain_pk'
)

## OR ##

nameservers = NestedHyperlinkedRelatedField(
many=True,
read_only=True, # Or add a queryset
view_name='domain-nameservers-detail'
parent_lookup_url_kwarg='domain_pk'
)
```


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.
```
/clients/
/clients/{pk}/
/clients/{client_pk}/maildrops/
/clients/{client_pk}/maildrops/{maildrop_pk}/
/clients/{client_pk}/maildrops/{maildrop_pk}/recipients/
/clients/{client_pk}/maildrops/{maildrop_pk}/recipients/{pk}/
```

```python
# urls.py
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)),
)
```

```python
# views.py
class ClientViewSet(viewsets.ViewSet):
serializer_class = ClientSerializer

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

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

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(serializer.data)

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(serializer.data)

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(serializer.data)

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(serializer.data)
```

Project details


Release history Release notifications

This version
History Node

0.2

History Node

0.1

Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
drf-routers-0.2.tar.gz (11.5 kB) Copy SHA256 hash SHA256 Source None Jul 28, 2016

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page