Building Hypermedia As The Engine Of Application State (HATEOAS) APIs

When exposing operations to be performed on an entity via RESTful services, one of the key things that gets undermined is exposing the entity relationships to the consumer of the service. The flow-on impact is that the consumer ends up hardcoding the logic in the client application.

Let's take the case of an online shopping cart application. Is it wise to allow the creation of an order without any products added to the basket or any payments done? Autonomously implementing an order, product, or payments entity service without considering the relationship is obviously not a good design. The realization of entity linking while developing RESTful services is made possible using the HATEOAS constraint. Also, this gives a representation of the state of the application, with the choice of the next possible actions based on the state of the entity. Since the next possible actions are commonly represented as the endpoint for a service or link, you must include all the possible links in the API responses when you build a HATEOAS-compliant API.

Please be warned that there is no universally accepted format for representing links between two resources in JSON.  Various API vendors or enterprises use different formats, depending upon the API guidelines that they follow. 

Choosing where to place the links is based on the REST API guidelines that you follow for your application. 

Programmatically building entity body links using JAX-RS APIs

Before getting into the declarative offerings from the Jersey framework to build HATEOAS APIs, let's see what is there in the JAX-RS API specification for solving this use case. JAX-RS 2.1 has the basic API support for representing hypermedia links with resources.

Let's take an example to understand the APIs provided by JAX-RS for building resource links. Consider the following REST resource class method, which returns a list of department resources:

//Rest of the code is omitted for brevity 
@GET 
@Path("departments") 
@Produces(MediaType.APPLICATION_JSON) 
public List<Department> findAllDeprtments(){ 
  //Finds all departments from database 
  List<Department> departments = findAllDepartmentEntities(); 
  return departments; 
} 

Let's see how we can add hypermedia links for accessing employee resources in each department resource representation returned by the preceding method. This link can be traversed by a client to read the employees for a department. To add a link, you use the javax.ws.rs.core.Link API. The entity provider components that come with the JAX-RS implementation will automatically convert the links to the appropriate media type representation at runtime:

//Other imports are omitted for brevity 
import javax.ws.rs.core.Link; 
import javax.xml.bind.annotation.adapters.XmlAdapter; 
@XmlRootElement 
public class Department { 
 
    private Short departmentId; 
    private String departmentName; 
    private Integer managerId; 
    private Short locationId; 
 
    Link employeesLink; 
   
    @XmlElement(name = "link") 
    @XmlJavaTypeAdapter(XmlAdapter.class) 
    public Link getEmployeesLink() { 
        employeesLink = Link.fromUri("{id}/employees") 
                .rel("employees").build(departmentId); 
        return employeesLink; 
     } 
 //Rest of the getters and setters are omitted for brevity 
 
} 

Here is a quick overview of the APIs used in this example:

• In the preceding code snippet, the Link.fromUri() method call creates a new hypermedia link builder object, which is an instance of javax.ws.rs.core.Link.Builder. This Builder instance is used for building hypermedia links.
• The rel() method on the Builder instance lets you set the name for the link field present in the resource. This example sets the link relation as employees.
• You can also set certain attributes on a link object, such as the media type, title, or parameter, by calling the respective methods, such as type(), title(), or param(), defined on the Builder instance.
• The final build() method results in building the hypermedia link with the supplied values. In this example, the build()method will replace the param {id} template present in the URI, with the supplied departmentId parameter.

Here is the sample JSON representation generated for the Department resource that we discussed in this example:

[{"departmentId":300,"departmentName":"Administration", 
"link":{"href":"300/employees","rel":"employees"}, 
"locationId":1700,"managerId":200} ...]