Pagination support by headers

[ekohl]

I dislike that the output of my API changes when I enable pagination. HTTP provides Range and Accept-Ranges headers for this, as documented on https://restful-api-design.readthedocs.org/en/latest/methods.html#ranges-pagination. I'm willing to provide some patches to change this behaviour, but that would mean an API change for users. Before I start I would like some opinion about this.

[tomchristie]

Supporting range headers as an option out-of-the-box seems like a good idea, yes.

It could become the default at some point in the future, but I don't think that'd happen straight away - I'm not sure there's enough consensus around pagination styles in APIs to merit that just yet.

A good place to start might be to ensure that when DEFAULT_PAGINATION_SERIALIZER_CLASS is None, but PAGINATE_BY is an integer value, that pagination is used, but that the serialization style does not change. After that we could look at how we deal with the headers.

[rhunwicks]

The Dojo JavaScript toolkit uses a similar approach in its dojo/store/JsonRest class (and earlier versions like dojo.data.JsonRestStore). It would be very useful (to me at least :-)) if any change supported Dojo through configuration rather than sub-classing. I recognize that providing compatibility with specific clients isn't in the design goals, but it would be good if any enhancement made it easier to support a range of clients. Clients that want to use a Range header or similar will need to:

• Specify items by start and end resource rather than by page
• Possibly want to know the total number of resources available
• Possibly want previous and next ranges available using headers or similar.

For Dojo, the client requests a subset of resources using a Range header: Range: items=0-24. This similar to the example at https://restful-api-design.readthedocs.org/en/latest/methods.html#ranges-pagination but uses the items range unit instead of resource.

The client expects the response to indicate which records were returned, and how many are available, using a Content-Range header: Content-Range: items 0-24/66

I calculate this total by executing queryset.count() against the queryset inside the list(). Note that http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html says that it is OK to return Content-Range: items 0-24/* - i.e. to use * if the total is expensive to calculate.

See http://dojotoolkit.org/reference-guide/1.9/dojo/store/JsonRest.html#paging for the full details if interested.

[tomchristie]

Superseeded by #1169