HATEOAS-enabled Spring Boot microservice

In the next example, Spring Initializr will be used to create a Spring Boot project. Spring Initializr is a drop-in replacement for the STS project wizard, and provides a web UI for configuring and generating a Spring Boot project. One of the advantages of the Spring Initializr is that it can generate a project through the website, which can then be imported into any IDE.

In this example, the concept of HyperMedia As The Engine Of Application State (HATEOAS) for REST-based services and the Hypertext Application Language (HAL) browser will be examined.

HATEOAS is useful for building conversational style microservices which exhibit strong affinity between UI and its backend services.

HATEOAS is a REST service pattern in which navigation links are provided as part of the payload metadata. The client application determines the state, and follows the transition URLs provided as part of the state. This methodology is particularly useful in responsive mobile and web applications where the client downloads additional data based on user navigation patterns.

The HAL browser is a handy API browser for hal+json data. HAL is a format based on JSON, which establishes conventions for representing hyperlinks between resources. HAL helps APIs to be more explorable and discoverable.

Here are the concrete steps for developing a HATEOAS sample using Spring Initilizr:

1. In order to use Spring Initilizr, go to https://start.spring.io:

1. Fill the details such as Maven Project, Spring Boot version, Group, and Artifact, as shown in the preceding screenshot, and click on Switch to the full version below the Generate Projects button. Select Web, HATEOAS, and Rest Repositories HAL Browser. Make sure the Java version is 8, and the package type is selected as Jar, as shown in the following screenshot:

1. Once selected, hit the Generate Project button. This will generate a Maven project, and download the project as a zip file into the download directory of the browser.
2. Unzip the file, and save it to a directory of your choice.

1. Open STS, go to the File menu, and click on Import:

1. Navigate to Maven | Existing Maven Projects, then click on Next.
2. Click on browse next to the root directory, and select the unzipped folder. Click on Finish. This will load the generated Maven project in STS Project Explorer.

1. Edit BoothateoasApplication.java to add a new REST endpoint as follows:

        @RequestMapping("/greeting")
        @ResponseBody
        public HttpEntity<Greet> greeting(@RequestParam(value = "name", 
          required = false, defaultValue = "HATEOAS") String name) {
           Greet greet = new Greet("Hello " + name);
           greet.add(linkTo(methodOn(GreetingController.class)
             .greeting(name)).withSelfRel());
           return new ResponseEntity<Greet>(greet, HttpStatus.OK);
        } 

1. Note that this is the same GreetingController class as in the previous example. But a method named greeting was added this time. In this new method, an additional optional request parameter is defined and defaulted to HATEOAS. The following code adds a link to the resulting JSON--in this case, it adds the link to the same API.
2. The following code adds a self-reference web link to the Greet object: "href": "http://localhost:8080/greeting?name=HATEOAS":

        greet.add(linkTo(methodOn(
          GreetingController.class).greeting(name)).withSelfRel());

In order to do this, we need to extend the Greet class from ResourceSupport as shown in following code. The rest of the code remains the same:

        class Greet extends ResourceSupport{

1. Add is a method on ResourceSupport. The linkTo and methodOn are static methods of ControllerLinkBuilder, a utility class for creating links on controller classes. The methodOn method does a dummy method invocation, and linkTo creates a link to the controller class. In this case, we use withSelfRel to point it to self.
2. This will essentially produce a link, /greeting?name=HATEOAS, by default. A client can read the link, and initiate another call.
3. Run as Spring Boot App. Once the server startup is completed, point the browser to http://localhost:8080.

1. This will open the HAL browser window. In the Explorer field, type /greeting?name=World!, and click on the Go button. If everything is fine, the response details will be seen in the HAL browser as shown in the following screenshot:

As shown in the preceding screenshot, the Response Body has the result with a link, href, which points back to the same service. This is because we pointed the reference to itself. Also, review the Links section. The little green box against self is the navigable link.

It does not make much sense in this simple example, but this could be handy in larger applications with many related entities. Using the links provided, the client can easily navigate back and forth between these entities with ease.