drf-routers 0.2

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)
```