This tutorial by Mario-Leander Reimer, the author of Building RESTful Services with Java EE 8, will show how you can traverse REST resources using hypermedia (with links and URIs).
JSON-P can be used to construct hypermedia-enabled JSON structures. You need to use the @Context and UriInfo objects to construct resource URIs programmatically. Also, this tutorial will take a look at how to set link headers with URIs on the HTTP response. The entire code for this tutorial can be found at https://github.com/PacktPublishing/Building-RESTful-Web-Services-with-Java-EE-8/tree/master/Chapter03.
To get started, switch to your IDE. Prepare a resource that will serve books and authors; both are individual REST resources. Obviously, books are written by authors, so you should be able to navigate from books to the authors and vice versa. This is where hypermedia comes into play.
Navigate to the book resource. In here, you have a method to serve a specific book. First up, obtain the book and then construct the URI for this book. createBookResourceUri is the URI used to reference this book:
| @GET | |
| @Path("/{isbn}") | |
| public Response book(@PathParam("isbn") String isbn) { | |
| Book book = books.get(isbn); | |
| URI bookUri = createBookResourceUri(isbn, uriInfo); | |
| URI authorUri = createAuthorResourceUri(book | |
| .authorId, uriInfo); | |
| return null; | |
| } |
You also need to construct the author URI for this book. If you look in here into one of those methods, you’ll see that the uriInfo object has been used and that you can obtain a base URI builder from it. You can then use the path methods to actually build the final URI. Using these path methods, you can construct the path from the @Path annotations of the resources and resource methods:
In the final result, you have a URI that references the actual resource:
Next up, create a JSON object from book from bookUri. Use JSON-P to create an object builder and add “isbn” and “title” to it. However, there’s one bit missing and that bit makes the final hypermedia-enabled JSON structure.
You need to add an additional object called “_links”, which is a JSON object, and this JSON object contains two other JSON objects, called “self” and “author”. The “self” object describes the URI of the REST resource itself, which in this case is the type of the book. Then, you need to specify “author” and give it an “href” attribute that points to authorUri:
| private JsonObject asJsonObject(Book book, URI bookUri, | |
| URI authorUri) { | |
| return Json.createObjectBuilder() | |
| .add("isbn", book.isbn) | |
| .add("title", book.title) | |
| .add("_links", Json.createObjectBuilder() | |
| .add("self", Json.createObjectBuilder() | |
| .add("href", bookUri.toString())) | |
| .add("author", Json.createObjectBuilder() | |
| .add("href", | |
| authorUri.toString()))) | |
| .build(); | |
| } |
Finally, return the JSON object, and on the response object, you can set the link HTTP headers as well so that you have two options. You can either specify the link header on the HTTP response or embed the URIs, which adds a linked JSON structure here.
You can pretty much do almost the same thing for authors; the code here is pretty much copy/paste. This follows the same procedure: get the authors and then construct the URI for the author and the books. Construct the JSON object where you’ll embed the links to “self”, which is “books” itself, and do the same for booksUri. Finally, you return the response of this JSON object and can also embed the link HTTP headers.
It’s time now to put this API to test. Open Postman and issue a GET request for the list of books. In here, you will see that the book has a title and that it also contains a list of links. For “self”, this is the book itself and for “author”, you get the author of the book, as shown in the following screenshot:
Click on the book (that is, the URI present in “self”) to get specific information about this book. As you can see, this returns a single book structure. If you want to navigate to the author, you can use the author link. Here, you have the author of this book, as shown in the following screenshot:
If you want to obtain the list of books that this author has written, you can use the “books” link, which gets all the books from this author’s ID, as shown in the preceding screenshot.
If you want to have a look at this book again, you can navigate from those two books. What you can also see here in the headers is that you have the two links for the author and the book itself:
There, you have it! If you found this tutorial helpful and want to learn more about building RESTful web services, you can explore Building RESTful Services with Java EE 8. It’s a comprehensive guide that shows you how to use the APIs provided by Java EE to create effective RESTful web services.