Spring HATEOAS - Reference Documentation

For 1.0 we took the chance to re-evaluate some of the design and package structure choices we had made for the 0.x branch. There had been an incredible amount of feedback on it and the major version bump seemed to be the most natural place to refactor those.

The fundamental idea of hypermedia is to enrich the representation of a resource with hypermedia elements. The simplest form of that are links. They indicate a client that it can navigate to a certain resource. The semantics of a related resource are defined in a so-called link relation. You might have seen this in the header of an HTML file already:

As you can see the link points to a resource theme.css and indicates that it is a style sheet. Links often carry additional information, like the media type that the resource pointed to will return. However, the fundamental building blocks of a link are its reference and relation.

Spring HATEOAS lets you work with links through its immutable Link value type. Its constructor takes both a hypertext reference and a link relation, the latter being defaulted to the IANA link relation self. Read more on the latter in Link relations.

Link exposes other attributes as defined in RFC-5988. You can set them by calling the corresponding wither method on a Link instance.

Find more information on how to create links pointing to Spring MVC and Spring WebFlux controllers in Building links in Spring MVC and Building links in Spring WebFlux.

For a Spring HATEOAS Link, the hypertext reference can not only be a URI, but also a URI template according to RFC-6570. A URI template contains so-called template variables and allows expansion of these parameters. This allows clients to turn parameterized templates into URIs without having to know about the structure of the final URI, it only needs to know about the names of the variables.

URI templates can be constructed manually and template variables added later on.

To indicate the relationship of the target resource to the current one so-called link relations are used. Spring HATEOAS provides a LinkRelation type to easily create String-based instances of it.

To easily create hypermedia enriched representations, Spring HATEOAS provides a set of classes with RepresentationModel at their root. It’s basically a container for a collection of Links and has convenient methods to add those to the model. The models can later be rendered into various media type formats that will define how the hypermedia elements look in the representation. For more information on this, have a look at Media types.

The default way to work with a RepresentationModel is to create a subclass of it to contain all the properties the representation is supposed to contain, create instances of that class, populate the properties and enrich it with links.

The generic self-typing is necessary to let RepresentationModel.add(…) return instances of itself. The model type can now be used like this:

If you returned such an instance from a Spring MVC or WebFlux controller and the client sent an Accept header set to application/hal+json, the response would look as follows:

Now we have the domain vocabulary in place, but the main challenge remains: how to create the actual URIs to be wrapped into Link instances in a less fragile way. Right now, we would have to duplicate URI strings all over the place. Doing so is brittle and unmaintainable.

Assume you have your Spring MVC controllers implemented as follows:

We see two conventions here. The first is a collection resource that is exposed through @GetMapping annotation of the controller method, with individual elements of that collection exposed as direct sub resources. The collection resource might be exposed at a simple URI (as just shown) or more complex ones (such as /people/{id}/addresses). Suppose you would like to link to the collection resource of all people. Following the approach from above would cause two problems:

Spring HATEOAS now provides a WebMvcLinkBuilder that lets you create links by pointing to controller classes. The following example shows how to do so:

The WebMvcLinkBuilder uses Spring’s ServletUriComponentsBuilder under the hood to obtain the basic URI information from the current request. Assuming your application runs at localhost:8080/your-app, this is exactly the URI on top of which you are constructing additional parts. The builder now inspects the given controller class for its root mapping and thus ends up with localhost:8080/your-app/people. You can also build more nested links as well. The following example shows how to do so:

The builder also allows creating URI instances to build up (for example, response header values):

TODO

REST-based resources provide not just data but controls. The last ingredient to form a flexible service are detailed affordances on how to use the various controls. Because affordances are associated with links, Spring HATEOAS provides an API to attach as many related methods as needed to a link. Just as you can create links by pointing to Spring MVC controller methods (see Building links in Spring MVC for details) you …​

The following code shows how to take a self link and associate two more affordances:

Using .andAffordance(afford(…​)), you can use the controller’s methods to connect a PUT and a PATCH operation to a GET operation. Imagine that the related methods afforded above look like this:

