How to use Spring HATEOAS LinkBuilder API with Spring REST?

Hypermedia as the Engine of Application State (HATEOAS) is a constraint for the REST architecture. If you are not familiar with the REST web services, REST is services exposed using an URI that is shared to the clients. A client can directly access that given URI to get the response which is mostly a JSON or XML type. It is very popular because it is light weight compared to the traditional web services. However, the drawback on this approach is that each service would have a seperate URL to be defined. It is not easy to remember and maintain the complete list of services and state transition by the clients.

Take an example, If you write a RESTful service to control the Virtual Machines. The different state of the VM is start, stop, restart. Client doesn’t aware of the current status of the VM. When you invoke a REST service for starting a VM that is already running, then in response server should send a next recommended action for the client. This us known as HATEOAS or constraint for the RESTful web services. Here the action is taken by the server instead of REST client.

Spring HATEOAS is a new project in the early stage of its release. The latest version available to the public is  0.7. Spring provides RESTful support through its Spring MVC module. With the existing Spring MVC application, you can use Spring HATEOAS APIs to provide the HATEOAS support.

This project is in the initial stage, I have created a very simple example code to demonstrated the HATSOAS APIs with the LinkBuilder APIs. It is the first step on understanding the Spring HATEOAS project. Here is the steps to understand this code sample.

1. Add Spring HATEOAS Dependencies

If you are using Maven, please add these dependencies to your pom.xml file.

<dependencies>
    <dependency>
        <groupId>org.springframework.hateoas</groupId>
        <artifactId>spring-hateoas</artifactId>
        <version>0.7.0.RELEASE</version>
    </dependency>
</dependencies>

2. Necessary Library files to Run Spring HATEOAS

If you are not using the maven build, look at below folder structure to understand the list of library files used for this demo. Also add all the libraries required to run a spring mvc web application.Also add these two jar files mockito-all-1.9.5.jar and org.apache.servicemix.bundles.aopalliance-1.0-1.0.0-rc1.jar which is internally used.

3. Setup Spring MVC Application

Setup a spring mvc application. I am not explaining that in detail, You can read our previous articles and complete that setup.

4. Controller Implementation With LinkBuilder API

Create VmStatusController.java.

package javabeat.net.springhateoas;
import static org.springframework.hateoas.mvc.ControllerLinkBuilder.linkTo;
import static org.springframework.hateoas.mvc.ControllerLinkBuilder.methodOn;
import org.springframework.hateoas.LinkDiscoverer;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
@Controller
public class VmStatusController {

	private static final String TEMPLATE = "Virtual Machine Status %s ";

	@RequestMapping("/controlvm")
	@ResponseBody
	public HttpEntity<VmStatus> controlvm(@RequestParam(value="status",required=false,
						defaultValue="start") String status ){
		VmStatus vmStatus = new VmStatus(String.format(TEMPLATE, status));
		vmStatus.add(linkTo(methodOn(VmStatusController.class).controlvm(status)).withSelfRel());
		return new ResponseEntity<VmStatus>(vmStatus, HttpStatus.OK);
	}
}

1. Look at the first two import statements, those are static imports as part of the spring hateoas api. linkTo and methodOn are used for adding the link to the response.
2. Response object is HttpEntiry with the model object which extends the ResourceSupport. Look at the below code.
3. The method arguments are similar to the normal spring mvc application.
4. We are creating a ResourceSupport object by passing the template string to the constructor method.
5. vmStatus.add is the most important code where we are adding the link by calling withSelfRel.

5. ResourceSupport Implementation

Create VmStatus.java

• ResourceSupport is the representation of resources. This class allows us to add the links and manage it.

package javabeat.net.springhateoas;
import org.springframework.hateoas.ResourceSupport;
public class VmStatus extends ResourceSupport{

	private final String content;

	public VmStatus(String content){
		this.content = content;
	}

	public String getContent(){
		return content;
	}
}

6. Run the sample application

Deploy the application in your server and access the application using this url;

http://localhost:8080/SpringExamples/controlvm?name=start

Your browser will display the output as:

{"content":"Virtual Machine Status start ","links":[{"rel":"test","href":"http://localhost:8080/SpringExamples/controlvm?status=start"}]}

When you change the name in the URL, the response also will be updated. If you have any questions, please write it in the comments section. In my future articles i will  write few more advanced concepts on the Spring HATEOAS.