Getting more properties through Spring HATEOAS

HATEOAS is a standard (though they use the word constraint) on a REST-based architecture. The idea is that the client can find out about everything via hyperlinks in the responses. Spring has a good overview on it and how it works. And, naturally, Spring has some excellent support for it. Make an interface, slap an annotation on it, and you are good to go. With Spring Boot and Spring Data JPA it really is that easy.

But say you want to add a bit more information in your response. Maybe you want to include the ID of the joined entities in the entity you are serving up. By default, it will only have a link to it, which you then have to make a client call to get, and then another call to see the whole thing.

I have set up a simple Spring Boot app that has some quotes in it. By default, by just going to http://localhost:8080/quotes/ I get the following in the response

  {

  {
    <span class="st">"_embedded"</span> : {
      <span class="st">"quotes"</span> : [ {
        <span class="st">"text"</span> : <span class="st">"Join Us Now And Share The Software"</span>,
        <span class="st">"_links"</span> : {
          <span class="st">"self"</span> : {
            <span class="st">"href"</span> : <span class="st">"http://localhost:8080/quotes/1"</span>
          },
          <span class="st">"quote"</span> : {
            <span class="st">"href"</span> : <span class="st">"http://localhost:8080/quotes/1"</span>
          },
          <span class="st">"author"</span> : {
            <span class="st">"href"</span> : <span class="st">"http://localhost:8080/quotes/1/author"</span>
          }
        }
      },
  .....
  }

Hey I get all my data in a response with just an annotation! That’s pretty cool. But note that it has just the text field in it. I don’t have any information about the author except where to go to find more information about it. That is HATEOAS.

If I follow http://localhost:8080/quotes/1/author I get the this:

  {
    <span class="st">"firstName"</span> : <span class="st">"Richard"</span>,
    <span class="st">"lastName"</span> : <span class="st">"Stallman"</span>,
    <span class="st">"_links"</span> : {
      <span class="st">"self"</span> : {
        <span class="st">"href"</span> : <span class="st">"http://localhost:8080/authors/1"</span>
      },
      <span class="st">"author"</span> : {
        <span class="st">"href"</span> : <span class="st">"http://localhost:8080/authors/1"</span>
      }
    }
  }

And there is the author information, including more of where to go for more information, as well the canonical URL (which is what self contains).

This is fine for a single quote but what if you were listing out each quote at http://localhost:8080/quotes ? If you have a 100 quotes in there, you would have to make a 101 requests to the server to get the author information. Isn’t there a way we can get all that information in one request? Yes there is, using Projections.

Projections are documented fairly well in the Spring HATEOAS documentation, but I had to connect the dots to see how this would help me. The implementation is fairly straightforward. Essentially you make an interface with some annotations and one or more getter methods. See the following:

This says: “Make a projection on the class, and combine the author’s first and last names and call it”

  <span class="fu">@Projection</span>(name = <span class="st">"AuthorNames"</span>, types = {Quote.<span class="fu">class</span>})
  <span class="kw">public</span> <span class="kw">interface</span> QuoteProjection {

      <span class="fu">@Value</span>(<span class="st">"#{target.author.firstName} #{target.author.lastName}"</span>)
      <span class="kw">public</span> String <span class="fu">getAuthorName</span>();

  }

Now we see the in the JSON

  {
        <span class="st">"authorName"</span> : <span class="st">"Richard Stallman"</span>,
        <span class="st">"_links"</span> : {
          <span class="st">"self"</span> : {
            <span class="st">"href"</span> : <span class="st">"http://localhost:8080/quotes/1"</span>
          },
          <span class="st">"quote"</span> : {
            <span class="st">"href"</span> : <span class="st">"http://localhost:8080/quotes/1{?projection}"</span>,
            <span class="st">"templated"</span> : <span class="kw">true</span>
          },
          <span class="st">"author"</span> : {
            <span class="st">"href"</span> : <span class="st">"http://localhost:8080/quotes/1/author"</span>
          }
        }

But wait!  We are missing the text field from the object itself! Well it seems we have to add it to our Projection interface:

  <span class="fu">@Projection</span>(name = <span class="st">"AuthorNames"</span>, types = {Quote.<span class="fu">class</span>})
  <span class="kw">public</span> <span class="kw">interface</span> QuoteProjection {

      <span class="fu">@Value</span>(<span class="st">"#{target.author.firstName} #{target.author.lastName}"</span>)
      <span class="kw">public</span> String <span class="fu">getAuthorName</span>();

      <span class="fu">@Value</span>(<span class="st">"#{target.text}"</span>)
      <span class="kw">public</span> String <span class="fu">getText</span>();

  }

And now we can see both properties at http://localhost:8080/quotes/

  {
     <span class="st">"text"</span> : <span class="st">"Join Us Now And Share The Software"</span>,
     <span class="st">"authorName"</span> : <span class="st">"Richard Stallman"</span>,
     <span class="st">"_links"</span> : {
       <span class="st">"self"</span> : {
         <span class="st">"href"</span> : <span class="st">"http://localhost:8080/quotes/1"</span>
       },
       <span class="st">"quote"</span> : {
         <span class="st">"href"</span> : <span class="st">"http://localhost:8080/quotes/1{?projection}"</span>,
         <span class="st">"templated"</span> : <span class="kw">true</span>
       },
       <span class="st">"author"</span> : {
         <span class="st">"href"</span> : <span class="dt">http</span>:<span class="co">//localhost:8080/quotes/1/author</span>
       }

     }
   },

So it’s fairly easy to put more properties in your JSON responses when you are using Spring HATEOAS. You can see my little quotes project at https://github.com/squarepegsys/spring-hateoas-quotes .

About the Author

Object Partners profile.

One thought on “Getting more properties through Spring HATEOAS

  1. Jesse says:

    Very useful thing to know. Thanks for the information!

Leave a Reply

Your email address will not be published.

Related Blog Posts
Building Better Data Visualization Experiences: Part 1 of 2
Through direct experience with data scientists, business analysts, lab technicians, as well as other UX professionals, I have found that we need a better understanding of the people who will be using our data visualization products in order to build them. Creating a product utilizing data with the goal of providing insight is fundamentally different from a typical user-centric web experience, although traditional UX process methods can help.
Kafka Schema Evolution With Java Spring Boot and Protobuf
In this blog I will be demonstrating Kafka schema evolution with Java, Spring Boot and Protobuf.  This app is for tutorial purposes, so there will be instances where a refactor could happen. I tried to […]
Redis Bitmaps: Storing state in small places
Redis is a popular open source in-memory data store that supports all kinds of abstract data structures. In this post and in an accompanying example Java project, I am going to explore two great use […]
Let’s build a WordPress & Kernel updated AMI with Packer
First, let’s start with What is an AMI? An Amazon Machine Image (AMI) is a master image for the creation of virtual servers in an AWS environment. The machine images are like templates that are configured with […]