Pointing to those methods using the afford(…) methods will cause Spring HATEOAS to analyze the request body and response types and capture metadata to allow different media type implementations to use that information to translate that into descriptions of the input and outputs.

RFC-7239 forwarding headers are most commonly used when your application is behind a proxy, behind a load balancer, or in the cloud. The node that actually receives the web request is part of the infrastructure, and forwards the request to your application.

Your application may be running on localhost:8080, but to the outside world you’re expected to be at reallycoolsite.com (and on the web’s standard port 80). By having the proxy include extra headers (which many already do), Spring HATEOAS can generate links properly as it uses Spring Framework functionality to obtain the base URI of the original request.

To enable forwarded header handling you need to register Spring’s ForwardedHeaderFilter for Spring MVC (details here) or ForwardedHeaderTransformer for Spring WebFlux (details here) in your application. In a Spring Boot application those components can be simply declared as Spring beans as described here.

This will create a servlet filter that processes all the X-Forwarded-… headers. And it will register it properly with the servlet handlers.

For a Spring WebFlux application, the reactive counterpart is ForwardedHeaderTransformer:

This will create a function that transforms reactive web requests, processing X-Forwarded-… headers. And it will register it properly with WebFlux.

With configuration as shown above in place, a request passing X-Forwarded-… headers will see those reflected in the links generated:

So far, we have created links by pointing to the web framework implementations (that is, the Spring MVC controllers) and inspected the mapping. In many cases, these classes essentially read and write representations backed by a model class.

The EntityLinks interface now exposes an API to look up a Link or LinkBuilder based on the model types. The methods essentially return links that point either to the collection resource (such as /people) or to an item resource (such as /people/1). The following example shows how to use EntityLinks:

EntityLinks is available via dependency injection by activating @EnableHypermediaSupport in your Spring MVC configuration. This will cause a variety of default implementations of EntityLinks being registered. The most fundamental one is ControllerEntityLinks that inspects SpringMVC controller classes. If you want to register your own implementation of EntityLinks, check out this section.

As the mapping from an entity to a representation model must be used in multiple places, it makes sense to create a dedicated class responsible for doing so. The conversion contains very custom steps but also a few boilerplate steps:

Spring HATEOAS now provides a RepresentationModelAssemblerSupport base class that helps reduce the amount of code you need to write. The following example shows how to use it:

Setting the class up as we did in the preceding example gives you the following benefits:

You can then use the assembler to either assemble a RepresentationModel or a CollectionModel. The following example creates a CollectionModel of PersonModel instances:

Sometimes you need to tweak and adjust hypermedia representations after they have been assembled.

A perfect example is when you have a controller that deals with order fulfillment, but you need to add links related to making payments.

Imagine having your ordering system producing this type of hypermedia:

You wish to add a link so the client can make payment, but don’t want to mix details about your PaymentController into the OrderController.

Instead of polluting the details of your ordering system, you can write a RepresentationModelProcessor like this:

Register the processor with your application:

Now when you issue a hypermedia respresentation of an Order, the client receives this:

This example is quite simple, but you can easily:

Also, in this example, the PaymentProcessor alters the provided EntityModel<Order>. You also have the power to replace it with another object. Just be advised the API requires the return type to equal the input type.

When building links, you usually need to determine the relation type to be used for the link. In most cases, the relation type is directly associated with a (domain) type. We encapsulate the detailed algorithm to look up the relation types behind a LinkRelationProvider API that lets you determine the relation types for single and collection resources. The algorithm for looking up the relation type follows:

A LinkRelationProvider is automatically exposed as a Spring bean when you use @EnableHypermediaSupport. You can plug in custom providers by implementing the interface and exposing them as Spring beans in turn.

JSON Hypertext Application Language or HAL is one of the simplest and most widely adopted hypermedia media types adopted when not discussing specific web stacks.

It was the first spec-based media type adopted by Spring HATEOAS.

HAL-FORMS is designed to add runtime FORM support to the HAL media type.

