- Memory consumption in server and client
- Bandwidth need to transfer the data.
- Latency to transfer huge amounts of data over slow networks
Inside RHQ we have the concept of a
PageList<?>where an internal
PageControlobject defines the page size and other criteria like sorting. The
PageListthen only contains the objects from a certain page. I think this is a pretty common setup.
And here is where my question comes:
What is the "best-practice" to represent such a
PageListin a RESTful api? So far I have seen two major ways:
- Add a
Link:header that contains the
nextrelations. This is what RFC 5988 suggests and what projects like AeroGear use. The advantage here is that the body still contains the "raw" data and not meta data. And for both cases of 'single' object and 'collection' the data is at the 'root' of the body. Also paging is available for HEAD requests.
- Put the
nextrelations in the body of the request next to the collection. This has the advantage that there is no need to parse the http header. Disadvantage is that the real payload is now shifted "one level down" for collections.
I sort of see the paging links as meta-data and think that this should not be mixed with the payload. Now a colleague of mine said: "Isn't that a state change link for the collection like the 'rel=edit' for a single object?". This sounds odd, but can't be denied.
Just to be clear: I am explicitly talking about paging of collections and not about affordances of individual objects.
So are there established best practices? How do others do it?
If going for the
Link:header: would people rather like to see multiple Link headers (see RFC 2616), one for each relation:
Link: <http://foo/?page=3>; rel='next'
Link: <http://foo/?page=1>; rel='prev'
or rather the combined way:
Link: <http://foo/?page=3>; rel='next', Link: <http://foo/?page=1>; rel='prev'
that is listed in RFC 5988?
I just saw that URLConnection.getHeaderField(name) does not support the multiple
Link:headers as it only returns the last occurrence:
If called on a connection that sets the same header multiple times with possibly different values, only the last value is returned.
While there may be other ways to access all the
Link:headers, this is a too obvious pitfall, that can be prevented by not using that style.