How to access one element of a REST collection through HATEOAS links? - spring

Question

I'm trying to build an architecture of RESTful services, and to build a gateway service for all of those, with Java Spring. In order to make the latter, I need to implement a client for the other services, which me and my colleagues tried to design around the HATEOAS principle, by providing links to related resources through spring-hateoas module.
Let's say I have a service running on localhost, listening on 8080 port, which returns a collection of resources with a GET operation on /resources. For example:
{
"_embedded" : {
"resources" : [ {
"label" : "My first resource!",
"resourceId" : 3,
"_links" : {
"self" : {
"href" : "http://localhost:8080/resources/3"
},
"meals" : {
"href" : "http://localhost:8080/resources",
"templated" : true
}
}
}, {
"label" : "Another resource!",
"resourceId" : 4,
"_links" : {
"self" : {
"href" : "http://localhost:8080/resources/4"
},
"meals" : {
"href" : "http://localhost:8080/resources",
"templated" : true
}
}
} ]
},
"_links" : {
"self" : {
"href" : "http://localhost:8080/resources",
"templated" : true
}
}
}
I'm trying to use a HATEOAS client such as Traverson. How could I follow a resource element simply by following HATEOAS links? My solution so far has been to add a link to item on my collection, such as follow:
"_links" : {
"self" : {
"href" : "http://localhost:8080/resources",
"templated" : true
},
"item" : {
"href" : "http://localhost:8080/resources/{id}",
"templated" : true
}
}
So then I can replace the id directly in the template with Traverson and follow the result. But is it a good practice? Should I proceed another way?

Answer 1

Simply put, Traverson is meant to find a link.
In the simplest cases, each link has a unique name (rel). By simply providing the name of the rel to Traverson's follow(...) function, it will use the proper LinkDiscoverer and navigate to the corresponding URI of that rel.
This is a Hop.
Since the goal is to navigate the API kind of like following links on a webpage, you must define a chain of hops.
In your case, it's a little more complication, since you have an embedded with multiple items. Asking for the self link isn't straightforward, since you can easily see three on the root document.
Hence Traverson's support for JSON-Path. If you check the reference documentation, it's easy to see that a JSON-Path expression can be supplied to help pick which link you want.
As long as the attribute being selected is the URI, then Traverson will "hop" to it.
NOTE: When simply using rels, you can supply multiple rels as strings in follow(...). When using anything else, like a JSON-Path expression or rel(...), then use one follow(...) per hop. Thankfully, this isn't hard to read of you put each hop on a separate line (again, see ref docs for examples).