REST HATEOAS with Spring

The Richardson maturity model breaks the REST architectural style into various levels of maturity.
  • Level zero describes a system that uses HTTP as a transport mechanism only (also known as URI tunnelling). A single URI and HTTP verb is typically used for all interactions with POX (plain old XML) being posted over the wire. Old school SOAP-RPC is a good level zero example.
  • Level one describes a system that builds on level zero by introducing the notion of resources. Resources typically represent some business entity and are usually described using nouns. Each resource is addressed via a unique URI and a single HTTP verb is used for all interactions.  
  • Level two builds on level one by using a broader range of HTTP verbs to interact with each resource. Typically GET, POST, PUT and DELETE are used to retrieve, create, update and delete resources, providing consumers with CRUD behaviour for each resource. 
  • Level three builds upon level two by introducing HATEOAS - Hypermedia As The Engine Of Application State. HATEOAS describes a RESTful system that returns hypermedia links with each response,  providing the consumer with options for subsequent API calls. Hypermedia links help guide consumers by providing options for further calls based on the current application state. 
Richardsons Maturity Model
Its probably fair to say that most RESTful applications achieve level two in Richardsons Maturity Model (certainly the case for most of the RESTful applications I've worked on). This post will look at level three and how you can implement HATEOAS in a Spring based application. Side note - if you're looking for a good example of a level 2 REST service take a look at this post.

Sample HATEOAS response

Before we write any code lets look at a sample HATEOAS response from the Customer endpoint we're going to write. The following is returned as the result of a HTTP GET request and includes a JSON representation of the Customer, as well a collection of hypermedia links. Each link contains a rel and href attribute. The rel attribute describes the relationship between the Customer and the supplied link, while the href attribute contains the actual URL.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    "customerId": 1,
    "firstName": "Joe",
    "lastName": "Smith",
        "dateOfBirth": "1982-01-10",
        "address": {
            "id": 1,
            "street": "High Street",
            "town": "Newry",
            "county": "Down",
            "postcode": "BT893PY"
        },
        "links": [{
                "rel": "self",
                "href": "http://localhost:8080/api/customer/1"
        }, {
                "rel": "update",
                "href": "http://localhost:8080/api/customer/1"
        }, {
                "rel": "delete",
                "href": "http://localhost:8080/api/customer/1"
        }, {
                "rel": "orders",
                "href": "http://localhost:8080/api/customer/1/orders"
        }]
}

The first link uses the rel value self  to indicate that this is a self referencing link. In other words this link can be used to retrieve this Customer definition. The next two links use the rel values update and delete respectively. These are pretty intuitive and as you'd expect provide links to endpoints for updating and deleting a Customer resource. The final link uses the rel value orders and provides a link for retrieving all Customer Orders associated with this Customer.

Navigating the API

Using the links provided, the client can update or delete the current Customer resource, or retrieve a list of Orders associated with the Customer. The orders link is particularly interesting as it allows the client to navigate the API to retrieve Order data related to this Customer. Following hypermedia links allows a client to navigate an API to find the data that they want.

The diagram below describes a simple journey through the API. The client begins by retrieving a Customer resource, then uses the order link to retrieve a list of associated Orders, and finally uses the products links to retrieve all products associated with each Order.
Using Links to navigate an API

HATEOAS - No Substitute For API Documentation

You may have noticed that the links provided do not include all the information required to make the call, like the HTTP verb to use for example. Take a look at the update and delete links in the Customer response. Both URL values are the same but it isn't specified that update should be called with a HTTP PUT and delete should be called with a HTTP DELETE. Update and delete are trivial examples because they map intuitively to HTTP verbs, but what if we had a link like deleteCustomerOrder. Would such a link simply remove the relationship between the Customer and the Order or would it delete the Order resource altogether? The answer is we simply don't know, without consulting the API documentation.

HATEOAS tells the consumer what options are available for a given resource. It doesn't tell them the circumstances in which each link should be used or what information should be sent. Its important to understand that HATEOAS is not a substitute for formal API documentation. Documentation should be provided that explains the semantics of each link (via the rel attribute) and how that associated link should be used. Information such as expected data structure, content type and HTTP verb should be expressed through documentation.

