Beginning Java EE 6 with GlassFish 3, Second Edition

CHAPTER 15 ■ RESTFUL WEB SERVICEScare of it. How would you point her to the incriminating line? You could say, “Go to line 42 of the classCreditCardValidator,” or, if your source code is addressable through a repository browser, you couldsave the URI of the line itself in the bug report. This raises the issue of defining the granularity of yourRESTful resources in your application: it could be at the line, method, or class level, and so forth.Unique URIs make your resources linkable, and, because they are exposed through a uniforminterface, everyone knows exactly how to interact with them, allowing people to use your application inways you would have never imagined.ConnectednessIn graph theory, a graph is called connected if every pair of distinct vertices in the graph can beconnected through some path. It is said to be strongly connected if it contains a direct path from u to vand a direct path from v to u for every pair of vertices u,v. REST advocates that resources should be asconnected as possible. As the now famous formulation goes: “Hypermedia as the engine of applicationstate.”Once again, this daunting statement resulted from an examination of the success of the Web. Webpages embed links to navigate through pages in a logical and smooth manner and, as such, the Web isvery well connected. If there is a strong relationship between two resources, they should be connected.REST states that web services should also take advantage of hypermedia to inform the client of what isavailable and where to go. It promotes the discoverability of services. From a single URI, a user agentaccessing a well-connected web service could discover all available actions, resources, their variousrepresentations, and so forth.For instance, when a user agent looks up the representation of a CD (see Listing 15-1), thisrepresentation could have not only the names of the artist, but also a link, or a URI, to the biography. It’sup to the user agent to actually retrieve it or not. The representation could also link to otherrepresentations of the resource or available actions.Listing 15-1. A CD Representation Connected to Other ServicesElla and Louis1956Ella FitzgeraldLouis ArmstrongAnother crucial aspect of the hypermedia principle is the state of the application, which must be ledby the hypermedia. In short, the fact that the web service provides a set of links enables the client tomove the application from one state to the next by simply following a link.In the preceding XML snippet, the client could change the state of the application by commentingon the album. The list of comments on the album is a resource addressable with the URIhttp://music.com/album/789/comments. Because this web service uses a uniform interface, once theclient knows the URI format, the available content types and the data format, it will know exactly how tointeract with it: a GET will retrieve the list of existing comments, a POST will create a new comment, and so462