Rest and HATEOAS

So, we’re going to use json for HATEOAS REST, but we have to decide what to do with collections on our objects first.

Problem: In a very popular online school system, I have a Course object that has a collection of Students who are/have attended. Typically there are a lot of students for one course (maybe millions). How is this represented in HATEOAS?

We don’t really want to embed the student collection in the course object. If we did that then we’d have a number of problems. First, the user may not be interested in that information, but we’ve just forced them to pay for downloading it. Second, the list is long, and will take a long time to transfer. Third, the app/page displaying the course object will have to know how to deal with students too, because they’re embedded in the course.

Rather than embed the collection we should instead include a link to the collection which the client can then present to the user and allow them to choose if they want to see any of that information. The HTML protocol  solves this by having a header section in the server’s responses that may include a list of links. HATEOAS suggests that we should copy the html protocol’s approach, but we can’t really do that because there isn’t a hateoas json standard — a json object represents a resource on the server and doesn’t have a header or links section.

Spring Data Rest has implemented Atom+RSS patterns in their json responses, so that there is a list of links in the json object that represents the requested resource. But, this really is an arbitrary choice. I think that I could design a much better links protocol for json myself — something tidier and simpler and easier, but it wouldn’t matter if I did because it’s still a solution that I’m writing myself and which won’t be interoperable with any other solutions. This means that we can’t yet write a generic json/rest/hateoas client that will work for all possible  services. We need a standard for this.

Personally, I think that the json response sent by the server should be wrapped in a response json wrapper that contains a header and body section, just like html, and the header should include links to javascript, css, and collections. That way, if I request a resource, my client can simply pull the code necessary to render it.

Now, if the code (javascript) to render an object were also standardized, so that it always displays in the given div, and the css were standardized in such a way that the given renderer is guaranteed not to draw outside the given container, then we’d have a way of accessing and viewing arbitrary resources without having prior knowledge of what they are, where they are, and how they work. Unfortunately, until we have these standards we’re left floundering around creating our own point solutions.

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s