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 Hypermedia 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.
Here are the concrete steps to develop a HATEOAS sample using Spring Initilizr:
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); }
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{
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./greeting?name=HATEOAS
, by default. A client can read the link and initiate another call.http://localhost:8080
./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: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.