RESTful web services - Making Java Groovy - page 325

{
"id": "771190753",
"title": "Star Trek Into Darkness",
"year": 2013,
...,
"synopsis": "The Star Trek franchise continues ...",
...,
"links": {
"self": "http://api.rottentomatoes.com/.../771190753.json",
"cast": "http://api.rottentomatoes.com/.../771190753/cast.json",
"clips": "http://api.rottentomatoes.com/.../771190753/clips.json",
"reviews": "http://api.rottentomatoes.com/.../771190753/reviews.json",
"similar": "http://api.rottentomatoes.com/.../771190753/similar.json"
}
}
The movie object (a resource using a JSON representation) includes an entry called
links , which itself is a map of keys and values. The keys in the links objects all point
to additional resources, such as a full cast listing or reviews.
The Rotten Tomatoes service adds links to the individual resources rather than appending
them to the response headers. The site uses its own format rather than some other stand-
ard. [ 19 ] It also handles content negotiation by embedding the “.json” string in the URL it-
self.
19 Attempts at standardizing JSON links include www.subbu.org/blog/2008/10/generalized-linking and
www.mnot.net/blog/2011/11/25/linking_in_json .
The client, of course, needs to know all of that, but by including a links section in the re-
sponse the server is identifying exactly what's expected next. The client can simply present
those links to the user, or it can try to place them in context, which requires additional un-
derstanding.
Generating a good client for a hypermedia-based RESTful service is not a trivial task.
Notice one interesting point: the entire API uses JSON to express the objects. So far in this
chapter I've used the term resource to represent not only the server-side object exposed to
the client, but also how it's expressed. Formally, the term representation is used to describe
the form of the resource.