A common requirement for resources which return large collections of records is paging. Paging can be implemented in many different ways. See the following pages as an entry point to the discussion:
In the following sections I will introduce three different solutions. All of them are implemented in Taoki - a small extension for Restlet.
Template Parameter
This implementation uses parts of the url to carry the paging information:
GET /books
GET /books/0/50
GET /books/0/50/author/asc
The advantage of this implementation is that the resource can be cached by proxies. The drawback is that a lot of template parameters are “wasted”. For example /books/report/{quarter} won’t be available as route, since it is occupied by /books/{offset}/{pageSize}
Query Parameter
This implementation uses query parameter.
GET /books
GET /books?offset=0&limit=50
GET /books?offset=0&limit=50&sortField=author&sortDir=asc
Most proxies won’t cache resources which include parameters, but there are no template parameters wasted.
Custom Header
This implementation uses the custom header Item-Range.
GET /books
GET /books
Item-Range: items=0-49
GET /books
Item-Range: items=0-49;author:desc
It combines the advantages of the other two implementations. A minor drawback of this solution is that the paging information is no longer visible in the URL.