Implementing HATEOAS 

Now that we've covered some of the theory and looked at a few examples, lets take a look at a simple implementation. A sample application with integration tests accompanies this post, so feel free to pull the code from Github. It might help to have the full source code locally before going any further.

Introducing Spring HATEOAS

Spring HATEOAS makes it easy to add hypermedia links by providing some useful utilities via the ControllerLinkBuilder class.  The sample code in this post makes use of the linkTo and methodOn methods. These can be statically imported as follows.

1
2
import static org.springframework.hateoas.mvc.ControllerLinkBuilder.linkTo;
import static org.springframework.hateoas.mvc.ControllerLinkBuilder.methodOn;

Domain Model - Adding ResourceSupport

As shown in the sample HATEOAS responses, each exposed entity can have a list of associated links. We can use Spring HATEOAS to make these links available on each entity via the ResourceSuppport base class as follows. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
@Entity
@ToString
public class Customer extends ResourceSupport {

    public Customer() {
    }
 
    public Customer(String firstName, String lastName, LocalDate dateOfBirth, Address address) {
        this.firstName = firstName;
        this.lastName = lastName;
        this.dateOfBirth = dateOfBirth;
        this.address = address;
    }

    @Id
    @Getter
    @GeneratedValue(strategy=GenerationType.AUTO)
    private long customerId;
 
    @Setter
    @Getter
    private String firstName;
 
    @Setter
    @Getter
    private String lastName;
 
    @Setter 
    @Getter
    private LocalDate dateOfBirth;

    @Setter
    @Getter
    @OneToOne(cascade = {CascadeType.ALL})
    private Address address;
 
    @Setter
    @Getter
    @JsonBackReference
    @OneToMany(cascade = { CascadeType.ALL })
    private Set<CustomerOrder> orders;
 
    public void addOrder(CustomerOrder order){
        if(orders == null){
            orders = new HashSet<>();
        }
        orders.add(order);
    }
}

Customer Controller - Get Customer

With ResourceSupport added we can now add links directly to the Customer entity. Spring HATEOAS provides a fluent API for adding links, using the controller and method name of the endpoint you want to link to. This is a neat approach as Spring can easily parse the endpoint method to determine the structure of the link. It's up to the developer to provide values for any arguments that are required to the endpoint.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
@RequestMapping(value = "/api/customer/{customerId}", method = RequestMethod.GET)
public ResponseEntity<Customer> getCustomer(@PathVariable("customerId") Long customerId) {
  
    /* validate Customer Id parameter */
    if (null==customerId) {
        throw new InvalidCustomerRequestException();
    }
  
    Customer customer = customerRepository.findOne(customerId);
  
    if(null==customer){
        throw new CustomerNotFoundException();
    }

    customer.add(linkTo(methodOn(CustomerController.class)
            .getCustomer(customer.getCustomerId()))
            .withSelfRel());
  
    customer.add(linkTo(methodOn(CustomerController.class)
            .updateCustomer(customer, customer.getCustomerId()))
            .withRel("update"));
  
    customer.add(linkTo(methodOn(CustomerController.class)
            .removeCustomer(customer.getCustomerId()))
            .withRel("delete"));

    customer.add(linkTo(methodOn(OrderController.class)
            .getCustomerOrders(customer.getCustomerId()))
            .withRel("orders"));
  
    return ResponseEntity.ok(customer);
}

Lines 16 to 19 create a link to the getCustomer method on the Customer controller, which in this case is actually the current method. The getCustomer method takes a single Customer Id parameter, so we have to supply this value when constructing the link. We're building a self referencing link in this instance so we use the Customer Id of the current Customer.  After specifying the target controller and method, we need to supply a rel value. We have two options here, either withSelfRel() to specify self, or withRel("anyValue") to specify an arbitrary value.

