How can I paginate included resources?

[esmail]

Per the spec., this is supposed to be possible:

...To paginate an included collection returned in a compound document, supply pagination links in the corresponding links object.
https://jsonapi.org/format/#fetching-pagination

But they don't mention a queryparam I could try out, and I didn't notice any mention of included resource pagination in the docs. for this project.

[sliverc]

It is currently only possible to do pagination on top level resources in DJA but not the included collection.

The specification states any pagination to be optional so if we wanted this to be added as a feature in DJA we should discuss actual use cases which such pagination would cover and then how to technically implement it.

A server MAY choose to limit the number of resources returned in a response to a subset (“page”) of the whole set available.

My first thought is that such a pagination is fairly limited as included collections can be a collection of different types. I haven't tested this but you could have related urls links which then allow you to paginate. This way your client can choose specifically what relationship needs to be paginated.

Just some thoughts. It would be great to hear what you actual use case is for such a feature and whether the above would cover it.

[esmail]

Thanks for the response. A simplified version of my use case that should still capture the important aspects is an endpoint providing grade data for per school semester in which more student-level data is available than the consuming client can receive at once. The criteria in their current form are along the lines of the following:

1. The object types in question are Semester (desired top level), StudentGroup (included), and Student (nested include with pagination desired)
2. The relationship between Semester and StudentGroup is one to many (student groups are particular to a semester), and the relationship between StudentGroup and Student is many to many. Consequently, the indirect relationship between Semester and Student (through StudentGroup) is also many to many (e.g. a student might've been a part of multiple semesters
3. A list/detail endpoint pair is wanted for Semester
4. The detail endpoint is meant to show aggregate data at the semester level (e.g. the average numerical grade across all students in the semester), aggregate data at the student group level, and individual grade data at the student level
5. The individual student grade data is specific to the context of the given semester (e.g. their grade average for the semester)
6. The consuming client is limited in how much data it can take in at once, so pagination at the student level is desired

[esmail]

I'm curious to hear any thoughts on how this might be implemented in a custom pagination class (if possible) or otherwise.

[sliverc]

Sorry for my late response. Finally have some time to respond.

Thanks for your example. Can you elaborate what the exact limitation the client has and why? To have proper pagination you would need a predictable order. The issue is that in JSON:API spec an included item must not be added twice. So if you paginate through the groups and the students at some point a student would simply be missing as already retrieved in an earlier page.

In your specific mentioned case I would design the API the way that the client gets semester with semester group included. Then it calls student with a filter of all student groups retrieved and then can easily paginate through the students. Just a thought to think about (maybe you already do it this way).

In terms of custom pagination class. Pagination class is a DRF feature and only has access to the main resources. The included resources are only extracted in the rest_framework_json_api.renderers.JSONRenderer class. You could make a custom renderer and overwrite the method extract_included.