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.