The links created for self, update, delete and orders are as follows.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
 "links": [{
     "rel": "self",
     "href": "http://localhost:8080/api/customer/1"
   }, {
     "rel": "update",
     "href": "http://localhost:8080/api/customer/1"
   }, {
     "rel": "delete",
     "href": "http://localhost:8080/api/customer/1"
   }, {
     "rel": "orders",
     "href": "http://localhost:8080/api/customer/1/orders"
 }]

The update, delete and orders links are created in exactly the same way. Note that orders is a link created between resources, allowing the client to view the relationship between Customers and Orders in this instance.

Order Controller - Get Customer Orders

The orders link shown above allows the client to retrieve all Orders associated with the specified Customer. Like the Customer entity, the CustomerOrder entity also extends ResourceSupport so that links can be added. The getCustomerOrders endpoint is defined as follows.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
@RequestMapping(value = "/api/customer/{customerId}/orders", method = RequestMethod.GET)
public ResponseEntity<Set<CustomerOrder>> getCustomerOrders(@PathVariable("customerId") Long customerId) {
  
    Set<CustomerOrder> orders = customerRepository.findOne(customerId).getOrders();
  
    orders.forEach(order -> {
   
        order.add(linkTo(methodOn(OrderController.class)
             .getOrder(order.getOrderId()))
             .withSelfRel());
   
        order.add(linkTo(methodOn(OrderController.class)
             .removeorder(order.getOrderId()))
             .withRel("delete"));

        order.add(linkTo(methodOn(OrderController.class)
             .getProductsFromOrder(order.getOrderId()))
             .withRel("products"));       
    });
  
    return ResponseEntity.ok(orders);
}

A Set of Orders is retrieved from the database using the supplied Customer Id. For each Order returned, a self referencing link, a delete link and a products link is added. The approach is identical to that used in the Customer controller, except this time the links refer to the CustomerOrder entity and a list of Products associated with the CustomerOrder. A sample JSON response from this endpoint is shown below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
[{
    "orderId": 1,
    "orderDate": "2017-07-13",
    "dispatchDate": "2017-07-16",
    "totalOrderAmount": 783.99,
        "links": [{
            "rel": "self",
            "href": "http://localhost:8080/api/order/1"
        }, {
            "rel": "delete",
            "href": "http://localhost:8080/api/order/1"
        }, {
            "rel": "products",
            "href": "http://localhost:8080/api/order/1/products"
        }]
 }, {
    "orderId": 3,
    "orderDate": "2017-07-13",
    "dispatchDate": "2017-07-14",
    "totalOrderAmount": 69.98,
        "links": [{
            "rel": "self",
            "href": "http://localhost:8080/api/order/3"
        }, {
            "rel": "delete",
            "href": "http://localhost:8080/api/order/3"
        }, {
            "rel": "products",
            "href": "http://localhost:8080/api/order/3/products"
        }]
}, {
    "orderId": 2,
    "orderDate": "2017-07-13",
    "dispatchDate": "2017-07-15",
    "totalOrderAmount": 619.99,
        "links": [{
            "rel": "self",
            "href": "http://localhost:8080/api/order/2"
        }, {
            "rel": "delete",
            "href": "http://localhost:8080/api/order/2"
        }, {
            "rel": "products",
            "href": "http://localhost:8080/api/order/2/products"
        }]
}]

Product Controller - Get Products From Order

The products link shown above allows the client to retrieve a list of Products associated with an Order. This link provides the final step in allowing the client to navigate the API, from Customer to related Orders, and finally through to Products. The getProductsFromOrder endpoint as the names suggests, retrieves all Products associated with an Order and is defined as follows.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
@RequestMapping(value = "/api/order/{orderId}/products", method = RequestMethod.GET)
public ResponseEntity<Set<Product>> getProductsFromOrder(@PathVariable("orderId") Long orderId) {
  
    Set<Product> products = orderRepository.findOne(orderId).getProducts();
  
    products.forEach(product -> {
   
        product.add(linkTo(methodOn(ProductController.class)
               .getProduct(product.getProductId()))
               .withSelfRel());
   
        product.add(linkTo(methodOn(OrderController.class)
               .deleteProductFromOrder(orderId, product.getProductId()))
               .withRel("delete-from-order"));
    });
  
    return ResponseEntity.ok(products);
}

