Fellow RESTafarions,

WRT Paging and HATEOAS...

For me, the #2 method (placing paging in the body) is advantageous for clients as they can just marshal the document body and get at the paging information via normal ways. The other advantage is that all the state (prev and next are alternate states for page results) is contained within the body. No need for the client to look up in the header to and figure out the format to parse the object in the header (and also know the key name for the header object). This all creates unneccessary work for the client when marshalling is pretty much automatic (like with JSON and Javascript).

How parsable is this format?

Link: <http://foo/?page=3>; rel='next'
Link: <http://foo/?page=1>; rel='prev'

It looks like a combination of formats that definately requires custom parsing on the client side. I realize it is RFC 5988, but you would think they could pick a more consistent(parser friendly) format. Any idea how prevalent this is? I did a search and couldn't find much but maybe I'm not aware of the right resources. I see that it was a 'Proposed Standard' in 2010  [http://datatracker.ietf.org/doc/rfc5988/] but not much activity since then. This deserves more research time than I can give it but does raise an eyebrow.

For those not familiar with HATEOAS, here is Bill Burke's definition for java developers:
"I’ve explained HATEOAS with this analogy to Java developers. Imagine, a Java Swing app passing value objects to a remote Hibernate service and merging the changes. Instead of Java objects are your value objects, think of XML or JSON. Now add the idea of embedding links into your XML or JSON that tell you where you can edit the service that represents these value objects, or links to other services related to this data."

Leaving everything in the body also sets a better precedent for state other than paging (HATEOAS) that should go into the doc body. HATEOAS is an essential part of REST and its use should be encouraged. REST representations are meant to support alternate states and allow for easy discoverability by the client. The encapsulated states sent to the client make for less logic on the client (meaning less brittle client applicatons). For instance, encapsulated states can be sent to the client to provide state machines or validation rules and cached by the client, cutting down the number of round trips to the server.

Pragmatically, the way our REST APIs will be used is primary via CL/I(javascript) so not having to reach into the header and parse pagnation data will make much simpler/powerful integration scripts for our customers (IMO).

I do believe the header is a good place to store non-state data that is not dependent on the on the body or relates to the body. Self describing meta-data comes to mind. Perhaps a link to schema or dtd where a light weight HEAD command could be used to first retrieve the schema and then the GET to actually retrieve the payload.

FYI: some other common link relations useful in HATEOAS and promoting discoverability are:

self - URI of the resource.
alternate - URI for an alternative version of the same resource.
edit - URI that clients can use to edit the resource.
related - URI to a related resource
previous
next 
first
last 

We will probably want to add self, first and last to prev/next regardless of the outcome of where to put this data. Also useful, would be record counts and/or page counts. Record counts via HEAD could provide client with insight as to whether or not they should retrieve resources via a GET.

Lastly, I add this in more for its humor value (since Roy is the REST creator):

"If the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that needs to be fixed?"
-- Roy Fielding
"REST APIs must be hypertext-driven"

Fowler's Richardson Maturity Model for REST
http://martinfowler.com/articles/richardsonMaturityModel.html

Another good article by Subbu Allamaraju on explaining state in HATEOAS: http://www.subbu.org/blog/2008/10/explaining-state-in-hateoas
The aricle boils down to essentially this example:
"There are three pages in a UI. The first page has a link to go to the second page. The second page has a link to go to the previous page as well as the third page. The third has a link to the second page and another link to the first page.
A client starts from the first page, and then through the link on that page, goes to the second page. The fact that this page has one link to the first page and another to the third page implies that the current state of the application (i.e. the interactions) is that "the client is viewing the second page". That is what it means by hypermedia as the engine of application state. It does not necessarily mean serializing application state, such as "<page>2</page>" into representations."

My Two cents,
-- Mike

On Feb 19, 2013, at 2:35 AM, Heiko W.Rupp <hrupp@redhat.com> wrote:

Hi,

as I am implementing paging through (large) collections - e.g. lists of resources,
I am investigating options. For this I have written a blog post at
http://pilhuhn.blogspot.com/2013/02/best-practice-for-paging-in-restful-apis.html

My current tendency is to support the "Link: header" style and possibly
with the multiple Link: headers style


--
Reg. Adresse: Red Hat GmbH, Technopark II, Haus C,
Werner-von-Siemens-Ring 14, D-85630 Grasbrunn
Handelsregister: Amtsgericht München HRB 153243
Geschaeftsführer:  Mark Hegarty, Charlie Peters, Michael Cunningham, Charles Cachera

_______________________________________________
rhq-devel mailing list
rhq-devel@lists.fedorahosted.org
https://lists.fedorahosted.org/mailman/listinfo/rhq-devel