Developing the Spring Boot microservice using Spring Initializr – the HATEOAS example

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 to configure and generate a Spring Boot project. One of the advantages of Spring Initializr is that it can generate a project through the website that then can be imported into any IDE.

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

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 in which 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 that establishes conventions to represent hyperlinks between resources. HAL helps APIs be more explorable and discoverable.

Note

The full source code of this example is available as the chapter2.boothateoas project in the code files of this book.

Here are the concrete steps to develop a HATEOAS sample using Spring Initilizr:

  1. In order to use Spring Initilizr, go to https://start.spring.io:
    Developing the Spring Boot microservice using Spring Initializr – the HATEOAS example
  2. Fill the details, such as whether it is a Maven project, Spring Boot version, group, and artifact ID, as shown earlier, and click on Switch to the full version link under the Generate Project button. Select Web, HATEOAS, and Rest Repositories HAL Browser. Make sure that the Java version is 8 and the package type is selected as JAR:
    Developing the Spring Boot microservice using Spring Initializr – the HATEOAS example
  3. 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.
  4. Unzip the file and save it to a directory of your choice.
  5. Open STS, go to the File menu and click on Import:
    Developing the Spring Boot microservice using Spring Initializr – the HATEOAS example
  6. Navigate to Maven | Existing Maven Projects and click on Next.
  7. Click on Browse next to Root Directory and select the unzipped folder. Click on Finish. This will load the generated Maven project into STS' Project Explorer.
  8. Edit the Application.java file 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);
}
  9. Note that this is the same GreetingController class as in the previous example. However, a method was added this time named greeting. 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 code. In this case, it adds the link to the same API: 
    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 here. The rest of the code remains the same:

    class Greet extends ResourceSupport{
  10. The add method is a method in ResourceSupport. The linkTo and methodOn methods are static methods of ControllerLinkBuilder, a utility class for creating links on controller classes. The methodOn method will do a dummy method invocation, and linkTo will create a link to the controller class. In this case, we will use withSelfRel to point it to itself.
  11. This will essentially produce a link, /greeting?name=HATEOAS, by default. A client can read the link and initiate another call.
  12. Run this as a Spring Boot app. Once the server startup is complete, point the browser to http://localhost:8080.
  13. 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 HAL browser will show the response details as shown in the following screenshot:
    Developing the Spring Boot microservice using Spring Initializr – the HATEOAS example

As shown in the screenshot, the Response Body section has the result with a link with href pointing 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.

上一章目录下一章