A Set of Products are retrieved from the database using the supplied Order Id. For each Product returned a self referencing link and a delete-from-order link is added.

Why use HATEOAS?

Ready Made URLs

I like the idea of providing the consumer with ready made URLs. The consumer needs to understand the semantic context of each link before they can use it, but complexity is reduced as URLs no longer have to built for each request. The real benefit comes from the fact that the API can be changed, including the URL structure, without affecting consumers. Client applications simply use URLs supplied via hypermedia links and when the structure of those links change, the client remains oblivious. Being able to update an API without introducing breaking changes is a huge benefit, especially for APIs that are public facing or have a large number if consumers.

Self Documenting APIs (sort of...)

HATEOAS systems are to a certain degree self documenting. The links provide the consumer with a list of operations that can performed based on the current state of the application. This is can be a useful starting point during development but is not a substitute for formal documentation.
API documentation is still required to describe the semantics of each link as well as the information required to use it. Request message structure, HTTP verb and content type are not documented by HATEOAS, yet this detail is essential for developers calling the service.

Wrapping Up

I hope this post has provided you with a decent introduction to HATEOAS and the knowledge required to build a hypermedia REST application with Spring. The sample code for this post is available on Github so feel free to pull it down and have a play around.  If you have any questions or comments please leave a note below. 

Comments

Post a Comment

Popular posts from this blog

Spring Web Services Tutorial

Image
Update
I've recently written a more up to date version of this post which describes how to build a contract first web service using Apache CXF. Check it out here.

Introduction
Modern enterprise applications are rarely stand alone and often rely on data and services provided by external systems. In order for different types of systems to communicate there must be a  communication protocol of some sort, a standard way of sending and receiving messages in a format that is recognised and supported by all major platforms. SOAP (Simple Object Application Protocol) is such a protocol, and allows applications to communicate by exchanging messages in a standard XML format.
SOAP Web Services provide a platform agnostic integration mechanism that allows disparate systems to exchange data regardless of the platform they are running on. For example, SOAP web services are commonly used to integrate .NET applications with applications running on the Java platform. Almost all modern platforms and …
Read more

REST Endpoint Testing With MockMvc

In this post I'm going to show you how to test a Spring MVC Rest endpoint without deploying your application to a server. In the past, full integration tests were the only meaningful way to test a Spring REST endpoint. This involved spinning up a test server like Tomcat or Jetty, deploying the application, calling the test endpoint, running some assertions and then terminating the server. While this is an effective way to test an endpoint, it isn't particularly fast. We're forced to wait while the entire application is stood up, just to test a single endpoint.
An alternative approach is to unit test by manually instantiating the Controller and mocking out any required dependencies.  While such a test will run much faster than a full integration test, its of limited value. The problem is that by manually instantiating the Controller we're bypassing Springs Dispatcher Servlet, and as a result missing out on core features like
request URL mapping request deserialization re…
Read more

Axis2 Web Service Client Tutorial

Image
Introduction
Axis2 is a Java framework that provides comprehensive support for exposing and consuming web services. This short post will look at its SOAP client support and how it can be used to get a simple web service client up and running.
For convenience I'm going to be calling a web service that I recently built as part of another blog post.  If you don't already have a web service to call you can grab the full source code for my sample service from github. Simply run a Maven build and deploy the WAR to your Servlet container.

What is a Web Service Client
This post doesn't attempt to explain the detailed inner workings of a web service client, but its still pretty useful to have an idea of what's going on under the hood. Most web service clients provide the following
A client side proxy for the remote service we want to call, that allows our application to invoke a SOAP service using a simple method call. The proxy insulates our application from the intricacies of s…
Read more

Health Checks, Metrics & More with Spring Boot Actuator

