Spring HATEOAS

Affordances provide metadata about how to use a resource (e.g., which HTTP methods are available). You can attach affordances to a link using .andAffordance(afford(...)).

Automatic Affordance Registration

You can point to controller methods to automatically capture metadata about request bodies and response types:

// Example: Associating a PUT and PATCH operation to a GET self link
link.andAffordance(afford(employeeController::updateEmployee))
    .andAffordance(afford(employeeController::partiallyUpdateEmployee));

Manual Affordance Registration

If you need to build affordances manually, use the Affordances API. This is useful for defining custom payloads and query parameters:

// Start from a Link instance
Affordances affordances = Affordances.of(link);

affordances
    .withHttpMethod(HttpMethod.PUT)
    .withPayloadDescription(Employee.class)
    .withName("update")
    .withQueryParameter("QueryParameter");

To avoid brittle URI string concatenation, use WebMvcLinkBuilder to create links by pointing to controller classes. This approach uses Spring's ServletUriComponentsBuilder to automatically resolve the base URI (protocol, host, port, etc.) from the current request.

Basic Link Creation

You can create a link to a collection resource by referencing the controller class and specifying a relation:

import static org.sfw.hateoas.server.mvc.WebMvcLinkBuilder.*;

Link link = linkTo(PersonController.class).withRel("people");

Nested and Self Links

You can build nested paths using .slash() and create self-referencing links using .withSelfRel():

Person person = new Person(1L, "Dave", "Matthews");
Link link = linkTo(PersonController.class).slash(person.getId()).withSelfRel();

Creating URIs for Headers

WebMvcLinkBuilder can also produce URI instances, which is useful for setting Location headers in responses:

HttpHeaders headers = new HttpHeaders();
headers.setLocation(linkTo(PersonController.class).slash(person).toUri());

return new ResponseEntity<PersonModel>(headers, HttpStatus.CREATED);

To ensure that RepresentationModel subtypes (like EntityModel and CollectionModel) are rendered according to specific hypermedia formats (such as HAL), use the @EnableHypermediaSupport annotation.

When you apply this annotation, Spring HATEOAS performs the following automatic configurations:

• Jackson Integration: Registers the necessary Jackson modules to render models in the chosen hypermedia format.
• Link Discovery: If JSONPath is on the classpath, it registers a LinkDiscoverer to look up links by rel in plain JSON.
• Entity Links: Enables entity links by default and bundles all EntityLinks implementations into a DelegatingEntityLinks instance available for autowiring.
• Relation Providers: Bundles all RelProvider implementations into a DelegatingRelProvider for autowiring. This includes support for @Relation on domain types and Spring MVC controllers. If EVO inflector is on the classpath, it uses that library to pluralize collection rel values.

@EnableHypermediaSupport(type = HypermediaType.HAL)
class MyHypermediaConfiguration {
    // Configuration details
}

When testing hypermedia-enabled APIs with WebTestClient, you must apply hypermedia support to the client instance. Note that WebTestClient is immutable, so you must capture the returned mutated instance.

Spring Boot Integration

In a @SpringBootTest with @AutoConfigureWebTestClient, autowire both the WebTestClient.Builder and the HypermediaWebTestClientConfigurer. Use the configurer to mutate the builder before calling .build().

@SpringBootTest
@AutoConfigureWebTestClient
class WebClientBasedTests {

@Test
    void exampleTest(@Autowired WebTestClient.Builder builder, @Autowired HypermediaWebTestClientConfigurer configurer) {
        client = builder.apply(configurer).build();

        client.get().uri("/")
                .exchange()
                .expectBody(new TypeReferences.EntityModelType<Employee>() {})
                .consumeWith(result -> {
                    // assert against this EntityModel<Employee>!
                });
    }
}