Organizing and consuming an API that apply HATEOAS

Question

The last year I have been working on a hobby project. I use Spring MVC (4 at the moment) and I have created a web service trying to adhere to REST principles.

I have a resource named Athlete that have relations to other resources such as SportEvent, 'Trainer` and so on.

These relations are not embedded in the athlete resource. Instead they are links. This is an example:

{
    "firstName": "James",
    "lastName":"Smith",
    "links": [{
        "rel": "trainer",
        "href" : "http://somehost.com/sport/trainers/4"
    },
    {
        "rel": "sport-events",
        "href" : "http://somehost.com/sport/athletes/4/sport-events"
    }]
}

I am currently writing the client side in AngularJS and I am going to consume this API. It was during this I discovered something that I hadn't thought through. How are the client actually going to consume this?

Let say I am building the regular detail page for a athlete. I want to show the athletes trainer as well. I have to somehow have a HTTP client library that is able to resolve the relations I want and attach the response to the "parent" resource (the one that has the relations) in a recursive manner.

How is it actually intended to navigate an API like this? You can't follow links without explicitly stating which you want to follow? Because if you don't you will end up creating potentially huge objects. You want some kind of criteriea?

I am definitly interested in how to actually consume my API (sounds weird, but I had not thought through the actual process of resolving the links dynamically). And it would be a huge bonus if I could get an explanation on how to do it in JavaScript (using a library is fine). I am using AngularJS so how to apply it there would be even better.

Answer 1

Angular-hateoas should do (most of) the job for you. However I agree with inf3rno and you should add the type to the links. So you may have to extend Angular-hateoas to handle it.

Answer 2

Yes, the client is supposed to navigate the links and retrieve whatever information it needs. There's nothing against you providing a summary resource that may have only some pieces of information needed, and the client retrieves the link for some relation when it needs more detail.

For instance, in HAL+JSON you have the _embedded property, in which you could embed a summary of the trainer, giving the bare minimum information needed about the trainer for the athlete's page.