Complete support for compound documents

docs/usage.md

@@ -4,6 +4,10 @@
 The DJA package implements a custom renderer, parser, exception handler, and
 pagination. To get started enable the pieces in `settings.py` that you want to use.
 
+Many features of the JSON:API format standard have been implemented using Mixin classes in `serializers.py`. 
+The easiest way to make use of those features is to import ModelSerializer variants 
+from `rest_framework_json_api` instead of the usual `rest_framework`
+
 ### Configuration
 We suggest that you simply copy the settings block below and modify it if necessary.
 ``` python

rest_framework_json_api/renderers.py

@@ -67,6 +67,12 @@ def render(self, data, accepted_media_type=None, renderer_context=None):
                 {resource_name: data}, accepted_media_type, renderer_context
             )
 
+        include_resources_param = request.query_params.get('include') if request else None
+        if include_resources_param:
+            included_resources = include_resources_param.split(',')
+        else:
+            included_resources = list()
+
         json_api_included = list()
 
         if view and hasattr(view, 'action') and view.action == 'list' and \
@@ -88,7 +94,7 @@ def render(self, data, accepted_media_type=None, renderer_context=None):
                 resource_instance = resource_serializer.instance[position]  # Get current instance
                 json_api_data.append(
                     utils.build_json_resource_obj(fields, resource, resource_instance, resource_name))
-                included = utils.extract_included(fields, resource, resource_instance)
+                included = utils.extract_included(fields, resource, resource_instance, included_resources)
                 if included:
                     json_api_included.extend(included)
         else:
@@ -97,7 +103,7 @@ def render(self, data, accepted_media_type=None, renderer_context=None):
                 fields = utils.get_serializer_fields(data.serializer)
                 resource_instance = data.serializer.instance
                 json_api_data = utils.build_json_resource_obj(fields, data, resource_instance, resource_name)
-                included = utils.extract_included(fields, data, resource_instance)
+                included = utils.extract_included(fields, data, resource_instance, included_resources)
                 if included:
                     json_api_included.extend(included)
             else:

rest_framework_json_api/serializers.py

@@ -1,4 +1,5 @@
 from django.utils.translation import ugettext_lazy as _
+from rest_framework.exceptions import ParseError
 from rest_framework.serializers import *
 
 from rest_framework_json_api.utils import format_relation_name, get_resource_type_from_instance, \
@@ -58,13 +59,78 @@ def __init__(self, *args, **kwargs):
         super(SparseFieldsetsMixin, self).__init__(*args, **kwargs)
 
 
-class HyperlinkedModelSerializer(SparseFieldsetsMixin, HyperlinkedModelSerializer):
+class IncludedResourcesValidationMixin(object):
+    def __init__(self, *args, **kwargs):
+        context = kwargs.get('context')
+        request = context.get('request') if context else None
+        view = context.get('view') if context else None
+
+        def validate_path(serializer_class, field_path, serializers, path):
+            serializers = {
+                key: serializer_class if serializer == 'self' else serializer
+                for key, serializer in serializers.items()
+                } if serializers else dict()
+            if serializers is None:
+                raise ParseError('This endpoint does not support the include parameter')
+            this_field_name = field_path[0]
+            this_included_serializer = serializers.get(this_field_name)
+            if this_included_serializer is None:
+                raise ParseError(
+                    'This endpoint does not support the include parameter for path {}'.format(
+                        path
+                    )
+                )
+            if len(field_path) > 1:
+                new_included_field_path = field_path[-1:]
+                # We go down one level in the path
+                validate_path(this_included_serializer, new_included_field_path, serializers, path)
+
+        if request and view:
+            include_resources_param = request.query_params.get('include') if request else None
+            if include_resources_param:
+                included_resources = include_resources_param.split(',')
+                for included_field_name in included_resources:
+                    included_field_path = included_field_name.split('.')
+                    this_serializer_class = view.serializer_class
+                    included_serializers = getattr(this_serializer_class, 'included_serializers', None)
+                    # lets validate the current path
+                    validate_path(this_serializer_class, included_field_path, included_serializers, included_field_name)
+
+        super(IncludedResourcesValidationMixin, self).__init__(*args, **kwargs)
+
+
+class HyperlinkedModelSerializer(IncludedResourcesValidationMixin, SparseFieldsetsMixin, HyperlinkedModelSerializer):
     """
     A type of `ModelSerializer` that uses hyperlinked relationships instead
     of primary key relationships. Specifically:
 
     * A 'url' field is included instead of the 'id' field.
     * Relationships to other instances are hyperlinks, instead of primary keys.
 
+    Included Mixins:
+    * A mixin class to enable sparse fieldsets is included
+    * A mixin class to enable validation of included resources is included
+    """
+
+
+class ModelSerializer(IncludedResourcesValidationMixin, SparseFieldsetsMixin, ModelSerializer):
+    """
+    A `ModelSerializer` is just a regular `Serializer`, except that:
+
+    * A set of default fields are automatically populated.
+    * A set of default validators are automatically populated.
+    * Default `.create()` and `.update()` implementations are provided.
+
+    The process of automatically determining a set of serializer fields
+    based on the model fields is reasonably complex, but you almost certainly
+    don't need to dig into the implementation.
+
+    If the `ModelSerializer` class *doesn't* generate the set of fields that
+    you need you should either declare the extra/differing fields explicitly on
+    the serializer class, or simply use a `Serializer` class.
+
+
+    Included Mixins:
     * A mixin class to enable sparse fieldsets is included
+    * A mixin class to enable validation of included resources is included
     """

rest_framework_json_api/utils.py

@@ -11,7 +11,6 @@
 from rest_framework.settings import api_settings
 from rest_framework.exceptions import APIException
 
-
 try:
     from rest_framework.compat import OrderedDict
 except ImportError:
@@ -190,7 +189,6 @@ def get_related_resource_type(relation):
 
 
 def get_instance_or_manager_resource_type(resource_instance_or_manager):
-
     if hasattr(resource_instance_or_manager, 'model'):
         return get_resource_type_from_manager(resource_instance_or_manager)
     if hasattr(resource_instance_or_manager, '_meta'):
@@ -395,19 +393,45 @@ def extract_relationships(fields, resource, resource_instance):
     return format_keys(data)
 
 
-def extract_included(fields, resource, resource_instance):
+def extract_included(fields, resource, resource_instance, included_resources):
     included_data = list()
+
+    current_serializer = fields.serializer
+    context = current_serializer.context
+    included_serializers = getattr(fields.serializer, 'included_serializers', None)
+
+    included_serializers = {
+        key: current_serializer.__class__ if serializer == 'self' else serializer
+        for key, serializer in included_serializers.items()
+        } if included_serializers else dict()
+
     for field_name, field in six.iteritems(fields):
         # Skip URL field
         if field_name == api_settings.URL_FIELD_NAME:
             continue
 
-        # Skip fields without serialized data
-        if not isinstance(field, BaseSerializer):
+        # Skip fields without relations or serialized data
+        if not isinstance(field, (RelatedField, ManyRelatedField, BaseSerializer)):
             continue
 
-        relation_instance_or_manager = getattr(resource_instance, field_name)
-        serializer_data = resource.get(field_name)
+        try:
+            included_resources.remove(field_name)
+            relation_instance_or_manager = getattr(resource_instance, field_name)
+            serializer_data = resource.get(field_name)
+            new_included_resources = [key.replace('%s.' % field_name, '', 1) for key in included_resources]
+        except ValueError:
+            # Skip fields not in requested included resources
+            continue
+
+        if isinstance(field, ManyRelatedField):
+            serializer_class = included_serializers.get(field_name)
+            field = serializer_class(relation_instance_or_manager.all(), many=True, context=context)
+            serializer_data = field.data
+
+        if isinstance(field, RelatedField):
+            serializer_class = included_serializers.get(field_name)
+            field = serializer_class(relation_instance_or_manager, context=context)
+            serializer_data = field.data
 
         if isinstance(field, ListSerializer):
             serializer = field.child
@@ -426,6 +450,11 @@ def extract_included(fields, resource, resource_instance):
                             serializer_fields, serializer_resource, nested_resource_instance, relation_type
                         )
                     )
+                    included_data.extend(
+                        extract_included(
+                            serializer_fields, serializer_resource, nested_resource_instance, new_included_resources
+                        )
+                    )
 
         if isinstance(field, ModelSerializer):
             model = field.Meta.model
@@ -435,7 +464,13 @@ def extract_included(fields, resource, resource_instance):
             serializer_fields = get_serializer_fields(field)
             if serializer_data:
                 included_data.append(
-                    build_json_resource_obj(serializer_fields, serializer_data, relation_instance_or_manager, relation_type)
+                    build_json_resource_obj(serializer_fields, serializer_data, relation_instance_or_manager,
+                                            relation_type)
+                )
+                included_data.extend(
+                    extract_included(
+                        serializer_fields, serializer_data, relation_instance_or_manager, new_included_resources
+                    )
                 )
 
     return format_keys(included_data)