Please take a look at my fork at http://bitbucket.org/joeb/django-piston/. I'm extending RFC 2616 sec. 14.35 to add a "records" range unit. Test cases are provided. To try it, add a request header in the form "Range: records=start-end" where start and end are in the naturals. The response will be a 206 with the Content-Range header set. An unparseable header will result in a 400 response, and an unsatifiable request will result in a 416. To experiment with the blog application, try:
I welcome comments and suggestions. I'm seriously considering adding request parameters support for ease of use when setting headers is more cumbersome, e.g., modifying the underlying XHR in jQuery, but I hesitate for two reasons:
The spec is designed to allow extension via range-units, so I feel this is in line with the design intention.
I don't want to worry about possibly interfering with existing applications' request namespaces, i.e., parameter name collisions.
My gripe is also with your second point, specifying this in the clients (setting headers is cumbersome.)
I'm not entirely sure how we can get around that. The other pagination fork uses GET parameters to specify beginning/count, but that pollutes the namespace, like you said.
Hm. Just a random idea: What if we had a configuration parameter, a two-tuple, containing the names of said GET parameters? E.g. PISTON_PAGINATION_PARAMS = ('start', 'count') by default, so that ?start=0&count=20 would translate into Range: records=0-20? It would still piggyback on your implementation, getting all the HTTP conforming goodies (416 etc.).
I don't know. I think we need to standardize pagination in Piston in a way that extends beyond the headers. As long as it's properly documented and configurable, I think we can get away with something like the above.
Done with a basic implementation. Add ?offset=n&limit=m to your query string. You can override the parameters in settings.py per your example, e.g.. PISTON_PAGINATION_PARAMS = ('start', 'count'). The nuances of the parameters are documented in the code and demonstrated in the test cases.
I suspect params support will be most useful in ajax contexts, so I think it's probably best to return 200 instead of 206 to support tools that only accept 200 as success. Also, I have the frequent need to consume my services with data-aware toolkits like YUI and Ext, so I intend to create specialized JSON emitters that construct the expected schemas out of the box.