To enable this media type, put the following configuration in your code:

Anytime a client supplies an Accept header with application/prs.hal-forms+json, you can expect something like this:

Check out the HAL-FORMS spec to understand the details of the _templates attribute. Read about the Affordances API to augment your controllers with this extra metadata.

As for single-item (EntityModel) and aggregate root collections (CollectionModel), Spring HATEOAS renders them identically to HAL documents.

Problem Details for HTTP APIs is a media type to carry machine-readable details of errors in a HTTP response to avoid the need to define new error response formats for HTTP APIs.

HTTP Problem Details defines a set of JSON properties that carry additional information to describe error details to HTTP clients. Find more details about those properties in particular in the relevant section of the RFC document.

You can create such a JSON response by using the Problem media type domain type in your Spring MVC Controller:

To use a dedicated object for custom properties, declare a type, create and populate an instance of it and hand this into the Problem instance either via ….withProperties(…) or on instance creation via Problem.create(…).

This will result in a response looking like this:

Collection+JSON is a JSON spec registered with IANA-approved media type application/vnd.collection+json.

Collection+JSON provides a uniform way to represent both single item resources as well as collections. To enable this media type, put the following configuration in your code:

This configuration will make your application respond to requests that have an Accept header of application/vnd.collection+json as shown below.

The following example from the spec shows a single item:

When rendering a collection of resources, the document is almost the same, except there will be multiple entries inside the items JSON array, one for each entry.

Spring HATEOAS more specifically will:

UBER is an experimental JSON spec

UBER provides a uniform way to represent both single item resources as well as collections. To enable this media type, put the following configuration in your code:

This configuration will make your application respond to requests using the Accept header application/vnd.amundsen-uber+json as show below:

This media type is still under development as is the spec itself. Feel free to open a ticket if you run into issues using it.

ALPS is a media type for providing profile-based metadata about another resource.

ALPS requires no special activation. Instead you "build" an Alps record and return it from either a Spring MVC or a Spring WebFlux web method as shown below:

This fragment has test data plugged in. It yields JSON like this:

Instead of linking each field "automatically" to a domain object’s fields, you can write them by hand if you like. It’s also possible to use Spring Framework’s message bundles and the MessageSource interface. This gives you the ability to delegate these values to locale-specific message bundles and even internationalize the metadata.

Spring HATEOAS allows to integrate support for custom media types through a set of SPIs, that third parties can implement. The building blocks of an such an implementation are:

To let the RepresentationModel subtypes be rendered according to the specification of various hypermedia representation types, you can activate support for a particular hypermedia representation format through @EnableHypermediaSupport. The annotation takes a HypermediaType enumeration as its argument. Currently, we support HAL as well as a default rendering. Using the annotation triggers the following:

Spring HATEOAS provides an API for client-side service traversal. It is inspired by the Traverson JavaScript library. The following example shows how to use it:

You can set up a Traverson instance by pointing it to a REST server and configuring the media types you want to set as Accept headers. You can then define the relation names you want to discover and follow. Relation names can either be simple names or JSONPath expressions (starting with an $).

The sample then hands a parameter map into the execution. The parameters are used to expand URIs (which are templated) found during the traversal. The traversal is concluded by accessing the representation of the final traversal. In the preceding example, we evaluate a JSONPath expression to access the actor’s name.

The preceding example is the simplest version of traversal, where the rel values are strings and, at each hop, the same template parameters are applied.

There are more options to customize template parameters at each level. The following example shows these options.

The static rel(…​) function is a convenient way to define a single Hop. Using .withParameter(key, value) makes it simple to specify URI template variables.

You can also load an entire Map of parameters by using .withParameters(Map).

When working with hypermedia enabled representations, a common task is to find a link with a particular relation type in it. Spring HATEOAS provides JSONPath-based implementations of the LinkDiscoverer interface for either the default representation rendering or HAL out of the box. When using @EnableHypermediaSupport, we automatically expose an instance supporting the configured hypermedia type as a Spring bean.

Alternatively, you can set up and use an instance as follows: