0
# Spring Boot Starter HATEOAS
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: spring-boot-starter-hateoas
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.springframework.boot</groupId>
13
    <artifactId>spring-boot-starter-hateoas</artifactId>
14
    <version>3.5.3</version>
15
  </dependency>
16
  ```
17
  
18
  Or for Gradle:
19
  ```gradle
20
  implementation 'org.springframework.boot:spring-boot-starter-hateoas:3.5.3'
21
  ```
22

23
## Core Imports
24

25
```java
26
import org.springframework.boot.autoconfigure.hateoas.HateoasProperties;
27
import org.springframework.boot.autoconfigure.hateoas.HypermediaAutoConfiguration;
28
import org.springframework.hateoas.mediatype.hal.HalConfiguration;
29
import org.springframework.hateoas.client.LinkDiscoverers;
30
```
31

32
For accessing Spring HATEOAS classes (provided as transitive dependencies):
33
```java
34
import org.springframework.hateoas.EntityModel;
35
import org.springframework.hateoas.Link;
36
import org.springframework.hateoas.RepresentationModel;
37
import org.springframework.hateoas.server.mvc.WebMvcLinkBuilder;
38

39
import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.linkTo;
40
import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.methodOn;
41
```
42

43
## Basic Usage
44

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

47
```java
48
@SpringBootApplication
49
public class MyHateoasApplication {
50
    public static void main(String[] args) {
51
        SpringApplication.run(MyHateoasApplication.class, args);
52
    }
53
}
54

55
@RestController
56
public class BookController {
57
    
58
    @GetMapping("/books/{id}")
59
    public EntityModel<Book> getBook(@PathVariable Long id) {
60
        Book book = bookService.findById(id);
61
        
62
        return EntityModel.of(book)
63
            .add(linkTo(methodOn(BookController.class).getBook(id)).withSelfRel())
64
            .add(linkTo(BookController.class).withRel("books"));
65
    }
66
}
67
```
68

69
## Architecture
70

71
The starter provides:
72

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

79
## Capabilities
80

81
### Auto-Configuration
82

83
The starter provides automatic configuration through the `HypermediaAutoConfiguration` class.
84

85
```java { .api }
86
@AutoConfiguration(after = { WebMvcAutoConfiguration.class, JacksonAutoConfiguration.class,
87
    HttpMessageConvertersAutoConfiguration.class, RepositoryRestMvcAutoConfiguration.class })
88
@ConditionalOnClass({ EntityModel.class, RequestMapping.class, RequestMappingHandlerAdapter.class, Plugin.class })
89
@ConditionalOnWebApplication
90
@EnableConfigurationProperties(HateoasProperties.class)
91
public class HypermediaAutoConfiguration {
92

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

99
    @Configuration(proxyBeanMethods = false)
100
    @ConditionalOnMissingBean(LinkDiscoverers.class)
101
    @ConditionalOnClass(ObjectMapper.class)
102
    @EnableHypermediaSupport(type = HypermediaType.HAL)
103
    protected static class HypermediaConfiguration {
104
    }
105
}
106
```
107

108
**Conditions for activation:**
109
- Web application context
110
- Required classes present: `EntityModel`, `RequestMapping`, `RequestMappingHandlerAdapter`, `Plugin`
111
- Runs after other web and Jackson auto-configurations
112

113
### Configuration Properties
114

115
The starter exposes configuration properties through the `HateoasProperties` class.
116

117
```java { .api }
118
@ConfigurationProperties("spring.hateoas")
119
public class HateoasProperties {
120

121
    /**
122
     * Whether application/hal+json responses should be sent to requests that accept
123
     * application/json.
124
     */
125
    private boolean useHalAsDefaultJsonMediaType = true;
126

127
    public boolean isUseHalAsDefaultJsonMediaType() {
128
        return this.useHalAsDefaultJsonMediaType;
129
    }
130
    
131
    public void setUseHalAsDefaultJsonMediaType(boolean useHalAsDefaultJsonMediaType) {
132
        this.useHalAsDefaultJsonMediaType = useHalAsDefaultJsonMediaType;
133
    }
134
}
135
```
136

137
**Configuration property:**
138
```properties
139
# Whether to use HAL as default JSON media type (default: true)
140
spring.hateoas.use-hal-as-default-json-media-type=true
141
```
142

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

145
### HAL Configuration Bean
146

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

149
```java { .api }
150
@Bean
151
@ConditionalOnMissingBean
152
@ConditionalOnClass(name = "com.fasterxml.jackson.databind.ObjectMapper")
153
@ConditionalOnBooleanProperty(name = "spring.hateoas.use-hal-as-default-json-media-type", matchIfMissing = true)
154
HalConfiguration applicationJsonHalConfiguration() {
155
    return new HalConfiguration().withMediaType(MediaType.APPLICATION_JSON);
156
}
157
```
158

159
Creates a `HalConfiguration` that maps HAL responses to `MediaType.APPLICATION_JSON`.
160

161
### Hypermedia Configuration
162

163
Inner configuration class that enables Spring HATEOAS hypermedia support.
164

165
```java { .api }
166
@Configuration(proxyBeanMethods = false)
167
@ConditionalOnMissingBean(LinkDiscoverers.class)
168
@ConditionalOnClass(ObjectMapper.class)
169
@EnableHypermediaSupport(type = HypermediaType.HAL)
170
protected static class HypermediaConfiguration {
171
}
172
```
173

174
**Activation conditions:**
175
- No existing `LinkDiscoverers` bean
176
- `ObjectMapper` class is present on classpath
177
- Enables HAL hypermedia type support
178

179
### Dependency Inclusion
180

181
The starter automatically includes these dependencies:
182

183
```java { .api }
184
// From build.gradle
185
dependencies {
186
    api(project(":spring-boot-project:spring-boot-starters:spring-boot-starter-web"))
187
    api("org.springframework.hateoas:spring-hateoas")
188
}
189
```
190

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

194
## Types
195

196
### HypermediaAutoConfiguration
197
```java { .api }
198
/**
199
 * Auto-configuration for Spring HATEOAS's EnableHypermediaSupport.
200
 */
201
@AutoConfiguration
202
public class HypermediaAutoConfiguration {
203
    // Configuration class providing automatic HATEOAS setup
204
}
205
```
206

207
### HateoasProperties
208
```java { .api }
209
/**
210
 * Configuration properties for Spring HATEOAS.
211
 */
212
@ConfigurationProperties("spring.hateoas")
213
public class HateoasProperties {
214
    private boolean useHalAsDefaultJsonMediaType = true;
215
    // Property class for customizing HATEOAS behavior
216
}
217
```
218

219
### HalConfiguration (from spring-hateoas)
220
```java { .api }
221
/**
222
 * Configuration for HAL media type handling.
223
 */
224
public class HalConfiguration {
225
    public HalConfiguration withMediaType(MediaType mediaType);
226
    public HalConfiguration withObjectMapperCustomizer(Consumer<ObjectMapper> customizer);
227
    public List<MediaType> getMediaTypes();
228
    // Note: Consumer is from java.util.function.Consumer
229
    // Configures HAL media type mappings and ObjectMapper customization
230
}
231
```
232

233
## Integration Notes
234

235
**Compatible with:**
236
- Spring MVC applications
237
- Jackson JSON processing
238
- Spring Data REST
239
- Spring Boot 3.x
240

241
**Not compatible with:**
242
- Spring WebFlux (use direct `spring-hateoas` dependency instead)
243

244
**Automatically configures:**
245
- HAL link discovery for client-side support
246
- Jackson ObjectMapper for HAL serialization
247
- Hypermedia support for REST controllers
248

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