or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/maven-org-springframework-boot--spring-boot-starter-hateoas

Starter for building hypermedia-based RESTful web application with Spring MVC and Spring HATEOAS

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:maven/org.springframework.boot/spring-boot-starter-hateoas@3.5.x

To install, run

npx @tessl/cli install tessl/maven-org-springframework-boot--spring-boot-starter-hateoas@3.5.0

Spring Boot Starter HATEOAS

Spring Boot Starter HATEOAS is a Spring Boot starter that provides auto-configuration for building hypermedia-based RESTful web applications using Spring MVC and Spring HATEOAS. It automatically configures the necessary components to support HATEOAS (Hypermedia as the Engine of Application State) principles, enabling REST APIs to include hypermedia links for navigation and discovery.

Package Information

Package Name: spring-boot-starter-hateoas
Package Type: maven
Language: Java

Installation:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-hateoas</artifactId>
  <version>3.5.3</version>
</dependency>

Or for Gradle:

implementation 'org.springframework.boot:spring-boot-starter-hateoas:3.5.3'

Core Imports

import org.springframework.boot.autoconfigure.hateoas.HateoasProperties;
import org.springframework.boot.autoconfigure.hateoas.HypermediaAutoConfiguration;
import org.springframework.hateoas.mediatype.hal.HalConfiguration;
import org.springframework.hateoas.client.LinkDiscoverers;

For accessing Spring HATEOAS classes (provided as transitive dependencies):

import org.springframework.hateoas.EntityModel;
import org.springframework.hateoas.Link;
import org.springframework.hateoas.RepresentationModel;
import org.springframework.hateoas.server.mvc.WebMvcLinkBuilder;

import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.linkTo;
import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.methodOn;

Basic Usage

The starter works through auto-configuration. Simply add the dependency to your Spring Boot application:

@SpringBootApplication
public class MyHateoasApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyHateoasApplication.class, args);
    }
}

@RestController
public class BookController {
    
    @GetMapping("/books/{id}")
    public EntityModel<Book> getBook(@PathVariable Long id) {
        Book book = bookService.findById(id);
        
        return EntityModel.of(book)
            .add(linkTo(methodOn(BookController.class).getBook(id)).withSelfRel())
            .add(linkTo(BookController.class).withRel("books"));
    }
}

Architecture

The starter provides:

Auto-Configuration: HypermediaAutoConfiguration automatically configures Spring HATEOAS when web components are detected
Configuration Properties: HateoasProperties allows customization of HATEOAS behavior
Dependency Management: Includes spring-boot-starter-web and spring-hateoas as transitive dependencies
HAL Support: Automatically configures HAL (Hypertext Application Language) as the default hypermedia format
Jackson Integration: Configures Jackson ObjectMapper for proper HAL serialization

Capabilities

Auto-Configuration

The starter provides automatic configuration through the HypermediaAutoConfiguration class.

@AutoConfiguration(after = { WebMvcAutoConfiguration.class, JacksonAutoConfiguration.class,
    HttpMessageConvertersAutoConfiguration.class, RepositoryRestMvcAutoConfiguration.class })
@ConditionalOnClass({ EntityModel.class, RequestMapping.class, RequestMappingHandlerAdapter.class, Plugin.class })
@ConditionalOnWebApplication
@EnableConfigurationProperties(HateoasProperties.class)
public class HypermediaAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    @ConditionalOnClass(name = "com.fasterxml.jackson.databind.ObjectMapper")
    @ConditionalOnBooleanProperty(name = "spring.hateoas.use-hal-as-default-json-media-type", matchIfMissing = true)
    HalConfiguration applicationJsonHalConfiguration();

    @Configuration(proxyBeanMethods = false)
    @ConditionalOnMissingBean(LinkDiscoverers.class)
    @ConditionalOnClass(ObjectMapper.class)
    @EnableHypermediaSupport(type = HypermediaType.HAL)
    protected static class HypermediaConfiguration {
    }
}

Conditions for activation:

