Implementing HATEOAS for RESTful Services

HATEOAS

HATEOAS acronyms for Hypermedia as the Engine of Application State. The term hypermedia refers to content that contains a link to other forms of media like images, movies, and text. It is a component of the REST application that distinguishes it from other network architecture. Using HATEOAS, a client interacts with a network application, whose application server provides information dynamically through Hypermedia.

Spring-HATEOAS

Spring-HATEOAS is the library of APIs. We can use these APIs for creating REST representations that follow the HATEOAS principle while working with Spring MVC.

In the Spring HATEOAS project, we do not require Servlet Context and concatenate the path variable to the base URI. Instead of this, Spring HATEOAS offers three abstractions for creating the URI: ContrrollerLinkBuilder, Link, and Resource Support. We can use these abstractions to create metadata, which associates with the resource representation.

Features

It supports hypermedia formats like HAL.
It provides Link builder API to create links pointing to MVC controller methods.
Model classes for the link, resource representation models.

Spring Boot does the following tasks:

Configure HAL support
Register support for entity links
Wire up message converter support

Suppose, we have requested a GET request for localhost:8080/users/1, it returns the details of user id 1. Along with this, it also returns a field called link that contains a link (localhost:8080/users) of all users so that consumers can retrieve all the users. This concept is called HATEOAS.

Let's implement the HATEOAS in the project.

Step1: Open the pom.xml and add the spring-boot-starter-hateoas dependency.

<dependency>d
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-hateoas</artifactId>
</dependency>

Step 2: Open UserResource.java and copy the retrieveUser() method.

Step 3: Paste the method and make the following changes:

Create a constructor of Resource class.

Remember that import the Resource class of org.springframework.hateoas package.

Add a link to retrieve all users by using the ControllerLinkBuilder class. It enables us to create a link from methods.
Import the ControllerLinkBuilder.

Use the method linkTo() of ControllerLinkBuilder class. It creates a new ControllerLinkBuilder with a base of mapping annotated to the given controller class.

ControllerLinkBuilder linkTo=linkTo(methodOn(this.getClass().retrieveAllUsers());

methodOn() is a wrapper for DummyInvocationUtils.methodOn(class, Object) to be available in case you work with the static import of ControllerLinkBuilder.

Add this link to the resource with the name which we want to use inside the HATEOAS.

withRel(String rel) is the method that creates the link built by the current builder instance with the given rel. The parameter rel must not be null.

Return the resource instead of the user.
Change the return type of method to Resource.

After making the above changes the UserResource.java file look like the following:

UserResource.java

package com.javatpoint.server.main.user;
import static org.springframework.hateoas.mvc.ControllerLinkBuilder.*;
import java.net.URI;
import java.util.List;
import javax.validation.Valid;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.hateoas.Resource;
import org.springframework.hateoas.mvc.ControllerLinkBuilder;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.support.ServletUriComponentsBuilder;
@RestController
public class UserResource 
{
@Autowired
private UserDaoService service;
@GetMapping("/users")
public List<User> retriveAllUsers()
{
return service.findAll();
}
@GetMapping("/users/{id}")
public Resource<User> retriveUser(@PathVariable int id)
{
User user= service.findOne(id);
if(user==null)
//runtime exception
throw new UserNotFoundException("id: "+ id);
//"all-users", SERVER_PATH + "/users"
//retrieveAllUsers
Resource<User> resource=new Resource<User>(user);	//constructor of Resource class
//add link to retrieve all the users
ControllerLinkBuilder linkTo=linkTo(methodOn(this.getClass()).retriveAllUsers());
resource.add(linkTo.withRel("all-users"));
return resource;
}
//method that delete a user resource
@DeleteMapping("/users/{id}")
public void deleteUser(@PathVariable int id)
{
User user= service.deleteById(id);
if(user==null)
//runtime exception
throw new UserNotFoundException("id: "+ id);
}
//method that posts a new user detail and returns the status of the user resource
@PostMapping("/users")
public ResponseEntity<Object> createUser(@Valid @RequestBody User user)	
{
User sevedUser=service.save(user);	
URI location=ServletUriComponentsBuilder.fromCurrentRequest().path("/{id}").buildAndExpand(sevedUser.getId()).toUri();
return ResponseEntity.created(location).build();
}
}

Step 4: Open the REST client Postman and send a GET request.

Implementing HATEOAS for RESTful Services

Here we can see that it returns the user along with the link to access all-users. Now click on the link and send a GET request again. It returns the list of all users, as shown in the following image.