Add option to specify default included resources

[knaperek]

Let's provide an extra JSONAPIMeta configuration option that specifies
resources to be listed in the 'included' section of the response.

These resources shall be included even if they're not explicitly mentioned
in the 'include' request parameter.

[jerel]

I don't believe this will result in behavior compliant with the spec. The spec states that "If an endpoint supports the include parameter and a client supplies it, the server MUST NOT include unrequested resource objects in the included section". So we should build included_resources from JSONAPIMeta.included_resources for a default but if include exists in the url then its value should be used instead.

[knaperek]

Thanks. fixed.

[scottfisk]

So you are implementing this MAY functionality from JSON api spec? That sounds good to me. 👍

Seems like we have a couple options for configuring it:

1. Using the JSONAPIMeta on serializer (like you have done here)
2. Define something in the included dictionary for that field like include_by_default=True
3. More implicitly include it like the default drf style where full objects are included if you define the field as a nested serializer.

@jerel Might have opinions on this, I am leaning towards 1 or 2. (2 might fit the existing implementation of includes better, idk)

[jerel]

Now that you mention option 2 that sounds slightly superior to adding included_resources to JSONAPIMeta because it's right at the point where the relationship is defined. Off the top of my head I'm not sure how painful/easy it would be to implement. Are there any downsides to include_by_default=True?

[knaperek]

Maybe one downside: you'd have to declare the field manually, unlike in the case of the solution I initially propose, which is coherent with many Django settings in Admin, for example, when you list fields that are to be included on various places (list_display, readonly_fields, list_editable, list_filter, search_fields, radio_fields, etc...).

[knaperek]

Another argument supporting the solution number 1 is this:
Let's say we have 3 models with their relation like this:
Comment -> Post -> User

We have defined serializers for all of them and want the root serializer (the UserSerializer) to automatically include its related resources. If we only wanted to inlcude the posts, both number 1 and 2 solutions could be seen as fit.

What if we also wanted to include all the related comments though (second level depth)? In that case I think it's much nicer to use the number 1 approach and define the UserSerializer class like this:

class UserSerializer(serializers.Serializer):
    name = serializers.CharField(max_length=200)
    posts = PostSerializer(many=True, read_only=True)

    class JSONAPIMeta:
        resource_name = 'user'
        included_resources = ['posts.comments']

[jerel]

I think that going with included_resources in JSONAPIMeta is probably the best route. @knaperek are you ready for this to be merged then? We should have some test coverage on this feature yet.

[knaperek]

Some tests added, waiting for merge. Thanks.

[scottfisk]

I wanted to make sure the include param should override the defaults, which is how you implemented it here.

If an endpoint supports the include parameter and a client supplies it, the server MUST NOT include unrequested resource objects in the included section of the compound document.

👍 , looks like this is all good.

[scottfisk]

lgtm 👍