Web application context
Required classes present: EntityModel, RequestMapping, RequestMappingHandlerAdapter, Plugin
Runs after other web and Jackson auto-configurations

Configuration Properties

The starter exposes configuration properties through the HateoasProperties class.

@ConfigurationProperties("spring.hateoas")
public class HateoasProperties {

    /**
     * Whether application/hal+json responses should be sent to requests that accept
     * application/json.
     */
    private boolean useHalAsDefaultJsonMediaType = true;

    public boolean isUseHalAsDefaultJsonMediaType() {
        return this.useHalAsDefaultJsonMediaType;
    }
    
    public void setUseHalAsDefaultJsonMediaType(boolean useHalAsDefaultJsonMediaType) {
        this.useHalAsDefaultJsonMediaType = useHalAsDefaultJsonMediaType;
    }
}

Configuration property:

# Whether to use HAL as default JSON media type (default: true)
spring.hateoas.use-hal-as-default-json-media-type=true

When enabled (default), requests accepting application/json will receive application/hal+json responses.

HAL Configuration Bean

Provides HAL (Hypertext Application Language) configuration for JSON responses.

@Bean
@ConditionalOnMissingBean
@ConditionalOnClass(name = "com.fasterxml.jackson.databind.ObjectMapper")
@ConditionalOnBooleanProperty(name = "spring.hateoas.use-hal-as-default-json-media-type", matchIfMissing = true)
HalConfiguration applicationJsonHalConfiguration() {
    return new HalConfiguration().withMediaType(MediaType.APPLICATION_JSON);
}

Creates a HalConfiguration that maps HAL responses to MediaType.APPLICATION_JSON.

Hypermedia Configuration

Inner configuration class that enables Spring HATEOAS hypermedia support.

@Configuration(proxyBeanMethods = false)
@ConditionalOnMissingBean(LinkDiscoverers.class)
@ConditionalOnClass(ObjectMapper.class)
@EnableHypermediaSupport(type = HypermediaType.HAL)
protected static class HypermediaConfiguration {
}

Activation conditions:

No existing LinkDiscoverers bean
ObjectMapper class is present on classpath
Enables HAL hypermedia type support

Dependency Inclusion

The starter automatically includes these dependencies:

// From build.gradle
dependencies {
    api(project(":spring-boot-project:spring-boot-starters:spring-boot-starter-web"))
    api("org.springframework.hateoas:spring-hateoas")
}

spring-boot-starter-web: Provides Spring MVC and web application support
spring-hateoas: Core Spring HATEOAS library with EntityModel, Link, RepresentationModel, etc.

Types

HypermediaAutoConfiguration

/**
 * Auto-configuration for Spring HATEOAS's EnableHypermediaSupport.
 */
@AutoConfiguration
public class HypermediaAutoConfiguration {
    // Configuration class providing automatic HATEOAS setup
}

HateoasProperties

/**
 * Configuration properties for Spring HATEOAS.
 */
@ConfigurationProperties("spring.hateoas")
public class HateoasProperties {
    private boolean useHalAsDefaultJsonMediaType = true;
    // Property class for customizing HATEOAS behavior
}

HalConfiguration (from spring-hateoas)

/**
 * Configuration for HAL media type handling.
 */
public class HalConfiguration {
    public HalConfiguration withMediaType(MediaType mediaType);
    public HalConfiguration withObjectMapperCustomizer(Consumer<ObjectMapper> customizer);
    public List<MediaType> getMediaTypes();
    // Note: Consumer is from java.util.function.Consumer
    // Configures HAL media type mappings and ObjectMapper customization
}

Integration Notes

Compatible with:

Spring MVC applications
Jackson JSON processing
Spring Data REST
Spring Boot 3.x

Not compatible with:

Spring WebFlux (use direct spring-hateoas dependency instead)

Automatically configures:

HAL link discovery for client-side support
Jackson ObjectMapper for HAL serialization
Hypermedia support for REST controllers

The starter simplifies HATEOAS setup by providing sensible defaults while allowing customization through properties and conditional bean replacement.