Image
I've been working with Spring Boot for a few years now and I'm a big fan. There are lots of things to like about Spring Boot, but one thing that really stands out for me is the emphasis on production readiness.
Production Readiness Production readiness is about looking beyond functional requirements and ensuring your application can be properly managed and monitored in production. Some key things to consider when thinking about production readiness are...
Health checksViewing application configuration - application properties, Environment variables etc. Viewing and altering log configurationViewing application metrics - JVM, classloader, threading and garbage collection. Audibility of key application events Spring provides all of this functionality out of the box via Spring Boot Actuator, a sub project of Spring Boot. A range of RESTful management and monitoring endpoints are provided so you don't have to implement these features each time you build an application. To enable…
Read more

An Introduction to Wiremock

This post provides a brief introduction to Wiremock, showing how it can be used to to quickly and easily mock remote API calls. We'll use Wiremock to write some integration tests for a simple Dropwizard app and show you how it can be put to use in a real world scenario.

Why would I need to mock external API calls? There are a number of scenarios where it makes sense to mock an external API rather than call a live service.
The external API may still be in development and not yet available for integration. In this instance as long as a data contract has been defined (e.g. Swagger spec, WSDL), the remote API can be stubbed based on the data contract. Stubbed endpoints allows a team to continue development even when external APIs isn't fully implemented.You may have little or no control over the external API uptime in development or test.  As a result you cannot guarantee it will be available to call when running integration tests. In this instance it makes sense to use mocked respo…
Read more

Spring Batch Tutorial

Image
Introduction Spring batch is a lightweight framework that provides a solid foundation on which to build robust and scalable batch applications. It provides developers with a set of tried and tested patterns that solve common batch problems and allows developers to focus more on the business requirement and less on complex batch infrastructure. Spring batch contains a variety of out of the box configurable components that can be used to satisfy many of the most common batch use cases. Extensive XML configuration and an extensible programming model mean that these components can be customised and used as building blocks to quickly deliver common batch functionality.
This tutorial will show you how to build a very simple batch application to read fixed length data from a flat file and write it to a database table. This is a common batch use case and should be sufficient to demonstrate some of the fundamental concepts of Spring batch and provide you with a foundation on which to build mor…
Read more

Externalising Spring Configuration

Enterprise applications typically contain a number of  properties and  runtime resources that must be configured before the application is deployed. Property and resource values can either be baked into the artefact at build time using something like Maven Profiles or derived at runtime using Spring Profiles. My preferred approach is to externalise all configuration so that the artefact taken from the build server is environment agnostic and can be deployed onto any environment . For example, we could take a WAR file from our build server and  deploy it to our development, UAT or production environments without changing any configuration in the WAR file itself.

Spring Property Configuration Spring applications use the PropertyPlaceholderConfigurer to load application properties. Property files are typically loaded from the class path but the example below uses a slightly different approach, loading the properties file from a directory outside of the application itself. This allows the…
Read more

Docker & Spring Boot

Docker allows you to package an application with its dependencies, into a light weight, portable container that can run on almost any environment.  You can think of a Docker container as a run time, a mini virtual machine that encapsulates your application and its dependencies.
In order to run a container you need a Docker image. An image is like a template that defines everything that will exist within the container. You can almost think of an container as a run time instance of the image it was created from. In this post we'll define and build 3 slightly different Docker images that run a simple Java app.

Installing Docker If you haven't already done so you'll need to install Docker. The official documentation is pretty good so following it step by step should see you up and running in about 15 minutes.
I've installed Docker on Windows and Ubuntu but to be honest I prefer running it on Ubuntu and have found it a bit more reliable than with Docker Toolbox on Windows.��…
Read more

Spring Boot & Amazon Web Services (EC2, RDS & S3)

Image
This post will take you through a step by step guide to building and deploying a simple Java application to the AWS cloud platform. The application will use a few well known AWS services which I'll describe along the way. There is quite a bit of material to cover in this post so the overview of the AWS services will be light. For those interested in finding out more I'll link to the appropriate section of the AWS documentation. Amazon have done a fine job documenting their platform so I'd encourage you to have a read if time permits.      

Prerequisites In order to get the sample application up and running you'll need access to AWS. If you don't already have access you can register for a free account which includes access to a bunch of great services and some pretty generous allowances. I'd encourage you to get an account set up now before going any further.

What will the sample application look like? The application we're going to build is very simple custo…
Read more